explico 0.13.0 → 0.14.0

package/dist/{course-config-rRtME5UV.d.ts → course-config-BLtIdkei.d.ts}

@@ -382,6 +382,154 @@ interface NormalizedCards {
 declare const CARDS_DEFAULTS: NormalizedCards;
 /** Validate `CourseConfig.cards` and apply its defaults. Throws on a bad value. */
 declare function normalizeCards(config: CourseConfig): NormalizedCards;
+/**
+ * The marks the sidebar puts beside a chapter or part page for one reader
+ * (`sidebarMarks` in the course settings, `page-marks.ts`): a quiet ring
+ * while they have not opened it, an accent dot when its content changed
+ * since they last did. Every field is optional; {@link normalizeSidebarMarks}
+ * fills in the defaults.
+ */
+interface CourseSidebarMarks {
+    /** Mark a page the reader has not opened yet. Default `true`. */
+    readonly unopened?: boolean;
+    /** Mark a page whose content changed since the reader last opened it. Default `true`. */
+    readonly changed?: boolean;
+}
+/** {@link CourseSidebarMarks} with every default applied. */
+interface NormalizedSidebarMarks {
+    readonly unopened: boolean;
+    readonly changed: boolean;
+}
+declare const SIDEBAR_MARKS_DEFAULTS: NormalizedSidebarMarks;
+/** Validate `CourseConfig.sidebarMarks` and apply its defaults. Throws on a bad value. */
+declare function normalizeSidebarMarks(config: CourseConfig): NormalizedSidebarMarks;
+/**
+ * Which edition of a lesson its sidebar row opens, for a reader who has not
+ * chosen (`sidebarEditions` in the course settings, `sidebar-editions.ts`). A
+ * lesson with a chapter and a deck is one row: the row opens the **lead**
+ * edition, and the **other** is an icon at the row's end, or not listed. A
+ * reader switches both in the sidebar's foot. The plain `string` fields
+ * arrive as JSON; {@link normalizeSidebarEditions} rejects any value it does
+ * not list.
+ */
+interface CourseSidebarEditions {
+    /** The edition a lesson's row opens: `chapter` (default) or `slides`. */
+    readonly lead?: string;
+    /** Whether the row also lists the other edition: `listed` (default) or `hidden`. */
+    readonly other?: string;
+}
+type SidebarEditionLead = 'chapter' | 'slides';
+type SidebarEditionOther = 'listed' | 'hidden';
+/** {@link CourseSidebarEditions} with every default applied. */
+interface NormalizedSidebarEditions {
+    readonly lead: SidebarEditionLead;
+    readonly other: SidebarEditionOther;
+}
+/** The engine's defaults (decision D10): the chapter leads, the slides are listed. */
+declare const SIDEBAR_EDITIONS_DEFAULTS: NormalizedSidebarEditions;
+/** Validate `CourseConfig.sidebarEditions` and apply its defaults. Throws on a bad value. */
+declare function normalizeSidebarEditions(config: CourseConfig): NormalizedSidebarEditions;
+/**
+ * A course's decks: the slide edition of a lesson (`<lesson>.deck.mdx`,
+ * `docs/authoring/deck.md`). Every field is optional; {@link normalizeDeck}
+ * fills in the defaults. The plain `string` fields arrive as JSON, and
+ * {@link normalizeDeck} rejects any value it does not list.
+ */
+interface CourseDeck {
+    /**
+     * The canvas every deck of the course is laid out on: `16:9` (default),
+     * `16:10` or `4:3`. One setting for the course, because the frame-fit check,
+     * the captured figures and the PDF's page all read it.
+     */
+    readonly aspectRatio?: string;
+    /**
+     * The line on a frame that names the symbols it shows: `first-use`
+     * (default, the symbols the deck has not shown before), `every-frame`
+     * (every symbol on the frame), or `off`.
+     */
+    readonly legend?: string;
+    /**
+     * Who sees a frame's speaker notes: `reader` (default — under each frame in
+     * the scroll view, in the presenter window and in the handout), `presenter`
+     * (the presenter window and the handout only), or `off` (nowhere; the
+     * handout PDF is not built).
+     */
+    readonly notes?: string;
+    /** End each deck on a frame of what its lesson's competencies say a student can now do. Default `true`. */
+    readonly outcomesFrame?: boolean;
+    /** Offer the slides-with-notes PDF beside the slides PDF. Default `true`. */
+    readonly handoutPdf?: boolean;
+}
+type DeckAspectRatio = '16:9' | '16:10' | '4:3';
+type DeckLegend = 'first-use' | 'every-frame' | 'off';
+type DeckNotes = 'reader' | 'presenter' | 'off';
+/**
+ * The logical canvas a frame is laid out on, in CSS pixels: the width of the
+ * page's reading column, so a figure, a table or a lab lays out on a frame at
+ * the size it was made for, and the frame is scaled to the screen. Every
+ * ratio is 450 px tall, so the type scale and a frame's capacity in lines are
+ * the same in all three. Printed, the canvas is scaled by 1.6 onto a page
+ * 7.5 in tall (13.333 × 7.5 in for 16:9).
+ */
+declare const DECK_CANVAS: Readonly<Record<DeckAspectRatio, {
+    readonly width: number;
+    readonly height: number;
+}>>;
+/** {@link CourseDeck} with every default applied, as the manifest publishes it. */
+interface NormalizedDeck {
+    readonly aspectRatio: DeckAspectRatio;
+    readonly legend: DeckLegend;
+    readonly notes: DeckNotes;
+    readonly outcomesFrame: boolean;
+    readonly handoutPdf: boolean;
+    readonly canvas: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+declare const DECK_DEFAULTS: Omit<NormalizedDeck, 'canvas'>;
+/** Validate `CourseConfig.deck` and apply its defaults. Throws on a bad value. */
+declare function normalizeDeck(config: CourseConfig): NormalizedDeck;
+/**
+ * Whether the course asks each reader if it may remember their reading in
+ * their browser (`readingMemory` in the course settings,
+ * `session/reading-memory.ts`): which chapters they opened (the sidebar's
+ * marks) and the cards they keep or carry, across visits. `ask` (default)
+ * shows the question until the reader answers; `off` never asks and never
+ * keeps reading memory, so the marks are off and cards last as long as the tab.
+ */
+type ReadingMemorySetting = 'ask' | 'off';
+/** Validate `CourseConfig.readingMemory`. Throws on a bad value. */
+declare function normalizeReadingMemory(config: CourseConfig): ReadingMemorySetting;
+/**
+ * How the page tells its zones apart, and how a deck's slides sit on it
+ * (`appearance` in the course settings; `zones.css` and `deck.css` hold the
+ * colours). `zones`: `tonal` (the default) gives both sidebars one step of the
+ * neutral grey and the header a step further; `accent-header` makes the
+ * header a deep band of the course accent; `paper` lays the reading column
+ * on the sidebars' colour as a sheet; `none` keeps Starlight's colours.
+ * `slides`: `lifted` (the default) gives each slide an edge and a drop
+ * shadow, and in the dark theme a sheet a step lighter than the page; `edge`
+ * the edge and shadow on the page's own colour; `sorter` lays the deck on a
+ * tinted well. Every field is optional; {@link normalizeAppearance} fills in
+ * the defaults.
+ */
+interface CourseAppearance {
+    /** `tonal` (default), `accent-header`, `paper` or `none`. */
+    readonly zones?: string;
+    /** `lifted` (default), `edge` or `sorter`. */
+    readonly slides?: string;
+}
+type AppearanceZones = 'tonal' | 'accent-header' | 'paper' | 'none';
+type AppearanceSlides = 'lifted' | 'edge' | 'sorter';
+/** {@link CourseAppearance} with every default applied. */
+interface NormalizedAppearance {
+    readonly zones: AppearanceZones;
+    readonly slides: AppearanceSlides;
+}
+declare const APPEARANCE_DEFAULTS: NormalizedAppearance;
+/** Validate `CourseConfig.appearance` and apply its defaults. Throws on a bad value. */
+declare function normalizeAppearance(config: CourseConfig): NormalizedAppearance;
 /**
  * Rule S2's word ranges (`rules.S2.bridgeMinWords` … in the course settings),
  * in the shape `gate-part-pages.ts` takes. Built by `partPageLimits` in
@@ -487,6 +635,21 @@ interface CourseConfig {
     readonly numbering?: CourseNumbering;
     /** How explanation cards start for a reader: "Carry cards" on or off. */
     readonly cards?: CourseCards;
+    /** The sidebar's marks for a page the reader has not opened, or that changed since. */
+    readonly sidebarMarks?: CourseSidebarMarks;
+    /** Which edition a lesson's sidebar row opens, and whether it lists the other. */
+    readonly sidebarEditions?: CourseSidebarEditions;
+    /** How the course's decks look and what they show (`docs/authoring/deck.md`). */
+    readonly deck?: CourseDeck;
+    /**
+     * Ask each reader whether the course may remember their reading in their
+     * browser (`ask`, the default), or never keep it (`off`). A plain `string`
+     * because the settings arrive as JSON; {@link normalizeReadingMemory}
+     * rejects any other value.
+     */
+    readonly readingMemory?: string;
+    /** How the page tells header, sidebars and article apart, and how slides sit on it. */
+    readonly appearance?: CourseAppearance;
     /**
      * How a check's and an example set's heading names its kind: `icon-word`
      * (default) or `icon` ({@link BlockLabels}). A plain `string` because the
@@ -504,4 +667,4 @@ declare function normalizeLessonExports(config: CourseConfig): NormalizedLessonE
  */
 declare function coursePartsOf(config: CourseConfig): readonly CoursePart[];
 
-export { type CourseOpenDefault as A, type BlockLabels as B, type CourseConfig as C, type CoursePart as D, type CourseSection as E, DISCLOSURE_DEFAULTS as F, coursePartsOf as G, normalizeBlockLabels as H, normalizeCards as I, normalizeDisclosure as J, normalizeLessonExports as K, type LessonExportsConfig as L, type ManifestRules as M, type NormalizedLessonExports as N, normalizeNumbering as O, type ResolvedRules as R, type NormalizedDisclosure as a, type NormalizedNumbering as b, type NormalizedCards as c, type ConfigDiagnostic as d, type CourseOperators as e, type CourseRomanLabels as f, type CourseAccents as g, type CourseAbbreviations as h, type NormalizedPartPages as i, type CourseRulesConfig as j, type RuleSettingsInput as k, catalogIds as l, disabledCodes as m, dropDisabled as n, rulesJsonSchema as o, partPageLimits as p, rulesSnapshot as q, resolveRules as r, BLOCK_LABELS_DEFAULT as s, CARDS_DEFAULTS as t, type CourseAbout as u, type CourseAuthor as v, type CourseCards as w, type CourseDisclosure as x, type CourseHeadingDisclosure as y, type CourseNumbering as z };
+export { SIDEBAR_EDITIONS_DEFAULTS as $, APPEARANCE_DEFAULTS as A, type BlockLabels as B, type CourseConfig as C, CARDS_DEFAULTS as D, type CourseAbout as E, type CourseAppearance as F, type CourseAuthor as G, type CourseCards as H, type CourseDeck as I, type CourseDisclosure as J, type CourseHeadingDisclosure as K, type CourseNumbering as L, type ManifestRules as M, type NormalizedLessonExports as N, type CourseOpenDefault as O, type CoursePart as P, type CourseSection as Q, type ReadingMemorySetting as R, type CourseSidebarEditions as S, type CourseSidebarMarks as T, DECK_CANVAS as U, DECK_DEFAULTS as V, DISCLOSURE_DEFAULTS as W, type DeckAspectRatio as X, type DeckLegend as Y, type DeckNotes as Z, type LessonExportsConfig as _, type NormalizedDisclosure as a, SIDEBAR_MARKS_DEFAULTS as a0, type SidebarEditionLead as a1, type SidebarEditionOther as a2, coursePartsOf as a3, normalizeAppearance as a4, normalizeBlockLabels as a5, normalizeCards as a6, normalizeDeck as a7, normalizeDisclosure as a8, normalizeLessonExports as a9, normalizeNumbering as aa, normalizeReadingMemory as ab, normalizeSidebarEditions as ac, normalizeSidebarMarks as ad, type NormalizedNumbering as b, type NormalizedCards as c, type NormalizedSidebarMarks as d, type NormalizedSidebarEditions as e, type NormalizedAppearance as f, type NormalizedDeck as g, type ConfigDiagnostic as h, type CourseOperators as i, type CourseRomanLabels as j, type CourseAccents as k, type CourseAbbreviations as l, type NormalizedPartPages as m, type CourseRulesConfig as n, type ResolvedRules as o, type RuleSettingsInput as p, catalogIds as q, disabledCodes as r, dropDisabled as s, partPageLimits as t, resolveRules as u, rulesJsonSchema as v, rulesSnapshot as w, type AppearanceSlides as x, type AppearanceZones as y, BLOCK_LABELS_DEFAULT as z };

package/dist/curriculum/competency-graph.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The competency dependency graph, cut into one piece per part
+ * (`<CurriculumMap graph="per-part">`).
+ *
+ * The whole-course graph is one diagram, and a course with many competencies
+ * lays it out far wider than the lesson column (rule V8) — narrower boxes do
+ * not help, since the widest rank holds a dozen competencies. One diagram per
+ * part keeps each to the competencies a reader meets together.
+ */
+interface GraphNode {
+    readonly id: string;
+    readonly text: string;
+}
+interface GraphEdge {
+    readonly from: string;
+    readonly to: string;
+}
+interface PartGraph {
+    /** The diagram's id, unique on the page: `competency-graph-<part dir>`. */
+    readonly id: string;
+    /** The part's overview title, its label when it has none; the untaught group's name. */
+    readonly title: string;
+    /** The competencies this group teaches, then one box per earlier competency they build on. */
+    readonly nodes: readonly GraphNode[];
+    /** An arrow from each prerequisite to a competency the group teaches. */
+    readonly edges: readonly GraphEdge[];
+}
+interface PartInput {
+    readonly dir: string;
+    readonly label: string;
+    /** Lesson ids in chapter order. */
+    readonly lessons: readonly string[];
+    readonly overview?: {
+        readonly title: string;
+    };
+}
+interface CompetencyInput {
+    readonly id: string;
+    readonly title: string;
+    readonly prerequisites: readonly string[];
+}
+declare const UNTAUGHT_GRAPH_ID = "competency-graph-untaught";
+declare const UNTAUGHT_TITLE = "Competencies no lesson teaches";
+/**
+ * One graph per part, in `parts` order, then a last one for competencies no
+ * lesson teaches, so every competency is drawn once as a taught box. A
+ * competency belongs to the first part whose lessons teach it. A prerequisite
+ * taught in another part is drawn in this one as a box labelled
+ * `<part label>: <title>`, so the arrow into the competency still shows.
+ * A part that teaches no competency has no graph.
+ */
+declare function competencyGraphsByPart(parts: readonly PartInput[], teachesByLesson: ReadonlyMap<string, readonly string[]>, competencies: readonly CompetencyInput[]): PartGraph[];
+
+export { type CompetencyInput, type GraphEdge, type GraphNode, type PartGraph, type PartInput, UNTAUGHT_GRAPH_ID, UNTAUGHT_TITLE, competencyGraphsByPart };

package/dist/curriculum/competency-graph.js

@@ -0,0 +1,41 @@
+const UNTAUGHT_GRAPH_ID = "competency-graph-untaught";
+const UNTAUGHT_TITLE = "Competencies no lesson teaches";
+function competencyGraphsByPart(parts, teachesByLesson, competencies) {
+  const partOf = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    for (const lessonId of part.lessons) {
+      for (const id of teachesByLesson.get(lessonId) ?? []) {
+        if (!partOf.has(id)) partOf.set(id, part);
+      }
+    }
+  }
+  const titleOf = new Map(competencies.map((competency) => [competency.id, competency.title]));
+  const graphs = [];
+  for (const part of [...parts, void 0]) {
+    const taught = competencies.filter((competency) => partOf.get(competency.id) === part);
+    if (taught.length === 0) continue;
+    const earlier = [...new Set(taught.flatMap((competency) => competency.prerequisites))].filter(
+      (id) => partOf.get(id) !== part
+    );
+    graphs.push({
+      id: part ? `competency-graph-${part.dir.replace(/[^A-Za-z0-9_-]/g, "-")}` : UNTAUGHT_GRAPH_ID,
+      title: part ? part.overview?.title ?? part.label : UNTAUGHT_TITLE,
+      nodes: [
+        ...taught.map((competency) => ({ id: competency.id, text: competency.title })),
+        ...earlier.map((id) => ({
+          id,
+          text: `${partOf.get(id)?.label ?? "Not taught"}: ${titleOf.get(id) ?? id}`
+        }))
+      ],
+      edges: taught.flatMap(
+        (competency) => competency.prerequisites.map((from) => ({ from, to: competency.id }))
+      )
+    });
+  }
+  return graphs;
+}
+export {
+  UNTAUGHT_GRAPH_ID,
+  UNTAUGHT_TITLE,
+  competencyGraphsByPart
+};

package/dist/reference/base-library.d.mts

@@ -1,5 +1,11 @@
 /** True when `token` is a base-library atom and needs no semantic key. */
 export function isBaseLibraryAtom(token: any): boolean;
+/**
+ * True when `glyph`, as a rendered page shows it, is a base-library atom. The
+ * rendered-page check (`figure-symbols.ts`) reads glyphs, not LaTeX, and
+ * exempts the same library the math gates do.
+ */
+export function isBaseLibraryGlyph(glyph: any): boolean;
 /**
  * The base notation library: a small, fixed set of universal identifier atoms
  * that the page-level glyph map never asks an author to declare.
@@ -15,3 +21,5 @@ export function isBaseLibraryAtom(token: any): boolean;
  * atoms, so the tokenizer never treats them as bindable symbols.
  */
 export const BASE_LIBRARY: Readonly<Set<string>>;
+/** What KaTeX draws for each base-library atom: `d`, `e`, `i`, `π`. */
+export const BASE_LIBRARY_GLYPHS: Readonly<Set<any>>;

package/dist/reference/base-library.mjs

@@ -25,3 +25,22 @@ export const BASE_LIBRARY = Object.freeze(
 export function isBaseLibraryAtom(token) {
   return BASE_LIBRARY.has(token);
 }
+
+// An atom's LaTeX is its own glyph unless it is a command: `\pi` draws `π`.
+// `tests/notation/figure-symbols.test.ts` renders every atom and holds this
+// table to what KaTeX draws, so a new command atom cannot be forgotten here.
+const DRAWN_AS = Object.freeze({ '\\pi': 'π' });
+
+/** What KaTeX draws for each base-library atom: `d`, `e`, `i`, `π`. */
+export const BASE_LIBRARY_GLYPHS = Object.freeze(
+  new Set([...BASE_LIBRARY].map((atom) => DRAWN_AS[atom] ?? atom)),
+);
+
+/**
+ * True when `glyph`, as a rendered page shows it, is a base-library atom. The
+ * rendered-page check (`figure-symbols.ts`) reads glyphs, not LaTeX, and
+ * exempts the same library the math gates do.
+ */
+export function isBaseLibraryGlyph(glyph) {
+  return BASE_LIBRARY_GLYPHS.has(glyph);
+}

package/dist/reference/consistency.d.ts

@@ -1,4 +1,4 @@
-import { e as CourseOperators, f as CourseRomanLabels, g as CourseAccents } from '../course-config-rRtME5UV.js';
+import { i as CourseOperators, j as CourseRomanLabels, k as CourseAccents } from '../course-config-BLtIdkei.js';
 import { NotationSpec } from '../compiler/collections.js';
 import { LintIgnore } from './lint-ignore.js';
 import { NotationRegistry, NotationRegistryInput } from './types.js';
@@ -18,7 +18,10 @@ import './gate-retired-keys.js';
  * snapshot. Nothing here changes content. A finding is silenced only by a
  * reviewed line in `lint-ignore.yml` (see `./lint-ignore`).
  *
- *   (a) glyph-unique-in-corpus       one rendered glyph → one meaning corpus-wide
+ *   (a) glyph-unique-in-corpus       one rendered glyph → one shared meaning; a
+ *                                    local card or a gloss may reuse a letter
+ *   (a') definition-repeated         one local key declared in two lessons
+ *   (a'') meaning-repeated           one symbol and name defined at two sites, any tier
  *   (b) notation-units / units-vocab  every entry has units or `dimensionless`,
  *                                     unit strings drawn from a controlled vocab
  *   (f) weak-local                  a `notation.local` symbol used only in its
@@ -44,7 +47,7 @@ import './gate-retired-keys.js';
  * `src/content/resolution-report.ts`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained' | 'roman-label-explained' | 'accent-explained' | 'accent-swallowed' | 'operator-suspended' | 'operator-suspension-reason' | 'operator-shadowed';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'weak-local' | 'notation-source-locator' | 'definition-repeated' | 'meaning-repeated' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained' | 'roman-label-explained' | 'accent-explained' | 'accent-swallowed' | 'operator-suspended' | 'operator-suspension-reason' | 'operator-shadowed';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — repairable violations are warnings; optional advice is info. */
@@ -69,6 +72,7 @@ interface ConsistencyInput {
     /** This course's edits to the (empty) accent baseline (rule N22). */
     readonly accents?: CourseAccents;
 }
+declare function glyphMatcher(latex: string): RegExp | undefined;
 /**
  * Run every consistency check. The result is sorted deterministically (code,
  * then lesson / key / glyph, then message) so it is byte-stable in the manifest
@@ -78,4 +82,4 @@ declare function runConsistencyChecks(input: ConsistencyInput): ConsistencyDiagn
 /** `{ code: count }` for the CLI summary and the report header. */
 declare function consistencyCounts(diagnostics: readonly ConsistencyDiagnostic[]): Record<ConsistencyCode, number>;
 
-export { type ConsistencyCode, type ConsistencyDiagnostic, type ConsistencyInput, consistencyCounts, runConsistencyChecks };
+export { type ConsistencyCode, type ConsistencyDiagnostic, type ConsistencyInput, consistencyCounts, glyphMatcher, runConsistencyChecks };

package/dist/reference/consistency.js

@@ -54,14 +54,14 @@ function checkGlyphUniqueness(input, out) {
     glyphs.set(trimmed, keys);
   };
   for (const definition of input.registry.definitions) {
-    if (definition.kind === "local") {
-      record(definition.notation, definition.key, definition.lessonId);
+    if (definition.kind === "shared") {
+      record(definition.notation, definition.key, "");
     }
   }
   for (const bundle of input.registry.bundles) {
     for (const binding of bundle.bindings) {
       const definition = byId.get(binding.definitionId);
-      if (definition) record(definition.notation, binding.key, bundle.lessonId);
+      if (definition?.kind === "shared") record(definition.notation, binding.key, bundle.lessonId);
     }
   }
   for (const [glyph, keys] of [...glyphs].sort(
@@ -69,12 +69,15 @@ function checkGlyphUniqueness(input, out) {
   )) {
     if (keys.size < 2) continue;
     if (input.lintIgnore.matches("glyph-unique-in-corpus", glyph)) continue;
-    const detail = [...keys].sort(([a], [b]) => a.localeCompare(b)).map(([key, lessons]) => `${key} (${[...lessons].sort().join(", ")})`).join("; ");
+    const detail = [...keys].sort(([a], [b]) => a.localeCompare(b)).map(([key, lessons]) => {
+      const bound = [...lessons].filter((lesson) => lesson !== "").sort();
+      return `${key} (${bound.length > 0 ? bound.join(", ") : "no lesson binds it"})`;
+    }).join("; ");
     out.push({
       code: "glyph-unique-in-corpus",
       severity: "warning",
       glyph,
-      message: `glyph ${JSON.stringify(glyph)} resolves to ${keys.size} meanings across the corpus: ${detail}`
+      message: `glyph ${JSON.stringify(glyph)} is ${keys.size} shared cards: ${detail}; course vocabulary gives a glyph one meaning \u2014 keep one card, or make the page-bound one a notation.local entry`
     });
   }
 }
@@ -144,34 +147,78 @@ function checkNotationSourceLocator(input, out) {
     }
   }
 }
-const GLOSS_PROMOTION_LIMIT = 3;
-function checkGlossWantsPromoting(input, out) {
-  const owners = /* @__PURE__ */ new Map();
-  const record = (ownerKey, gloss) => {
-    const id = `${gloss.notation}\0${gloss.label.toLowerCase()}`;
-    const current = owners.get(id) ?? { label: gloss.label, keys: /* @__PURE__ */ new Set() };
-    current.keys.add(ownerKey);
-    owners.set(id, current);
+function checkDefinitionRepeated(input, out) {
+  const byKey = /* @__PURE__ */ new Map();
+  const chapters = input.notationInput.lessons.filter((lesson) => lesson.scopeLessonIds === void 0);
+  for (const lesson of [...chapters].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
+    for (const definition of lesson.localDefinitions) {
+      const list = byKey.get(definition.key) ?? [];
+      if (!list.some((entry) => entry.lessonId === lesson.lessonId)) {
+        list.push({ lessonId: lesson.lessonId, file: lesson.source.file, definition });
+      }
+      byKey.set(definition.key, list);
+    }
+  }
+  for (const [key, copies] of [...byKey].sort(([a], [b]) => a.localeCompare(b))) {
+    if (copies.length < 2) continue;
+    if (input.lintIgnore.matches("definition-repeated", key)) continue;
+    const first = copies[0];
+    const differing = ["notation", "label", "summary", "units", "sources"].filter(
+      (field) => copies.some((copy) => JSON.stringify(copy.definition[field] ?? null) !== JSON.stringify(first.definition[field] ?? null))
+    );
+    const lessons = copies.map((copy) => copy.lessonId).sort();
+    out.push({
+      code: "definition-repeated",
+      severity: "warning",
+      key,
+      lessonId: first.lessonId,
+      file: first.file,
+      count: copies.length,
+      message: `local entry ${key} (${first.definition.notation}) is declared in ${copies.length} lessons (${lessons.join(", ")}); ` + (differing.length === 0 ? "the copies agree" : `the copies differ in ${differing.join(", ")}`) + ` \u2014 move one copy to content/notation/${key}.md and delete the others: every [[${key}]] and \\explain{${key}} keeps working; if they are two meanings, give one another key`
+    });
+  }
+}
+function checkMeaningRepeated(input, out) {
+  const normalize = (label) => label.toLowerCase().replace(/\s+/g, " ").trim();
+  const groups = /* @__PURE__ */ new Map();
+  const record = (notation, label, site) => {
+    const id = `${notation.trim()}\0${normalize(label)}`;
+    const group = groups.get(id) ?? { notation: notation.trim(), label, sites: [] };
+    if (!group.sites.some((known) => known.tier === site.tier && known.key === site.key && known.where === site.where)) {
+      group.sites.push(site);
+    }
+    groups.set(id, group);
   };
   for (const definition of input.notationInput.sharedDefinitions) {
-    for (const gloss of definition.glosses) record(definition.key, gloss);
+    record(definition.notation, definition.label, { tier: "shared", key: definition.key, where: `card ${definition.key}` });
+    for (const gloss of definition.glosses) {
+      record(gloss.notation, gloss.label, { tier: "gloss", key: gloss.key, where: `gloss on ${definition.key}` });
+    }
   }
   for (const lesson of input.notationInput.lessons) {
+    if (lesson.scopeLessonIds !== void 0) continue;
     for (const definition of lesson.localDefinitions) {
-      for (const gloss of definition.glosses) record(definition.key, gloss);
+      record(definition.notation, definition.label, {
+        tier: "local",
+        key: definition.key,
+        where: `local ${definition.key} on ${lesson.lessonId}`
+      });
+      for (const gloss of definition.glosses) {
+        record(gloss.notation, gloss.label, { tier: "gloss", key: gloss.key, where: `gloss on ${definition.key} (${lesson.lessonId})` });
+      }
     }
   }
-  for (const [id, { label, keys }] of [...owners].sort(
-    ([a], [b]) => a.localeCompare(b)
-  )) {
-    if (keys.size < GLOSS_PROMOTION_LIMIT) continue;
-    const glyph = id.split("\0")[0] ?? "";
-    if (input.lintIgnore.matches("gloss-wants-promoting", glyph)) continue;
+  for (const [, group] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
+    if (group.sites.length < 2) continue;
+    if (group.sites.every((site) => site.tier === "local" && site.key === group.sites[0].key)) continue;
+    if (input.lintIgnore.matches("meaning-repeated", group.notation)) continue;
+    const shared = group.sites.find((site) => site.tier === "shared");
     out.push({
-      code: "gloss-wants-promoting",
+      code: "meaning-repeated",
       severity: "info",
-      glyph,
-      message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(", ")}); a meaning reused this widely wants promoting to a card`
+      glyph: group.notation,
+      count: group.sites.length,
+      message: `${group.notation} as ${JSON.stringify(group.label)} is defined ${group.sites.length} times: ${group.sites.map((site) => site.where).join("; ")}` + (shared ? ` \u2014 ${shared.key} is the shared card; bind it with [[${shared.key}]] (or \\explain{${shared.key}}{${group.notation}} in a formula) instead of declaring it again` : " \u2014 one shared card would serve every site; promote it and reference it")
     });
   }
 }
@@ -435,7 +482,8 @@ const CHECKS = [
   checkNotationUnits,
   checkWeakLocal,
   checkNotationSourceLocator,
-  checkGlossWantsPromoting,
+  checkDefinitionRepeated,
+  checkMeaningRepeated,
   checkCardWantsDemoting,
   checkGlossNameShape,
   checkOperatorExplained,
@@ -457,7 +505,8 @@ function consistencyCounts(diagnostics) {
     "units-vocab": 0,
     "weak-local": 0,
     "notation-source-locator": 0,
-    "gloss-wants-promoting": 0,
+    "definition-repeated": 0,
+    "meaning-repeated": 0,
     "card-wants-demoting": 0,
     "gloss-name-shape": 0,
     "operator-explained": 0,
@@ -473,5 +522,6 @@ function consistencyCounts(diagnostics) {
 }
 export {
   consistencyCounts,
+  glyphMatcher,
   runConsistencyChecks
 };

package/dist/reference/deck-remark.d.mts

@@ -0,0 +1,123 @@
+/**
+ * The deck a docs file is, or `undefined`. A lesson's: `{ scope: 'lesson',
+ * lessonSlug, lessonId, path, chapterPath }`, the chapter being the lesson's
+ * `.mdx` (or `.md`) beside it. A part's (`<part>/index.deck.mdx`): `{ scope:
+ * 'part', partDir, pageId, path }`, its page id `<part>.slides`.
+ */
+export function deckOfFile(file: any): {
+    scope: string;
+    path: string;
+    partDir: string;
+    pageId: string;
+} | {
+    chapterPath?: string | undefined;
+    scope: string;
+    path: string;
+    lessonSlug: string;
+    lessonId: string;
+    partDir?: undefined;
+    pageId?: undefined;
+} | undefined;
+/**
+ * The chapter file of a lesson of a part's deck's part (`motion/range` →
+ * `…/motion/range.mdx`, or `.md`), beside the deck, if there is one.
+ */
+export function partChapterPath(deck: any, lessonSlug: any): string | undefined;
+/**
+ * The chapter files whose scope a deck's symbols bind in, in order: a
+ * lesson's deck its chapter (none for a slides-first lesson); a part's deck
+ * every chapter of its part, in reading order (`manifest.parts[].lessons`).
+ */
+export function deckScopeChapters(deck: any, manifest: any): any;
+/** A chapter file's frontmatter and body, read once per change of the file. */
+export function readChapter(chapterPath: any): any;
+/**
+ * The manifest's deck for a deck file (`deckOfFile`) — a lesson's or a
+ * part's — or, given a lesson id, for that lesson, if there is one.
+ */
+export function manifestDeckOf(manifest: any, owner: any): any;
+/**
+ * Replace each `<Recall ref="eq-…" />` (or `fig-`, `tab-`, `dia-`) with the
+ * chapter's own float, parsed from the chapter with this page's parser.
+ * A recalled equation's math node and a recalled float's element carry
+ * `data.explicoRecall = { prefix, key, number, href }`; the imports a
+ * recalled float's components need are added to the deck's own.
+ */
+/**
+ * What MDX's compile does to a tree before any course plugin sees it: a
+ * paragraph holding only JSX (and white space) becomes that JSX, as flow.
+ * An inline SVG's `<text x="…">0</text>` line parses as such a paragraph;
+ * kept, it would put a `<p>` inside the `<svg>`. `processor.parse` stops
+ * short of that step, so a chapter read for a recall takes it here
+ * (`remark-mark-and-unravel` in `@mdx-js/mdx`).
+ */
+export function unravelJsxParagraphs(tree: any): any;
+export function expandRecalls(tree: any, { processor, deck, deckEntry, manifest, base, fail }: {
+    processor: any;
+    deck: any;
+    deckEntry: any;
+    manifest: any;
+    base: any;
+    fail: any;
+}): void;
+/**
+ * The deck page's equations and floats, in its reading order, and what each
+ * shows: a recalled one the chapter's number, a labelled equation of the
+ * deck its own (1), (2) in label order (`manifest.decks[].equations`), and
+ * the deck's own floats no number.
+ */
+export function collectDeckFloats(tree: any, deckEntry: any): {
+    equations: Map<any, any>;
+    floats: Map<any, any>;
+};
+/**
+ * Give the deck's `##` and `###` headings the anchors and frame numbers the
+ * manifest decided, in order; a different count fails the build (a stale
+ * manifest), as a chapter's headings do.
+ */
+export function stampDeckHeadings(tree: any, deckEntry: any, fail: any): void;
+/**
+ * On a part's deck, give each `<AssessmentSet>` the lesson whose checks it
+ * asks (`lesson`, the component's prop): the chapter its frame's section
+ * covers (`frames[].chapter`). A frame in no such section asks none, which
+ * the manifest reports as `deck-check-no-chapter`.
+ */
+export function markDeckChecks(tree: any, deckEntry: any, fail: any): void;
+/**
+ * The generated title frame: the deck's title, its course, its authors and
+ * the version its content is at (rules D10 and C5), in the words of a
+ * chapter's PDF (`versionPhrase` in compiler/page-versions.ts).
+ */
+export function titleFrameNode(manifest: any, deckEntry: any): {
+    type: string;
+    data: {
+        hName: any;
+        hProperties: any;
+    };
+    children: any[];
+};
+/**
+ * The competencies a deck's outcomes frame lists: its lesson's, or on a
+ * part's deck every covered chapter's, in reading order, each once.
+ */
+export function deckTeaches(manifest: any, deckEntry: any): any;
+/** The generated outcomes frame: what the lesson's competencies say a student can now do. */
+export function outcomesFrameNode(manifest: any, deckEntry: any, lesson: any): {
+    type: string;
+    data: {
+        hName: any;
+        hProperties: any;
+    };
+    children: any[];
+} | undefined;
+/**
+ * After notation ran: give each `###` frame its legend line — the symbols it
+ * shows for the first time in the deck (`first-use`), or all it shows
+ * (`every-frame`) — as math the page's KaTeX pass renders, each symbol bound
+ * to its card. `resolved` is the page's resolved notation (`key → entry`).
+ */
+export function insertLegends(tree: any, { resolved, mode }: {
+    resolved: any;
+    mode: any;
+}): void;
+export const DECK_CAPTION_PATTERN: RegExp;