explico 0.12.0 → 0.13.0

package/dist/compiler/exports/markdown-export.js

@@ -0,0 +1,240 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { courseFileStem } from "./export-pages.js";
+import {
+  consoleLogger,
+  diagramsOf,
+  figuresOf,
+  imageExtension,
+  imageFile,
+  imagesOf,
+  needsCapture,
+  prepareChapters,
+  readBuiltPage
+} from "./export-chapters.js";
+import { checkItems } from "./latex/document.js";
+import { serializeMarkdownNodes, serializeMarkdownPage } from "./markdown/serialize.js";
+import { zip } from "./zip.js";
+async function pagePictures(outputRoot, base, page, captured, assetDir) {
+  const pictures = /* @__PURE__ */ new Map();
+  const copy = async (key, src, name) => {
+    const file = imageFile(outputRoot, base, page.route, src);
+    pictures.set(key, { path: `${assetDir}/${name}${extname(file).toLowerCase()}`, content: await readFile(file) });
+  };
+  for (const figure of figuresOf(page.blocks)) {
+    if (figure.picture.kind === "image" && (!needsCapture(figure) || imageExtension(figure.picture.src) === ".svg")) {
+      await copy(figure.anchor, figure.picture.src, figure.anchor);
+      continue;
+    }
+    const png = captured?.get(figure.anchor)?.png;
+    if (png) pictures.set(figure.anchor, { path: `${assetDir}/${figure.anchor}.png`, content: png });
+  }
+  for (const diagram of diagramsOf(page.blocks)) {
+    const png = captured?.get(diagram.anchor)?.png;
+    if (png) pictures.set(diagram.anchor, { path: `${assetDir}/${diagram.anchor}.png`, content: png });
+  }
+  for (const image of imagesOf(page.blocks)) {
+    if (pictures.has(image.src)) continue;
+    const name = basename(new URL(image.src, "https://x.invalid/").pathname, extname(image.src)) || "image";
+    await copy(image.src, image.src, name);
+  }
+  return pictures;
+}
+function twoDigits(value) {
+  return String(value).padStart(2, "0");
+}
+function chapterFile(lesson) {
+  return `${twoDigits(lesson.part)}-${twoDigits(lesson.chapter)}-${lesson.slug.split("/").at(-1) ?? lesson.slug}.md`;
+}
+function partFile(part) {
+  return `${twoDigits(part.ordinal)}-00-${part.dir}.md`;
+}
+function relativeTo(files, route) {
+  return new Map([...files].map(([key, file]) => [key, key === route ? "" : file]));
+}
+async function writeMarkdownExports(directory, manifest, options = {}) {
+  if (!manifest.lessonExports.markdown) return;
+  const logger = options.logger ?? consoleLogger;
+  const outputRoot = fileURLToPath(directory);
+  const { base, chapters, captures } = options.prepared ?? await prepareChapters(outputRoot, manifest, { logger, projectRoot: options.projectRoot });
+  const canonicalBaseUrl = manifest.lessonExports.canonicalBaseUrl;
+  const course = manifest.about.material.name;
+  const version = manifest.about.knowledge.version;
+  const source = (route) => ({
+    course,
+    version,
+    ...canonicalBaseUrl ? { url: `${canonicalBaseUrl}${route ? `${route}/` : ""}` } : {}
+  });
+  const chapterFiles = async (chapter, file, assetDir, documentFiles) => {
+    const { lesson, page } = chapter;
+    const pictures = await pagePictures(outputRoot, base, page, captures.get(page.route), assetDir);
+    const markdown = serializeMarkdownPage(
+      {
+        page,
+        documentFiles: relativeTo(documentFiles, page.route),
+        ...canonicalBaseUrl ? { canonicalBaseUrl } : {},
+        pictures: new Map([...pictures].map(([key, picture]) => [key, picture.path])),
+        checkItems: checkItems(manifest, lesson),
+        source: source(page.route)
+      },
+      { number: `${lesson.part}.${lesson.chapter}` }
+    );
+    return [
+      { path: file, content: markdown },
+      ...[...pictures.values()].map((picture) => ({ path: picture.path, content: picture.content }))
+    ];
+  };
+  const pending = [];
+  const pack = (target, folder, entries) => {
+    const unique = new Map(entries.map((entry) => [entry.path, entry]));
+    pending.push({
+      target: join(outputRoot, "downloads", target),
+      content: zip([...unique.values()].map((entry) => ({ path: `${folder}/${entry.path}`, content: entry.content })))
+    });
+  };
+  for (const chapter of chapters) {
+    const name = chapter.lesson.slug.split("/").at(-1) ?? chapter.lesson.slug;
+    pack(
+      `${chapter.lesson.slug}-markdown.zip`,
+      `${name}-markdown`,
+      await chapterFiles(chapter, "lesson.md", "assets", /* @__PURE__ */ new Map([[chapter.page.route, "lesson.md"]]))
+    );
+  }
+  const byId = new Map(chapters.map((chapter) => [chapter.lesson.id, chapter]));
+  const pageSlugs = new Set(manifest.pages.map((page) => page.slug));
+  const parts = manifest.parts.map((part) => ({
+    part,
+    chapters: part.lessons.flatMap((id) => byId.has(id) ? [byId.get(id)] : []),
+    overview: pageSlugs.has(`${part.dir}/index`) ? `${part.dir}/index` : void 0
+  })).filter((entry) => entry.chapters.length > 0);
+  const overviewMarkdown = async (entry, documentFiles, assetDir) => {
+    if (!entry.overview) {
+      return { markdown: serializeMarkdownNodes([{ type: "heading", depth: 1, children: [{ type: "text", value: entry.part.label }] }]), pictures: [] };
+    }
+    const { page } = await readBuiltPage(outputRoot, entry.overview);
+    const pictures = await pagePictures(outputRoot, base, page, void 0, assetDir);
+    const markdown = serializeMarkdownPage(
+      {
+        page,
+        documentFiles: relativeTo(documentFiles, page.route),
+        ...canonicalBaseUrl ? { canonicalBaseUrl } : {},
+        pictures: new Map([...pictures].map(([key, picture]) => [key, picture.path])),
+        checkItems: /* @__PURE__ */ new Map(),
+        source: source(page.route)
+      },
+      { number: `Part ${entry.part.ordinal}:` }
+    );
+    return { markdown, pictures: [...pictures.values()].map((picture) => ({ path: picture.path, content: picture.content })) };
+  };
+  const contents = (entry, files) => entry.chapters.map((chapter) => ({
+    type: "listItem",
+    spread: false,
+    children: [
+      {
+        type: "paragraph",
+        children: [
+          {
+            type: "link",
+            url: files.get(chapter.page.route) ?? "",
+            children: [{ type: "text", value: `${chapter.lesson.part}.${chapter.lesson.chapter} ${chapter.page.title}` }]
+          }
+        ]
+      }
+    ]
+  }));
+  for (const entry of parts) {
+    const files = new Map([
+      ...entry.overview ? [[entry.part.dir, "index.md"]] : [],
+      ...entry.chapters.map((chapter) => [chapter.page.route, chapterFile(chapter.lesson)])
+    ]);
+    const overview = await overviewMarkdown(entry, files, "assets/index");
+    const index = `${overview.markdown}
+` + serializeMarkdownNodes([
+      { type: "heading", depth: 2, children: [{ type: "text", value: "Contents" }] },
+      { type: "list", ordered: false, spread: false, children: contents(entry, files) }
+    ]);
+    const entries = [{ path: "index.md", content: index }, ...overview.pictures];
+    for (const chapter of entry.chapters) {
+      const file = chapterFile(chapter.lesson);
+      entries.push(...await chapterFiles(chapter, file, `assets/${file.replace(/\.md$/u, "")}`, files));
+    }
+    pack(`part/${entry.part.dir}-markdown.zip`, `${entry.part.dir}-markdown`, entries);
+  }
+  if (parts.length > 0) {
+    const files = new Map([
+      ["", "index.md"],
+      ...parts.flatMap((entry) => [
+        ...entry.overview ? [[entry.part.dir, partFile(entry.part)]] : [],
+        ...entry.chapters.map((chapter) => [chapter.page.route, chapterFile(chapter.lesson)])
+      ])
+    ]);
+    const entries = [];
+    for (const entry of parts) {
+      if (entry.overview) {
+        const file = partFile(entry.part);
+        const overview = await overviewMarkdown(entry, files, `assets/${file.replace(/\.md$/u, "")}`);
+        entries.push({ path: file, content: overview.markdown }, ...overview.pictures);
+      }
+      for (const chapter of entry.chapters) {
+        const file = chapterFile(chapter.lesson);
+        entries.push(...await chapterFiles(chapter, file, `assets/${file.replace(/\.md$/u, "")}`, files));
+      }
+    }
+    const index = serializeMarkdownNodes([
+      { type: "heading", depth: 1, children: [{ type: "text", value: course }] },
+      {
+        type: "paragraph",
+        children: [
+          { type: "text", value: `Content version ${version}.` },
+          ...canonicalBaseUrl ? [
+            { type: "text", value: " Interactive version: " },
+            { type: "link", url: canonicalBaseUrl, children: [{ type: "text", value: canonicalBaseUrl }] },
+            { type: "text", value: "." }
+          ] : []
+        ]
+      },
+      ...manifest.about.material.summary ? [{ type: "paragraph", children: [{ type: "text", value: manifest.about.material.summary }] }] : [],
+      { type: "heading", depth: 2, children: [{ type: "text", value: "Contents" }] },
+      {
+        type: "list",
+        ordered: false,
+        spread: false,
+        children: parts.map((entry) => ({
+          type: "listItem",
+          spread: false,
+          children: [
+            {
+              type: "paragraph",
+              children: entry.overview ? [
+                {
+                  type: "link",
+                  url: partFile(entry.part),
+                  children: [{ type: "text", value: `Part ${entry.part.ordinal}: ${entry.part.label}` }]
+                }
+              ] : [{ type: "text", value: `Part ${entry.part.ordinal}: ${entry.part.label}` }]
+            },
+            { type: "list", ordered: false, spread: false, children: contents(entry, files) }
+          ]
+        }))
+      }
+    ]);
+    entries.push({ path: "index.md", content: index });
+    pack("course-markdown.zip", `${courseFileStem(manifest)}-markdown`, entries);
+  }
+  try {
+    for (const file of pending) {
+      await mkdir(dirname(file.target), { recursive: true });
+      await writeFile(`${file.target}.tmp-${process.pid}`, file.content);
+    }
+    for (const file of pending) await rename(`${file.target}.tmp-${process.pid}`, file.target);
+  } finally {
+    await Promise.all(pending.map((file) => rm(`${file.target}.tmp-${process.pid}`, { force: true })));
+  }
+  logger.info(
+    `Markdown export: ${chapters.length} chapter(s), ${parts.length} part(s)` + (parts.length > 0 ? " and the course" : "") + "."
+  );
+}
+export {
+  writeMarkdownExports
+};

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

@@ -1,11 +1,12 @@
 import { Manifest } from '../manifest.js';
 import '../../curriculum/validation.js';
 import '../../reference/consistency.js';
-import '../../course-config-Dsnri9Tk.js';
+import '../../course-config-rRtME5UV.js';
 import '../../rules/catalog.js';
 import '../../rules/course-rules.js';
 import '../collections.js';
 import '../../reference/types.js';
+import '../../reference/gate-retired-keys.js';
 import '../../reference/lint-ignore.js';
 import '../../reference/equations-validate.js';
 import '../../reference/tables-validate.js';
@@ -24,17 +25,25 @@ import '../../rules/waivers.js';
 import '../knowledge-version.js';
 import '../lesson-derivation.js';
 
-/** Inputs for producing one standalone lesson from Astro's final HTML. */
+/** Inputs for producing one standalone page from Astro's final HTML. */
 interface StandaloneLessonInput {
     readonly html: string;
     readonly sourceFile: string;
     readonly outputRoot: string;
+    /** The page's docs slug: a chapter's, or `index`, `motion/index`, `glossary`. */
     readonly lessonSlug: string;
     readonly canonicalBaseUrl?: string;
 }
-/** Build one fully inlined lesson document without writing it. */
+/** Build one fully inlined page document without writing it. */
 declare function buildStandaloneLessonHtml(input: StandaloneLessonInput): Promise<string>;
-/** Emit all opt-in lesson HTML artifacts from Astro's completed static output. */
+/** Astro's built HTML file of a docs slug. */
+declare function pageSourceFile(outputRoot: string, slug: string): Promise<string>;
+/**
+ * Emit the opt-in standalone HTML artifact of every chapter
+ * (`standalonePageSlugs`) from Astro's completed static output, at
+ * `downloads/<docs slug>.html`. A page that is not a chapter is in its
+ * part's and the course's files (`combined-html.ts`).
+ */
 declare function writeStandaloneLessonExports(directory: URL, manifest: Manifest): Promise<void>;
 
-export { type StandaloneLessonInput, buildStandaloneLessonHtml, writeStandaloneLessonExports };
+export { type StandaloneLessonInput, buildStandaloneLessonHtml, pageSourceFile, writeStandaloneLessonExports };

package/dist/compiler/exports/standalone-html.js

@@ -9,10 +9,14 @@ import {
 import { Buffer } from "node:buffer";
 import { dirname, extname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parse, serialize } from "parse5";
+import { exportPageRoute, standalonePageSlugs } from "./export-pages.js";
 import {
-  parse,
-  serialize
-} from "parse5";
+  attribute,
+  elements,
+  hasClass,
+  inferBasePrefix
+} from "./html-tree.js";
 const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
 const CSS_URL = /url\(\s*(?:(["'])(.*?)\1|([^)]*?))\s*\)/giu;
 const CSS_IMPORT = /@import\s+(?:url\(\s*(?:(["'])(.*?)\1|([^)]*?))\s*\)|(["'])(.*?)\4)\s*([^;]*);/giu;
@@ -98,38 +102,11 @@ const STANDALONE_THEME_SCRIPT = `(() => {
   });
   apply('auto');
 })();`;
-function isElement(node) {
-  return "tagName" in node;
-}
-function childrenOf(node) {
-  return "childNodes" in node ? node.childNodes : [];
-}
-function walk(node, visit) {
-  visit(node);
-  for (const child of childrenOf(node)) walk(child, visit);
-  if (isElement(node) && node.tagName === "template") {
-    const template = node;
-    for (const child of template.content.childNodes) walk(child, visit);
-  }
-}
-function elements(root, predicate) {
-  const found = [];
-  walk(root, (node) => {
-    if (isElement(node) && (predicate?.(node) ?? true)) found.push(node);
-  });
-  return found;
-}
 function firstElement(root, tagName) {
   const found = elements(root, (node) => node.tagName === tagName)[0];
   if (!found) throw new Error(`Standalone HTML source has no <${tagName}> element.`);
   return found;
 }
-function attribute(node, name) {
-  return node.attrs.find((entry) => entry.name === name)?.value;
-}
-function hasClass(node, name) {
-  return (attribute(node, "class") ?? "").split(/\s+/u).includes(name);
-}
 function setAttribute(node, name, value = "") {
   const existing = node.attrs.find((entry) => entry.name === name);
   if (existing) existing.value = value;
@@ -392,7 +369,7 @@ async function bundleBrowserGraph(entryPaths, requests, context) {
   });
   const javascript = result.outputFiles.find((file) => file.path.endsWith(".js"));
   if (!javascript) {
-    throw new Error("Browser bundler produced no JavaScript for the standalone lesson.");
+    throw new Error("Browser bundler produced no JavaScript for the standalone page.");
   }
   const unsupported = result.outputFiles.filter(
     (file) => !file.path.endsWith(".js") && !file.path.endsWith(".css")
@@ -408,17 +385,6 @@ async function bundleBrowserGraph(entryPaths, requests, context) {
     css: result.outputFiles.filter((file) => file.path.endsWith(".css")).map((file) => file.text)
   };
 }
-function inferBasePrefix(document) {
-  for (const node of elements(document)) {
-    for (const name of ["href", "src", "component-url", "renderer-url"]) {
-      const value = attribute(node, name);
-      if (!value?.startsWith("/")) continue;
-      const marker = value.indexOf("/astro-assets/");
-      if (marker !== -1) return `${value.slice(0, marker)}/`;
-    }
-  }
-  return "/";
-}
 function normalizedPagePath(pathname) {
   return pathname.replace(/\/index\.html$/iu, "/").replace(/\.html$/iu, "").replace(/\/+$/u, "");
 }
@@ -429,14 +395,17 @@ function rewriteCourseLink(href, lessonSlug, basePrefix, canonicalBaseUrl) {
   if (hasScheme(trimmed)) {
     throw new Error(`Standalone HTML cannot publish local navigation URL ${JSON.stringify(href)}.`);
   }
-  const pagePath = `${basePrefix}${lessonSlug}/`.replace(/\/{2,}/gu, "/");
+  const pagePath = `${basePrefix}${exportPageRoute(lessonSlug)}/`.replace(
+    /\/{2,}/gu,
+    "/"
+  );
   const resolved = new URL(trimmed, `https://explico.invalid${pagePath}`);
   if (normalizedPagePath(resolved.pathname) === normalizedPagePath(pagePath)) {
     return `${resolved.search}${resolved.hash}` || "#_top";
   }
   if (!canonicalBaseUrl) {
     throw new Error(
-      `Lesson ${lessonSlug} links outside itself (${JSON.stringify(href)}), so \`lessonExports.canonicalBaseUrl\` is required for standalone HTML.`
+      `Page ${lessonSlug} links outside itself (${JSON.stringify(href)}), so \`lessonExports.canonicalBaseUrl\` is required for standalone HTML.`
     );
   }
   let coursePath = resolved.pathname;
@@ -751,7 +720,7 @@ async function buildStandaloneLessonHtml(input) {
   const outputRoot = resolve(input.outputRoot);
   const sourceFile = resolve(input.sourceFile);
   if (!insideRoot(sourceFile, outputRoot)) {
-    throw new Error("Standalone lesson source must be inside Astro build output.");
+    throw new Error("Standalone page source must be inside Astro build output.");
   }
   const context = {
     outputRoot,
@@ -778,8 +747,10 @@ async function buildStandaloneLessonHtml(input) {
   auditStandaloneHtml(html, input.lessonSlug);
   return html;
 }
-async function lessonSourceFile(outputRoot, slug) {
-  const candidates = [join(outputRoot, slug, "index.html"), join(outputRoot, `${slug}.html`)];
+async function pageSourceFile(outputRoot, slug) {
+  const route = exportPageRoute(slug);
+  const candidates = [join(outputRoot, route, "index.html")];
+  if (route) candidates.push(join(outputRoot, `${route}.html`));
   for (const candidate of candidates) if (await isFile(candidate)) return candidate;
   throw new Error(
     `Standalone HTML could not find Astro's built page for ${slug}; tried ` + candidates.map((path) => relative(outputRoot, path)).join(", ")
@@ -789,9 +760,9 @@ async function writeStandaloneLessonExports(directory, manifest) {
   if (!manifest.lessonExports.standaloneHtml) return;
   const outputRoot = fileURLToPath(directory);
   const pending = [];
-  for (const lesson of manifest.lessons) {
-    const sourceFile = await lessonSourceFile(outputRoot, lesson.slug);
-    const target = join(outputRoot, "downloads", `${lesson.slug}.html`);
+  for (const slug of standalonePageSlugs(manifest)) {
+    const sourceFile = await pageSourceFile(outputRoot, slug);
+    const target = join(outputRoot, "downloads", `${slug}.html`);
     pending.push({
       target,
       temporary: `${target}.tmp-${process.pid}`,
@@ -799,7 +770,7 @@ async function writeStandaloneLessonExports(directory, manifest) {
         html: await readFile(sourceFile, "utf8"),
         sourceFile,
         outputRoot,
-        lessonSlug: lesson.slug,
+        lessonSlug: slug,
         canonicalBaseUrl: manifest.lessonExports.canonicalBaseUrl
       })
     });
@@ -812,5 +783,6 @@ async function writeStandaloneLessonExports(directory, manifest) {
 }
 export {
   buildStandaloneLessonHtml,
+  pageSourceFile,
   writeStandaloneLessonExports
 };

package/dist/compiler/exports/static-tree.d.ts

@@ -0,0 +1,253 @@
+import { HtmlElement, HtmlNode } from './html-tree.js';
+import 'parse5';
+
+/**
+ * explico's static reading tree: a built page reduced to what a reader reads,
+ * with explico's meaning kept — a float with its number and captions, a
+ * cross-reference by its target, a check by its anchor. Print exporters (the
+ * LaTeX source now, Markdown later) serialize this tree; none of them
+ * re-walks `content/` or recomputes a number.
+ *
+ * It is read off Astro's static output, where every disclosure's body, every
+ * table row and every formula's TeX already sit in the markup, whatever the
+ * reader would see collapsed. What the static page does not hold — a lab's
+ * drawing, a check's answers — comes from the capture pass and the manifest.
+ *
+ * Math keeps the author's `\explain{key}{…}` and `\slot{key}{…}` markers (the
+ * KaTeX annotation, not the stripped `data-latex`): a printer that understands
+ * them (explico's LaTeX class) needs no stripping, and one that doesn't strips
+ * them itself.
+ */
+type RefKind = 'equation' | 'figure' | 'table' | 'diagram' | 'section' | 'example' | 'check' | 'memo' | 'anchor' | 'page';
+/** A link target inside the course: a page route (base-relative, no slashes at the ends) and an anchor. */
+interface CourseTarget {
+    readonly route: string;
+    readonly anchor: string;
+}
+type Inline = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'emphasis';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'strong';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'superscript';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'subscript';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'code';
+    readonly value: string;
+} | {
+    readonly kind: 'math';
+    readonly tex: string;
+} | {
+    readonly kind: 'break';
+} | {
+    readonly kind: 'link';
+    readonly href: string;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'ref';
+    readonly refKind: RefKind;
+    readonly target: CourseTarget;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'term';
+    readonly key: string;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'cite';
+    readonly number: string;
+    readonly anchor: string;
+    readonly sourceId?: string;
+    readonly locator?: string;
+} | {
+    readonly kind: 'memoMark';
+    readonly anchor: string;
+    readonly label: string;
+} | {
+    readonly kind: 'noteMark';
+    readonly anchor: string;
+    readonly children: readonly Inline[];
+};
+interface TableCell {
+    readonly header: boolean;
+    readonly colspan: number;
+    readonly rowspan: number;
+    readonly align?: 'left' | 'center' | 'right';
+    readonly children: readonly Inline[];
+}
+interface DiagramNodeShape {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly radius: number;
+    readonly text?: string;
+    readonly tex?: string;
+}
+interface DiagramGeometry {
+    readonly width: number;
+    readonly height: number;
+    readonly nodes: readonly DiagramNodeShape[];
+    /** Each edge as its polyline, start to end; the arrowhead sits at the end. */
+    readonly edges: readonly (readonly (readonly [number, number])[])[];
+}
+/** What a figure shows: an image file, or something only a browser can draw. */
+type FigurePicture = {
+    readonly kind: 'image';
+    readonly src: string;
+    readonly alt: string;
+} | {
+    readonly kind: 'diagram';
+    readonly geometry: DiagramGeometry;
+} | {
+    readonly kind: 'capture';
+};
+interface FloatBase {
+    /** The float's anchor id on its page (`fig-…`, `tab-…`, `dia-…`). */
+    readonly anchor: string;
+    readonly number: string;
+    readonly key?: string;
+    readonly short?: string;
+    /** The long caption. */
+    readonly caption: readonly Inline[];
+}
+type Block = {
+    readonly kind: 'heading';
+    readonly level: number;
+    readonly anchor?: string;
+    readonly number?: string;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'paragraph';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'list';
+    readonly ordered: boolean;
+    readonly start?: number;
+    readonly items: readonly (readonly Block[])[];
+} | {
+    readonly kind: 'equation';
+    readonly anchor: string;
+    readonly number: string;
+    readonly key?: string;
+    readonly tex: string;
+} | {
+    readonly kind: 'displayMath';
+    readonly tex: string;
+} | (FloatBase & {
+    readonly kind: 'figure';
+    /** The live clause a lab writes after its caption; empty in the static page. */
+    readonly live: readonly Inline[];
+    readonly picture: FigurePicture;
+    /** The lab's own accessible label, when it gives one. */
+    readonly alt?: string;
+}) | (FloatBase & {
+    readonly kind: 'table';
+    readonly head: readonly (readonly TableCell[])[];
+    readonly body: readonly (readonly TableCell[])[];
+}) | (FloatBase & {
+    readonly kind: 'diagram';
+    readonly geometry: DiagramGeometry;
+}) | {
+    readonly kind: 'memo';
+    readonly anchor: string;
+    readonly label: string;
+    readonly short?: string;
+    readonly title: readonly Inline[];
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'note';
+    readonly anchor: string;
+    readonly title: string;
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'aside';
+    readonly variant: string;
+    readonly title: readonly Inline[];
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'fold';
+    readonly title?: readonly Inline[];
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'examples';
+    readonly anchor: string;
+    readonly number: string;
+    readonly title: readonly Inline[];
+    readonly items: readonly {
+        readonly title: readonly Inline[];
+        readonly children: readonly Block[];
+    }[];
+} | {
+    readonly kind: 'check';
+    readonly anchor: string;
+    readonly number: string;
+    readonly assessmentId: string;
+    readonly title: readonly Inline[];
+} | {
+    readonly kind: 'quote';
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'image';
+    readonly src: string;
+    readonly alt: string;
+} | {
+    readonly kind: 'code';
+    readonly value: string;
+} | {
+    readonly kind: 'rule';
+} | {
+    readonly kind: 'references';
+    readonly items: readonly {
+        readonly number: string;
+        readonly anchor: string;
+        readonly children: readonly Inline[];
+    }[];
+};
+interface NotationEntry {
+    readonly key: string;
+    readonly anchor: string;
+    readonly symbolTex?: string;
+    readonly label: readonly Inline[];
+    readonly summary: readonly Inline[];
+    readonly units?: readonly Inline[];
+    readonly formulaTex?: string;
+}
+interface StaticPage {
+    /** The page's docs slug, e.g. `projectiles/optimal-launch-angle`. */
+    readonly slug: string;
+    /** Base-relative route of the page, e.g. `projectiles/optimal-launch-angle`. */
+    readonly route: string;
+    readonly title: string;
+    readonly blocks: readonly Block[];
+    /** "Notation used on this page", in the page's order. */
+    readonly notation: readonly NotationEntry[];
+    /** The notation list's page-specific remarks ("On this page, ′ is not an operator …"). */
+    readonly notationRemarks: readonly (readonly Inline[])[];
+}
+interface ReadContext {
+    readonly route: string;
+    readonly base: string;
+}
+/** All text below `node`, as a reader sees it: no screen-reader-only or hidden helpers. */
+declare function readableText(node: HtmlNode): string;
+/** Resolve a link to a course target, or `undefined` when it leaves the course. */
+declare function courseTarget(href: string, context: ReadContext): CourseTarget | undefined;
+/** Node boxes and edge polylines of a built `<Diagram>`'s SVG. */
+declare function readDiagramGeometry(figure: HtmlElement): DiagramGeometry | undefined;
+/**
+ * Inline content from an HTML fragment of a page — a lab's live caption
+ * clause, which only exists once the lab has run.
+ */
+declare function readInlineFragment(html: string, route: string, base?: string): Inline[];
+/** Read the static reading tree of one built page. */
+declare function readStaticPage(html: string, slug: string, route: string): StaticPage;
+
+export { type Block, type CourseTarget, type DiagramGeometry, type DiagramNodeShape, type FigurePicture, type Inline, type NotationEntry, type RefKind, type StaticPage, type TableCell, courseTarget, readDiagramGeometry, readInlineFragment, readStaticPage, readableText };