explico 0.11.1 → 0.13.0

package/dist/compiler/exports/export-chapters.d.ts

@@ -0,0 +1,98 @@
+import { ManifestLesson, Manifest } from '../manifest.js';
+import { StaticPage, Block } from './static-tree.js';
+import { CaptureResults } from './latex/capture.js';
+import '../../curriculum/validation.js';
+import '../../reference/consistency.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';
+import '../../reference/keyed-float-validate.js';
+import '../../reference/figures-validate.js';
+import '../../reference/diagrams-validate.js';
+import '../../reference/examples-validate.js';
+import '../../reference/folds-validate.js';
+import '../../reference/knowledge-checks-validate.js';
+import '../../reference/raw-floats-validate.js';
+import '../../reference/lab-katex-validate.js';
+import '../../reference/gate-math.js';
+import '../../reference/mixed-content.js';
+import '../../reference/gloss.js';
+import '../../rules/waivers.js';
+import '../knowledge-version.js';
+import '../lesson-derivation.js';
+import './html-tree.js';
+import 'parse5';
+
+/**
+ * What the print exporters (LaTeX, Markdown) share: every chapter's static
+ * reading tree, read once from Astro's output, and one capture pass that
+ * draws what only a browser can — a lab, a course component's SVG, and for
+ * Markdown an explico `<Diagram>` — as vector PDF and, for Markdown, PNG.
+ */
+interface ExportLogger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+declare const consoleLogger: ExportLogger;
+/** In CI or with `EXPLICO_LATEX_STRICT=1`, a missing engine or browser fails the build. */
+declare function strictMode(): boolean;
+/** The content date as seconds since 1970: every export's timestamps. */
+declare function epochOf(manifest: Pick<Manifest, 'about'>): number;
+type FigureBlock = Extract<Block, {
+    kind: 'figure';
+}>;
+type DiagramBlock = Extract<Block, {
+    kind: 'diagram';
+}>;
+declare function figuresOf(blocks: readonly Block[]): FigureBlock[];
+declare function diagramsOf(blocks: readonly Block[]): DiagramBlock[];
+/** Every inline `image` block, in reading order. */
+declare function imagesOf(blocks: readonly Block[]): Extract<Block, {
+    kind: 'image';
+}>[];
+/** The image file a URL names, by extension. */
+declare function imageExtension(src: string): string;
+/** Whether a figure is drawn by the browser rather than included as a file. */
+declare function needsCapture(figure: FigureBlock): boolean;
+/** The built file an image URL on a page names. */
+declare function imageFile(outputRoot: string, base: string, route: string, src: string): string;
+/** The page with each captured lab's live caption clause filled in. */
+declare function withLiveClauses(page: StaticPage, captured: ReadonlyMap<string, {
+    liveHtml: string;
+}>, base: string): StaticPage;
+interface PreparedChapter {
+    readonly lesson: ManifestLesson;
+    /** The chapter's reading tree, its labs' live caption clauses filled in. */
+    readonly page: StaticPage;
+}
+interface PreparedChapters {
+    /** The site's base path, `/` or `/course/`. */
+    readonly base: string;
+    readonly chapters: readonly PreparedChapter[];
+    /** What the capture pass drew, by route and anchor. */
+    readonly captures: CaptureResults;
+}
+/** Read one built page into its reading tree. */
+declare function readBuiltPage(outputRoot: string, slug: string): Promise<{
+    html: string;
+    page: StaticPage;
+}>;
+/**
+ * Read every chapter and draw its figures once, for whichever print exports
+ * the course has on: a figure the browser draws for LaTeX (as vector PDF)
+ * and for Markdown (as PNG too), and for Markdown each `<Diagram>`, which
+ * LaTeX draws itself as TikZ. Without Playwright's Chromium the figures stay
+ * placeholders, with a warning — or, in CI, the build fails.
+ */
+declare function prepareChapters(outputRoot: string, manifest: Manifest, options?: {
+    readonly logger?: ExportLogger;
+    readonly projectRoot?: string;
+}): Promise<PreparedChapters>;
+
+export { type ExportLogger, type PreparedChapter, type PreparedChapters, consoleLogger, diagramsOf, epochOf, figuresOf, imageExtension, imageFile, imagesOf, needsCapture, prepareChapters, readBuiltPage, strictMode, withLiveClauses };

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

@@ -0,0 +1,164 @@
+import { readFile } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+import { parse } from "parse5";
+import { inferBasePrefix } from "./html-tree.js";
+import { readInlineFragment, readStaticPage } from "./static-tree.js";
+import {
+  captureFigures,
+  courseChromium,
+  figureMeasure,
+  LABEL_PT
+} from "./latex/capture.js";
+const consoleLogger = {
+  info: (message) => console.log(message),
+  warn: (message) => console.warn(message)
+};
+function strictMode() {
+  const ci = process.env.CI;
+  return !!ci && ci !== "false" && ci !== "0" || process.env.EXPLICO_LATEX_STRICT === "1";
+}
+function epochOf(manifest) {
+  const date = manifest.about.knowledge.date;
+  const parsed = date ? Date.parse(`${date}T00:00:00Z`) : Number.NaN;
+  return Number.isFinite(parsed) ? Math.floor(parsed / 1e3) : 0;
+}
+function blocksOf(blocks, kind) {
+  const found = [];
+  const visit = (list) => {
+    for (const block of list) {
+      if (block.kind === kind) found.push(block);
+      if (block.kind === "list") block.items.forEach(visit);
+      if (block.kind === "examples") block.items.forEach((item) => visit(item.children));
+      if ("children" in block && block.kind !== "paragraph" && block.kind !== "heading" && Array.isArray(block.children)) {
+        visit(block.children);
+      }
+    }
+  };
+  visit(blocks);
+  return found;
+}
+function figuresOf(blocks) {
+  return blocksOf(blocks, "figure");
+}
+function diagramsOf(blocks) {
+  return blocksOf(blocks, "diagram");
+}
+function imagesOf(blocks) {
+  return blocksOf(blocks, "image");
+}
+const INCLUDABLE_IMAGES = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".pdf"]);
+function imageExtension(src) {
+  return extname(new URL(src, "https://x.invalid/").pathname).toLowerCase();
+}
+function needsCapture(figure) {
+  if (figure.picture.kind === "capture") return true;
+  if (figure.picture.kind === "image") return !INCLUDABLE_IMAGES.has(imageExtension(figure.picture.src));
+  return false;
+}
+function imageFile(outputRoot, base, route, src) {
+  const url = new URL(src, `https://x.invalid${base}${route ? `${route}/` : ""}`);
+  let path = decodeURIComponent(url.pathname);
+  if (path.startsWith(base)) path = path.slice(base.length);
+  return resolve(outputRoot, path);
+}
+function withLiveClauses(page, captured, base) {
+  const update = (blocks) => blocks.map((block) => {
+    if (block.kind === "figure") {
+      const live = captured.get(block.anchor)?.liveHtml;
+      return live ? { ...block, live: readInlineFragment(live, page.route, base) } : block;
+    }
+    if (block.kind === "memo" || block.kind === "note" || block.kind === "aside" || block.kind === "fold" || block.kind === "quote") {
+      return { ...block, children: update(block.children) };
+    }
+    if (block.kind === "examples") {
+      return { ...block, items: block.items.map((item) => ({ ...item, children: update(item.children) })) };
+    }
+    if (block.kind === "list") return { ...block, items: block.items.map(update) };
+    return block;
+  });
+  return { ...page, blocks: update(page.blocks) };
+}
+async function readBuiltPage(outputRoot, slug) {
+  const route = slug.replace(/(?:^|\/)index$/u, "");
+  const html = await readFile(join(outputRoot, route, "index.html"), "utf8");
+  return { html, page: readStaticPage(html, slug, route) };
+}
+async function prepareChapters(outputRoot, manifest, options = {}) {
+  const logger = options.logger ?? consoleLogger;
+  const strict = strictMode();
+  const { latex, markdown } = manifest.lessonExports;
+  const read = [];
+  let base = "/";
+  for (const lesson of manifest.lessons) {
+    const { html, page } = await readBuiltPage(outputRoot, lesson.slug);
+    if (read.length === 0) base = inferBasePrefix(parse(html));
+    read.push({ lesson, page });
+  }
+  const requests = (latex || markdown ? read : []).map(({ page }) => ({
+    route: page.route,
+    anchors: [
+      ...figuresOf(page.blocks).filter(needsCapture).map((figure) => figure.anchor),
+      ...markdown ? diagramsOf(page.blocks).map((diagram) => diagram.anchor) : []
+    ]
+  })).filter((request) => request.anchors.length > 0);
+  let captures = /* @__PURE__ */ new Map();
+  if (requests.length > 0) {
+    const chromium = await courseChromium(options.projectRoot ?? process.cwd());
+    if (chromium) {
+      try {
+        captures = await captureFigures(requests, {
+          outputRoot,
+          base,
+          chromium,
+          measure: figureMeasure(manifest.lessonExports.latexPaper === "a4" ? "a4" : "letter"),
+          epoch: epochOf(manifest),
+          png: markdown
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (strict || !/Executable doesn't exist|browserType\.launch/u.test(message)) throw error;
+        logger.warn(`Exports: figures stay placeholders, the browser did not start. ${message.split("\n")[0]}`);
+      }
+    } else {
+      const message = "Exports: drawing figures needs Playwright with Chromium in the course (`pnpm add -D @playwright/test && pnpm exec playwright install chromium`).";
+      if (strict) throw new Error(message);
+      logger.warn(`${message} Figures stay placeholders.`);
+    }
+  }
+  for (const [route, figures] of captures) {
+    for (const [anchor, figure] of figures) {
+      if (figure.machineFonts.length > 0) {
+        logger.warn(
+          `Exports: ${route}#${anchor} draws some text in this machine's ${figure.machineFonts.join(", ")}, not the site's fonts, so another machine may draw it differently.`
+        );
+      }
+      if (figure.labelPt !== void 0 && figure.labelPt < LABEL_PT - 0.5) {
+        logger.info(
+          `Exports: the labels of ${route}#${anchor} print at ${figure.labelPt} pt, not ${LABEL_PT} pt; any larger and two of them would touch.`
+        );
+      }
+    }
+  }
+  return {
+    base,
+    captures,
+    chapters: read.map(({ lesson, page }) => {
+      const captured = captures.get(page.route);
+      return { lesson, page: captured ? withLiveClauses(page, captured, base) : page };
+    })
+  };
+}
+export {
+  consoleLogger,
+  diagramsOf,
+  epochOf,
+  figuresOf,
+  imageExtension,
+  imageFile,
+  imagesOf,
+  needsCapture,
+  prepareChapters,
+  readBuiltPage,
+  strictMode,
+  withLiveClauses
+};

package/dist/compiler/exports/export-pages.d.ts

@@ -0,0 +1,48 @@
+import { Manifest } from '../manifest.js';
+import '../../curriculum/validation.js';
+import '../../reference/consistency.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';
+import '../../reference/keyed-float-validate.js';
+import '../../reference/figures-validate.js';
+import '../../reference/diagrams-validate.js';
+import '../../reference/examples-validate.js';
+import '../../reference/folds-validate.js';
+import '../../reference/knowledge-checks-validate.js';
+import '../../reference/raw-floats-validate.js';
+import '../../reference/lab-katex-validate.js';
+import '../../reference/gate-math.js';
+import '../../reference/mixed-content.js';
+import '../../reference/gloss.js';
+import '../../rules/waivers.js';
+import '../knowledge-version.js';
+import '../lesson-derivation.js';
+
+/**
+ * Every page a reader can print or download, by docs slug: each chapter
+ * (`motion/constant-acceleration`) and each non-chapter page the manifest
+ * knows — the landing page (`index`), a part's page (`motion/index`), the
+ * glossary. The 404 route is not one.
+ */
+declare function exportPageSlugs(manifest: Pick<Manifest, 'lessons' | 'pages'>): string[];
+/** Where Astro serves a docs slug, below the base: `motion/index` → `motion`, `index` → ``. */
+declare function exportPageRoute(slug: string): string;
+/** The name a download is saved under: `projectile-range.html`, `motion.html`, `index.html`. */
+declare function standaloneFilename(slug: string): string;
+/**
+ * The pages with an HTML download of their own: every chapter (D8). A page
+ * that is not a chapter — the landing page, a part's page, the glossary —
+ * is in its part's file and the course's (`combined-html.ts`).
+ */
+declare function standalonePageSlugs(manifest: Pick<Manifest, 'lessons'>): string[];
+/** The name the course's files are saved under: `Explico Playground — Motion` → `explico-playground-motion`. */
+declare function courseFileStem(manifest: Pick<Manifest, 'about'>): string;
+
+export { courseFileStem, exportPageRoute, exportPageSlugs, standaloneFilename, standalonePageSlugs };

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

@@ -0,0 +1,22 @@
+function exportPageSlugs(manifest) {
+  return [...manifest.lessons, ...manifest.pages].map((page) => page.slug);
+}
+function exportPageRoute(slug) {
+  return slug.replace(/(?:^|\/)index$/u, "");
+}
+function standaloneFilename(slug) {
+  return `${exportPageRoute(slug).split("/").at(-1) || "index"}.html`;
+}
+function standalonePageSlugs(manifest) {
+  return manifest.lessons.map((lesson) => lesson.slug);
+}
+function courseFileStem(manifest) {
+  return manifest.about.material.name.normalize("NFKD").replace(/[\u0300-\u036f]/gu, "").toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "") || "course";
+}
+export {
+  courseFileStem,
+  exportPageRoute,
+  exportPageSlugs,
+  standaloneFilename,
+  standalonePageSlugs
+};

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

@@ -0,0 +1,22 @@
+import { DefaultTreeAdapterMap } from 'parse5';
+
+/**
+ * Read-only queries over a parse5 tree, shared by the exporters that work on
+ * Astro's built pages (`standalone-html.ts`, `static-tree.ts`).
+ */
+type HtmlNode = DefaultTreeAdapterMap['node'];
+type HtmlParent = DefaultTreeAdapterMap['parentNode'];
+type HtmlChild = DefaultTreeAdapterMap['childNode'];
+type HtmlElement = DefaultTreeAdapterMap['element'];
+type HtmlText = DefaultTreeAdapterMap['textNode'];
+declare function isElement(node: HtmlNode): node is HtmlElement;
+declare function childrenOf(node: HtmlNode): readonly HtmlChild[];
+/** Depth-first, `<template>` content included. */
+declare function walk(node: HtmlNode, visit: (node: HtmlNode) => void): void;
+declare function elements(root: HtmlNode, predicate?: (node: HtmlElement) => boolean): HtmlElement[];
+declare function attribute(node: HtmlElement, name: string): string | undefined;
+declare function hasClass(node: HtmlElement, name: string): boolean;
+/** The site's base path (`/`, `/course/`), read off Astro's asset URLs. */
+declare function inferBasePrefix(document: HtmlNode): string;
+
+export { type HtmlChild, type HtmlElement, type HtmlNode, type HtmlParent, type HtmlText, attribute, childrenOf, elements, hasClass, inferBasePrefix, isElement, walk };

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

@@ -0,0 +1,47 @@
+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 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 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 "/";
+}
+export {
+  attribute,
+  childrenOf,
+  elements,
+  hasClass,
+  inferBasePrefix,
+  isElement,
+  walk
+};

package/dist/compiler/exports/latex/capture.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The capture pass: draw each figure a browser has to draw (a hydrated lab, a
+ * course component's SVG) and print it as a vector PDF for the LaTeX source.
+ *
+ * Recipe, from the spike that tested it:
+ * 1. Serve the finished `dist/` on loopback, at the site's base path.
+ * 2. Open the page in a fresh light-mode context and fire
+ *    `explico:prepare-static-export` in `markdown` mode, which opens every
+ *    disclosure so a figure in a collapsed section gets a layout box.
+ * 3. Scroll each figure into view so its `client:visible` lab hydrates, and
+ *    wait until it has drawn and stopped changing.
+ * 4. Clone the hydrated figure into a clean page *on the same origin* that
+ *    links the site's stylesheets — hiding the rest of the live page around it
+ *    loses Plot's tick labels and blanks a diagram, and a page on another
+ *    origin cannot load the site's fonts (fonts are CORS-restricted).
+ * 5. Print that page at the figure's size: every path and label stays vector,
+ *    with its fonts embedded.
+ *
+ * Playwright is resolved from the course itself, so the browser it drives is
+ * the one the course installed for its own tests.
+ */
+interface CaptureRequest {
+    /** Base-relative route of the page, e.g. `projectiles/optimal-launch-angle`. */
+    readonly route: string;
+    /** Anchor ids of the figures and diagrams to capture (`fig-…`, `dia-…`). */
+    readonly anchors: readonly string[];
+}
+interface CapturedFigure {
+    /** The figure's picture as a one-page vector PDF. */
+    readonly pdf: Uint8Array;
+    /** The same picture as PNG at two device pixels per CSS pixel, when asked for. */
+    readonly png?: Uint8Array;
+    /** The caption's live clause after the lab wrote it, as HTML. */
+    readonly liveHtml: string;
+    /** Fonts some of the figure's text came from that the machine supplied, not the site. */
+    readonly machineFonts: readonly string[];
+    /** The size, in points, the figure's most common SVG label prints at in the book. */
+    readonly labelPt?: number;
+}
+/** By route, then by figure anchor. */
+type CaptureResults = Map<string, Map<string, CapturedFigure>>;
+interface ChromiumLike {
+    launch(options?: Record<string, unknown>): Promise<BrowserLike>;
+}
+interface BrowserLike {
+    newContext(options?: Record<string, unknown>): Promise<ContextLike>;
+    close(): Promise<void>;
+}
+interface ContextLike {
+    newPage(): Promise<PageLike>;
+    /** Chromium only: the DevTools protocol, which names the fonts text was drawn with. */
+    newCDPSession?(page: PageLike): Promise<SessionLike>;
+    close(): Promise<void>;
+}
+interface SessionLike {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    detach(): Promise<void>;
+}
+interface PageLike {
+    goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
+    setContent(html: string, options?: Record<string, unknown>): Promise<void>;
+    evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg?: A): Promise<R>;
+    emulateMedia(options: Record<string, unknown>): Promise<void>;
+    pdf(options: Record<string, unknown>): Promise<Uint8Array>;
+    screenshot(options: Record<string, unknown>): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+/** Playwright's Chromium from the course's own dependencies, or `undefined`. */
+declare function courseChromium(projectRoot: string): Promise<ChromiumLike | undefined>;
+/** The size a figure's most common label prints at, as `\footnotesize` in the book's 11 pt. */
+declare const LABEL_PT = 9;
+/** The book's measure, in PostScript points: the most a figure is set at. */
+interface FigureMeasure {
+    /** `\linewidth` of the page. */
+    readonly width: number;
+    /** `0.6\textheight`, the tallest a figure is included. */
+    readonly maxHeight: number;
+}
+/** The measure of explico.cls on letter or A4 paper with one-inch margins. */
+declare function figureMeasure(paper: 'letter' | 'a4'): FigureMeasure;
+/**
+ * Chromium stamps a PDF with the moment it prints it (`/CreationDate`,
+ * `/ModDate`), and LaTeX copies an included PDF's dates into its own, so
+ * no two builds would agree. Each date becomes `epoch`'s, written in the
+ * same number of bytes so the cross-reference table stays right.
+ */
+declare function stampPdfDates(pdf: Uint8Array, epoch: number): Uint8Array;
+interface CaptureOptions {
+    /** The finished build output. */
+    readonly outputRoot: string;
+    /** The site's base path, `/` or `/course/`. */
+    readonly base: string;
+    readonly chromium: ChromiumLike;
+    /** The book's measure, which sizes figure labels (letter paper's by default). */
+    readonly measure?: FigureMeasure;
+    /** Seconds since 1970 to date every figure PDF with, so a build is reproducible. */
+    readonly epoch?: number;
+    /** Also take each figure as PNG, from the same page as its PDF (Markdown). */
+    readonly png?: boolean;
+    /** Per-figure limit for hydrating and settling. */
+    readonly timeoutMs?: number;
+}
+/** Capture every requested figure, one browser for the whole build. */
+declare function captureFigures(requests: readonly CaptureRequest[], options: CaptureOptions): Promise<CaptureResults>;
+
+export { type CaptureOptions, type CaptureRequest, type CaptureResults, type CapturedFigure, type FigureMeasure, LABEL_PT, captureFigures, courseChromium, figureMeasure, stampPdfDates };