explico 0.1.0 → 0.1.1

package/dist/compiler/cli.js

@@ -12,7 +12,7 @@ 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 { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation";
+import { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const DOCS_ROOT = join(CONTENT_ROOT, "docs");

package/dist/compiler/collections.js

@@ -1,16 +1,16 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
-import { isSubstantiveMeaning } from "../reference/prose";
+import { isSubstantiveMeaning } from "../reference/prose.js";
 import { parseEquationRef } from "../reference/equations.mjs";
-import { resolveLabel } from "../reference/label";
+import { resolveLabel } from "../reference/label.js";
 import {
   deriveRequires,
   deriveSources,
   isLessonSlug,
   lessonIdFromSlug,
   parseCheckList
-} from "./lesson-derivation";
+} from "./lesson-derivation.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 function filesBelow(directory, extensions) {

package/dist/compiler/manifest.js

@@ -10,32 +10,32 @@ import { dirname, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
 import {
   validateCurriculum
-} from "../curriculum/validation";
+} from "../curriculum/validation.js";
 import {
   runConsistencyChecks
-} from "../reference/consistency";
-import { validateNotationAlignment } from "../reference/curriculum-alignment";
+} from "../reference/consistency.js";
+import { validateNotationAlignment } from "../reference/curriculum-alignment.js";
 import {
   validateEquations
-} from "../reference/equations-validate";
+} from "../reference/equations-validate.js";
 import {
   gateContentMath
-} from "../reference/gate-math";
-import { loadLintIgnore } from "../reference/lint-ignore";
-import { buildNotationRegistry } from "../reference/registry";
-import { resolveReferenceId } from "../reference/references";
+} from "../reference/gate-math.js";
+import { loadLintIgnore } from "../reference/lint-ignore.js";
+import { buildNotationRegistry } from "../reference/registry.js";
+import { resolveReferenceId } from "../reference/references.js";
 import {
   loadCurriculumCatalog,
   loadNotationDefinitions,
   loadNotationRegistryInput,
   loadNotationSpecs,
   loadSourceRecords
-} from "./collections";
+} from "./collections.js";
 import {
   buildSidebar,
   deriveSources,
   isLessonSlug
-} from "./lesson-derivation";
+} from "./lesson-derivation.js";
 const MANIFEST_SCHEMA_VERSION = 3;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");

package/dist/compiler/resolution-report.js

@@ -9,8 +9,8 @@ import {
 import { join } from "node:path";
 import {
   consistencyCounts
-} from "../reference/consistency";
-import { MANIFEST_SCHEMA_VERSION } from "./manifest";
+} from "../reference/consistency.js";
+import { MANIFEST_SCHEMA_VERSION } from "./manifest.js";
 const REPOSITORY_ROOT = process.cwd();
 const RESOLUTION_DIR = join(REPOSITORY_ROOT, "build", "resolution");
 const RESOLUTION_PREFIX = "build/resolution/";

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

@@ -0,0 +1,17 @@
+/** True when `token` is a base-library atom and needs no semantic key. */
+export function isBaseLibraryAtom(token: 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.
+ *
+ * Rationale (cleanup plan, "Decide once"): keep a base library so the
+ * completeness gate does not choke on mathematical constants and the
+ * differential operator. It is deliberately tiny and greppable — anything a
+ * lesson uses with a domain meaning (rates, indices, prices) still resolves to
+ * a semantic key or fails at `file:line:token`.
+ *
+ * Function names (`\ln`, `\exp`, `\log`, `\sin`, `\max`, `\sum`, `\prod`, …)
+ * are not listed here: KaTeX parses them as operator nodes, not identifier
+ * atoms, so the tokenizer never treats them as bindable symbols.
+ */
+export const BASE_LIBRARY: Readonly<Set<string>>;

package/dist/reference/citation-format.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Short author label: one surname, "A & B" for two, "A et al." for more.
+ * Falls back to the publishing organization for official guidance.
+ *
+ * @param {Record<string, unknown>} record
+ * @returns {string}
+ */
+export function formatAuthors(record: Record<string, unknown>): string;
+/**
+ * The "(4th ed., 2022)" tail, omitting whichever parts are absent.
+ *
+ * @param {Record<string, unknown>} record
+ * @returns {string}
+ */
+export function formatEditionYear(record: Record<string, unknown>): string;
+/**
+ * One reference-list line: "Authors, Title (edition, year). Locator."
+ * `locator` is the text an author passed after the `;` in `[@id; locator]` and is
+ * optional. The source record's own catalog `locator` is not used here.
+ *
+ * @param {Record<string, unknown>} record
+ * @param {string | undefined} locator
+ * @returns {string}
+ */
+export function formatReferenceText(record: Record<string, unknown>, locator: string | undefined): string;
+/**
+ * Recover the source label (authors + title, no locator) from a rendered
+ * reference-list line — the inverse of the ". <locator>." tail
+ * `formatReferenceText` appends. Lets the citation hover panel read its
+ * heading off the page's own "References" list instead of a second serialized
+ * copy of the source database. Falls back to the whole line if the tail is
+ * not where it is expected.
+ *
+ * @param {string} referenceText  text of the `#cite-n` list item
+ * @param {string | undefined} locator  the marker's `data-citation-locator`
+ * @returns {string}
+ */
+export function referenceLabelFromText(referenceText: string, locator: string | undefined): string;
+/**
+ * The compact "Tuckman & Serrat, Fixed Income Securities (4th ed., 2022)"
+ * shown as the panel heading, without the locator.
+ *
+ * @param {Record<string, unknown>} record
+ * @returns {string}
+ */
+export function formatSourceLabel(record: Record<string, unknown>): string;
+/**
+ * Pure helpers for turning a source record plus a per-citation locator into
+ * the strings shown in the inline panel and the end-of-page reference list.
+ *
+ * Imported by both the remark adapter (build-time list rendering) and the
+ * `CitationLayer` island (hover panel), so it must not touch the DOM, the
+ * file system, or Astro APIs.
+ */
+export const SOURCE_ID_PATTERN: RegExp;

package/dist/reference/consistency.js

@@ -1,4 +1,4 @@
-import { offVocabularyTokens } from "./units-vocab";
+import { offVocabularyTokens } from "./units-vocab.js";
 const CONVENTION_RE = /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
 function stripCode(text) {
   return text.replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, " ")).replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, " "));

package/dist/reference/curriculum-alignment.js

@@ -1,4 +1,4 @@
-import { compareDiagnostics } from "./references";
+import { compareDiagnostics } from "./references.js";
 function validateNotationAlignment(registry, catalog) {
   const diagnostics = [];
   const competencies = new Map(

package/dist/reference/equations.d.mts

@@ -0,0 +1,57 @@
+/** `{ lesson?, key }` when `raw` is an equation reference, else `undefined`. */
+export function parseEquationRef(raw: any): {
+    lesson: string;
+    key: string;
+} | {
+    key: string;
+    lesson?: undefined;
+} | undefined;
+/** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
+export function stripEquationLabels(latex: any): string;
+/**
+ * Every keyed display equation in a Markdown body, in appearance order, with
+ * its assigned number. `$$…$$` blocks only; `##` headings between them advance
+ * the section counter.
+ */
+export function scanEquationLabels(markdown: any): {
+    key: string | undefined;
+    number: string;
+    section: number;
+    indexInSection: number;
+}[];
+/**
+ * The mdast equivalent of `scanEquationLabels`: walk the tree in document
+ * order, advancing the section counter on every depth-2 heading and emitting a
+ * label for every `math` node whose source carries `\label{eq:…}`.
+ */
+export function collectEquationLabels(tree: any): any[];
+/**
+ * Equation identity (Step D7) — shared, framework-free helpers.
+ *
+ * An author marks a display equation by putting a trailing `\label{eq:<key>}`
+ * inside its `$$…$$` block (inside math, so the `:` is safe and the form
+ * matches amsmath). The compiler assigns the *visible* number from appearance
+ * order, scoped to the enclosing `##` section (`(2.4)` = fourth keyed equation
+ * under the second section). The number is never authored; unkeyed display
+ * equations render clean and stay un-referenceable. Prose refers to an
+ * equation with the reserved `eq-` prefix (a bare `:` in `[[…]]` prose would
+ * be eaten by `remark-directive`):
+ *
+ *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
+ *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
+ *
+ * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
+ * MUST agree — `tests/notation/equations.test.ts` checks that on the real
+ * corpus. Both are here so `manifest.ts` and `remark-notation.mjs` share one
+ * numbering algorithm.
+ */
+/** `eq:` key grammar — the notation-key shape without the dotted namespaces. */
+export const EQ_KEY_PATTERN: RegExp;
+/** A `\label{eq:<key>}` anywhere in a math source. Global; `key` in group 1. */
+export const EQ_LABEL_PATTERN: RegExp;
+/**
+ * A `[[ … ]]` payload that targets an equation: `eq-<key>` on the current page,
+ * or `<lesson-slug>#eq-<key>` across pages. `lesson` (group 1) is a `/`-slug.
+ * The `eq-` prefix is reserved — a notation key may not start with it.
+ */
+export const EQ_REF_PATTERN: RegExp;

package/dist/reference/katex-options.d.mts

@@ -0,0 +1,33 @@
+/**
+ * KaTeX trust callback that permits exactly one inert marker attribute:
+ * `data-notation-key` (a registry key) or `data-lab-slot` (a lab value hole).
+ * Links, styles, classes, IDs, protocols, and every other data attribute stay
+ * untrusted. Key existence is checked by the remark adapter, the lab-math
+ * renderer, and the workspace validator before KaTeX runs.
+ */
+export function trustNotationMarker(context: any): boolean;
+/**
+ * Add non-security KaTeX settings while keeping the notation macros and trust
+ * boundary non-overridable.
+ */
+export function createNotationKatexOptions(overrides?: {}): {
+    output: "htmlAndMathml";
+    throwOnError: true;
+    trust: typeof trustNotationMarker;
+    macros: any;
+    strict: typeof strictNotation;
+};
+export const EXPLAIN_MACRO: string;
+export const SLOT_MACRO: string;
+export const notationKatexOptions: Readonly<{
+    output: "htmlAndMathml";
+    throwOnError: true;
+    strict: typeof strictNotation;
+    trust: typeof trustNotationMarker;
+    macros: Readonly<{
+        '\\explain': string;
+        '\\slot': string;
+    }>;
+}>;
+declare function strictNotation(errorCode: any): "ignore" | "warn";
+export {};

package/dist/reference/lab-math-scope.js

@@ -1,4 +1,4 @@
-import { loadManifest } from "../compiler/manifest";
+import { loadManifest } from "../compiler/manifest.js";
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
 async function labMathScope(notation, body = "") {

package/dist/reference/math-glyphs.d.mts

@@ -0,0 +1,46 @@
+/**
+ * Resolve and annotate one KaTeX expression against a page's flat glyph table.
+ * Source offsets in the result always refer to the original, unmodified LaTeX.
+ *
+ * @param {string} latex
+ * @param {Array<{key: string, notation: string}>} definitions
+ */
+export function resolveMathGlyphs(latex: string, definitions: Array<{
+    key: string;
+    notation: string;
+}>): {
+    latex: string;
+    bindings: {
+        key: any;
+        level: any;
+        match: any;
+        token: any;
+    }[];
+    unresolved: any;
+};
+/**
+ * Page-level glyph-map resolver (cleanup plan, D1 decision 2026-09-02).
+ *
+ * A page declares its glyphs once — `notation.local` plus the shared entries it
+ * introduces in prose with `[[key]]` — so the glyph table handed in here is a
+ * flat list with **one meaning per glyph**. This module parses one `$…$` /
+ * `$$…$$` expression, matches each declared symbol against it (whole canonical
+ * form first, then a unique base glyph for a shorter or instantiated form),
+ * marks every match with a validated `\explain` marker, and reports any
+ * remaining identifier atom so the caller can fail at `file:line:token`.
+ * `\explain{key}{latex}` in the source stays as the escape hatch for a
+ * compound or glyph-colliding symbol.
+ *
+ * Because the table is unambiguous, matching is a lookup, not a search: no
+ * cross-definition candidate solving, no ambiguity permutation. What remains is
+ * the tokenizer the page-glyph-map syntax requires — a KaTeX parse plus the
+ * structural signatures that let `CF_k` be found as a three-node run and `D` be
+ * found as the head of `D(0,2)`. `katex.__parse` is that tokenizer; the version
+ * guard below keeps a dependency bump from silently changing its tree.
+ */
+export const SUPPORTED_KATEX_PARSE_VERSION: "0.16.47";
+export class GlyphResolutionError extends Error {
+    constructor(code: any, message: any, details?: undefined);
+    code: any;
+    details: any;
+}

package/dist/reference/registry.js

@@ -5,7 +5,7 @@ import {
   localDefinitionId,
   resolveReferenceId,
   sharedDefinitionId
-} from "./references";
+} from "./references.js";
 function buildNotationRegistry(rawInput) {
   const diagnostics = [];
   const lessons = buildLessonIndex(rawInput.lessons, diagnostics);

package/dist/reference/rehype-fail-katex-errors.d.mts

@@ -0,0 +1,6 @@
+/**
+ * rehype-katex reports parse failures as non-fatal VFile messages and renders
+ * a `.katex-error` fallback. Turn those recovered failures into compiler
+ * errors so Astro cannot successfully build a lesson containing broken math.
+ */
+export default function rehypeFailKatexErrors(): (tree: any, file: any) => void;

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

@@ -0,0 +1,6 @@
+/**
+ * @param {{ sources?: Map<string, object> | readonly object[] | (() => Map<string, object> | readonly object[]) }} [options]
+ */
+export default function remarkCitation(options?: {
+    sources?: Map<string, object> | readonly object[] | (() => Map<string, object> | readonly object[]);
+}): (tree: any, file: any) => void;

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

@@ -0,0 +1,49 @@
+/**
+ * @param {{
+ *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
+ *   resolve?: (key: string, context: object) => object | undefined,
+ *   unknown?: 'error' | 'warn' | 'ignore',
+ *   base?: string,
+ *   equations?: Record<string, Record<string, string>>,
+ * }} [options]
+ */
+export default function remarkNotation(options?: {
+    definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>);
+    resolve?: (key: string, context: object) => object | undefined;
+    unknown?: "error" | "warn" | "ignore";
+    base?: string;
+    equations?: Record<string, Record<string, string>>;
+}): (tree: any, file: any) => void;
+/**
+ * Remark adapter for semantic notation references.
+ *
+ * Author syntax:
+ *   - Prose introduces a meaning: `[[rates.discount-factor]]`
+ *   - Later math uses ordinary LaTeX: `D(0,t)`
+ *   - `\\explain{rates.discount-factor}{D(0,t)}` remains available inside math
+ *     when lexical scope cannot select one meaning unambiguously.
+ *
+ * Prose references become ordinary links. Lesson math is resolved against the
+ * page glyph table — `notation.local` plus the shared entries the page names
+ * with `[[key]]` (or `\\explain{key}{…}`) — and the base library; the
+ * adapter then injects the narrowly trusted `\\explain` marker before
+ * build-time KaTeX rendering. `notation.uses` is retired: the use is the
+ * declaration (D1 decision, 2026-09-02).
+ *
+ * Definitions can be supplied as a Map, an array, an object keyed by the
+ * semantic key, or a loader returning one of those forms. Loaders are
+ * evaluated for every document transform so a long-running development
+ * server can discover definitions created after startup. A resolver can
+ * provide page-local lexical scoping:
+ *
+ *   remarkNotation({
+ *     definitions: sharedDefinitions,
+ *     resolve(key, { file, kind, localDefinitions, sharedDefinitions }) {
+ *       return localDefinitions.get(key) ?? sharedDefinitions.get(key);
+ *     },
+ *   })
+ *
+ * A definition may be either its data object or an Astro collection entry
+ * with the data object under `.data`.
+ */
+export const NOTATION_KEY_PATTERN: RegExp;

package/dist/session/user-context.js

@@ -1,5 +1,5 @@
 import { createContext, useContext } from "react";
-import { anonymousUser } from "./user";
+import { anonymousUser } from "./user.js";
 const SessionUserContext = createContext(anonymousUser);
 function useSessionUser() {
   return useContext(SessionUserContext);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",
@@ -48,6 +48,6 @@
     "typescript": "6.0.2"
   },
   "scripts": {
-    "build": "tsup && node scripts/copy-assets.mjs"
+    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json"
   }
 }