explico 0.2.0 → 0.4.0

package/dist/compiler/manifest.js

@@ -6,6 +6,7 @@ import {
   readdirSync,
   writeFileSync
 } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
 import {
@@ -15,9 +16,17 @@ import {
   runConsistencyChecks
 } from "../reference/consistency.js";
 import { validateNotationAlignment } from "../reference/curriculum-alignment.js";
+import { countDisplayEquations } from "../reference/equations.mjs";
+import { countKeyedJsxFloats } from "../reference/keyed-jsx-floats.mjs";
 import {
   validateEquations
 } from "../reference/equations-validate.js";
+import {
+  validateTables
+} from "../reference/tables-validate.js";
+import {
+  validateFigures
+} from "../reference/figures-validate.js";
 import {
   gateContentMath
 } from "../reference/gate-math.js";
@@ -25,6 +34,10 @@ 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 {
+  resolveKnowledgeVersion
+} from "./knowledge-version.js";
 import {
   loadCurriculumCatalog,
   loadNotationDefinitions,
@@ -35,12 +48,22 @@ import {
 import {
   buildSidebar,
   deriveSources,
-  isLessonSlug
+  isLessonSlug,
+  lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 3;
+const MANIFEST_SCHEMA_VERSION = 7;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");
+let enginePackage;
+function readEnginePackage() {
+  if (!enginePackage) {
+    enginePackage = createRequire(import.meta.url)(
+      "explico/package.json"
+    );
+  }
+  return enginePackage;
+}
 const CITE_PATTERN = /\[@([a-z0-9][a-z0-9.-]*)(?:;[ \t\r\n]*([^\]]*))?\]/g;
 function lessonCitations(body) {
   const withoutCode = body.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
@@ -156,6 +179,11 @@ function lessonFrontmatterById() {
   return result;
 }
 async function compileManifest(courseConfig) {
+  if (courseConfig.about === void 0 || courseConfig.about.version === void 0 || courseConfig.about.authors === void 0 || courseConfig.about.disclaimer === void 0) {
+    throw new Error(
+      "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([
     loadCurriculumCatalog(),
     loadNotationRegistryInput()
@@ -202,20 +230,71 @@ async function compileManifest(courseConfig) {
     catalog.lessons.map((lesson) => [lesson.id, lesson])
   );
   const frontmatterById = lessonFrontmatterById();
-  const equationValidation = validateEquations(
-    notationInput.lessons.map((lesson) => ({
+  const lessonSlugs = [...notationInput.lessons].map((lesson) => lesson.lessonId.replace(/\./g, "/")).sort();
+  const sidebar = buildSidebar(
+    catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
+    lessonSlugs,
+    coursePartsOf(courseConfig)
+  );
+  const bodyByLessonId = new Map(
+    notationInput.lessons.map((lesson) => [lesson.lessonId, lesson.body])
+  );
+  const placementByLessonId = /* @__PURE__ */ new Map();
+  let partCursor = 0;
+  for (const group of sidebar) {
+    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 };
+    let chapterCursor = 0;
+    for (const lessonId of lessonIds) {
+      const body = bodyByLessonId.get(lessonId) ?? "";
+      placementByLessonId.set(lessonId, {
+        part: partCursor,
+        chapter: ++chapterCursor,
+        numbering: { ...used }
+      });
+      used.equations += countDisplayEquations(body);
+      used.tables += countKeyedJsxFloats(body, { tagName: "Table" });
+      used.figures += countKeyedJsxFloats(body, { tagName: "Figure" });
+    }
+  }
+  const floatInputs = (kind) => 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
-    }))
-  );
+      body: lesson.body,
+      ...placement ? {
+        numbering: {
+          prefix: placement.part,
+          offset: placement.numbering[kind]
+        }
+      } : {}
+    };
+  });
+  const equationValidation = validateEquations(floatInputs("equations"));
   const equationsBySlug = new Map(
     Object.entries(equationValidation.numbersBySlug).map(([slug, table]) => [
       slug,
       Object.entries(table).map(([key, number]) => ({ key, number }))
     ])
   );
+  const tableValidation = validateTables(floatInputs("tables"));
+  const tablesBySlug = new Map(
+    Object.entries(tableValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number }))
+    ])
+  );
+  const figureValidation = validateFigures(floatInputs("figures"));
+  const figuresBySlug = new Map(
+    Object.entries(figureValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number }))
+    ])
+  );
   const lessons = [];
   for (const notationLesson of notationInput.lessons) {
     const id = notationLesson.lessonId;
@@ -229,6 +308,16 @@ async function compileManifest(courseConfig) {
     lessons.push({
       id,
       slug: id.replace(/\./g, "/"),
+      // 0 = the lesson is not placed in any configured part; a curriculum
+      // diagnostic covers that separately, and both numbering paths then fall
+      // back to the legacy `##`-section scheme.
+      part: placementByLessonId.get(id)?.part ?? 0,
+      chapter: placementByLessonId.get(id)?.chapter ?? 0,
+      numbering: placementByLessonId.get(id)?.numbering ?? {
+        equations: 0,
+        tables: 0,
+        figures: 0
+      },
       file: notationLesson.source.file,
       title: frontmatter.title,
       description: frontmatter.description,
@@ -240,6 +329,8 @@ async function compileManifest(courseConfig) {
       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, "/")) ?? [],
       prereqEdges: sortEdges(
         teaches.flatMap(
           (to) => (prerequisitesById.get(to) ?? []).filter((from) => !teaches.includes(from)).map((from) => ({ from, to }))
@@ -264,7 +355,8 @@ async function compileManifest(courseConfig) {
     specs: loadNotationSpecs(),
     catalog,
     lintIgnore: loadLintIgnore(),
-    conventions: courseConfig.conventions
+    conventions: courseConfig.conventions,
+    ...courseConfig.operators === void 0 ? {} : { operators: courseConfig.operators }
   });
   const rawNotation = [...loadNotationDefinitions()].sort(
     (a, b) => String(a.key).localeCompare(String(b.key))
@@ -272,14 +364,40 @@ 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 lessonSlugs = [...notationInput.lessons].map((lesson) => lesson.lessonId.replace(/\./g, "/")).sort();
-  const sidebar = buildSidebar(
-    catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
-    lessonSlugs,
-    courseConfig.sections
-  );
+  const hashes = contentHashes();
+  const knowledgeChangelogPath = join(CONTENT_ROOT, "CHANGELOG.md");
+  const knowledge = resolveKnowledgeVersion({
+    changelogText: existsSync(knowledgeChangelogPath) ? readFileSync(knowledgeChangelogPath, "utf8") : void 0,
+    declaredVersion: courseConfig.about.version,
+    file: relative(REPOSITORY_ROOT, knowledgeChangelogPath).replace(/\\/g, "/")
+  });
+  const enginePkg = readEnginePackage();
+  const about = {
+    engine: {
+      name: enginePkg.name,
+      version: enginePkg.version,
+      ...enginePkg.homepage === void 0 ? {} : { homepage: enginePkg.homepage }
+    },
+    material: {
+      name: courseConfig.about.materialName ?? courseConfig.title,
+      summary: courseConfig.about.summary ?? courseConfig.description
+    },
+    knowledge: {
+      version: knowledge.version,
+      ...knowledge.latest?.date === void 0 ? {} : { date: knowledge.latest.date },
+      notes: knowledge.latest?.notes ?? [],
+      contentTree: hashes.contentTree
+    },
+    authors: courseConfig.about.authors.map((author) => ({
+      name: author.name,
+      ...author.contact === void 0 ? {} : { contact: author.contact }
+    })),
+    disclaimer: courseConfig.about.disclaimer,
+    ...courseConfig.about.changelogHref === void 0 ? {} : { changelogHref: courseConfig.about.changelogHref }
+  };
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
+    about,
     notation: {
       definitions: registry.definitions,
       bundles: registry.bundles,
@@ -297,15 +415,26 @@ async function compileManifest(courseConfig) {
       labels: equationValidation.labels,
       numbersBySlug: equationValidation.numbersBySlug
     },
+    tables: {
+      labels: tableValidation.labels,
+      numbersBySlug: tableValidation.numbersBySlug
+    },
+    figures: {
+      labels: figureValidation.labels,
+      numbersBySlug: figureValidation.numbersBySlug
+    },
     diagnostics: {
       curriculum: curriculumIssues,
       notation: registry.diagnostics,
       alignment: alignmentIssues,
       math: mathIssues,
       consistency: consistencyIssues,
-      equations: equationValidation.diagnostics
+      equations: equationValidation.diagnostics,
+      tables: tableValidation.diagnostics,
+      figures: figureValidation.diagnostics,
+      knowledge: knowledge.diagnostics
     },
-    hashes: contentHashes()
+    hashes
   };
 }
 function byId(a, b) {
@@ -340,15 +469,15 @@ function readManifestSync() {
   return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
 }
 async function loadManifest(courseConfig) {
-  if (existsSync(MANIFEST_PATH)) return readManifestSync();
-  if (!courseConfig) {
-    throw new Error(
-      `${relative(REPOSITORY_ROOT, MANIFEST_PATH)} not found. Run \`pnpm validate:content\` first.`
-    );
+  if (courseConfig) {
+    const manifest = await compileManifest(courseConfig);
+    writeManifest(manifest);
+    return manifest;
   }
-  const manifest = await compileManifest(courseConfig);
-  writeManifest(manifest);
-  return manifest;
+  if (existsSync(MANIFEST_PATH)) return readManifestSync();
+  throw new Error(
+    `${relative(REPOSITORY_ROOT, MANIFEST_PATH)} not found. Run \`pnpm validate:content\` first.`
+  );
 }
 export {
   MANIFEST_PATH,

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

@@ -6,8 +6,12 @@ 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/gate-math.js';
 import '../reference/gloss.js';
+import './knowledge-version.js';
 import './lesson-derivation.js';
 
 /**

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

@@ -0,0 +1,38 @@
+/**
+ * The operators a course treats as common, given its `course.config.ts`
+ * `operators` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} operators
+ * @returns {Set<string>}
+ */
+export function effectiveOperatorAllowlist(operators: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+} | undefined): Set<string>;
+/** True when `name` needs no notation entry for this course. */
+export function isBaseOperator(name: any, operators: any): boolean;
+/**
+ * The base operator library: the named mathematical operators every reader is
+ * assumed to know, so a lesson never has to introduce them with a notation
+ * entry.
+ *
+ * Rationale (parallel to `base-library.mjs`): the completeness gate has no
+ * opinion about operators — KaTeX parses `\exp`, `\int`, `\sin`, … as operator
+ * nodes, and `\operatorname{Var}` as an `operatorname` node, none of which the
+ * glyph resolver treats as a bindable symbol. The `operator-explained`
+ * consistency check (rule N8) fills that gap: an operator 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. This set is the "everyone knows these"
+ * baseline — trig, the exponential and logarithms, limits, extrema, and the
+ * big operators — kept greppable and small like the base library.
+ *
+ * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
+ * written `\operatorname{…}` and is NOT here: it earns a card, a
+ * `notation.local` entry, or an explicit line in `course.config.ts`
+ * (`operators.allow`).
+ *
+ * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
+ * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).
+ * Matching is case-sensitive.
+ */
+export const BASE_OPERATORS: Readonly<Set<string>>;

package/dist/reference/base-operators.mjs

@@ -0,0 +1,103 @@
+/**
+ * The base operator library: the named mathematical operators every reader is
+ * assumed to know, so a lesson never has to introduce them with a notation
+ * entry.
+ *
+ * Rationale (parallel to `base-library.mjs`): the completeness gate has no
+ * opinion about operators — KaTeX parses `\exp`, `\int`, `\sin`, … as operator
+ * nodes, and `\operatorname{Var}` as an `operatorname` node, none of which the
+ * glyph resolver treats as a bindable symbol. The `operator-explained`
+ * consistency check (rule N8) fills that gap: an operator 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. This set is the "everyone knows these"
+ * baseline — trig, the exponential and logarithms, limits, extrema, and the
+ * big operators — kept greppable and small like the base library.
+ *
+ * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
+ * written `\operatorname{…}` and is NOT here: it earns a card, a
+ * `notation.local` entry, or an explicit line in `course.config.ts`
+ * (`operators.allow`).
+ *
+ * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
+ * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).
+ * Matching is case-sensitive.
+ */
+export const BASE_OPERATORS = 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',
+    // limits
+    'lim',
+    'limsup',
+    'liminf',
+    'injlim',
+    'projlim',
+    'varlimsup',
+    'varliminf',
+    'varinjlim',
+    'varprojlim',
+    // extrema
+    'max',
+    'min',
+    'sup',
+    'inf',
+    // linear algebra / number theory / misc
+    'arg',
+    'deg',
+    'det',
+    'dim',
+    'gcd',
+    'hom',
+    'ker',
+    'Pr',
+    'mod',
+    // big operators
+    'sum',
+    'prod',
+    'coprod',
+    'int',
+    'iint',
+    'iiint',
+    'oint',
+  ]),
+);
+
+/**
+ * The operators a course treats as common, given its `course.config.ts`
+ * `operators` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} operators
+ * @returns {Set<string>}
+ */
+export function effectiveOperatorAllowlist(operators) {
+  const allow = operators?.allow ?? [];
+  const deny = new Set(operators?.deny ?? []);
+  const effective = new Set(BASE_OPERATORS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `name` needs no notation entry for this course. */
+export function isBaseOperator(name, operators) {
+  return effectiveOperatorAllowlist(operators).has(name);
+}

package/dist/reference/consistency.d.ts

@@ -1,4 +1,4 @@
-import { CourseConventions } from '../compiler/course-config.js';
+import { CourseConventions, CourseOperators } from '../compiler/course-config.js';
 import { CurriculumCatalog } from '../curriculum/validation.js';
 import { NotationSpec } from '../compiler/collections.js';
 import { LintIgnore } from './lint-ignore.js';
@@ -25,12 +25,15 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  *   (f) weak-local                   a `notation.local` symbol used only in its
  *                                     own defining equation and prose
  *   (g) notation-source-locator      every notation `sources` entry has a locator
+ *   (h) operator-explained           a named operator a lesson uses is on the
+ *                                     shipped/course operator allowlist or
+ *                                     carries a notation entry (rule N8)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — every finding here is a warning until content is brought clean. */
@@ -51,6 +54,8 @@ interface ConsistencyInput {
     readonly lintIgnore: LintIgnore;
     /** Convention keys this course anchors on (from `content/course.config.ts`). */
     readonly conventions: CourseConventions;
+    /** This course's edits to the named-operator baseline (rule N8). */
+    readonly operators?: CourseOperators;
 }
 /**
  * Run every consistency check. The result is sorted deterministically (code,

package/dist/reference/consistency.js

@@ -1,3 +1,5 @@
+import { effectiveOperatorAllowlist } from "./base-operators.mjs";
+import { collectOperators } from "./math-glyphs.mjs";
 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) {
@@ -285,6 +287,51 @@ function checkGlossNameShape(input, out) {
     }
   }
 }
+function checkOperatorExplained(input, out) {
+  const allowlist = effectiveOperatorAllowlist(input.operators);
+  const byId = new Map(
+    input.registry.definitions.map((definition) => [definition.id, definition])
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings])
+  );
+  for (const lesson of input.notationInput.lessons) {
+    const explained = /* @__PURE__ */ new Set();
+    const noteEntryOperators = (latex) => {
+      for (const operator of collectOperators(latex)) {
+        explained.add(operator.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryOperators(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryOperators(definition.notation);
+    }
+    const reported = /* @__PURE__ */ new Set();
+    for (const span of mathSpans(lesson.body)) {
+      for (const operator of collectOperators(span.latex)) {
+        if (allowlist.has(operator.name)) continue;
+        if (explained.has(operator.name)) continue;
+        if (reported.has(operator.name)) continue;
+        reported.add(operator.name);
+        if (input.lintIgnore.matches("operator-explained", operator.name)) {
+          continue;
+        }
+        const display = operator.source === "operatorname" ? `\\operatorname{${operator.name}}` : `\\${operator.name}`;
+        out.push({
+          code: "operator-explained",
+          severity: "warning",
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: operator.name,
+          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to operators.allow in course.config.ts`
+        });
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
@@ -294,7 +341,8 @@ const CHECKS = [
   checkNotationSourceLocator,
   checkGlossWantsPromoting,
   checkCardWantsDemoting,
-  checkGlossNameShape
+  checkGlossNameShape,
+  checkOperatorExplained
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -314,7 +362,8 @@ function consistencyCounts(diagnostics) {
     "notation-source-locator": 0,
     "gloss-wants-promoting": 0,
     "card-wants-demoting": 0,
-    "gloss-name-shape": 0
+    "gloss-name-shape": 0,
+    "operator-explained": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/dist/reference/diagram-layout.d.ts

@@ -0,0 +1,63 @@
+interface DiagramNodeInput {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+}
+interface DiagramEdgeInput {
+    readonly from: string;
+    readonly to: string;
+}
+interface DiagramLayoutOptions {
+    /** Top-to-bottom (default) or left-to-right. */
+    readonly direction?: 'TB' | 'LR';
+    readonly nodeSeparation?: number;
+    readonly rankSeparation?: number;
+    /** Uniform padding added around the computed bounding box. */
+    readonly padding?: number;
+}
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+interface LaidOutNode {
+    readonly id: string;
+    /** Top-left corner, not the center dagre itself works in. */
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface LaidOutEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly points: readonly Point[];
+}
+interface DiagramLayout {
+    readonly nodes: readonly LaidOutNode[];
+    readonly edges: readonly LaidOutEdge[];
+    /** The SVG canvas size a caller should use as the `viewBox`. */
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Lay out a small directed graph. Node ids must be unique; an edge naming an
+ * undeclared node fails loudly rather than silently dropping it (dagre itself
+ * would otherwise create a phantom zero-size node).
+ */
+declare function layoutDiagram(nodes: readonly DiagramNodeInput[], edges: readonly DiagramEdgeInput[], options?: DiagramLayoutOptions): DiagramLayout;
+interface BoxSizeEstimate {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Estimate a diagram node's box from its label text (or raw, pre-resolution
+ * LaTeX for a formula node). Deliberately generous: it is meant to avoid
+ * clipping, not to match a real render pixel-for-pixel. Pass an explicit
+ * `width`/`height` on the node to override for a label this estimate gets
+ * badly wrong.
+ */
+declare function estimateBoxSize(content: string, kind: 'text' | 'formula', options?: {
+    readonly maxWidth?: number;
+}): BoxSizeEstimate;
+
+export { type BoxSizeEstimate, type DiagramEdgeInput, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodeInput, type LaidOutEdge, type LaidOutNode, type Point, estimateBoxSize, layoutDiagram };