explico 0.4.0 → 0.5.0

package/src/compiler/course-config.ts

@@ -49,6 +49,39 @@ export interface CourseOperators {
   readonly deny?: readonly string[];
 }
 
+/**
+ * A course's edits to the shipped roman-label baseline (`BASE_ROMAN_LABELS`),
+ * consumed by the `roman-label-explained` consistency check (rule N10). A
+ * `\mathrm{…}` multi-letter label a lesson uses is fine when it is on the
+ * baseline plus `allow` minus `deny`; otherwise it needs a notation entry the
+ * reader can hover. Same shape as {@link CourseOperators}, one level down:
+ * this governs `\mathrm{KE}`-style labels, not `\operatorname{Var}`-style
+ * operators.
+ */
+export interface CourseRomanLabels {
+  /** Labels this course also treats as universal qualifiers (`eff`, `net`, …). */
+  readonly allow?: readonly string[];
+  /** Baseline labels this course wants explained anyway. */
+  readonly deny?: readonly string[];
+}
+
+/**
+ * A course's edits to the shipped abbreviation baseline (`BASE_ABBREVIATIONS`),
+ * consumed by the `abbreviation-explained` gate (rule N14). An abbreviation-
+ * shaped token — an all-caps acronym or a dotted form like `w.r.t.` — a
+ * lesson uses in prose is fine when it is on the baseline plus `allow` minus
+ * `deny`; otherwise it needs an entry in the `abbreviations` content
+ * collection, or — if it also names a math quantity — a notation entry the
+ * reader can hover. Same shape as {@link CourseOperators} / {@link
+ * CourseRomanLabels}.
+ */
+export interface CourseAbbreviations {
+  /** Abbreviations this course also treats as universal (`GDP`, `CPU`, …). */
+  readonly allow?: readonly string[];
+  /** Baseline abbreviations this course wants explained anyway. */
+  readonly deny?: readonly string[];
+}
+
 /** One person or team credited for the study material. */
 export interface CourseAuthor {
   readonly name: string;
@@ -83,6 +116,26 @@ export interface CourseAbout {
   readonly changelogHref?: string;
 }
 
+/** Optional, build-time lesson artifacts exposed to readers. */
+export interface LessonExportsConfig {
+  /** Emit one self-contained, offline-capable HTML file per lesson. */
+  readonly standaloneHtml?: boolean;
+  /** Offer the browser's native print dialog with explico's lesson print layout. */
+  readonly print?: boolean;
+  /**
+   * Published course root used for links that intentionally leave the exported
+   * lesson. Required at export time when such a link is present.
+   */
+  readonly canonicalBaseUrl?: string;
+}
+
+/** The stable, non-optional export settings carried by the manifest. */
+export interface NormalizedLessonExports {
+  readonly standaloneHtml: boolean;
+  readonly print: boolean;
+  readonly canonicalBaseUrl?: string;
+}
+
 export interface CourseConfig {
   readonly title: string;
   readonly description: string;
@@ -103,6 +156,45 @@ export interface CourseConfig {
   readonly about: CourseAbout;
   /** Edits to the shipped named-operator baseline (rule N8). Optional. */
   readonly operators?: CourseOperators;
+  /** Edits to the shipped roman-label baseline (rule N10). Optional. */
+  readonly romanLabels?: CourseRomanLabels;
+  /** Edits to the shipped abbreviation baseline (rule N14). Optional. */
+  readonly abbreviations?: CourseAbbreviations;
+  /** Per-lesson export actions and downloadable artifacts. Disabled when omitted. */
+  readonly lessonExports?: LessonExportsConfig;
+}
+
+/** Validate and canonicalize the build-facing lesson-export configuration. */
+export function normalizeLessonExports(
+  config: CourseConfig,
+): NormalizedLessonExports {
+  const standaloneHtml = config.lessonExports?.standaloneHtml === true;
+  const print = config.lessonExports?.print === true;
+  const rawBase = config.lessonExports?.canonicalBaseUrl;
+  if (rawBase === undefined) return { standaloneHtml, print };
+
+  let parsed: URL;
+  try {
+    parsed = new URL(rawBase);
+  } catch {
+    throw new Error(
+      `CourseConfig lessonExports.canonicalBaseUrl must be an absolute ` +
+        `http(s) URL; received ${JSON.stringify(rawBase)}.`,
+    );
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(
+      `CourseConfig lessonExports.canonicalBaseUrl must use http(s); ` +
+        `received ${JSON.stringify(rawBase)}.`,
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw new Error(
+      'CourseConfig lessonExports.canonicalBaseUrl cannot contain a query or fragment.',
+    );
+  }
+  if (!parsed.pathname.endsWith('/')) parsed.pathname += '/';
+  return { standaloneHtml, print, canonicalBaseUrl: parsed.toString() };
 }
 
 /**