@brandon_m_behring/book-scaffold-astro 4.17.0 → 4.18.0

package/CLAUDE.md

@@ -96,7 +96,7 @@ Two callout families coexist. Authors import what they need.
 
 **Tools family** (`src/components/callouts/`, 8 components): `SkillBox`, `CaseStudy`, `ConceptBox`, `KeyIdea`, `TryThis`, `Recovery`, `Convergence`, `Divergence`.
 
-**Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof). **Props (v4.14.3, #121):** `kind=` is canonical; `type=` is accepted as a legacy alias (likewise `title=`/`label=` alias `name=`). An absent or unknown kind **throws at build** (via `src/lib/theorem-label`) rather than rendering an empty label; `book-scaffold validate` flags a `<Theorem>` with neither `kind=` nor `type=` even earlier.
+**Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof). **Props (v4.14.3, #121):** `kind=` is canonical; `type=` is accepted as a legacy alias (likewise `title=`/`label=` alias `name=`). An absent or unknown kind **throws at build** (via `src/lib/theorem-label`) rather than rendering an empty label; `book-scaffold validate` flags a `<Theorem>` with neither `kind=` nor `type=` even earlier. **Numbering (v4.18.0, #126):** a theorem with an `id` auto-numbers from `labels.json` — the same index `<XRef>` reads — so the heading number equals every cross-reference to it by construction; explicit `n=` is a fallback for un-id'd theorems. `build-labels` indexes the kind-accurate word (`Proposition 8.1`, not a kind-blind `Theorem 8.1`) and throws on an unknown kind.
 
 **Pedagogy family** (v4.1.0+, any profile, 3 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop). Slot bullets/code freely; render at any preset.
 

package/components/Theorem.astro

@@ -10,29 +10,54 @@
  * (ssm-foundations ch1–11 + the LaTeX-env mental model pass `type=`). `name`
  * is canonical with `title=`/`label=` accepted. An absent or unknown kind
  * THROWS at build (see `src/lib/theorem-label`) — it never renders an empty
- * label. Pass `n` to number the environment.
+ * label.
  *
- * Auto-numbering note: the LaTeX preamble shares a counter between
- * theorem/proposition/lemma/corollary and gives definition/example/exercise/
- * remark their own; in MDX the author passes `n` explicitly when it matters.
+ * Auto-numbering (#126): when the theorem has an `id`, its number is read from
+ * `src/data/labels.json` — the same map <XRef> resolves — so the heading number
+ * EQUALS every cross-reference to it by construction. No hand-passed `n=`, no
+ * drift; inserting a theorem renumbers the chapter from one counter
+ * (`book-scaffold build-labels`). Explicit `n=` stays a fallback for an un-id'd
+ * theorem (or before labels.json is built); when an id resolves, the labels.json
+ * number wins so the two surfaces can never disagree.
  *
  * Usage:
- *   <Theorem kind="theorem" n="4.2" name="Stable continuous-time eigenvalues" id="thm-w4-stability">
- *     For …
+ *   <Theorem kind="theorem" name="Stable continuous-time eigenvalues" id="thm-w4-stability">
+ *     For …                      // number auto-resolved from labels.json
  *   </Theorem>
  *
  *   <Theorem kind="definition" n="4.1" name="HiPPO-LegS">
- *     The HiPPO-LegS state matrix …
+ *     The HiPPO-LegS state matrix …   // explicit n= (un-cross-referenced)
  *   </Theorem>
  */
-import { theoremLabel, type TheoremLabelProps } from '../src/lib/theorem-label';
+import { theoremLabel, resolveTheoremNumber, type TheoremLabelProps } from '../src/lib/theorem-label';
 
 interface Props extends TheoremLabelProps {
   id?: string;
 }
 
+// #126: resolve THIS theorem's number from the same labels.json that <XRef>
+// reads, so the heading number == the cross-reference display by construction.
+// build-labels.mjs writes { href, display, number } keyed by id. Mirror XRef's
+// project-root glob (Vite resolves `/` to the consumer root, not the package);
+// a missing file → empty map → fall back to explicit n= (the same soft-degrade
+// path as XRef — the validator catches unknown ids at CI).
+type LabelEntry = { href: string; display: string; number?: string | null };
+const labelsModules = import.meta.glob<{ default: Record<string, LabelEntry> }>(
+  '/src/data/labels.json',
+  { eager: true },
+);
+const labelsMap = (labelsModules['/src/data/labels.json']?.default ?? {}) as Record<
+  string,
+  LabelEntry
+>;
+
 const { id } = Astro.props;
-const { kind, fullLabel } = theoremLabel(Astro.props);
+// labels.json (by id) is the number source; explicit n= is the fallback when no
+// id resolves. When both exist the shared source wins — that is what guarantees
+// heading == xref (a stale n= can't reintroduce drift).
+const entry = id ? labelsMap[id] : undefined;
+const resolvedN = resolveTheoremNumber(entry, Astro.props.n);
+const { kind, fullLabel } = theoremLabel({ ...Astro.props, n: resolvedN });
 ---
 <div class="theorem" data-kind={kind} id={id}>
   <span class="theorem-label">{fullLabel}.</span>

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
 import { d as BookConfigOptions, g as BookScaffoldIntegrationOptions, a5 as volatilityLevels, i as ChaptersRenderer, t as academicParts, Q as Question, q as Style } from './types-CMPuyZGP.js';
 export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BloomLevel, c as BookConfigError, e as BookPreset, f as BookProfile, h as BookSchemasOptions, C as ChapterFor, j as CourseNotesChapter, F as FreshnessAffordance, k as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, l as PartialRouteToggles, m as ProfileDefinition, n as Provenance, o as QuestionType, R as ResearchPortfolioChapter, p as RouteToggles, S as StatusBadge, r as StyleInput, T as ToolsChapter, V as VolatilityBadge, s as academicChapterSchema, u as bloomLevels, v as changeKinds, w as changelogSchema, x as chapterStatus, y as citationBackstops, z as composeStyles, D as courseNotesChapterSchema, E as defineProfile, G as defineStyle, H as minimalChapterSchema, I as normalizeFrontmatterConfig, J as patternCategories, K as patternsSchema, L as provenanceObject, N as provenanceSchema, O as questionDifficulties, U as questionSchema, W as questionTypes, X as refineQuestion, Y as refinedQuestionSchema, Z as researchPortfolioChapterSchema, _ as resolvePreset, $ as resolveProfile, a0 as sourceTiers, a1 as sourceTiersResearch, a2 as sourcesSchema, a3 as toolSlugs, a4 as toolsChapterSchema } from './types-CMPuyZGP.js';
+export { KIND_LABEL, ResolvedTheoremLabel, THEOREM_KINDS, TheoremKind, TheoremLabelProps, resolveTheoremNumber, theoremLabel } from './lib/theorem-label.js';
 import 'astro/zod';
 
 /**
@@ -204,54 +205,6 @@ declare function academicPartOrdinal(part: string): number;
  */
 declare function academicPartHeading(part: string): string;
 
-/**
- * theorem-label — resolve a `<Theorem>` component's label from its props,
- * failing loud instead of rendering a silent empty label (#121).
- *
- * Vocabulary: `kind` is canonical; `type` is an accepted **legacy alias** (many
- * consumer books — ssm-foundations ch1–11 — and the LaTeX `\begin{<env>}`
- * mental model pass `type=`). Likewise `name` is canonical with `title`/`label`
- * accepted as aliases. Aliases keep existing content valid; they are synonyms,
- * not deprecations, so they neither warn nor throw.
- *
- * Failure mode: an absent or unrecognized kind THROWS a build-failing,
- * actionable error rather than computing `KIND_LABEL[undefined]` → a bare "."
- * (the v4.8–4.14 silent defect, live across 32+ ssm-foundations theorems). A
- * typo'd kind — silent before — now stops the build with the offending value.
- *
- * Extracted from the `Theorem.astro` frontmatter so the contract is unit-tested
- * in the pure `node --test` suite (see tests/theorem-label.test.mjs) — the same
- * single-source-of-truth move as `academic-parts.ts` (#95).
- */
-declare const THEOREM_KINDS: readonly ["theorem", "proposition", "lemma", "corollary", "definition", "example", "exercise", "remark", "proof"];
-type TheoremKind = (typeof THEOREM_KINDS)[number];
-declare const KIND_LABEL: Record<TheoremKind, string>;
-interface TheoremLabelProps {
-    /** Canonical environment selector. */
-    kind?: string;
-    /** Legacy alias for `kind` (LaTeX-env mental model; ssm-foundations ch1–11). */
-    type?: string;
-    /** Explicit number, e.g. "4.2"; omit for an unnumbered environment. */
-    n?: string;
-    /** Canonical display name shown in parentheses. */
-    name?: string;
-    /** Legacy aliases for `name`. */
-    title?: string;
-    label?: string;
-}
-interface ResolvedTheoremLabel {
-    /** The validated, canonical kind (for `data-kind`). */
-    kind: TheoremKind;
-    /** The composed "Kind N (Name)" label (never empty). */
-    fullLabel: string;
-}
-/**
- * Resolve a `<Theorem>`'s `kind` (canonical or legacy `type=`) and compose its
- * full label. Throws — never returns an empty label — when the kind is absent
- * or not one of {@link THEOREM_KINDS}.
- */
-declare function theoremLabel(props: TheoremLabelProps): ResolvedTheoremLabel;
-
 /**
  * repo-url — resolve and build GitHub source links for CodeRef / CodeBlock.
  *
@@ -504,4 +457,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, KIND_LABEL, Question, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, sortQuestions, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, Question, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, sortQuestions, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -1498,6 +1498,9 @@ function theoremLabel(props) {
   const fullLabel = name ? `${numbered} (${name})` : numbered;
   return { kind: raw, fullLabel };
 }
+function resolveTheoremNumber(entry, n) {
+  return entry?.number ?? n;
+}
 
 // src/lib/assert-prop.ts
 function assertEnumProp(value, allowed, ctx) {
@@ -1691,6 +1694,7 @@ export {
   resolveGithubRepo,
   resolvePreset,
   resolveProfile,
+  resolveTheoremNumber,
   sortQuestions,
   sourceTiers,
   sourceTiersResearch,

package/dist/lib/theorem-label.d.ts

@@ -0,0 +1,64 @@
+/**
+ * theorem-label — resolve a `<Theorem>` component's label from its props,
+ * failing loud instead of rendering a silent empty label (#121).
+ *
+ * Vocabulary: `kind` is canonical; `type` is an accepted **legacy alias** (many
+ * consumer books — ssm-foundations ch1–11 — and the LaTeX `\begin{<env>}`
+ * mental model pass `type=`). Likewise `name` is canonical with `title`/`label`
+ * accepted as aliases. Aliases keep existing content valid; they are synonyms,
+ * not deprecations, so they neither warn nor throw.
+ *
+ * Failure mode: an absent or unrecognized kind THROWS a build-failing,
+ * actionable error rather than computing `KIND_LABEL[undefined]` → a bare "."
+ * (the v4.8–4.14 silent defect, live across 32+ ssm-foundations theorems). A
+ * typo'd kind — silent before — now stops the build with the offending value.
+ *
+ * Extracted from the `Theorem.astro` frontmatter so the contract is unit-tested
+ * in the pure `node --test` suite (see tests/theorem-label.test.mjs) — the same
+ * single-source-of-truth move as `academic-parts.ts` (#95).
+ */
+declare const THEOREM_KINDS: readonly ["theorem", "proposition", "lemma", "corollary", "definition", "example", "exercise", "remark", "proof"];
+type TheoremKind = (typeof THEOREM_KINDS)[number];
+declare const KIND_LABEL: Record<TheoremKind, string>;
+interface TheoremLabelProps {
+    /** Canonical environment selector. */
+    kind?: string;
+    /** Legacy alias for `kind` (LaTeX-env mental model; ssm-foundations ch1–11). */
+    type?: string;
+    /** Explicit number, e.g. "4.2"; omit for an unnumbered environment. */
+    n?: string;
+    /** Canonical display name shown in parentheses. */
+    name?: string;
+    /** Legacy aliases for `name`. */
+    title?: string;
+    label?: string;
+}
+interface ResolvedTheoremLabel {
+    /** The validated, canonical kind (for `data-kind`). */
+    kind: TheoremKind;
+    /** The composed "Kind N (Name)" label (never empty). */
+    fullLabel: string;
+}
+/**
+ * Resolve a `<Theorem>`'s `kind` (canonical or legacy `type=`) and compose its
+ * full label. Throws — never returns an empty label — when the kind is absent
+ * or not one of {@link THEOREM_KINDS}.
+ */
+declare function theoremLabel(props: TheoremLabelProps): ResolvedTheoremLabel;
+/**
+ * Resolve a theorem's display number for {@link theoremLabel}'s `n` (#126). The
+ * labels.json entry's `number` — the single source `<XRef>` also reads — wins;
+ * an explicit `n=` is the fallback for an un-id'd theorem (or before
+ * labels.json is built). Both `null` (a `label=` display override that opted
+ * out of auto-numbering) and `undefined` (no entry) fall through to `n`.
+ *
+ * The #126 invariant in one place: when an id resolves, the index wins, so a
+ * stale `n=` can't reintroduce heading/cross-reference drift. Extracted from
+ * `Theorem.astro` so the precedence is unit-tested in the pure node:test suite
+ * (Astro is peerDep-only — the `.astro` frontmatter can't be loaded there).
+ */
+declare function resolveTheoremNumber(entry: {
+    number?: string | null;
+} | undefined, n: string | undefined): string | undefined;
+
+export { KIND_LABEL, type ResolvedTheoremLabel, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, resolveTheoremNumber, theoremLabel };

package/dist/lib/theorem-label.mjs

@@ -0,0 +1,49 @@
+// src/lib/theorem-label.ts
+var THEOREM_KINDS = [
+  "theorem",
+  "proposition",
+  "lemma",
+  "corollary",
+  "definition",
+  "example",
+  "exercise",
+  "remark",
+  "proof"
+];
+var KIND_LABEL = {
+  theorem: "Theorem",
+  proposition: "Proposition",
+  lemma: "Lemma",
+  corollary: "Corollary",
+  definition: "Definition",
+  example: "Example",
+  exercise: "Exercise",
+  remark: "Remark",
+  proof: "Proof"
+};
+function isTheoremKind(value) {
+  return value !== void 0 && THEOREM_KINDS.includes(value);
+}
+function theoremLabel(props) {
+  const raw = props.kind ?? props.type;
+  if (!isTheoremKind(raw)) {
+    const detail = raw === void 0 ? "no kind= (or legacy type=) prop was passed" : `kind="${raw}" is not one of ${THEOREM_KINDS.join(", ")}`;
+    const hint = props.type !== void 0 && props.kind === void 0 ? " (you passed type=; kind= is canonical, type= is accepted)" : "";
+    throw new Error(
+      `<Theorem>: cannot resolve a label \u2014 ${detail}. Pass a valid kind, e.g. kind="theorem"${hint}.`
+    );
+  }
+  const name = props.name ?? props.title ?? props.label;
+  const numbered = props.n ? `${KIND_LABEL[raw]} ${props.n}` : KIND_LABEL[raw];
+  const fullLabel = name ? `${numbered} (${name})` : numbered;
+  return { kind: raw, fullLabel };
+}
+function resolveTheoremNumber(entry, n) {
+  return entry?.number ?? n;
+}
+export {
+  KIND_LABEL,
+  THEOREM_KINDS,
+  resolveTheoremNumber,
+  theoremLabel
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.17.0",
+  "version": "4.18.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/scripts/build-labels.mjs

@@ -4,9 +4,18 @@
  *
  * Walks the consumer's `src/content/chapters/**\/*.mdx`, extracts each
  * labelable component invocation (Theorem, Figure, Section, … — see
- * `LABELABLE_TYPES` below), and assigns it a display string of the form
- * `<Type> <chapter>.<n>` (e.g. `Theorem 4.2`), matching the LaTeX `\cref`
- * convention. The resulting map is consumed by XRef.astro via
+ * `LABELABLE_TYPES` below), and assigns it an entry of the form
+ *   { href, display: "Theorem 4.2", number: "4.2" }
+ * matching the LaTeX `\cref` convention. The map is consumed by XRef.astro
+ * (display + href) AND Theorem.astro (#126: `number`, so a heading auto-
+ * numbers from the same source the xref reads — they agree by construction).
+ *
+ * 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.
+ *
+ * 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
@@ -37,6 +46,12 @@
 import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
 import { resolve, relative, join, basename, dirname } from 'node:path';
 import { readChaptersBase } from './walk-mdx.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
+// throw as the render path, #121) one build step earlier. Requires `dist/`
+// (run `npm run build` first; the published tarball ships dist + scripts).
+import { theoremLabel } from '../dist/lib/theorem-label.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-labels
@@ -188,20 +203,52 @@ async function main() {
     let foundInChapter = 0;
 
     for (const match of source.matchAll(tagRegex)) {
-      const [, type, attrs] = match;
+      const [, componentName, attrs] = match;
       const id = extractAttr(attrs, 'id');
       if (!id) continue;
 
-      counters[type] = (counters[type] ?? 0) + 1;
+      // 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;
 
+      // Resolve the display word only when it will actually be used. A `label=`
+      // override supplies its own display, so we neither compute nor (for
+      // <Theorem>) kind-validate it — computing would throw on a kindless
+      // override, the documented `<Theorem id label="…">` form. For <Theorem>
+      // the word is kind-aware and THROWS on an absent/unknown kind (the #121
+      // contract, one build step earlier than render). extractAttr returns null
+      // for an absent attr → normalize to undefined so theoremLabel reports
+      // "no kind=" rather than the misleading kind="null".
       const labelOverride = extractAttr(attrs, 'label');
-      const display =
-        labelOverride ??
-        (chapterNum != null
-          ? `${TYPE_DISPLAY[type]} ${chapterNum}.${counters[type]}`
-          : `${TYPE_DISPLAY[type]} ${counters[type]}`);
+      let word;
+      if (labelOverride == null) {
+        if (componentName === 'Theorem') {
+          try {
+            word = theoremLabel({
+              kind: extractAttr(attrs, 'kind') ?? undefined,
+              type: extractAttr(attrs, 'type') ?? undefined,
+            }).fullLabel;
+          } catch (err) {
+            throw new Error(
+              `<Theorem id="${id}"> in ${relative(cwd, file)}: ${err.message}`,
+            );
+          }
+        } else {
+          word = TYPE_DISPLAY[componentName];
+        }
+      }
+
+      // 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 display = labelOverride ?? `${word} ${number}`;
 
       if (labels[id]) {
         // Duplicate id — surface but don't fail; consumer's validator
@@ -214,6 +261,7 @@ async function main() {
       labels[id] = {
         href: `/chapters/${slug}#${id}`,
         display,
+        number: labelOverride ? null : number,
       };
     }
 

package/scripts/validate.mjs

@@ -314,14 +314,27 @@ for (const rel of chapterFiles) {
   // 6. Theorem requires a resolvable kind (#121) — kind= canonical, type=
   //    legacy alias. Catches the silent-empty-label / build-throw case at the
   //    earliest gate. (Value typos are caught at build by theoremLabel's throw.)
+  //    Plus (#126): an id'd <Theorem> without a label= override auto-numbers
+  //    from labels.json — an id absent from the index silently renders the
+  //    heading UNNUMBERED (no [?id] placeholder, unlike <XRef>). Fail loud to
+  //    restore symmetry with check #2. (A label= override opts out → number:null.)
   for (const m of content.matchAll(RE_THEOREM)) {
-    if (!/\b(?:kind|type)\s*=/.test(m[1])) {
+    const attrs = m[1];
+    if (!/\b(?:kind|type)\s*=/.test(attrs)) {
       fail(
         rel,
         lineOf(content, m.index),
         `<Theorem> has no kind= (or legacy type=) — renders an empty label / throws at build. Add e.g. kind="theorem".`,
       );
     }
+    const thmId = attrs.match(/\bid=["']([^"']+)["']/);
+    if (thmId && !/\blabel\s*=\s*["']/.test(attrs) && !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.`,
+      );
+    }
   }
 
   // 7. BookLink (#96): structural (book= + to=) + best-effort registry membership.
@@ -431,7 +444,9 @@ let questionsChecked = 0;
     }
   }
   const labelsPath = join(DATA_DIR, 'labels.json');
-  const hasXrefErrors = errors.some((e) => /Unknown XRef/.test(e.msg));
+  // #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` +

package/src/lib/theorem-label.ts

@@ -96,3 +96,22 @@ export function theoremLabel(props: TheoremLabelProps): ResolvedTheoremLabel {
   const fullLabel = name ? `${numbered} (${name})` : numbered;
   return { kind: raw, fullLabel };
 }
+
+/**
+ * Resolve a theorem's display number for {@link theoremLabel}'s `n` (#126). The
+ * labels.json entry's `number` — the single source `<XRef>` also reads — wins;
+ * an explicit `n=` is the fallback for an un-id'd theorem (or before
+ * labels.json is built). Both `null` (a `label=` display override that opted
+ * out of auto-numbering) and `undefined` (no entry) fall through to `n`.
+ *
+ * The #126 invariant in one place: when an id resolves, the index wins, so a
+ * stale `n=` can't reintroduce heading/cross-reference drift. Extracted from
+ * `Theorem.astro` so the precedence is unit-tested in the pure node:test suite
+ * (Astro is peerDep-only — the `.astro` frontmatter can't be loaded there).
+ */
+export function resolveTheoremNumber(
+  entry: { number?: string | null } | undefined,
+  n: string | undefined,
+): string | undefined {
+  return entry?.number ?? n;
+}