@brandon_m_behring/book-scaffold-astro 4.14.2 → 4.15.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).
+**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.
 
 **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/CodeBlock.astro

@@ -4,9 +4,9 @@
  * build time, with syntax highlighting and a "View on GitHub" header
  * link pointing to the exact line range.
  *
- * Reads the file from the repo root (resolved relative to
- * guides/web/), slices `lines` ("N-M" or "N"), and hands the snippet
- * to Astro's `<Code>` component for Shiki rendering.
+ * Reads the file from the code repo root (the consumer's project root by
+ * default; set BOOK_REPO_ROOT for a monorepo subdir layout), slices `lines`
+ * ("N-M" or "N"), and hands the snippet to Astro's `<Code>` for Shiki.
  *
  * Build fails if:
  *   - The file does not exist on disk
@@ -28,6 +28,7 @@ import { Code } from 'astro:components';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { buildGithubUrl } from '../src/lib/repo-url';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 interface Props {
   src: string;
@@ -37,11 +38,15 @@ interface Props {
 
 const { src, lines, lang } = Astro.props;
 
-// Resolve src relative to repo root. Astro's build runs with cwd =
-// guides/web/, so the repo root is two levels up. Using process.cwd()
+// #109: resolve src relative to the code repo root. Defaults to the consumer's
+// project root (process.cwd() during astro build — book + code in one repo);
+// set BOOK_REPO_ROOT when the code lives elsewhere (e.g. a monorepo where the
+// book is a subdir, the old guides/web/ → '../..' case). Using an env + cwd
 // (not import.meta.dirname) survives Astro's bundling — at runtime
 // import.meta.dirname points to the emitted .mjs chunk, not the source.
-const REPO_ROOT = resolve(process.cwd(), '..', '..');
+const REPO_ROOT = process.env.BOOK_REPO_ROOT
+  ? resolve(process.env.BOOK_REPO_ROOT)
+  : process.cwd();
 const absPath = resolve(REPO_ROOT, src);
 
 if (!existsSync(absPath)) {
@@ -102,7 +107,15 @@ const inferLang = (path: string): string => {
 
 const language = (lang ?? inferLang(src)) as Parameters<typeof Code>[0]['lang'];
 
-const githubUrl = buildGithubUrl(src, startLine, endLine);
+// #109: fail loud rather than link the wrong repo (see CodeRef for the rationale).
+if (!bookConfig.githubRepo) {
+  throw new Error(
+    `<CodeBlock src="${src}">: no GitHub repo resolved. Set githubRepo in ` +
+      `defineBookConfig(), or add a "repository" field to package.json (or an ` +
+      `origin git remote) so the scaffold can auto-detect owner/repo.`,
+  );
+}
+const githubUrl = buildGithubUrl(bookConfig.githubRepo, bookConfig.githubBranch, src, startLine, endLine);
 const rangeText = startLine === endLine ? `:${startLine}` : `:${startLine}-${endLine}`;
 const displayPath = `${src}${rangeText}`;
 ---

package/components/CodeRef.astro

@@ -1,7 +1,8 @@
 ---
 /**
  * CodeRef — inline reference to a specific file (and optional line range)
- * in the post_transformers repo on GitHub.
+ * in the book's GitHub repo (resolved per book — #109: defineBookConfig
+ * `githubRepo`, else auto-detected from package.json / git remote).
  *
  * Maps the LaTeX `\code{path:N}` and `\path{path}` idioms (which only
  * styled monospace text) to a real hyperlink that lands the reader on
@@ -26,6 +27,7 @@
  * synthesized.
  */
 import { buildGithubUrl } from '../src/lib/repo-url';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 interface Props {
   path: string;
@@ -34,7 +36,18 @@ interface Props {
 }
 
 const { path, line, lineEnd } = Astro.props;
-const url = buildGithubUrl(path, line, lineEnd);
+
+// #109: fail loud rather than link to the wrong repo. `githubRepo` is null
+// only when neither defineBookConfig({ githubRepo }) nor auto-detection
+// (package.json repository / git remote) resolved one.
+if (!bookConfig.githubRepo) {
+  throw new Error(
+    `<CodeRef path="${path}">: no GitHub repo resolved. Set githubRepo in ` +
+      `defineBookConfig(), or add a "repository" field to package.json (or an ` +
+      `origin git remote) so the scaffold can auto-detect owner/repo.`,
+  );
+}
+const url = buildGithubUrl(bookConfig.githubRepo, bookConfig.githubBranch, path, line, lineEnd);
 const hasSlot = await Astro.slots.has('default');
 const basename = path.split('/').pop() ?? path;
 const defaultText =

package/components/PocLayout.astro

@@ -11,12 +11,20 @@
  * Closed `kind` union: discriminated literal type. To add a 6th kind in
  * a future release, expand the union + add a CSS block in poc-layouts.css.
  */
-export type PocLayoutKind = 'tutorial' | 'how-to' | 'tldr' | 'part-summary' | 'cheat-sheet';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const POC_LAYOUT_KINDS = ['tutorial', 'how-to', 'tldr', 'part-summary', 'cheat-sheet'] as const;
+export type PocLayoutKind = (typeof POC_LAYOUT_KINDS)[number];
 
 interface Props {
   kind: PocLayoutKind;
 }
-const { kind } = Astro.props;
+// #109 sweep: fail loud on an out-of-union kind instead of emitting a
+// poc-layout-<bogus> class that matches no CSS rule.
+const kind = assertEnumProp(Astro.props.kind, POC_LAYOUT_KINDS, {
+  component: 'PocLayout',
+  prop: 'kind',
+});
 ---
 <div class={`poc-layout poc-layout-${kind}`}>
   <slot />

package/components/Practice.astro

@@ -11,12 +11,21 @@
  *
  * Family: book-genre (cross-profile).
  */
-type Difficulty = '1' | '2' | '3' | '4';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const PRACTICE_DIFFICULTIES = ['1', '2', '3', '4'] as const;
+type Difficulty = (typeof PRACTICE_DIFFICULTIES)[number];
 interface Props {
   id: string;
   difficulty: Difficulty;
 }
-const { id, difficulty } = Astro.props;
+const { id } = Astro.props;
+// #109 sweep: coerce (tolerates difficulty={3} numeric usage), then fail loud
+// on anything outside 1-4 instead of rendering empty / NaN diamond markers.
+const difficulty = assertEnumProp(String(Astro.props.difficulty), PRACTICE_DIFFICULTIES, {
+  component: 'Practice',
+  prop: 'difficulty',
+});
 const anchorId = `practice-${id}`;
 const filled = Number.parseInt(difficulty, 10);
 const markers = '◆'.repeat(filled) + '◇'.repeat(4 - filled);

package/components/StatusBadge.astro

@@ -11,14 +11,18 @@
  * Internal frontmatter retains the 7-state value for STATUS.md alignment;
  * this component is the public-facing translator.
  */
-type InternalStatus =
-  | 'implemented'
-  | 'chapter_only'
-  | 'reading_only'
-  | 'prose_only'
-  | 'code_only'
-  | 'scaffolded'
-  | 'planned';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const INTERNAL_STATUSES = [
+  'implemented',
+  'chapter_only',
+  'reading_only',
+  'prose_only',
+  'code_only',
+  'scaffolded',
+  'planned',
+] as const;
+type InternalStatus = (typeof INTERNAL_STATUSES)[number];
 
 type PublicStatus = 'published' | 'draft' | 'coming-soon';
 
@@ -42,7 +46,12 @@ interface Props {
   status: InternalStatus;
 }
 
-const { status } = Astro.props;
+// #109 sweep: fail loud on an unknown status instead of rendering an empty
+// badge label (PUBLIC_OF[undefined] -> undefined -> blank).
+const status = assertEnumProp(Astro.props.status, INTERNAL_STATUSES, {
+  component: 'StatusBadge',
+  prop: 'status',
+});
 const publicStatus = PUBLIC_OF[status];
 const label = PUBLIC_LABEL[publicStatus];
 ---

package/components/Theorem.astro

@@ -4,15 +4,17 @@
  *
  * Maps LaTeX `\begin{theorem}`, `\begin{proposition}`, `\begin{lemma}`,
  * `\begin{corollary}`, `\begin{definition}`, `\begin{example}`,
- * `\begin{exercise}`, `\begin{remark}` to a single component with a
- * `kind` prop.
+ * `\begin{exercise}`, `\begin{remark}`, `\begin{proof}` to a single component.
+ *
+ * Props (#121): `kind` is canonical; `type=` is an accepted **legacy alias**
+ * (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.
  *
  * Auto-numbering note: the LaTeX preamble shares a counter between
- * theorem/proposition/lemma/corollary (`\newtheorem{lemma}[theorem]`)
- * and gives each of definition/example/exercise/remark its own counter.
- * In MDX we accept that as a contract: per-chapter counters are
- * implemented in Phase 2.6 (label scanner) — for now, the author
- * passes `n` explicitly when numbering matters.
+ * theorem/proposition/lemma/corollary and gives definition/example/exercise/
+ * remark their own; in MDX the author passes `n` explicitly when it matters.
  *
  * Usage:
  *   <Theorem kind="theorem" n="4.2" name="Stable continuous-time eigenvalues" id="thm-w4-stability">
@@ -23,41 +25,14 @@
  *     The HiPPO-LegS state matrix …
  *   </Theorem>
  */
-type Kind =
-  | 'theorem'
-  | 'proposition'
-  | 'lemma'
-  | 'corollary'
-  | 'definition'
-  | 'example'
-  | 'exercise'
-  | 'remark'
-  | 'proof';
+import { theoremLabel, type TheoremLabelProps } from '../src/lib/theorem-label';
 
-interface Props {
-  kind: Kind;
-  n?: string;
-  name?: string;
+interface Props extends TheoremLabelProps {
   id?: string;
 }
 
-const { kind, n, name, id } = Astro.props;
-
-const KIND_LABEL: Record<Kind, string> = {
-  theorem: 'Theorem',
-  proposition: 'Proposition',
-  lemma: 'Lemma',
-  corollary: 'Corollary',
-  definition: 'Definition',
-  example: 'Example',
-  exercise: 'Exercise',
-  remark: 'Remark',
-  proof: 'Proof',
-};
-
-const label = KIND_LABEL[kind];
-const numbered = n ? `${label} ${n}` : label;
-const fullLabel = name ? `${numbered} (${name})` : numbered;
+const { id } = Astro.props;
+const { kind, fullLabel } = theoremLabel(Astro.props);
 ---
 <div class="theorem" data-kind={kind} id={id}>
   <span class="theorem-label">{fullLabel}.</span>

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-CULHImU4.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CULHImU4.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-CjOseOSG.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CjOseOSG.js';
 import 'astro/zod';
 
 /**
@@ -204,6 +204,122 @@ 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.
+ *
+ * The repo is no longer hardcoded (#109). `buildGithubUrl` takes an explicit
+ * `repo` + `branch`; the integration resolves them per book — from
+ * `defineBookConfig({ githubRepo })` (override), else auto-detected from the
+ * consumer's own `package.json` `repository` (or git remote) via
+ * `parseRepoSlug`. When nothing resolves, the components throw rather than
+ * emit links to the wrong repo (the old silent default was
+ * `brandon-behring/post_transformers`).
+ */
+/** Default branch when a book configures a repo but no branch. */
+declare const DEFAULT_GITHUB_BRANCH = "main";
+/**
+ * Derive an `owner/repo` slug from an npm `repository` field (string or
+ * `{ url }`) or a raw git remote URL. Handles https, ssh, the `git+` prefix,
+ * a trailing `.git`, and the `github:owner/repo` npm shorthand. Returns null
+ * for anything that isn't a recognizable GitHub repo — no silent guess.
+ */
+declare function parseRepoSlug(repository: string | {
+    url?: string;
+} | null | undefined): string | null;
+/** Extract the `origin` remote URL from the text of a `.git/config` file. */
+declare function originUrlFromGitConfig(gitConfigText: string): string | null;
+/**
+ * Resolve a GitHub `owner/repo` by precedence (#109) — the rule that keeps a
+ * book from ever silently linking to the wrong repo:
+ *   1. explicit `override` (defineBookConfig `githubRepo`)
+ *   2. the consumer's `package.json` `repository`
+ *   3. the `origin` remote in `.git/config`
+ *   4. null — the components then throw rather than guess.
+ */
+declare function resolveGithubRepo(sources: {
+    override?: string | null;
+    packageJsonRepository?: string | {
+        url?: string;
+    } | null;
+    gitConfigText?: string | null;
+}): string | null;
+/**
+ * Build a GitHub line-anchor URL for an explicit repo + branch.
+ *   buildGithubUrl('o/r', 'main', 'a/b.py')        -> https://github.com/o/r/blob/main/a/b.py
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42)     -> …/a/b.py#L42
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42, 58) -> …/a/b.py#L42-L58
+ */
+declare function buildGithubUrl(repo: string, branch: string, path: string, line?: number, lineEnd?: number): string;
+
+/**
+ * assert-prop — shared fail-loud validator for closed-union component props
+ * (#109 / the v4.15.0 parseProps sweep).
+ *
+ * Astro has no runtime prop validation, so a closed-union prop given an
+ * out-of-range value silently produces a broken render — an empty StatusBadge
+ * label, a `poc-layout-<bogus>` class that matches no CSS, NaN difficulty
+ * markers. This is the same silent-degradation class as the #121 Theorem bug.
+ * `assertEnumProp` converts it into a loud, actionable build-time throw.
+ */
+/**
+ * Return `value` when it's one of `allowed`; otherwise throw an actionable
+ * error naming the component, prop, the offending value, and the legal set.
+ * Never returns a fallback — a closed union with no valid value is an authoring
+ * error that should stop the build, not render something wrong.
+ */
+declare function assertEnumProp<T extends string>(value: unknown, allowed: readonly T[], ctx: {
+    component: string;
+    prop: string;
+}): T;
+
 /**
  * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
  *
@@ -305,4 +421,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, type Freshness, type FreshnessStatus, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, KIND_LABEL, 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, bookScaffoldIntegration, buildGithubUrl, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveGithubRepo, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -788,6 +788,8 @@ function resolveProfile(explicit) {
 
 // src/integration.ts
 import { fileURLToPath } from "url";
+import { readFileSync as readFileSync2 } from "fs";
+import { join } from "path";
 
 // src/lib/define-style.ts
 function defineStyle(opts) {
@@ -855,6 +857,44 @@ function normalizeFrontmatterConfig(v) {
   return v;
 }
 
+// src/lib/repo-url.ts
+var DEFAULT_GITHUB_BRANCH = "main";
+function parseRepoSlug(repository) {
+  const raw = typeof repository === "string" ? repository : repository && typeof repository === "object" ? repository.url : void 0;
+  if (!raw || typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (s === "") return null;
+  const shorthand = s.match(/^github:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i);
+  if (shorthand) return `${shorthand[1]}/${shorthand[2]}`;
+  const m = s.replace(/^git\+/, "").match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+function originUrlFromGitConfig(gitConfigText) {
+  const m = gitConfigText.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+  return m ? m[1] : null;
+}
+function resolveGithubRepo(sources) {
+  if (sources.override) return sources.override;
+  const fromPkg = parseRepoSlug(sources.packageJsonRepository ?? null);
+  if (fromPkg) return fromPkg;
+  if (sources.gitConfigText) {
+    const fromGit = parseRepoSlug(originUrlFromGitConfig(sources.gitConfigText));
+    if (fromGit) return fromGit;
+  }
+  return null;
+}
+function buildGithubUrl(repo, branch, path, line, lineEnd) {
+  const cleanPath = path.replace(/^\/+/, "");
+  let url = `https://github.com/${repo}/blob/${branch}/${cleanPath}`;
+  if (line !== void 0) {
+    url += `#L${line}`;
+    if (lineEnd !== void 0 && lineEnd !== line) {
+      url += `-L${lineEnd}`;
+    }
+  }
+  return url;
+}
+
 // src/mdx-components-resolver.ts
 import { existsSync as existsSync2 } from "fs";
 import { resolve } from "path";
@@ -915,6 +955,23 @@ function makeBookConfigVitePlugin(config) {
     }
   };
 }
+function resolveBookGithubRepo(override, consumerRoot) {
+  let packageJsonRepository = null;
+  let gitConfigText = null;
+  try {
+    packageJsonRepository = JSON.parse(readFileSync2(join(consumerRoot, "package.json"), "utf8")).repository ?? null;
+  } catch {
+  }
+  try {
+    gitConfigText = readFileSync2(join(consumerRoot, ".git", "config"), "utf8");
+  } catch {
+  }
+  return resolveGithubRepo({
+    override,
+    packageJsonRepository,
+    gitConfigText
+  });
+}
 var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
 var ROUTE_REGISTRY = {
   references: { pattern: "/references", file: "references.astro" },
@@ -968,7 +1025,10 @@ function bookScaffoldIntegration(opts) {
     // v4.6.0: book-level author + SEO config, propagated through the
     // (renamed) book-config virtual module to Base.astro + Chapter.astro.
     author,
-    seo
+    seo,
+    // v4.15.0 (#109): optional GitHub repo/branch override for CodeRef/CodeBlock.
+    githubRepo,
+    githubBranch
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -1009,6 +1069,8 @@ function bookScaffoldIntegration(opts) {
         }
         const consumerRoot = fileURLToPath(config.root);
         const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
+        const resolvedGithubRepo = resolveBookGithubRepo(githubRepo, consumerRoot);
+        const resolvedGithubBranch = githubBranch ?? DEFAULT_GITHUB_BRANCH;
         const presetLiteral = JSON.stringify(profile);
         const enabledRouteNames = Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name);
         updateConfig({
@@ -1024,7 +1086,9 @@ function bookScaffoldIntegration(opts) {
                 seo: {
                   ogImage: seo?.ogImage ?? null,
                   twitterHandle: seo?.twitterHandle ?? null
-                }
+                },
+                githubRepo: resolvedGithubRepo,
+                githubBranch: resolvedGithubBranch
               })
             ],
             define: {
@@ -1157,7 +1221,10 @@ async function defineBookConfig(opts) {
       // Base.astro + Chapter.astro. `seo.sitemap` is NOT passed through —
       // it's consumed below at config-time by the @astrojs/sitemap call.
       author: opts.author,
-      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0
+      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0,
+      // v4.15.0 (#109): repo/branch override; integration auto-detects when undefined.
+      githubRepo: opts.githubRepo,
+      githubBranch: opts.githubBranch
     }),
     ...mergedExtraIntegrations
   ];
@@ -1199,6 +1266,9 @@ async function defineBookConfig(opts) {
     // v4.6.0: strip new book-level SEO opts (author + seo block).
     author: _author,
     seo: _seo,
+    // v4.15.0: strip repo opts so they don't leak into AstroUserConfig.
+    githubRepo: _githubRepo,
+    githubBranch: _githubBranch,
     ...rest
   } = opts;
   void _styles;
@@ -1215,6 +1285,8 @@ async function defineBookConfig(opts) {
   void _portfolio;
   void _author;
   void _seo;
+  void _githubRepo;
+  void _githubBranch;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const restVite = rest.vite ?? {};
   const restSsr = restVite.ssr ?? {};
@@ -1253,6 +1325,58 @@ function chapterSortKey(data) {
   return partOrdinal * 1e3 + within;
 }
 
+// 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 };
+}
+
+// src/lib/assert-prop.ts
+function assertEnumProp(value, allowed, ctx) {
+  if (typeof value === "string" && allowed.includes(value)) {
+    return value;
+  }
+  const got = value === void 0 ? "nothing" : JSON.stringify(value);
+  throw new Error(
+    `<${ctx.component}>: ${ctx.prop}=${got} is not one of ${allowed.join(", ")}.`
+  );
+}
+
 // src/styles/built-in.ts
 var academicStyle = defineStyle({
   name: "academic",
@@ -1299,6 +1423,9 @@ export {
   BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
+  DEFAULT_GITHUB_BRANCH,
+  KIND_LABEL,
+  THEOREM_KINDS,
   UNKNOWN_PART_ORDINAL,
   academicChapterSchema,
   academicChaptersRenderer,
@@ -1307,7 +1434,9 @@ export {
   academicPartOrdinal,
   academicParts,
   academicStyle,
+  assertEnumProp,
   bookScaffoldIntegration,
+  buildGithubUrl,
   changeKinds,
   changelogSchema,
   chapterSortKey,
@@ -1327,17 +1456,21 @@ export {
   minimalChapterSchema,
   minimalStyle,
   normalizeFrontmatterConfig,
+  originUrlFromGitConfig,
+  parseRepoSlug,
   patternCategories,
   patternsSchema,
   provenanceObject,
   provenanceSchema,
   researchPortfolioChapterSchema,
   researchPortfolioStyle,
+  resolveGithubRepo,
   resolvePreset,
   resolveProfile,
   sourceTiers,
   sourceTiersResearch,
   sourcesSchema,
+  theoremLabel,
   toolSlugs,
   toolsChapterSchema,
   toolsChaptersRenderer,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-CULHImU4.js';
+import { g as BookSchemasOptions } from './types-CjOseOSG.js';
 import 'astro';
 import 'astro/zod';
 

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.14.2",
+  "version": "4.15.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/recipes/08-decisions-ledger.md

@@ -105,6 +105,23 @@ Not in v2.0:
 
 Until v3.0 triggers, accept that bug fixes don't auto-flow to existing books. Both books are currently low-churn.
 
+## Visual-suite migration → gallery + Playwright (v5.x infra, 2026-06)
+
+### D18 — Replace run.sh with a component gallery + Playwright
+**Decision**: A standalone `gallery/` app renders every component × state × theme; Playwright (`channel:'chrome'`, full-page, pixelmatch) drives it (`playwright.config.ts`) **and** the 6 profile fixtures' 24 routes (`playwright.fixtures.config.ts`). `run.sh` + its 96 baselines + `visual-regression.yml` + `update-baselines.yml` are retired; `visual-pw.yml` is the sole visual gate.
+**Reasoning**: run.sh's `--window-size=Wx2000` cap left below-fold content untested (root of #82); full-page `toHaveScreenshot` removes the fold + adds interaction (expand `<details>`, dark-mode toggle, canvas recolor). `channel:'chrome'` uses system Chrome — dissolves the "chromium-headless-shell won't build on every distro" objection that drove run.sh.
+**Deviate when**: Never reintroduce viewport-capped screenshots. New components → gallery pages; new routes → fixture-suite entries.
+
+### D19 — Baselines are CI-generated (glyph pages especially)
+**Decision**: Commit baselines from the `visual-pw` `update` dispatch (ubuntu + system chrome). ASCII/common-glyph pages are byte-identical CI==local, but math/Unicode-glyph pages (λ, ℂ, Λ) render with platform fallback fonts and MUST be CI-generated.
+**Reasoning**: Cross-OS font rendering diverges; pixelmatch `maxDiffPixels` absorbs AA, not glyph substitution.
+**Deviate when**: Never hand-commit a glyph-page baseline from a dev box.
+
+### D20 — Full route parity before retiring run.sh (Q3)
+**Decision**: The fixture suite covers run.sh's 24 routes (2 widths: mobile 768 + desktop 1280; run.sh's 1440/1920 were redundant) before deletion. Porting caught a stale run.sh route (research-portfolio `/chapters/example/` was a silently-screenshotted 404 — real slug `ch01-fixture`) + the hardcoded-`GITHUB_REPO` CodeRef/CodeBlock wart (#109).
+**Reasoning**: #82 itself was a coverage gap — don't trade coverage for speed.
+**Deviate when**: Never delete a visual gate without equivalent-or-better coverage in the replacement.
+
 ## How to use this ledger
 
 When a future change in the scaffold contradicts a decision above, update this ledger first. Don't change behavior silently — the ledger is the durable record of "why this is shaped like it is."

package/scripts/validate.mjs

@@ -13,6 +13,8 @@
  *   4. Internal markdown links [text](/foo) — target resolves.
  *   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).
  *
  * Run from the consumer's project root. Closes #8 (was resolving paths
  * from the package's own directory inside node_modules — false negatives
@@ -209,6 +211,9 @@ 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;
 
 async function fileExists(p) {
   try {
@@ -278,6 +283,19 @@ 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.)
+  for (const m of content.matchAll(RE_THEOREM)) {
+    if (!/\b(?:kind|type)\s*=/.test(m[1])) {
+      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".`,
+      );
+    }
+  }
 }
 
 // ===== v4.6.0 (issue #77): missing-prereq re-framing =====

package/src/lib/assert-prop.ts

@@ -0,0 +1,30 @@
+/**
+ * assert-prop — shared fail-loud validator for closed-union component props
+ * (#109 / the v4.15.0 parseProps sweep).
+ *
+ * Astro has no runtime prop validation, so a closed-union prop given an
+ * out-of-range value silently produces a broken render — an empty StatusBadge
+ * label, a `poc-layout-<bogus>` class that matches no CSS, NaN difficulty
+ * markers. This is the same silent-degradation class as the #121 Theorem bug.
+ * `assertEnumProp` converts it into a loud, actionable build-time throw.
+ */
+
+/**
+ * Return `value` when it's one of `allowed`; otherwise throw an actionable
+ * error naming the component, prop, the offending value, and the legal set.
+ * Never returns a fallback — a closed union with no valid value is an authoring
+ * error that should stop the build, not render something wrong.
+ */
+export function assertEnumProp<T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+  ctx: { component: string; prop: string },
+): T {
+  if (typeof value === 'string' && (allowed as readonly string[]).includes(value)) {
+    return value as T;
+  }
+  const got = value === undefined ? 'nothing' : JSON.stringify(value);
+  throw new Error(
+    `<${ctx.component}>: ${ctx.prop}=${got} is not one of ${allowed.join(', ')}.`,
+  );
+}

package/src/lib/repo-url.ts

@@ -1,27 +1,92 @@
 /**
- * Repository URL constants used by CodeRef and CodeBlock components.
+ * repo-url — resolve and build GitHub source links for CodeRef / CodeBlock.
  *
- * Centralized here so renaming the repo or moving branches is a one-file
- * change rather than a hunt across components.
- *
- * If the repo is later mirrored to a different host, update GITHUB_BASE
- * accordingly; the components do not assume GitHub-specific anchor syntax
- * beyond #L<N>-L<M>, which all major hosts (GitHub, GitLab, Codeberg)
- * support.
+ * The repo is no longer hardcoded (#109). `buildGithubUrl` takes an explicit
+ * `repo` + `branch`; the integration resolves them per book — from
+ * `defineBookConfig({ githubRepo })` (override), else auto-detected from the
+ * consumer's own `package.json` `repository` (or git remote) via
+ * `parseRepoSlug`. When nothing resolves, the components throw rather than
+ * emit links to the wrong repo (the old silent default was
+ * `brandon-behring/post_transformers`).
+ */
+
+/** Default branch when a book configures a repo but no branch. */
+export const DEFAULT_GITHUB_BRANCH = 'main';
+
+/**
+ * Derive an `owner/repo` slug from an npm `repository` field (string or
+ * `{ url }`) or a raw git remote URL. Handles https, ssh, the `git+` prefix,
+ * a trailing `.git`, and the `github:owner/repo` npm shorthand. Returns null
+ * for anything that isn't a recognizable GitHub repo — no silent guess.
  */
-export const GITHUB_REPO = 'brandon-behring/post_transformers';
-export const GITHUB_BRANCH = 'main';
-export const GITHUB_BASE = `https://github.com/${GITHUB_REPO}/blob/${GITHUB_BRANCH}`;
+export function parseRepoSlug(
+  repository: string | { url?: string } | null | undefined,
+): string | null {
+  const raw =
+    typeof repository === 'string'
+      ? repository
+      : repository && typeof repository === 'object'
+        ? repository.url
+        : undefined;
+  if (!raw || typeof raw !== 'string') return null;
+  const s = raw.trim();
+  if (s === '') return null;
+
+  // npm shorthand: github:owner/repo
+  const shorthand = s.match(/^github:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i);
+  if (shorthand) return `${shorthand[1]}/${shorthand[2]}`;
+
+  // https://github.com/owner/repo(.git), git+https://…, ssh git@github.com:owner/repo(.git)
+  const m = s
+    .replace(/^git\+/, '')
+    .match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** Extract the `origin` remote URL from the text of a `.git/config` file. */
+export function originUrlFromGitConfig(gitConfigText: string): string | null {
+  const m = gitConfigText.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Resolve a GitHub `owner/repo` by precedence (#109) — the rule that keeps a
+ * book from ever silently linking to the wrong repo:
+ *   1. explicit `override` (defineBookConfig `githubRepo`)
+ *   2. the consumer's `package.json` `repository`
+ *   3. the `origin` remote in `.git/config`
+ *   4. null — the components then throw rather than guess.
+ */
+export function resolveGithubRepo(sources: {
+  override?: string | null;
+  packageJsonRepository?: string | { url?: string } | null;
+  gitConfigText?: string | null;
+}): string | null {
+  if (sources.override) return sources.override;
+  const fromPkg = parseRepoSlug(sources.packageJsonRepository ?? null);
+  if (fromPkg) return fromPkg;
+  if (sources.gitConfigText) {
+    const fromGit = parseRepoSlug(originUrlFromGitConfig(sources.gitConfigText));
+    if (fromGit) return fromGit;
+  }
+  return null;
+}
 
 /**
- * Build a GitHub line-anchor URL.
- *   buildGithubUrl('experiments/jax/week04/s4.py', 42)        -> .../s4.py#L42
- *   buildGithubUrl('experiments/jax/week04/s4.py', 42, 58)    -> .../s4.py#L42-L58
- *   buildGithubUrl('experiments/jax/week04/s4.py')            -> .../s4.py
+ * Build a GitHub line-anchor URL for an explicit repo + branch.
+ *   buildGithubUrl('o/r', 'main', 'a/b.py')        -> https://github.com/o/r/blob/main/a/b.py
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42)     -> …/a/b.py#L42
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42, 58) -> …/a/b.py#L42-L58
  */
-export function buildGithubUrl(path: string, line?: number, lineEnd?: number): string {
+export function buildGithubUrl(
+  repo: string,
+  branch: string,
+  path: string,
+  line?: number,
+  lineEnd?: number,
+): string {
   const cleanPath = path.replace(/^\/+/, '');
-  let url = `${GITHUB_BASE}/${cleanPath}`;
+  let url = `https://github.com/${repo}/blob/${branch}/${cleanPath}`;
   if (line !== undefined) {
     url += `#L${line}`;
     if (lineEnd !== undefined && lineEnd !== line) {

package/src/lib/theorem-label.ts

@@ -0,0 +1,98 @@
+/**
+ * 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).
+ */
+
+export const THEOREM_KINDS = [
+  'theorem',
+  'proposition',
+  'lemma',
+  'corollary',
+  'definition',
+  'example',
+  'exercise',
+  'remark',
+  'proof',
+] as const;
+
+export type TheoremKind = (typeof THEOREM_KINDS)[number];
+
+export const KIND_LABEL: Record<TheoremKind, string> = {
+  theorem: 'Theorem',
+  proposition: 'Proposition',
+  lemma: 'Lemma',
+  corollary: 'Corollary',
+  definition: 'Definition',
+  example: 'Example',
+  exercise: 'Exercise',
+  remark: 'Remark',
+  proof: 'Proof',
+};
+
+export 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;
+}
+
+export interface ResolvedTheoremLabel {
+  /** The validated, canonical kind (for `data-kind`). */
+  kind: TheoremKind;
+  /** The composed "Kind N (Name)" label (never empty). */
+  fullLabel: string;
+}
+
+function isTheoremKind(value: string | undefined): value is TheoremKind {
+  return value !== undefined && (THEOREM_KINDS as readonly string[]).includes(value);
+}
+
+/**
+ * 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}.
+ */
+export function theoremLabel(props: TheoremLabelProps): ResolvedTheoremLabel {
+  const raw = props.kind ?? props.type;
+  if (!isTheoremKind(raw)) {
+    const detail =
+      raw === undefined
+        ? 'no kind= (or legacy type=) prop was passed'
+        : `kind="${raw}" is not one of ${THEOREM_KINDS.join(', ')}`;
+    const hint =
+      props.type !== undefined && props.kind === undefined
+        ? ' (you passed type=; kind= is canonical, type= is accepted)'
+        : '';
+    throw new Error(
+      `<Theorem>: cannot resolve a label — ${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 };
+}