explico 0.12.0 → 0.13.1

package/src/compiler/exports/export-chapters.ts

@@ -0,0 +1,233 @@
+import { readFile } from 'node:fs/promises';
+import { extname, join, resolve } from 'node:path';
+import { parse } from 'parse5';
+
+import type { Manifest, ManifestLesson } from '../manifest';
+import { inferBasePrefix } from './html-tree';
+import { readInlineFragment, readStaticPage, type Block, type StaticPage } from './static-tree';
+import {
+  captureFigures,
+  courseChromium,
+  figureMeasure,
+  LABEL_PT,
+  type CaptureRequest,
+  type CaptureResults,
+} from './latex/capture';
+
+/**
+ * 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.
+ */
+
+export interface ExportLogger {
+  info(message: string): void;
+  warn(message: string): void;
+}
+
+export const consoleLogger: ExportLogger = {
+  info: (message) => console.log(message),
+  warn: (message) => console.warn(message),
+};
+
+/** In CI or with `EXPLICO_LATEX_STRICT=1`, a missing engine or browser fails the build. */
+export function strictMode(): boolean {
+  const ci = process.env.CI;
+  return (!!ci && ci !== 'false' && ci !== '0') || process.env.EXPLICO_LATEX_STRICT === '1';
+}
+
+/** The content date as seconds since 1970: every export's timestamps. */
+export function epochOf(manifest: Pick<Manifest, 'about'>): number {
+  const date = manifest.about.knowledge.date;
+  const parsed = date ? Date.parse(`${date}T00:00:00Z`) : Number.NaN;
+  return Number.isFinite(parsed) ? Math.floor(parsed / 1000) : 0;
+}
+
+type FigureBlock = Extract<Block, { kind: 'figure' }>;
+type DiagramBlock = Extract<Block, { kind: 'diagram' }>;
+
+/** Every block of a kind, at any depth, in reading order. */
+function blocksOf<K extends Block['kind']>(blocks: readonly Block[], kind: K): Extract<Block, { kind: K }>[] {
+  const found: Extract<Block, { kind: K }>[] = [];
+  const visit = (list: readonly Block[]) => {
+    for (const block of list) {
+      if (block.kind === kind) found.push(block as Extract<Block, { kind: K }>);
+      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 as readonly Block[]);
+      }
+    }
+  };
+  visit(blocks);
+  return found;
+}
+
+export function figuresOf(blocks: readonly Block[]): FigureBlock[] {
+  return blocksOf(blocks, 'figure');
+}
+
+export function diagramsOf(blocks: readonly Block[]): DiagramBlock[] {
+  return blocksOf(blocks, 'diagram');
+}
+
+/** Every inline `image` block, in reading order. */
+export function imagesOf(blocks: readonly Block[]): Extract<Block, { kind: 'image' }>[] {
+  return blocksOf(blocks, 'image');
+}
+
+/** Raster formats a document includes as they are; anything else is drawn by the browser. */
+const INCLUDABLE_IMAGES = new Set(['.png', '.jpg', '.jpeg', '.pdf']);
+
+/** The image file a URL names, by extension. */
+export function imageExtension(src: string): string {
+  return extname(new URL(src, 'https://x.invalid/').pathname).toLowerCase();
+}
+
+/** Whether a figure is drawn by the browser rather than included as a file. */
+export function needsCapture(figure: FigureBlock): boolean {
+  if (figure.picture.kind === 'capture') return true;
+  if (figure.picture.kind === 'image') return !INCLUDABLE_IMAGES.has(imageExtension(figure.picture.src));
+  return false;
+}
+
+/** The built file an image URL on a page names. */
+export function imageFile(outputRoot: string, base: string, route: string, src: string): string {
+  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);
+}
+
+/** The page with each captured lab's live caption clause filled in. */
+export function withLiveClauses(
+  page: StaticPage,
+  captured: ReadonlyMap<string, { liveHtml: string }>,
+  base: string,
+): StaticPage {
+  const update = (blocks: readonly Block[]): Block[] =>
+    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) };
+}
+
+export interface PreparedChapter {
+  readonly lesson: ManifestLesson;
+  /** The chapter's reading tree, its labs' live caption clauses filled in. */
+  readonly page: StaticPage;
+}
+
+export 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. */
+export async function readBuiltPage(outputRoot: string, slug: string): Promise<{ html: string; page: StaticPage }> {
+  const route = slug.replace(/(?:^|\/)index$/u, '');
+  const html = await readFile(join(outputRoot, route, 'index.html'), 'utf8');
+  return { html, page: readStaticPage(html, slug, route) };
+}
+
+/**
+ * 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.
+ */
+export async function prepareChapters(
+  outputRoot: string,
+  manifest: Manifest,
+  options: { readonly logger?: ExportLogger; readonly projectRoot?: string } = {},
+): Promise<PreparedChapters> {
+  const logger = options.logger ?? consoleLogger;
+  const strict = strictMode();
+  const { latex, markdown } = manifest.lessonExports;
+
+  const read: { lesson: ManifestLesson; page: StaticPage }[] = [];
+  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: CaptureRequest[] = (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: CaptureResults = 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 !== undefined && 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 };
+    }),
+  };
+}

package/src/compiler/exports/export-pages.ts

@@ -0,0 +1,44 @@
+import type { Manifest } from '../manifest';
+
+/**
+ * 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.
+ */
+export function exportPageSlugs(
+  manifest: Pick<Manifest, 'lessons' | 'pages'>,
+): string[] {
+  return [...manifest.lessons, ...manifest.pages].map((page) => page.slug);
+}
+
+/** Where Astro serves a docs slug, below the base: `motion/index` → `motion`, `index` → ``. */
+export function exportPageRoute(slug: string): string {
+  return slug.replace(/(?:^|\/)index$/u, '');
+}
+
+/** The name a download is saved under: `projectile-range.html`, `motion.html`, `index.html`. */
+export function standaloneFilename(slug: string): string {
+  return `${exportPageRoute(slug).split('/').at(-1) || 'index'}.html`;
+}
+
+/**
+ * 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`).
+ */
+export function standalonePageSlugs(manifest: Pick<Manifest, 'lessons'>): string[] {
+  return manifest.lessons.map((lesson) => lesson.slug);
+}
+
+/** The name the course's files are saved under: `Explico Playground — Motion` → `explico-playground-motion`. */
+export function courseFileStem(manifest: Pick<Manifest, 'about'>): string {
+  return (
+    manifest.about.material.name
+      .normalize('NFKD')
+      .replace(/[\u0300-\u036f]/gu, '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/gu, '-')
+      .replace(/^-+|-+$/gu, '') || 'course'
+  );
+}

package/src/compiler/exports/html-tree.ts

@@ -0,0 +1,62 @@
+import type { 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`).
+ */
+
+export type HtmlNode = DefaultTreeAdapterMap['node'];
+export type HtmlParent = DefaultTreeAdapterMap['parentNode'];
+export type HtmlChild = DefaultTreeAdapterMap['childNode'];
+export type HtmlElement = DefaultTreeAdapterMap['element'];
+export type HtmlText = DefaultTreeAdapterMap['textNode'];
+
+export function isElement(node: HtmlNode): node is HtmlElement {
+  return 'tagName' in node;
+}
+
+export function childrenOf(node: HtmlNode): readonly HtmlChild[] {
+  return 'childNodes' in node ? node.childNodes : [];
+}
+
+/** Depth-first, `<template>` content included. */
+export function walk(node: HtmlNode, visit: (node: HtmlNode) => void): void {
+  visit(node);
+  for (const child of childrenOf(node)) walk(child, visit);
+  if (isElement(node) && node.tagName === 'template') {
+    const template = node as DefaultTreeAdapterMap['template'];
+    for (const child of template.content.childNodes) walk(child, visit);
+  }
+}
+
+export function elements(
+  root: HtmlNode,
+  predicate?: (node: HtmlElement) => boolean,
+): HtmlElement[] {
+  const found: HtmlElement[] = [];
+  walk(root, (node) => {
+    if (isElement(node) && (predicate?.(node) ?? true)) found.push(node);
+  });
+  return found;
+}
+
+export function attribute(node: HtmlElement, name: string): string | undefined {
+  return node.attrs.find((entry) => entry.name === name)?.value;
+}
+
+export function hasClass(node: HtmlElement, name: string): boolean {
+  return (attribute(node, 'class') ?? '').split(/\s+/u).includes(name);
+}
+
+/** The site's base path (`/`, `/course/`), read off Astro's asset URLs. */
+export function inferBasePrefix(document: HtmlNode): string {
+  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 '/';
+}