@brandon_m_behring/book-scaffold-astro 4.14.1 → 4.14.3

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.
 
@@ -106,6 +106,28 @@ Two callout families coexist. Authors import what they need.
 
 Full reference in `recipes/04-component-library.md`.
 
+### Theme-change event (v4.14.2)
+
+`Base.astro` emits `book:theme:change` on `window` whenever the **effective** theme changes — both the chrome's dark-mode toggle and a system `prefers-color-scheme` flip (the latter only when no explicit theme is pinned). Use it for **canvas / JS islands** that can't recolor via CSS alone; CSS-token elements recolor automatically from the `[data-theme]` attribute.
+
+```ts
+// inside a Preact island (client:visible / client:idle)
+function currentTheme(): 'light' | 'dark' {
+  const t = document.documentElement.getAttribute('data-theme');
+  return t === 'light' || t === 'dark'
+    ? t
+    : matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+useEffect(() => {
+  draw(currentTheme());                                 // initial paint
+  const onChange = (e: Event) => draw((e as CustomEvent).detail.theme);
+  window.addEventListener('book:theme:change', onChange);
+  return () => window.removeEventListener('book:theme:change', onChange);
+}, []);
+```
+
+`detail.theme` is `'light' | 'dark'`. Pull design-token colors via `getComputedStyle(document.documentElement).getPropertyValue('--…')` so the canvas matches the page, and respect `prefers-reduced-motion` for any redraw animation. (Event-only by design — a `useThemeColors` helper graduates with the demo kit, #103.)
+
 ## Citation patterns
 
 Academic profile uses BibTeX → `references.json`:

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

@@ -204,6 +204,54 @@ 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;
+
 /**
  * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
  *
@@ -305,4 +353,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, 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, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -1253,6 +1253,47 @@ 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/styles/built-in.ts
 var academicStyle = defineStyle({
   name: "academic",
@@ -1299,6 +1340,8 @@ export {
   BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
+  KIND_LABEL,
+  THEOREM_KINDS,
   UNKNOWN_PART_ORDINAL,
   academicChapterSchema,
   academicChaptersRenderer,
@@ -1338,6 +1381,7 @@ export {
   sourceTiers,
   sourceTiersResearch,
   sourcesSchema,
+  theoremLabel,
   toolSlugs,
   toolsChapterSchema,
   toolsChaptersRenderer,

package/layouts/Base.astro

@@ -176,21 +176,47 @@ const ogDescription = description ?? bookConfig.description ?? '';
     ) : (
       <main><slot /></main>
     )}
+    {/*
+      Theme-change hook (#103, v4.14.2). Whenever the EFFECTIVE theme changes,
+      emit `book:theme:change` on `window` with `detail.theme` ∈ {'light','dark'}.
+      CSS recolors via the `data-theme` attribute alone; canvas/JS islands can't,
+      so they subscribe to this event (and read the attribute / matchMedia on
+      mount for the initial value) to redraw. Contract documented in the package
+      CLAUDE.md. Event-only by design — a `useThemeColors` helper graduates later
+      with the demo kit.
+    */}
     <script is:inline>
       (function () {
+        var root = document.documentElement;
+        function effectiveTheme() {
+          var explicit = root.getAttribute('data-theme');
+          if (explicit === 'light' || explicit === 'dark') return explicit;
+          return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+        }
+        function emitThemeChange() {
+          window.dispatchEvent(new CustomEvent('book:theme:change', { detail: { theme: effectiveTheme() } }));
+        }
         var btn = document.getElementById('theme-toggle');
-        if (!btn) return;
-        btn.addEventListener('click', function () {
-          var current = document.documentElement.getAttribute('data-theme');
-          // If no explicit theme, pick the opposite of prefers-color-scheme.
-          if (!current) {
-            var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-            current = prefersDark ? 'dark' : 'light';
-          }
-          var next = current === 'dark' ? 'light' : 'dark';
-          document.documentElement.setAttribute('data-theme', next);
-          try { localStorage.setItem('theme', next); } catch (e) {}
-        });
+        if (btn) {
+          btn.addEventListener('click', function () {
+            var current = root.getAttribute('data-theme');
+            // If no explicit theme, pick the opposite of prefers-color-scheme.
+            if (!current) {
+              current = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+            }
+            var next = current === 'dark' ? 'light' : 'dark';
+            root.setAttribute('data-theme', next);
+            try { localStorage.setItem('theme', next); } catch (e) {}
+            emitThemeChange();
+          });
+        }
+        // A system-preference flip only changes the effective theme when no
+        // explicit theme is pinned — emit then so islands can redraw too.
+        try {
+          window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function () {
+            if (!root.getAttribute('data-theme')) emitThemeChange();
+          });
+        } catch (e) { /* older browsers: no media-query change events */ }
       })();
     </script>
   </body>

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.1",
+  "version": "4.14.3",
   "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/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 };
+}