explico 0.11.1 → 0.13.0

package/dist/compiler/exports/zip.js

@@ -0,0 +1,72 @@
+import { Buffer } from "node:buffer";
+import { crc32, deflateRawSync } from "node:zlib";
+const DOS_DATE_1980_01_01 = 33;
+const UTF8_NAMES = 2048;
+const REGULAR_FILE_644 = 33188 << 16;
+function zip(entries) {
+  const sorted = [...entries].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const seen = /* @__PURE__ */ new Set();
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+  for (const entry of sorted) {
+    if (!entry.path || entry.path.startsWith("/") || entry.path.split("/").includes("..")) {
+      throw new Error(`Zip entry path ${JSON.stringify(entry.path)} is not a relative path.`);
+    }
+    if (seen.has(entry.path)) throw new Error(`Zip entry ${entry.path} appears twice.`);
+    seen.add(entry.path);
+    const name = Buffer.from(entry.path, "utf8");
+    const data = typeof entry.content === "string" ? Buffer.from(entry.content, "utf8") : Buffer.from(entry.content);
+    const deflated = deflateRawSync(data, { level: 9 });
+    const stored = deflated.length >= data.length;
+    const body = stored ? data : deflated;
+    const checksum = crc32(data) >>> 0;
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(67324752, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(UTF8_NAMES, 6);
+    local.writeUInt16LE(stored ? 0 : 8, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(DOS_DATE_1980_01_01, 12);
+    local.writeUInt32LE(checksum, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, name, body);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(33639248, 0);
+    central.writeUInt16LE(3 << 8 | 20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(UTF8_NAMES, 8);
+    central.writeUInt16LE(stored ? 0 : 8, 10);
+    central.writeUInt16LE(0, 12);
+    central.writeUInt16LE(DOS_DATE_1980_01_01, 14);
+    central.writeUInt32LE(checksum, 16);
+    central.writeUInt32LE(body.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(REGULAR_FILE_644 >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, name);
+    offset += local.length + name.length + body.length;
+  }
+  const directory = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(101010256, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(sorted.length, 8);
+  end.writeUInt16LE(sorted.length, 10);
+  end.writeUInt32LE(directory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+  return Buffer.concat([...locals, directory, end]);
+}
+export {
+  zip
+};

package/dist/compiler/lesson-derivation.d.ts

@@ -5,7 +5,7 @@
  * layout, the tests) goes through that one loader.
  *
  * Authored per lesson after C2: `title`, `description`, `teaches`, `assumptions`,
- * `editorialStatus`, `notation.local`. Everything below is derived:
+ * `notation.local`. Everything below is derived:
  *
  * - `lessonId`      — the doc slug, `/` → `.` (`foundations/discount-factors`).
  * - `requires`      — direct competency-graph prerequisites of `teaches`, minus
@@ -31,6 +31,12 @@ declare function lessonIdFromSlug(slug: string): string;
  * future `<section>/index` page would not be one either.
  */
 declare function isLessonSlug(slug: string): boolean;
+/**
+ * The docs slugs a Starlight route id can stand for. The glob loader shortens
+ * `<dir>/index.mdx` to the id `<dir>`, and may give the landing page an empty
+ * one, so a manifest entry matches its route either way.
+ */
+declare function docsSlugsForRoute(routeSlug: string): readonly string[];
 /**
  * Direct prerequisites of everything the lesson `teaches`, minus the taught
  * competencies themselves, sorted. Editorial "you should also know" extras that
@@ -103,4 +109,4 @@ declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonl
     readonly floatIndex?: boolean;
 }): SidebarGroup[];
 
-export { PART_OVERVIEW_CLASS, type SidebarGroup, type SidebarItem, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };
+export { PART_OVERVIEW_CLASS, type SidebarGroup, type SidebarItem, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, docsSlugsForRoute, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };

package/dist/compiler/lesson-derivation.js

@@ -1,3 +1,4 @@
+import { citedIds, withoutLinkCitations } from "../reference/citation-format.mjs";
 function lessonIdFromSlug(slug) {
   return slug.replace(/\.(md|mdx)$/, "").replace(/\//g, ".");
 }
@@ -5,6 +6,9 @@ function isLessonSlug(slug) {
   const clean = slug.replace(/\.(md|mdx)$/, "");
   return clean.includes("/") && !clean.endsWith("/index");
 }
+function docsSlugsForRoute(routeSlug) {
+  return routeSlug === "" ? ["index"] : [routeSlug, `${routeSlug}/index`];
+}
 function deriveRequires(teaches, prerequisitesById) {
   const taught = new Set(teaches);
   const required = /* @__PURE__ */ new Set();
@@ -17,13 +21,7 @@ function deriveRequires(teaches, prerequisitesById) {
 }
 function citedSourceIds(body) {
   const withoutCode = body.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
-  const ids = /* @__PURE__ */ new Set();
-  for (const match of withoutCode.matchAll(
-    /\[@([a-z0-9][a-z0-9.-]*)(?:;[^\]]*)?\]/g
-  )) {
-    ids.add((match[1] ?? "").trim());
-  }
-  return ids;
+  return citedIds(withoutLinkCitations(withoutCode));
 }
 function deriveSources(body) {
   return [...citedSourceIds(body)].sort();
@@ -99,6 +97,7 @@ export {
   citedSourceIds,
   deriveRequires,
   deriveSources,
+  docsSlugsForRoute,
   isLessonSlug,
   lessonIdFromSlug,
   mergeTrackOrder,

package/dist/compiler/manifest.d.ts

@@ -8,15 +8,17 @@ import { ExampleLabelRecord, ExampleDiagnostic } from '../reference/examples-val
 import { FoldDiagnostic } from '../reference/folds-validate.js';
 import { KnowledgeCheckLabelRecord, KnowledgeCheckDiagnostic } from '../reference/knowledge-checks-validate.js';
 import { RawFloatDiagnostic } from '../reference/raw-floats-validate.js';
+import { LabKatexDiagnostic } from '../reference/lab-katex-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 { b as NormalizedLessonExports, c as NormalizedDisclosure, d as NormalizedNumbering, B as BlockLabels, M as ManifestRules, e as ConfigDiagnostic, C as CourseConfig } from '../course-config-Dsnri9Tk.js';
+import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, NotationGlossEntry } from '../reference/types.js';
+import { N as NormalizedLessonExports, a as NormalizedDisclosure, b as NormalizedNumbering, B as BlockLabels, c as NormalizedCards, M as ManifestRules, d as ConfigDiagnostic, C as CourseConfig } from '../course-config-rRtME5UV.js';
 import { WaiverDiagnostic } from '../rules/waivers.js';
 import { KnowledgeVersionDiagnostic } from './knowledge-version.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
+import '../reference/gate-retired-keys.js';
 import '../reference/lint-ignore.js';
 import '../reference/keyed-float-validate.js';
 import '../rules/catalog.js';
@@ -167,8 +169,48 @@ import '../rules/course-rules.js';
  * state of a `<Fold>`; `disclosure.figures` now says whether a lab's tools
  * start open; `diagnostics.folds` holds `fold-unnamed`
  * (docs/plans/figures-and-short-captions.md, Parts 1–2).
+ *
+ * v25 (cards on non-chapter pages, rule S10): `pages` — every docs page that
+ * is not a chapter (the landing page, a part's overview page, …) with its
+ * `id`, `slug`, `file` and a `notation` bundle of the lesson shape, so the
+ * footer renders the cards its `[[key]]` terms and math open.
+ * `notation.bundles` and `notation.backlinks` now carry those pages' ids too.
+ *
+ * v26 (carried cards, additive): `cards` — the course's `cards` settings with
+ * the engine defaults applied: whether "Carry cards" starts on (rule K1).
+ *
+ * v27 (LaTeX export): `lessonExports.latex` and `lessonExports.latexPaper`;
+ * every `assessmentContent` item carries its `type`, a choice item's
+ * `options` (plain-text labels) and `correctOptionId`, and a
+ * numeric item's `answer`, so an answer key can be printed without re-reading
+ * `content/assessments/`.
+ *
+ * v28 (Markdown export): `lessonExports.markdown`.
+ *
+ * v29 (no editorial status): the draft / in-review / reviewed flag is gone —
+ * `lessons[].status`, `editorialStatus` on the notation definitions of
+ * `lessons[]` and `pages[]`, and `status` on `notation.definitions[]` and
+ * `notation.bundles[]`. `diagnostics.curriculum` carries `retired-key`, with
+ * `file` and `line`, for a content file that still sets the key, and the
+ * lesson-assumptions check reports `missing-assumptions`, not `review-state`.
+ *
+ * v30 (headings with math, additive): `lessons[].headings[].text` is what a
+ * reader sees — inline math as it reads (`$\explain{k}{R}$` is `R`, not its
+ * LaTeX) and a `[[key]]` term as its label — and `math: true` marks a heading
+ * with inline math. A heading's `slug` is unchanged. Each choice option of
+ * `assessmentContent` carries `labelSegments`, its label split into text and
+ * math like `promptSegments`, so a label's math renders.
+ *
+ * v31 (indexed symbols, rule N23): the `notation` bundle of `lessons[]` and
+ * `pages[]` gains `derived` — the derived cards its body math uses, each
+ * composed from a base entry and an index entry (`\mathbf{v}_0` from
+ * `\mathbf{v}` and `{}_0`), keyed `<base>.sub.<index>`. A notation
+ * definition carries `reads`, `range`, `fixedIndex` and an index entry's
+ * `formulaTemplate` when its entry sets them, and a bundle definition its
+ * `range`. `diagnostics.math` carries `index-explained`, `index-swallowed`,
+ * `index-range` and `derived-key-taken`.
  */
-declare const MANIFEST_SCHEMA_VERSION = 24;
+declare const MANIFEST_SCHEMA_VERSION = 31;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -200,10 +242,11 @@ interface ManifestLessonNotation {
     readonly notation: string;
     readonly label: string;
     readonly summary: string;
-    readonly editorialStatus: EditorialStatus;
     readonly seeAlso: readonly string[];
     readonly units?: string;
     readonly formula?: string;
+    /** Rule N23: the set a running index letter runs over, shown on its card (v31). */
+    readonly range?: string;
     /** Symbols the formula names that have no card of their own (D15). */
     readonly glosses: readonly NotationGlossEntry[];
     /**
@@ -213,6 +256,26 @@ interface ManifestLessonNotation {
      */
     readonly formulaScope: readonly GlyphScopeEntry[];
 }
+/**
+ * A derived card (rule N23, v31): the card of a symbol with a subscript that
+ * an index entry explains, composed from the `base` entry and the `index`
+ * entry by `derived-notation.mjs`. Its title and summary are about the
+ * indexed symbol; its formula names the base, whose card is one level deeper.
+ * It is listed nowhere — not in the Page notation panel, the glossary or an
+ * export's notation section — and opens only from the symbol.
+ */
+interface ManifestDerivedNotation {
+    readonly key: string;
+    readonly base: string;
+    readonly index: string;
+    readonly notation: string;
+    readonly label: string;
+    readonly summary: string;
+    readonly units?: string;
+    readonly formula?: string;
+    readonly glosses: readonly NotationGlossEntry[];
+    readonly formulaScope: readonly GlyphScopeEntry[];
+}
 /**
  * One keyed float of a lesson (v21): its key and number, and its caption pair
  * — `short` (an equation's `\caption{…}`, or the `short` prop) and, for a
@@ -280,9 +343,12 @@ interface ManifestLesson {
      */
     readonly headings: readonly {
         readonly slug: string;
+        /** What a reader sees: math as it reads, a `[[key]]` term as its label (v30). */
         readonly text: string;
         readonly level: number;
         readonly number?: string;
+        /** The heading has inline math (v30). */
+        readonly math?: true;
     }[];
     readonly file: string;
     readonly title: string;
@@ -292,7 +358,6 @@ interface ManifestLesson {
         readonly min: number;
         readonly max: number;
     };
-    readonly status: EditorialStatus;
     /** Ordered — the curriculum contract. */
     readonly teaches: readonly string[];
     readonly requires: readonly string[];
@@ -336,10 +401,25 @@ interface ManifestLesson {
         }[];
         readonly definitionIds: readonly string[];
         readonly definitions: readonly ManifestLessonNotation[];
+        /** The derived cards (rule N23) the page's body math uses (v31). */
+        readonly derived: readonly ManifestDerivedNotation[];
         /** Every `[[key]]` / `\explain{key}` occurrence, resolved and located. */
         readonly resolution: readonly ManifestNotationResolution[];
     };
 }
+/**
+ * A docs page that is not a chapter (v25, rule S10) — the landing page, a
+ * part's overview page, any page outside a part directory. It numbers
+ * nothing, so it carries only what its cards need: the notation bundle its
+ * `[[key]]` terms and math reach, shared entries only.
+ */
+interface ManifestPage {
+    /** `index`, `motion.index`, `glossary` — `lessonIdFromSlug` of the slug; never a lesson id. */
+    readonly id: string;
+    readonly slug: string;
+    readonly file: string;
+    readonly notation: ManifestLesson['notation'];
+}
 /** The reader-facing "about this material" bundle — the `[?]` panel's data. */
 interface ManifestAbout {
     /** `explico`'s own identity, from its `package.json` (the version's golden source). */
@@ -376,6 +456,25 @@ interface ManifestAssessmentItemContent {
     readonly itemId: string;
     readonly promptSegments: readonly ContentSegment[];
     readonly explanationSegments: readonly ContentSegment[];
+    /** What kind of answer the item takes (v27). */
+    readonly type: 'single-choice' | 'numeric';
+    /**
+     * A choice item's options in authored order: the label as authored, and
+     * split into text and math like the prompt (`labelSegments`, v30), so a
+     * label's math renders.
+     */
+    readonly options?: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly labelSegments: readonly ContentSegment[];
+    }[];
+    /** A choice item's correct option. */
+    readonly correctOptionId?: string;
+    /** A numeric item's accepted value and tolerance. */
+    readonly answer?: {
+        readonly value: number;
+        readonly tolerance: number;
+    };
 }
 /**
  * One **part** (v17) — a sidebar group and the directory its chapters live in,
@@ -419,6 +518,8 @@ interface Manifest {
     readonly numbering: NormalizedNumbering;
     /** How a check's and an example set's heading names its kind (`CourseConfig.blockLabels`). */
     readonly blockLabels: BlockLabels;
+    /** How the explanation cards start for a reader, defaults applied (`CourseConfig.cards`). */
+    readonly cards: NormalizedCards;
     /** Reader-facing identity + versions (the `[?]` About panel). */
     readonly about: ManifestAbout;
     readonly notation: {
@@ -438,6 +539,8 @@ interface Manifest {
     /** The course's parts in config order, with their chapters and overview pages. */
     readonly parts: readonly ManifestPart[];
     readonly lessons: readonly ManifestLesson[];
+    /** Every docs page that is not a chapter, by id (v25). */
+    readonly pages: readonly ManifestPage[];
     /** Full competency prerequisite graph. */
     readonly prereqEdges: readonly PrereqEdge[];
     /** Equation identity (D7): every labelled display equation + the render-path lookup. */
@@ -501,8 +604,12 @@ interface Manifest {
         readonly equations: readonly EquationDiagnostic[];
         /** `<Table>` identity checks (F-tables-figures) — same codes, `tab-` prefixed. */
         readonly tables: readonly TableDiagnostic[];
-        /** `<Figure>` identity checks (F-tables-figures) — same codes, `fig-` prefixed. */
-        readonly figures: readonly FigureDiagnostic[];
+        /**
+         * `<Figure>` identity checks (F-tables-figures) — same codes, `fig-`
+         * prefixed — and rule V3's `lab-katex-direct`: a file a lesson imports
+         * that calls KaTeX itself.
+         */
+        readonly figures: readonly (FigureDiagnostic | LabKatexDiagnostic)[];
         /** `<Diagram>` identity checks — same codes, `dia-` prefixed. */
         readonly diagrams: readonly DiagramDiagnostic[];
         /** Knowledge-check identity and `[[check-…]]` reference checks. */
@@ -549,4 +656,4 @@ declare function readManifestSync(): Manifest;
  */
 declare function loadManifest(courseConfig?: CourseConfig): Promise<Manifest>;
 
-export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestAssessmentItemContent, type ManifestCitation, type ManifestLesson, type ManifestLessonFloat, type ManifestLessonNotation, type ManifestNotationResolution, type ManifestPart, type ManifestTitledBlock, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };
+export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestAssessmentItemContent, type ManifestCitation, type ManifestDerivedNotation, type ManifestLesson, type ManifestLessonFloat, type ManifestLessonNotation, type ManifestNotationResolution, type ManifestPage, type ManifestPart, type ManifestTitledBlock, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };