explico 0.4.0 → 0.5.0

package/dist/compiler/manifest.d.ts

@@ -3,10 +3,14 @@ import { ConsistencyDiagnostic } from '../reference/consistency.js';
 import { EquationLabelRecord, EquationDiagnostic } from '../reference/equations-validate.js';
 import { TableLabelRecord, TableDiagnostic } from '../reference/tables-validate.js';
 import { FigureLabelRecord, FigureDiagnostic } from '../reference/figures-validate.js';
+import { DiagramLabelRecord, DiagramDiagnostic } from '../reference/diagrams-validate.js';
+import { KnowledgeCheckLabelRecord, KnowledgeCheckDiagnostic } from '../reference/knowledge-checks-validate.js';
+import { RawFloatDiagnostic } from '../reference/raw-floats-validate.js';
 import { MathGateDiagnostic } from '../reference/gate-math.js';
+import { ContentSegment } from '../reference/mixed-content.js';
 import { GlyphScopeEntry } from '../reference/gloss.js';
 import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus, NotationGlossEntry } from '../reference/types.js';
-import { CourseConfig } from './course-config.js';
+import { NormalizedLessonExports, CourseConfig } from './course-config.js';
 import { KnowledgeVersionDiagnostic } from './knowledge-version.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
@@ -51,7 +55,7 @@ import '../reference/keyed-float-validate.js';
  * `lessons[].equations`, and `diagnostics.equations`.
  * v4 (F-tables-figures): `tables`/`figures` (same shape as `equations`, for
  * `<Table>`/`<Figure>`), `lessons[].tables`/`lessons[].figures`, and
- * `diagnostics.tables`/`diagnostics.figures`.
+ * `diagnostics.tables`/`diagnostics.figures`/`diagnostics.diagrams`.
  * v5 (about): `about` (engine identity from `explico`'s `package.json`, the
  * course's reader-facing `about` block, and the knowledge version resolved
  * against `content/CHANGELOG.md`) and `diagnostics.knowledge`.
@@ -61,8 +65,33 @@ import '../reference/keyed-float-validate.js';
  * now the number before the dot), `lessons[].chapter` redefined as the
  * lesson's ordinal *within its part*, and `lessons[].numbering` — the
  * per-kind offsets that make `n` run continuously across a part.
+ * v8 (assessment math): `assessmentContent` — every assessment item's
+ * `prompt` / `explanation`, pre-split into text/math segments and resolved
+ * against the scope of the lesson that embeds it, so `AssessmentSet.astro`
+ * can render them through the same KaTeX pipeline as lesson body math instead
+ * of showing raw text.
+ * v9 (diagram identity): `diagrams` (the independent `<Diagram>` number and
+ * cross-page lookup), `lessons[].diagrams`, `lessons[].numbering.diagrams`,
+ * and `diagnostics.diagrams`.
+ * v10 (knowledge-check identity): `checks` (part-wide numbering and cross-page
+ * lookup), `lessons[].knowledgeChecks`, `lessons[].numbering.checks`, and
+ * `diagnostics.checks`.
+ * v11 (lesson exports): normalized standalone HTML and print build/UI settings.
+ * v12 (abbreviation hover cards): `manifest.abbreviations` — the
+ * `abbreviations` content collection (N14), flattened to plain
+ * `{key, abbr, expansion, aliases, domain?}` records sorted by key, the way
+ * `manifest.notation.raw` already carries notation frontmatter for
+ * `remarkNotation`. `remarkAbbreviations` reads it to wrap the first
+ * occurrence of a known abbreviation in a lesson's prose with a hover/click
+ * card.
+ * v13 (raw-float diagnostics, additive): `diagnostics.rawFloats` — a raw
+ * Markdown table, a raw HTML `<table>`, or an Explico `<Diagram>` that is
+ * unkeyed or nested outside `<Table>`/`<Figure>` never reaches keyed-float
+ * validation and can never get a stable number or `[[…]]` reference; this
+ * flags it (warning-only — the manifest shape a client already reads is
+ * unchanged).
  */
-declare const MANIFEST_SCHEMA_VERSION = 7;
+declare const MANIFEST_SCHEMA_VERSION = 13;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -114,8 +143,9 @@ interface ManifestLesson {
     /**
      * The 1-based ordinal of the **part** this lesson sits in — its sidebar
      * group's position in `courseConfig.parts`. It is the number before the dot
-     * in every equation, table, and figure number on the page: `(2.1)` is the
-     * first equation of part 2. See `docs/authoring/structure.md`.
+     * in every equation, table, figure, diagram, and knowledge-check number on
+     * the page: `(2.1)` is the first equation of part 2. See
+     * `docs/authoring/structure.md`.
      */
     readonly part: number;
     /**
@@ -133,6 +163,8 @@ interface ManifestLesson {
         readonly equations: number;
         readonly tables: number;
         readonly figures: number;
+        readonly diagrams: number;
+        readonly checks: number;
     };
     readonly file: string;
     readonly title: string;
@@ -143,6 +175,11 @@ interface ManifestLesson {
     readonly requires: readonly string[];
     readonly assumptions: readonly string[];
     readonly assessments: readonly string[];
+    /** Numbered knowledge checks from `assessments`, in `.checks.yml` order. */
+    readonly knowledgeChecks: readonly {
+        readonly key: string;
+        readonly number: string;
+    }[];
     readonly sources: readonly string[];
     readonly citations: readonly ManifestCitation[];
     /** Competency prerequisite edges this lesson introduces. */
@@ -162,6 +199,11 @@ interface ManifestLesson {
         readonly key: string;
         readonly number: string;
     }[];
+    /** Keyed `<Diagram>` elements in appearance order. */
+    readonly diagrams: readonly {
+        readonly key: string;
+        readonly number: string;
+    }[];
     readonly notation: {
         readonly bindings: readonly {
             readonly key: string;
@@ -202,8 +244,18 @@ interface ManifestAbout {
     readonly disclaimer: string;
     readonly changelogHref?: string;
 }
+/** One assessment item's pre-rendered `prompt` / `explanation` (v8). */
+interface ManifestAssessmentItemContent {
+    readonly lessonId: string;
+    readonly assessmentId: string;
+    readonly itemId: string;
+    readonly promptSegments: readonly ContentSegment[];
+    readonly explanationSegments: readonly ContentSegment[];
+}
 interface Manifest {
     readonly schemaVersion: number;
+    /** Normalized build/UI settings for opt-in per-lesson exports. */
+    readonly lessonExports: NormalizedLessonExports;
     /** Reader-facing identity + versions (the `[?]` About panel). */
     readonly about: ManifestAbout;
     readonly notation: {
@@ -217,6 +269,8 @@ interface Manifest {
     readonly competencies: readonly Record<string, unknown>[];
     readonly sources: readonly Record<string, unknown>[];
     readonly tracks: readonly Record<string, unknown>[];
+    /** Abbreviations table (N14), for `remarkAbbreviations`. Ordered by key. */
+    readonly abbreviations: readonly Record<string, unknown>[];
     readonly sidebar: readonly SidebarGroup[];
     readonly lessons: readonly ManifestLesson[];
     /** Full competency prerequisite graph. */
@@ -237,6 +291,26 @@ interface Manifest {
         readonly labels: readonly FigureLabelRecord[];
         readonly numbersBySlug: Record<string, Record<string, string>>;
     };
+    /** Keyed-float identity for `<Diagram>` — independent of figure numbering. */
+    readonly diagrams: {
+        readonly labels: readonly DiagramLabelRecord[];
+        readonly numbersBySlug: Record<string, Record<string, string>>;
+    };
+    /** Knowledge-check identity, derived from each lesson's `.checks.yml`. */
+    readonly checks: {
+        readonly labels: readonly KnowledgeCheckLabelRecord[];
+        readonly numbersBySlug: Record<string, Record<string, string>>;
+    };
+    /**
+     * Every assessment item's `prompt` / `explanation`, pre-split into
+     * text/math segments (v8). `AssessmentSet.astro` filters this by
+     * `lessonId` + `assessmentId` and renders each `math` segment's `latex`
+     * through `renderNotationMath` before handing the result to
+     * `AssessmentRunner`. An assessment embedded in more than one lesson (via
+     * more than one `checks.yml`) appears once per lesson here, since each
+     * lesson's scope can resolve its glyphs differently.
+     */
+    readonly assessmentContent: readonly ManifestAssessmentItemContent[];
     readonly diagnostics: {
         readonly curriculum: readonly CurriculumIssue[];
         readonly notation: readonly NotationDiagnostic[];
@@ -252,6 +326,16 @@ interface Manifest {
         readonly tables: readonly TableDiagnostic[];
         /** `<Figure>` identity checks (F-tables-figures) — same codes, `fig-` prefixed. */
         readonly figures: readonly FigureDiagnostic[];
+        /** `<Diagram>` identity checks — same codes, `dia-` prefixed. */
+        readonly diagrams: readonly DiagramDiagnostic[];
+        /** Knowledge-check identity and `[[check-…]]` reference checks. */
+        readonly checks: readonly KnowledgeCheckDiagnostic[];
+        /**
+         * A raw Markdown table, a raw HTML `<table>`, or an Explico `<Diagram>`
+         * that is unkeyed or nested outside `<Table>`/`<Figure>` — invisible to
+         * keyed-float validation above. Warnings only.
+         */
+        readonly rawFloats: readonly RawFloatDiagnostic[];
     };
     readonly hashes: {
         /** `sha256` of every content source file, keyed by repo-relative path. */
@@ -280,4 +364,4 @@ declare function readManifestSync(): Manifest;
  */
 declare function loadManifest(courseConfig?: CourseConfig): Promise<Manifest>;
 
-export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestCitation, type ManifestLesson, type ManifestLessonNotation, type ManifestNotationResolution, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };
+export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestAssessmentItemContent, type ManifestCitation, type ManifestLesson, type ManifestLessonNotation, type ManifestNotationResolution, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };

package/dist/compiler/manifest.js

@@ -28,17 +28,39 @@ import {
   validateFigures
 } from "../reference/figures-validate.js";
 import {
-  gateContentMath
+  validateDiagrams
+} from "../reference/diagrams-validate.js";
+import {
+  validateKnowledgeChecks
+} from "../reference/knowledge-checks-validate.js";
+import {
+  validateRawFloats
+} from "../reference/raw-floats-validate.js";
+import {
+  gateContentMath,
+  pageScope
 } from "../reference/gate-math.js";
+import {
+  gateProseNotation,
+  gateProseNotationInAssessments
+} from "../reference/gate-prose-notation.js";
+import { gateAbbreviations } from "../reference/gate-abbreviations.js";
+import {
+  splitMixedContent
+} from "../reference/mixed-content.js";
 import { loadLintIgnore } from "../reference/lint-ignore.js";
 import { buildNotationRegistry } from "../reference/registry.js";
 import { formulaGlyphScope } from "../reference/gloss.js";
 import { resolveReferenceId } from "../reference/references.js";
-import { coursePartsOf } from "./course-config.js";
+import {
+  coursePartsOf,
+  normalizeLessonExports
+} from "./course-config.js";
 import {
   resolveKnowledgeVersion
 } from "./knowledge-version.js";
 import {
+  loadAbbreviationRegistryInput,
   loadCurriculumCatalog,
   loadNotationDefinitions,
   loadNotationRegistryInput,
@@ -51,7 +73,7 @@ import {
   isLessonSlug,
   lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 7;
+const MANIFEST_SCHEMA_VERSION = 13;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");
@@ -184,9 +206,10 @@ async function compileManifest(courseConfig) {
       "course.config.ts is missing a complete `about` block (required since explico 0.3.0): `about: { version, authors: [{ name }], disclaimer, materialName?, summary?, changelogHref? }`. See docs/authoring/migrating.md (\xA7 0.2.x \u2192 0.3.0) in the installed package."
     );
   }
-  const [catalog, notationInput] = await Promise.all([
+  const [catalog, notationInput, abbreviationsInput] = await Promise.all([
     loadCurriculumCatalog(),
-    loadNotationRegistryInput()
+    loadNotationRegistryInput(),
+    loadAbbreviationRegistryInput()
   ]);
   const registry = buildNotationRegistry(notationInput);
   const cardsByKey = new Map(
@@ -202,16 +225,53 @@ async function compileManifest(courseConfig) {
   const bundlesByLesson = new Map(
     registry.bundles.map((bundle) => [bundle.lessonId, bundle])
   );
+  const assessmentsInput = catalog.assessments;
   const curriculumIssues = validateCurriculum(catalog);
   const alignmentIssues = validateNotationAlignment(registry, catalog);
-  const mathIssues = gateContentMath({
-    notationInput,
-    assessments: catalog.assessments,
-    lessonAssessments: catalog.lessons.map((lesson) => ({
-      lessonId: lesson.id,
-      assessmentIds: lesson.assessments
-    }))
-  });
+  const mathIssues = [
+    ...gateContentMath({
+      notationInput,
+      assessments: assessmentsInput,
+      lessonAssessments: catalog.lessons.map((lesson) => ({
+        lessonId: lesson.id,
+        assessmentIds: lesson.assessments
+      }))
+    }),
+    ...gateProseNotation(notationInput.lessons),
+    ...gateProseNotationInAssessments(assessmentsInput),
+    ...gateAbbreviations({
+      notationInput,
+      abbreviations: abbreviationsInput,
+      courseAbbreviations: courseConfig.abbreviations
+    })
+  ];
+  const notationLessonById = new Map(
+    notationInput.lessons.map((lesson) => [lesson.lessonId, lesson])
+  );
+  const assessmentInputById = new Map(
+    assessmentsInput.map((assessment) => [assessment.id, assessment])
+  );
+  const assessmentContent = [];
+  for (const lesson of catalog.lessons) {
+    if (lesson.assessments.length === 0) continue;
+    const lessonInput = notationLessonById.get(lesson.id);
+    if (!lessonInput) continue;
+    const scope = pageScope(lessonInput, cardsByKey);
+    for (const assessmentId of lesson.assessments) {
+      const assessment = assessmentInputById.get(assessmentId);
+      if (!assessment?.items) continue;
+      for (const item of assessment.items) {
+        if (!item.id) continue;
+        assessmentContent.push({
+          lessonId: lesson.id,
+          assessmentId,
+          itemId: item.id,
+          promptSegments: splitMixedContent(item.prompt ?? "", scope),
+          explanationSegments: splitMixedContent(item.explanation ?? "", scope)
+        });
+      }
+    }
+  }
   const prerequisitesById = new Map(
     catalog.competencies.map((competency) => [
       competency.id,
@@ -245,7 +305,13 @@ async function compileManifest(courseConfig) {
     const lessonIds = group.items.filter((item) => typeof item === "string").map(lessonIdFromSlug);
     if (lessonIds.length === 0) continue;
     partCursor += 1;
-    const used = { equations: 0, tables: 0, figures: 0 };
+    const used = {
+      equations: 0,
+      tables: 0,
+      figures: 0,
+      diagrams: 0,
+      checks: 0
+    };
     let chapterCursor = 0;
     for (const lessonId of lessonIds) {
       const body = bodyByLessonId.get(lessonId) ?? "";
@@ -257,6 +323,8 @@ async function compileManifest(courseConfig) {
       used.equations += countDisplayEquations(body);
       used.tables += countKeyedJsxFloats(body, { tagName: "Table" });
       used.figures += countKeyedJsxFloats(body, { tagName: "Figure" });
+      used.diagrams += countKeyedJsxFloats(body, { tagName: "Diagram" });
+      used.checks += lessonMetaById.get(lessonId)?.assessments.length ?? 0;
     }
   }
   const floatInputs = (kind) => notationInput.lessons.map((lesson) => {
@@ -295,6 +363,45 @@ async function compileManifest(courseConfig) {
       Object.entries(table).map(([key, number]) => ({ key, number }))
     ])
   );
+  const diagramValidation = validateDiagrams(floatInputs("diagrams"));
+  const diagramsBySlug = new Map(
+    Object.entries(diagramValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number }))
+    ])
+  );
+  const checkValidation = validateKnowledgeChecks(
+    notationInput.lessons.map((lesson) => {
+      const placement = placementByLessonId.get(lesson.lessonId);
+      return {
+        lessonId: lesson.lessonId,
+        slug: lesson.lessonId.replace(/\./g, "/"),
+        file: lesson.source.file,
+        body: lesson.body,
+        assessmentIds: lessonMetaById.get(lesson.lessonId)?.assessments ?? [],
+        ...placement ? {
+          numbering: {
+            prefix: placement.part,
+            offset: placement.numbering.checks
+          }
+        } : {}
+      };
+    })
+  );
+  const checksBySlug = new Map(
+    Object.entries(checkValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number }))
+    ])
+  );
+  const rawFloatDiagnostics = validateRawFloats(
+    notationInput.lessons.map((lesson) => ({
+      lessonId: lesson.lessonId,
+      slug: lesson.lessonId.replace(/\./g, "/"),
+      file: lesson.source.file,
+      body: lesson.body
+    }))
+  );
   const lessons = [];
   for (const notationLesson of notationInput.lessons) {
     const id = notationLesson.lessonId;
@@ -316,7 +423,9 @@ async function compileManifest(courseConfig) {
       numbering: placementByLessonId.get(id)?.numbering ?? {
         equations: 0,
         tables: 0,
-        figures: 0
+        figures: 0,
+        diagrams: 0,
+        checks: 0
       },
       file: notationLesson.source.file,
       title: frontmatter.title,
@@ -326,11 +435,13 @@ async function compileManifest(courseConfig) {
       requires: [...meta.requires],
       assumptions: [...meta.assumptions],
       assessments: [...meta.assessments],
+      knowledgeChecks: checksBySlug.get(id.replace(/\./g, "/")) ?? [],
       sources: deriveSources(notationLesson.body),
       citations: lessonCitations(notationLesson.body),
       equations: equationsBySlug.get(id.replace(/\./g, "/")) ?? [],
       tables: tablesBySlug.get(id.replace(/\./g, "/")) ?? [],
       figures: figuresBySlug.get(id.replace(/\./g, "/")) ?? [],
+      diagrams: diagramsBySlug.get(id.replace(/\./g, "/")) ?? [],
       prereqEdges: sortEdges(
         teaches.flatMap(
           (to) => (prerequisitesById.get(to) ?? []).filter((from) => !teaches.includes(from)).map((from) => ({ from, to }))
@@ -356,7 +467,8 @@ async function compileManifest(courseConfig) {
     catalog,
     lintIgnore: loadLintIgnore(),
     conventions: courseConfig.conventions,
-    ...courseConfig.operators === void 0 ? {} : { operators: courseConfig.operators }
+    ...courseConfig.operators === void 0 ? {} : { operators: courseConfig.operators },
+    ...courseConfig.romanLabels === void 0 ? {} : { romanLabels: courseConfig.romanLabels }
   });
   const rawNotation = [...loadNotationDefinitions()].sort(
     (a, b) => String(a.key).localeCompare(String(b.key))
@@ -364,6 +476,13 @@ async function compileManifest(courseConfig) {
   const competencies = catalog.competencies.map((entry) => ({ ...entry })).sort(byId);
   const sources = [...loadSourceRecords()].sort(byId);
   const tracks = catalog.tracks.map((entry) => ({ ...entry })).sort(byId);
+  const abbreviations = abbreviationsInput.map((entry) => ({
+    key: entry.key,
+    abbr: entry.abbr,
+    expansion: entry.expansion,
+    aliases: entry.aliases,
+    ...entry.domain === void 0 ? {} : { domain: entry.domain }
+  })).sort((a, b) => a.key.localeCompare(b.key));
   const hashes = contentHashes();
   const knowledgeChangelogPath = join(CONTENT_ROOT, "CHANGELOG.md");
   const knowledge = resolveKnowledgeVersion({
@@ -397,6 +516,7 @@ async function compileManifest(courseConfig) {
   };
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
+    lessonExports: normalizeLessonExports(courseConfig),
     about,
     notation: {
       definitions: registry.definitions,
@@ -408,6 +528,7 @@ async function compileManifest(courseConfig) {
     competencies,
     sources,
     tracks,
+    abbreviations,
     sidebar,
     lessons,
     prereqEdges,
@@ -423,6 +544,15 @@ async function compileManifest(courseConfig) {
       labels: figureValidation.labels,
       numbersBySlug: figureValidation.numbersBySlug
     },
+    diagrams: {
+      labels: diagramValidation.labels,
+      numbersBySlug: diagramValidation.numbersBySlug
+    },
+    checks: {
+      labels: checkValidation.labels,
+      numbersBySlug: checkValidation.numbersBySlug
+    },
+    assessmentContent,
     diagnostics: {
       curriculum: curriculumIssues,
       notation: registry.diagnostics,
@@ -432,7 +562,10 @@ async function compileManifest(courseConfig) {
       equations: equationValidation.diagnostics,
       tables: tableValidation.diagnostics,
       figures: figureValidation.diagnostics,
-      knowledge: knowledge.diagnostics
+      diagrams: diagramValidation.diagnostics,
+      checks: checkValidation.diagnostics,
+      knowledge: knowledge.diagnostics,
+      rawFloats: rawFloatDiagnostics
     },
     hashes
   };

package/dist/compiler/resolution-report.d.ts

@@ -9,7 +9,11 @@ import '../reference/equations-validate.js';
 import '../reference/tables-validate.js';
 import '../reference/keyed-float-validate.js';
 import '../reference/figures-validate.js';
+import '../reference/diagrams-validate.js';
+import '../reference/knowledge-checks-validate.js';
+import '../reference/raw-floats-validate.js';
 import '../reference/gate-math.js';
+import '../reference/mixed-content.js';
 import '../reference/gloss.js';
 import './knowledge-version.js';
 import './lesson-derivation.js';

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

@@ -0,0 +1,30 @@
+/**
+ * The abbreviations a course treats as common, given its `course.config.ts`
+ * `abbreviations` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} abbreviations
+ * @returns {Set<string>}
+ */
+export function effectiveAbbreviationAllowlist(abbreviations: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+} | undefined): Set<string>;
+/** True when `token` needs no abbreviations-table entry for this course. */
+export function isBaseAbbreviation(token: any, abbreviations: any): boolean;
+/**
+ * The base abbreviation baseline: acronyms and dotted abbreviations every
+ * reader is assumed to know, so a lesson never has to introduce them with an
+ * abbreviations-table entry. The `\operatorname{…}` / `\mathrm{…}` twins are
+ * `base-operators.mjs` (rule N8) / `base-roman-labels.mjs` (rule N10); this is
+ * the plain-prose equivalent for rule N14.
+ *
+ * Kept intentionally small, same rationale as `BASE_ROMAN_LABELS`: a
+ * course-specific acronym (`OLS`, `SSR`, `MSE`) is exactly the thing a reader
+ * benefits from having spelled out, so it belongs in the course's own
+ * `content/abbreviations/*.md` table, not here. This baseline only holds
+ * abbreviations so common in ordinary English/academic writing that spelling
+ * them out on every course would be noise, not help. A course adds a real
+ * one via `abbreviations.allow` in `course.config.ts`, the same shape as
+ * `operators.allow` / `romanLabels.allow`.
+ */
+export const BASE_ABBREVIATIONS: Readonly<Set<string>>;

package/dist/reference/base-abbreviations.mjs

@@ -0,0 +1,60 @@
+/**
+ * The base abbreviation baseline: acronyms and dotted abbreviations every
+ * reader is assumed to know, so a lesson never has to introduce them with an
+ * abbreviations-table entry. The `\operatorname{…}` / `\mathrm{…}` twins are
+ * `base-operators.mjs` (rule N8) / `base-roman-labels.mjs` (rule N10); this is
+ * the plain-prose equivalent for rule N14.
+ *
+ * Kept intentionally small, same rationale as `BASE_ROMAN_LABELS`: a
+ * course-specific acronym (`OLS`, `SSR`, `MSE`) is exactly the thing a reader
+ * benefits from having spelled out, so it belongs in the course's own
+ * `content/abbreviations/*.md` table, not here. This baseline only holds
+ * abbreviations so common in ordinary English/academic writing that spelling
+ * them out on every course would be noise, not help. A course adds a real
+ * one via `abbreviations.allow` in `course.config.ts`, the same shape as
+ * `operators.allow` / `romanLabels.allow`.
+ */
+export const BASE_ABBREVIATIONS = Object.freeze(
+  new Set([
+    // dotted Latin/English abbreviations
+    'e.g.',
+    'i.e.',
+    'etc.',
+    'cf.',
+    'vs.',
+    'a.m.',
+    'p.m.',
+    'a.k.a.',
+    'et al.',
+    // generic acronyms with no domain-specific meaning in this engine
+    'AI',
+    'ID',
+    'OK',
+    'URL',
+    'FAQ',
+    'US',
+    'UK',
+    'EU',
+  ]),
+);
+
+/**
+ * The abbreviations a course treats as common, given its `course.config.ts`
+ * `abbreviations` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} abbreviations
+ * @returns {Set<string>}
+ */
+export function effectiveAbbreviationAllowlist(abbreviations) {
+  const allow = abbreviations?.allow ?? [];
+  const deny = new Set(abbreviations?.deny ?? []);
+  const effective = new Set(BASE_ABBREVIATIONS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `token` needs no abbreviations-table entry for this course. */
+export function isBaseAbbreviation(token, abbreviations) {
+  return effectiveAbbreviationAllowlist(abbreviations).has(token);
+}

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

@@ -36,3 +36,18 @@ export function isBaseOperator(name: any, operators: any): boolean;
  * Matching is case-sensitive.
  */
 export const BASE_OPERATORS: Readonly<Set<string>>;
+/**
+ * The subset of {@link BASE_OPERATORS} that must never appear with a bare
+ * (unparenthesized) argument: every trigonometric, inverse-trigonometric, and
+ * hyperbolic function, plus the exponential and logarithms (N13). `\sin x`
+ * leaves how far the argument extends ambiguous the moment anything follows
+ * it (`\sin x + 1` — is the `+1` inside or outside the sine?); `\sin(x)`
+ * never does, even for a single-symbol argument. Kept separate from
+ * `BASE_OPERATORS`: this is a formatting rule layered on top of the "does it
+ * need a notation card" question that set answers, so an operator can be
+ * universal (N8) and still owe a parenthesized argument. Enforced by
+ * `resolveMathGlyphs` in `math-glyphs.mjs`, which every rendered-math context
+ * (lesson body, notation `formula`, assessments, `Diagram` nodes, lab math)
+ * already calls.
+ */
+export const PARENTHESIZED_FUNCTIONS: Readonly<Set<string>>;

package/dist/reference/base-operators.mjs

@@ -81,6 +81,46 @@ export const BASE_OPERATORS = Object.freeze(
   ]),
 );
 
+/**
+ * The subset of {@link BASE_OPERATORS} that must never appear with a bare
+ * (unparenthesized) argument: every trigonometric, inverse-trigonometric, and
+ * hyperbolic function, plus the exponential and logarithms (N13). `\sin x`
+ * leaves how far the argument extends ambiguous the moment anything follows
+ * it (`\sin x + 1` — is the `+1` inside or outside the sine?); `\sin(x)`
+ * never does, even for a single-symbol argument. Kept separate from
+ * `BASE_OPERATORS`: this is a formatting rule layered on top of the "does it
+ * need a notation card" question that set answers, so an operator can be
+ * universal (N8) and still owe a parenthesized argument. Enforced by
+ * `resolveMathGlyphs` in `math-glyphs.mjs`, which every rendered-math context
+ * (lesson body, notation `formula`, assessments, `Diagram` nodes, lab math)
+ * already calls.
+ */
+export const PARENTHESIZED_FUNCTIONS = Object.freeze(
+  new Set([
+    // exponential / logarithms
+    'exp',
+    'log',
+    'ln',
+    'lg',
+    // trigonometric
+    'sin',
+    'cos',
+    'tan',
+    'cot',
+    'sec',
+    'csc',
+    // inverse trigonometric
+    'arcsin',
+    'arccos',
+    'arctan',
+    // hyperbolic
+    'sinh',
+    'cosh',
+    'tanh',
+    'coth',
+  ]),
+);
+
 /**
  * The operators a course treats as common, given its `course.config.ts`
  * `operators` block: the shipped baseline, plus `allow`, minus `deny`.

package/dist/reference/base-roman-labels.d.mts

@@ -0,0 +1,35 @@
+/**
+ * The roman labels a course treats as common, given its `course.config.ts`
+ * `romanLabels` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} romanLabels
+ * @returns {Set<string>}
+ */
+export function effectiveRomanLabelAllowlist(romanLabels: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+} | undefined): Set<string>;
+/** True when `name` needs no notation entry for this course. */
+export function isBaseRomanLabel(name: any, romanLabels: any): boolean;
+/**
+ * The base roman-label baseline: `\mathrm{…}` multi-letter labels every
+ * reader is assumed to know, so a lesson never has to introduce them with a
+ * notation entry. The `\operatorname{…}` counterpart is `base-operators.mjs`
+ * (rule N8); this is its `\mathrm{…}` twin (rule N10).
+ *
+ * Rationale: the completeness gate has no opinion about `\mathrm{…}` bodies —
+ * they are a typographic label to KaTeX, not a bindable symbol, and N3
+ * requires the format without asking whether the label is ever explained.
+ * The `roman-label-explained` consistency check fills that gap: a label a
+ * lesson uses is either on this list (or the course's additions to it) or it
+ * carries a notation entry the reader can hover.
+ *
+ * Kept intentionally small — unlike `sin`/`exp`, an upright label is almost
+ * always a course-specific named quantity (`KE`, `PV`, `Var`-as-a-label) that
+ * genuinely benefits from a hover card, so the shipped baseline holds only
+ * the qualifiers that function like an operator's extremum subscript
+ * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. A course
+ * adds a real one via `romanLabels.allow` in `course.config.ts`, the same
+ * shape as `operators.allow`.
+ */
+export const BASE_ROMAN_LABELS: Readonly<Set<string>>;