explico 0.3.0 → 0.5.0

package/dist/compiler/astro.js

@@ -0,0 +1,258 @@
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import {
+  compileManifest,
+  writeManifest
+} from "./manifest.js";
+import { missingNotationPayloadKeys } from "../reference/page-notation.js";
+import { writeStandaloneLessonExports } from "./exports/standalone-html.js";
+const watchedServers = /* @__PURE__ */ new WeakSet();
+function normalizedBasePath(base) {
+  const segment = base.replace(/^\/+|\/+$/gu, "");
+  return segment ? `/${segment}/` : "/";
+}
+function matchStandaloneDownload(pathname, base, lessonSlugs) {
+  const prefix = `${normalizedBasePath(base)}downloads/`;
+  if (!pathname.startsWith(prefix) || !pathname.endsWith(".html")) return void 0;
+  const slug = pathname.slice(prefix.length, -".html".length);
+  return lessonSlugs.includes(slug) ? slug : void 0;
+}
+async function buildDevelopmentDownloads(config, lessonSlugs) {
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "explico-standalone-"));
+  const outputRoot = join(temporaryRoot, "dist");
+  try {
+    const projectRoot = fileURLToPath(config.root);
+    const astroEntry = fileURLToPath(import.meta.resolve("astro"));
+    const astroCli = resolve(dirname(astroEntry), "..", "bin", "astro.mjs");
+    await new Promise((resolveBuild, rejectBuild) => {
+      const child = spawn(
+        process.execPath,
+        [
+          astroCli,
+          "build",
+          "--root",
+          projectRoot,
+          "--outDir",
+          outputRoot,
+          "--silent"
+        ],
+        {
+          cwd: projectRoot,
+          env: { ...process.env, NODE_ENV: "production" },
+          stdio: ["ignore", "pipe", "pipe"]
+        }
+      );
+      let diagnostic = "";
+      const capture = (chunk) => {
+        if (diagnostic.length < 16e3) diagnostic += chunk.toString("utf8");
+      };
+      child.stdout.on("data", capture);
+      child.stderr.on("data", capture);
+      child.once("error", rejectBuild);
+      child.once("close", (code) => {
+        if (code === 0) {
+          resolveBuild();
+          return;
+        }
+        rejectBuild(
+          new Error(
+            `Astro's standalone development build exited with code ${code}.` + (diagnostic.trim() ? `
+${diagnostic.trim()}` : "")
+          )
+        );
+      });
+    });
+    return new Map(
+      await Promise.all(
+        lessonSlugs.map(async (slug) => [
+          slug,
+          await readFile(join(outputRoot, "downloads", `${slug}.html`))
+        ])
+      )
+    );
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+function assertLocalNotationParity(lessonId, authoredKeys, renderedKeys) {
+  const authored = [...new Set(authoredKeys)].sort();
+  const rendered = [...new Set(renderedKeys)].sort();
+  if (authored.length === rendered.length && authored.every((key, index) => key === rendered[index])) {
+    return;
+  }
+  throw new Error(
+    `Stale Explico manifest for ${lessonId}: lesson notation.local has [${authored.join(", ")}], but the page notation bundle has [${rendered.join(", ")}]. Pass courseConfig to loadManifest() and add explicoContentRefresh() to the Astro integrations.`
+  );
+}
+function assertNotationPayloadHtml(page, html) {
+  const missing = missingNotationPayloadKeys(html);
+  if (missing.length === 0) return;
+  throw new Error(
+    `Explico notation payload invariant failed for rendered page "${page}": ${missing.map((key) => `data-notation-key="${key}"`).join(", ")} ${missing.length === 1 ? "has" : "have"} no matching \`data-notation-entry\` popup definition. A nested Astro component that emits notation must register its formula dependencies; use Diagram, NotationFormula, or labMathScope(..., { locals: Astro.locals, context }).`
+  );
+}
+async function validateGeneratedNotationPayloads(directory) {
+  const root = fileURLToPath(directory);
+  const walk = async (path) => {
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) {
+        await walk(child);
+      } else if (entry.isFile() && entry.name.endsWith(".html")) {
+        assertNotationPayloadHtml(relative(root, child), await readFile(child, "utf8"));
+      }
+    }
+  };
+  await walk(root);
+}
+function replaceInPlace(target, source) {
+  if (Array.isArray(target) && Array.isArray(source)) {
+    target.splice(0, target.length, ...source);
+    return;
+  }
+  if (!target || !source || typeof target !== "object" || typeof source !== "object") {
+    return;
+  }
+  const mutable = target;
+  const fresh = source;
+  for (const key of Object.keys(mutable)) {
+    if (!(key in fresh)) delete mutable[key];
+  }
+  for (const [key, value] of Object.entries(fresh)) {
+    const current = mutable[key];
+    if (Array.isArray(current) && Array.isArray(value) || current && value && typeof current === "object" && typeof value === "object" && !Array.isArray(current) && !Array.isArray(value)) {
+      replaceInPlace(current, value);
+    } else {
+      mutable[key] = value;
+    }
+  }
+}
+function explicoContentRefresh(courseConfig, manifest) {
+  let developmentConfig;
+  return {
+    name: "explico-content-refresh",
+    hooks: {
+      "astro:config:setup": ({ command, config }) => {
+        if (command === "dev") {
+          developmentConfig = { root: config.root, base: config.base };
+        }
+      },
+      "astro:server:setup": ({ server, logger }) => {
+        if (watchedServers.has(server)) return;
+        watchedServers.add(server);
+        const contentRoot = `${resolve(process.cwd(), "content")}${sep}`;
+        let timer;
+        let restarting = false;
+        let developmentDownloads;
+        const developmentRoot = developmentConfig ? fileURLToPath(developmentConfig.root) : process.cwd();
+        const generatedDevelopmentRoots = [
+          ".astro",
+          "build",
+          "dist",
+          "node_modules"
+        ].map((directory) => `${resolve(developmentRoot, directory)}${sep}`);
+        const invalidateDevelopmentDownloads = (path) => {
+          const absolute = resolve(path);
+          if (generatedDevelopmentRoots.some((root) => absolute.startsWith(root))) {
+            return;
+          }
+          developmentDownloads = void 0;
+        };
+        const refresh = (path) => {
+          const absolute = resolve(path);
+          if (!absolute.startsWith(contentRoot) || restarting) return;
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(async () => {
+            restarting = true;
+            try {
+              const fresh = await compileManifest(courseConfig);
+              writeManifest(fresh);
+              replaceInPlace(manifest, fresh);
+              await server.restart();
+            } catch (error) {
+              server.config.logger.error(
+                `Explico could not refresh the content manifest: ${error instanceof Error ? error.message : String(error)}`
+              );
+            } finally {
+              restarting = false;
+            }
+          }, 50);
+        };
+        server.watcher.on("add", refresh);
+        server.watcher.on("change", refresh);
+        server.watcher.on("unlink", refresh);
+        const configuredDevelopment = developmentConfig;
+        if (manifest.lessonExports?.standaloneHtml && configuredDevelopment) {
+          server.watcher.on("add", invalidateDevelopmentDownloads);
+          server.watcher.on("change", invalidateDevelopmentDownloads);
+          server.watcher.on("unlink", invalidateDevelopmentDownloads);
+          server.middlewares.use(async (request, response, next) => {
+            if (request.method !== "GET" && request.method !== "HEAD") return next();
+            let pathname;
+            try {
+              pathname = decodeURIComponent(
+                new URL(request.url ?? "/", "http://localhost").pathname
+              );
+            } catch {
+              return next();
+            }
+            const slug = matchStandaloneDownload(
+              pathname,
+              configuredDevelopment.base,
+              manifest.lessons.map((lesson) => lesson.slug)
+            );
+            if (!slug) return next();
+            try {
+              logger.info(
+                developmentDownloads ? `Serving cached standalone lesson ${slug}.html` : "Building standalone lesson downloads for local development\u2026"
+              );
+              developmentDownloads ??= buildDevelopmentDownloads(
+                configuredDevelopment,
+                manifest.lessons.map((lesson) => lesson.slug)
+              );
+              const currentDownloads = developmentDownloads;
+              currentDownloads.catch(() => {
+                if (developmentDownloads === currentDownloads) {
+                  developmentDownloads = void 0;
+                }
+              });
+              const artifact = (await currentDownloads).get(slug);
+              if (!artifact) return next();
+              const filename = `${slug.split("/").at(-1) ?? "lesson"}.html`;
+              response.statusCode = 200;
+              response.setHeader("Content-Type", "text/html; charset=utf-8");
+              response.setHeader("Content-Length", artifact.byteLength);
+              response.setHeader(
+                "Content-Disposition",
+                `attachment; filename="${filename}"`
+              );
+              response.setHeader("Cache-Control", "no-store");
+              response.end(request.method === "HEAD" ? void 0 : artifact);
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              logger.error(`Could not build standalone lesson downloads: ${message}`);
+              response.statusCode = 500;
+              response.setHeader("Content-Type", "text/plain; charset=utf-8");
+              response.end(`Could not build standalone lesson download.
+${message}
+`);
+            }
+          });
+        }
+      },
+      "astro:build:done": async ({ dir }) => {
+        await validateGeneratedNotationPayloads(dir);
+        await writeStandaloneLessonExports(dir, manifest);
+      }
+    }
+  };
+}
+export {
+  assertLocalNotationParity,
+  assertNotationPayloadHtml,
+  explicoContentRefresh,
+  matchStandaloneDownload
+};

package/dist/compiler/cli.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';
@@ -107,6 +111,7 @@ interface StatusReport {
         readonly keyedEquations: number;
         readonly keyedTables: number;
         readonly keyedFigures: number;
+        readonly keyedDiagrams: number;
     };
     readonly draftDebt: {
         readonly lessons: readonly string[];
@@ -161,6 +166,14 @@ interface ContextReport {
         key: string;
         number: string;
     }[];
+    readonly diagrams: readonly {
+        key: string;
+        number: string;
+    }[];
+    readonly knowledgeChecks: readonly {
+        key: string;
+        number: string;
+    }[];
     readonly sources: readonly {
         id: string;
         title: string;

package/dist/compiler/cli.js

@@ -12,7 +12,11 @@ import remarkMdx from "remark-mdx";
 import { createNotationKatexOptions } from "../reference/katex-options.mjs";
 import rehypeFailKatexErrors from "../reference/rehype-fail-katex-errors.mjs";
 import remarkCitation from "../reference/remark-citation.mjs";
-import remarkNotation from "../reference/remark-notation.mjs";
+import remarkMemo from "../reference/remark-memo.mjs";
+import remarkNotation, {
+  createRemarkNotationOptions
+} from "../reference/remark-notation.mjs";
+import remarkShortNote from "../reference/remark-short-note.mjs";
 import { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
@@ -84,7 +88,10 @@ function lessonDiagnostics(manifest, lesson) {
   }
   for (const diagnostic of [
     ...manifest.diagnostics.tables,
-    ...manifest.diagnostics.figures
+    ...manifest.diagnostics.figures,
+    ...manifest.diagnostics.diagrams,
+    ...manifest.diagnostics.checks,
+    ...manifest.diagnostics.rawFloats
   ]) {
     if (diagnostic.lessonId !== id && diagnostic.file !== file && !mentions(diagnostic.message, id, file)) {
       continue;
@@ -121,15 +128,18 @@ function processorFor(manifest) {
       // shape here that it does there (D7/F-tables-figures parity).
       remarkMdx,
       remarkMath,
-      [
-        remarkNotation,
-        {
-          definitions: manifest.notation.raw,
-          equations: manifest.equations.numbersBySlug,
-          tables: manifest.tables.numbersBySlug,
-          figures: manifest.figures.numbersBySlug
-        }
-      ],
+      remarkShortNote,
+      remarkMemo,
+      // `manifest` carries the number tables *and* the part/offset placement
+      // together, so this check numbers a page exactly as the Astro build
+      // does. Passing the tables alone silently numbered pages by `##` section
+      // here while cross-page references read the part-scheme manifest.
+      // No `strict: true` here: `renderLesson()` below is also called
+      // directly with a synthetic path/body that has no manifest entry at all
+      // (fixture renderability checks — see its own doc comment), which
+      // strict mode would reject as "catalogued lesson with no numbering",
+      // even though it was never meant to be catalogued in the first place.
+      [remarkNotation, createRemarkNotationOptions(manifest)],
       [remarkCitation, { sources: manifest.sources }]
     ],
     rehypePlugins: [
@@ -303,6 +313,9 @@ function contentStatus(manifest) {
     ...manifest.diagnostics.equations.map((d) => d.severity),
     ...manifest.diagnostics.tables.map((d) => d.severity),
     ...manifest.diagnostics.figures.map((d) => d.severity),
+    ...manifest.diagnostics.diagrams.map((d) => d.severity),
+    ...manifest.diagnostics.checks.map((d) => d.severity),
+    ...manifest.diagnostics.rawFloats.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map(() => "warning"),
     ...manifest.diagnostics.knowledge.map((d) => d.severity)
   ];
@@ -318,6 +331,10 @@ function contentStatus(manifest) {
     (count, lesson) => count + lesson.figures.length,
     0
   );
+  const keyedDiagrams = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.diagrams.length,
+    0
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments)
   ).size;
@@ -332,7 +349,8 @@ function contentStatus(manifest) {
       notationDefinitions: manifest.notation.definitions.length,
       keyedEquations,
       keyedTables,
-      keyedFigures
+      keyedFigures,
+      keyedDiagrams
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -388,6 +406,8 @@ function contentContext(manifest, rawId) {
     equations: lesson.equations.map((equation) => ({ ...equation })),
     tables: lesson.tables.map((table) => ({ ...table })),
     figures: lesson.figures.map((figure) => ({ ...figure })),
+    diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
+    knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id);
       return {

package/dist/compiler/collections.d.ts

@@ -1,5 +1,5 @@
 import { CurriculumCatalog } from '../curriculum/validation.js';
-import { NotationReferenceInput, NotationRegistryInput } from '../reference/types.js';
+import { NotationReferenceInput, AbbreviationDefinitionInput, NotationRegistryInput } from '../reference/types.js';
 
 /**
  * The single path from content files to typed data.
@@ -20,6 +20,7 @@ import { NotationReferenceInput, NotationRegistryInput } from '../reference/type
  */
 declare function extractNotationReferences(text: string, file: string, kind: NotationReferenceInput['kind'] | undefined): NotationReferenceInput[];
 declare function loadCurriculumCatalog(): Promise<CurriculumCatalog>;
+declare function loadAbbreviationRegistryInput(): Promise<readonly AbbreviationDefinitionInput[]>;
 declare function loadNotationRegistryInput(): Promise<NotationRegistryInput>;
 /**
  * Notation frontmatter objects for `remark-notation`'s `definitions` option.
@@ -67,4 +68,4 @@ declare function notationSourceLocatorGaps(): {
     total: number;
 };
 
-export { type NotationSpec, extractNotationReferences, loadCurriculumCatalog, loadLessonChecks, loadNotationDefinitions, loadNotationRegistryInput, loadNotationSpecs, loadSourceRecords, notationSourceLocatorGaps };
+export { type NotationSpec, extractNotationReferences, loadAbbreviationRegistryInput, loadCurriculumCatalog, loadLessonChecks, loadNotationDefinitions, loadNotationRegistryInput, loadNotationSpecs, loadSourceRecords, notationSourceLocatorGaps };

package/dist/compiler/collections.js

@@ -4,6 +4,8 @@ import { parseFrontmatter } from "@astrojs/markdown-remark";
 import { isSubstantiveMeaning } from "../reference/prose.js";
 import { parseEquationRef } from "../reference/equations.mjs";
 import { parseKeyedFloatRef } from "../reference/keyed-jsx-floats.mjs";
+import { parseKnowledgeCheckRef } from "../reference/knowledge-checks.mjs";
+import { parseMemoRef } from "../reference/remark-memo.mjs";
 import { resolveLabel } from "../reference/label.js";
 import { resolveGlosses } from "../reference/gloss.js";
 import {
@@ -137,7 +139,7 @@ function extractNotationReferences(text, file, kind) {
   for (const [pattern, referenceKind] of patterns) {
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? "").trim();
-      if (parseEquationRef(key) || parseKeyedFloatRef(key, { prefix: "tab" }) || parseKeyedFloatRef(key, { prefix: "fig" })) {
+      if (parseEquationRef(key) || parseKeyedFloatRef(key, { prefix: "tab" }) || parseKeyedFloatRef(key, { prefix: "fig" }) || parseKeyedFloatRef(key, { prefix: "dia" }) || parseKnowledgeCheckRef(key) || parseMemoRef(key)) {
         continue;
       }
       references.push({
@@ -291,6 +293,30 @@ function sharedNotationEntries() {
     };
   });
 }
+function abbreviationEntries() {
+  const directory = join(CONTENT_ROOT, "abbreviations");
+  if (!existsSync(directory)) return [];
+  return filesBelow(directory, [".md"]).map((path) => {
+    const { file, data } = parseDocument(path);
+    const key = string(data.key, `${file} key`);
+    const filenameKey = basename(path, ".md");
+    if (key !== filenameKey) {
+      throw new Error(`${file} declares key ${key}; expected ${filenameKey}`);
+    }
+    const domain = optionalString(data.domain, `${file} domain`);
+    return {
+      key,
+      abbr: string(data.abbr, `${file} abbr`),
+      expansion: meaningText(data.expansion, `${file} expansion`),
+      aliases: strings(data.aliases, `${file} aliases`),
+      source: { file },
+      ...domain === void 0 ? {} : { domain }
+    };
+  });
+}
+async function loadAbbreviationRegistryInput() {
+  return abbreviationEntries();
+}
 function notationLessonEntries() {
   const lessons = [];
   for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
@@ -403,6 +429,7 @@ function notationSourceLocatorGaps() {
 }
 export {
   extractNotationReferences,
+  loadAbbreviationRegistryInput,
   loadCurriculumCatalog,
   loadLessonChecks,
   loadNotationDefinitions,

package/dist/compiler/course-config.d.ts

@@ -6,12 +6,23 @@
  * data value and passes it here, typed against `CourseConfig`. A second course
  * supplies its own value of this shape.
  */
-interface CourseSection {
+/**
+ * One **part** — a sidebar group, holding the chapters (lessons) whose slugs
+ * start with `dir`. A part's 1-based position in `CourseConfig.parts` is the
+ * number before the dot in every equation, table, and figure number inside it.
+ * See `docs/authoring/structure.md` for the full level taxonomy.
+ */
+interface CoursePart {
     /** Lesson-slug prefix, e.g. `bonds` for `bonds/yield-to-maturity`. */
     readonly dir: string;
     /** Sidebar group heading. */
     readonly label: string;
 }
+/**
+ * @deprecated Renamed to {@link CoursePart}. "Section" now only ever means an
+ * `##` heading inside a lesson. Removed in the next MINOR release.
+ */
+type CourseSection = CoursePart;
 interface CourseConventions {
     /** Notation key a lesson's stated sign convention must resolve to. */
     readonly signConventionKey: string;
@@ -33,6 +44,37 @@ interface CourseOperators {
     /** Baseline operators this course wants explained anyway. */
     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.
+ */
+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}.
+ */
+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. */
 interface CourseAuthor {
     readonly name: string;
@@ -65,11 +107,37 @@ interface CourseAbout {
     /** Link to the published content changelog (repo blob, docs page, …). */
     readonly changelogHref?: string;
 }
+/** Optional, build-time lesson artifacts exposed to readers. */
+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. */
+interface NormalizedLessonExports {
+    readonly standaloneHtml: boolean;
+    readonly print: boolean;
+    readonly canonicalBaseUrl?: string;
+}
 interface CourseConfig {
     readonly title: string;
     readonly description: string;
-    /** Sidebar section groups, in order. */
-    readonly sections: readonly CourseSection[];
+    /**
+     * The course's parts (sidebar groups), in order. Exactly one of `parts` or
+     * the deprecated `sections` must be given.
+     */
+    readonly parts?: readonly CoursePart[];
+    /**
+     * @deprecated Renamed to {@link CourseConfig.parts}. Still honoured, so a
+     * course on the old name keeps building; removed in the next MINOR release.
+     */
+    readonly sections?: readonly CoursePart[];
     /** Namespaces used by competency / notation `domain` fields. */
     readonly domains: readonly string[];
     readonly conventions: CourseConventions;
@@ -77,6 +145,20 @@ 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. */
+declare function normalizeLessonExports(config: CourseConfig): NormalizedLessonExports;
+/**
+ * The course's parts, from whichever field the config uses. Throws rather than
+ * silently producing a course with no sidebar groups — a config with neither
+ * field would otherwise number every float by the `##`-section fallback.
+ */
+declare function coursePartsOf(config: CourseConfig): readonly CoursePart[];
 
-export type { CourseAbout, CourseAuthor, CourseConfig, CourseConventions, CourseOperators, CourseSection };
+export { type CourseAbbreviations, type CourseAbout, type CourseAuthor, type CourseConfig, type CourseConventions, type CourseOperators, type CoursePart, type CourseRomanLabels, type CourseSection, type LessonExportsConfig, type NormalizedLessonExports, coursePartsOf, normalizeLessonExports };

package/dist/compiler/course-config.js

@@ -0,0 +1,39 @@
+function normalizeLessonExports(config) {
+  const standaloneHtml = config.lessonExports?.standaloneHtml === true;
+  const print = config.lessonExports?.print === true;
+  const rawBase = config.lessonExports?.canonicalBaseUrl;
+  if (rawBase === void 0) return { standaloneHtml, print };
+  let parsed;
+  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() };
+}
+function coursePartsOf(config) {
+  const parts = config.parts ?? config.sections;
+  if (!parts || parts.length === 0) {
+    throw new Error(
+      "CourseConfig needs at least one entry in `parts` (a sidebar group: { dir, label }). The old name `sections` is still accepted."
+    );
+  }
+  return parts;
+}
+export {
+  coursePartsOf,
+  normalizeLessonExports
+};

package/dist/compiler/exports/standalone-html.d.ts

@@ -0,0 +1,34 @@
+import { Manifest } from '../manifest.js';
+import '../../curriculum/validation.js';
+import '../../reference/consistency.js';
+import '../course-config.js';
+import '../collections.js';
+import '../../reference/types.js';
+import '../../reference/lint-ignore.js';
+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';
+
+/** Inputs for producing one standalone lesson from Astro's final HTML. */
+interface StandaloneLessonInput {
+    readonly html: string;
+    readonly sourceFile: string;
+    readonly outputRoot: string;
+    readonly lessonSlug: string;
+    readonly canonicalBaseUrl?: string;
+}
+/** Build one fully inlined lesson document without writing it. */
+declare function buildStandaloneLessonHtml(input: StandaloneLessonInput): Promise<string>;
+/** Emit all opt-in lesson HTML artifacts from Astro's completed static output. */
+declare function writeStandaloneLessonExports(directory: URL, manifest: Manifest): Promise<void>;
+
+export { type StandaloneLessonInput, buildStandaloneLessonHtml, writeStandaloneLessonExports };