explico 0.12.0 → 0.13.1

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

@@ -0,0 +1,669 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse, serialize } from 'parse5';
+
+import type { Manifest } from '../manifest';
+import { exportPageRoute } from './export-pages';
+import {
+  attribute,
+  childrenOf,
+  elements,
+  hasClass,
+  inferBasePrefix,
+  type HtmlChild,
+  type HtmlElement,
+  type HtmlNode,
+  type HtmlParent,
+} from './html-tree';
+import { buildStandaloneLessonHtml, pageSourceFile } from './standalone-html';
+
+/**
+ * One offline HTML file of several built pages (decision D7): a part — its
+ * overview page, then its chapters — or the whole course.
+ *
+ * It is assembled from the pages Astro already built, not rendered again:
+ * each page keeps everything explico rendered for it, its body and the card
+ * layers at its foot (notation, citations, abbreviations, float references),
+ * so every number, card and check is the website's. Each page becomes one
+ * `<section>`, and so that ids stay unique, every id in it gains the page's
+ * suffix (`eq-range` → `eq-range--projectiles-projectile-range`), with every
+ * reference to it: fragment links, ARIA id lists, `for`, `popovertarget`,
+ * SVG `href` and `url(#…)`. A suffix, not a prefix, keeps the kind an id
+ * starts with (`eq-`, `fig-`, `cite-`), which the card layers read. A link
+ * to another page of the document becomes a link into it, so its hover
+ * preview works offline. The standalone exporter then inlines the document
+ * as it does one page.
+ */
+
+export interface CombinedPage {
+  /** The page's docs slug: `projectiles/index`, `projectiles/projectile-range`. */
+  readonly slug: string;
+  /** Astro's built HTML of the page. */
+  readonly html: string;
+}
+
+/** A line of the document's contents; its title is the page's own `<h1>`. */
+export interface ContentsEntry {
+  readonly slug: string;
+  /** `Part 2`, `2.1`; none for a page outside the numbered parts. */
+  readonly number?: string;
+  readonly children?: readonly ContentsEntry[];
+}
+
+export interface CombinedDocumentInput {
+  /** The document's title: the part's label or the course's name. */
+  readonly title: string;
+  /** The pages in reading order. */
+  readonly pages: readonly CombinedPage[];
+  /** The contents, set after the first page; none for a single page. */
+  readonly contents?: readonly ContentsEntry[];
+}
+
+/** Attributes holding one id. */
+const ID_ATTRIBUTES = [
+  'for',
+  'list',
+  'form',
+  'popovertarget',
+  'commandfor',
+  'aria-activedescendant',
+  'data-notation-layer-id',
+];
+
+/** Attributes holding a space-separated list of ids. */
+const ID_LIST_ATTRIBUTES = [
+  'aria-controls',
+  'aria-describedby',
+  'aria-details',
+  'aria-errormessage',
+  'aria-flowto',
+  'aria-labelledby',
+  'aria-owns',
+  'headers',
+];
+
+/** Attributes holding a URL, whose fragment may name an id. */
+const URL_ATTRIBUTES = ['href', 'xlink:href', 'data-notation-href'];
+
+/**
+ * The card shells every page repeats, looked up by these ids: kept once,
+ * unchanged. (A notation layer's own shell is found inside the layer, so
+ * each page keeps its own.)
+ */
+const SHARED_TEMPLATE_IDS = new Set(['citation-panel', 'abbreviation-panel', 'float-ref-panel']);
+
+const COMBINED_STYLE = `
+.explico-combined-page {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 1200px;
+}
+.explico-combined-page + .explico-combined-page,
+.explico-combined-contents + .explico-combined-page {
+  border-top: 1px solid var(--sl-color-hairline);
+}
+.explico-combined-contents ol {
+  list-style: none;
+  padding-inline-start: 0;
+}
+.explico-combined-contents ol ol {
+  padding-inline-start: 1.5rem;
+}
+.explico-combined-contents li {
+  margin-block: 0.25rem;
+}
+.explico-combined-contents li:has(> ol) {
+  font-weight: 600;
+}
+.explico-combined-contents li li {
+  font-weight: normal;
+}
+.explico-combined-contents__number {
+  display: inline-block;
+  min-width: 3.5em;
+  font-variant-numeric: tabular-nums;
+}
+@media print {
+  .explico-combined-page {
+    content-visibility: visible;
+  }
+  .explico-combined-page + .explico-combined-page,
+  .explico-combined-contents + .explico-combined-page {
+    border-top: 0;
+    break-before: page;
+  }
+}
+`;
+
+/** The suffix a page's ids gain: its route, `/` as `-`; the landing page is `home`. */
+export function pageKey(slug: string): string {
+  return exportPageRoute(slug).replace(/\//gu, '-') || 'home';
+}
+
+/** The id of a page's section in the combined document. */
+export function pageSectionId(slug: string): string {
+  return `page--${pageKey(slug)}`;
+}
+
+function setAttribute(node: HtmlElement, name: string, value: string): void {
+  const existing = node.attrs.find((entry) => entry.name === name);
+  if (existing) existing.value = value;
+  else node.attrs.push({ name, value });
+}
+
+function firstElement(root: HtmlNode, tagName: string): HtmlElement {
+  const found = elements(root, (node) => node.tagName === tagName)[0];
+  if (!found) throw new Error(`Combined HTML source has no <${tagName}> element.`);
+  return found;
+}
+
+function detach(node: HtmlChild): void {
+  const parent = node.parentNode as HtmlParent | null;
+  if (!parent) return;
+  const index = parent.childNodes.indexOf(node);
+  if (index !== -1) parent.childNodes.splice(index, 1);
+  node.parentNode = null;
+}
+
+function appendChild(parent: HtmlParent, child: HtmlChild): void {
+  detach(child);
+  parent.childNodes.push(child);
+  child.parentNode = parent;
+}
+
+function element(tagName: string, attrs: Record<string, string>, children: HtmlChild[] = []): HtmlElement {
+  const node: HtmlElement = {
+    nodeName: tagName,
+    tagName,
+    attrs: Object.entries(attrs).map(([name, value]) => ({ name, value })),
+    namespaceURI: 'http://www.w3.org/1999/xhtml' as HtmlElement['namespaceURI'],
+    parentNode: null,
+    childNodes: [],
+  };
+  for (const child of children) appendChild(node, child);
+  return node;
+}
+
+function text(value: string): HtmlChild {
+  return { nodeName: '#text', value, parentNode: null } as HtmlChild;
+}
+
+function textOf(node: HtmlNode): string {
+  if ('value' in node && node.nodeName === '#text') return String(node.value);
+  return childrenOf(node)
+    .map((child) => textOf(child))
+    .join('');
+}
+
+/** A path below the base, without `index.html` or slashes at either end: `projectiles/projectile-range`. */
+function routeOfPath(pathname: string, base: string): string | undefined {
+  if (!pathname.startsWith(base)) return undefined;
+  let route: string;
+  try {
+    route = decodeURIComponent(pathname.slice(base.length));
+  } catch {
+    return undefined;
+  }
+  return route
+    .replace(/(?:^|\/)index\.html$/u, '')
+    .replace(/\.html$/u, '')
+    .replace(/^\/+|\/+$/gu, '');
+}
+
+interface PageParts {
+  readonly slug: string;
+  readonly route: string;
+  readonly key: string;
+  readonly document: HtmlNode;
+  readonly main: HtmlElement;
+  /** The page's own ids, to their ids in the combined document. */
+  readonly ids: Map<string, string>;
+}
+
+/**
+ * Make every relative URL in a page absolute, so it means the same thing
+ * from the combined document's location.
+ */
+function absolutizeUrls(page: PageParts, base: string): void {
+  const location = new URL(`https://explico.invalid${base}${page.route ? `${page.route}/` : ''}`);
+  const absolute = (value: string) => {
+    const trimmed = value.trim();
+    if (!trimmed || /^(?:[a-z][a-z\d+.-]*:|\/|#)/iu.test(trimmed)) return value;
+    const url = new URL(trimmed, location);
+    return `${url.pathname}${url.search}${url.hash}`;
+  };
+  for (const node of elements(page.document)) {
+    for (const name of ['href', 'src', 'poster', 'data', 'component-url', 'renderer-url', 'before-hydration-url']) {
+      const value = attribute(node, name);
+      if (value) setAttribute(node, name, absolute(value));
+    }
+    for (const name of ['srcset', 'imagesrcset']) {
+      const value = attribute(node, name);
+      if (!value) continue;
+      setAttribute(
+        node,
+        name,
+        value
+          .split(',')
+          .map((candidate) => {
+            const [url = '', ...rest] = candidate.trim().split(/\s+/u);
+            return [absolute(url), ...rest].join(' ');
+          })
+          .join(', '),
+      );
+    }
+  }
+}
+
+/** `url(#id)` references in CSS text or an SVG presentation attribute. */
+function rewriteCssFragments(value: string, ids: ReadonlyMap<string, string>): string {
+  return value.replace(/url\(\s*(["']?)#([^"')\s]+)\1\s*\)/gu, (match, quote: string, id: string) => {
+    const next = ids.get(id);
+    return next ? `url(${quote}#${next}${quote})` : match;
+  });
+}
+
+/**
+ * Rewrite a URL that names a page of the document: its own fragment, or a
+ * path to a page in it. Anything else is left for the standalone exporter.
+ */
+function rewriteUrl(
+  value: string,
+  page: PageParts,
+  pages: ReadonlyMap<string, PageParts>,
+  base: string,
+): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('#')) {
+    let id: string;
+    try {
+      id = decodeURIComponent(trimmed.slice(1));
+    } catch {
+      return value;
+    }
+    const next = page.ids.get(id);
+    return next ? `#${next}` : value;
+  }
+  if (!trimmed.startsWith('/') || trimmed.startsWith('//')) return value;
+  const url = new URL(trimmed, 'https://explico.invalid/');
+  const route = routeOfPath(url.pathname, base);
+  const target = route === undefined ? undefined : pages.get(route);
+  if (!target) return value;
+  if (!url.hash) return `#${pageSectionId(target.slug)}`;
+  let id: string;
+  try {
+    id = decodeURIComponent(url.hash.slice(1));
+  } catch {
+    return `#${pageSectionId(target.slug)}`;
+  }
+  const next = target.ids.get(id);
+  return next ? `#${next}` : `#${pageSectionId(target.slug)}`;
+}
+
+function rewriteReferences(page: PageParts, pages: ReadonlyMap<string, PageParts>, base: string): void {
+  for (const node of elements(page.main)) {
+    for (const name of URL_ATTRIBUTES) {
+      const value = attribute(node, name);
+      if (value) setAttribute(node, name, rewriteUrl(value, page, pages, base));
+    }
+    for (const name of ID_ATTRIBUTES) {
+      const value = attribute(node, name);
+      const next = value ? page.ids.get(value) : undefined;
+      if (next) setAttribute(node, name, next);
+    }
+    for (const name of ID_LIST_ATTRIBUTES) {
+      const value = attribute(node, name);
+      if (!value) continue;
+      setAttribute(
+        node,
+        name,
+        value
+          .split(/\s+/u)
+          .filter(Boolean)
+          .map((id) => page.ids.get(id) ?? id)
+          .join(' '),
+      );
+    }
+    for (const entry of node.attrs) {
+      if (entry.value.includes('url(')) entry.value = rewriteCssFragments(entry.value, page.ids);
+    }
+    if (node.tagName === 'style') {
+      for (const child of childrenOf(node)) {
+        if ('value' in child) child.value = rewriteCssFragments(String(child.value), page.ids);
+      }
+    }
+  }
+}
+
+/** Every element inside an island: what its framework rendered and will hydrate. */
+function islandContents(root: HtmlNode): Set<HtmlElement> {
+  const inside = new Set<HtmlElement>();
+  for (const island of elements(root, (node) => node.tagName === 'astro-island')) {
+    for (const node of elements(island)) if (node !== island) inside.add(node);
+  }
+  return inside;
+}
+
+/**
+ * Every `id` in the page's `<main>`, with its id in the combined document.
+ * An island's own ids stay: its framework renders them again when it
+ * hydrates (see `uniqueIslandPrefixes`). The first page keeps `_top`, the
+ * document's top.
+ */
+function collectIds(page: Omit<PageParts, 'ids'>, first: boolean): Map<string, string> {
+  const ids = new Map<string, string>();
+  const islands = islandContents(page.main);
+  for (const node of elements(page.main)) {
+    const id = attribute(node, 'id');
+    if (!id || ids.has(id) || islands.has(node)) continue;
+    if (node.tagName === 'template' && SHARED_TEMPLATE_IDS.has(id)) continue;
+    ids.set(id, first && id === '_top' ? id : `${id}--${page.key}`);
+  }
+  return ids;
+}
+
+/**
+ * Astro numbers a page's islands (`prefix="r5"`), and React builds every
+ * id an island renders from that prefix (`useId`: `_r5R_d_`), so two pages'
+ * islands repeat each other's ids. A prefix an earlier page used gets the
+ * page's index (`r5p2`), and every attribute in the island that holds one
+ * of its ids is rewritten to match what React renders when it hydrates: a
+ * server-rendered React id has the prefix followed by `R`.
+ */
+function uniqueIslandPrefixes(pages: readonly PageParts[]): void {
+  const used = new Set<string>();
+  pages.forEach((page, index) => {
+    for (const island of elements(page.main, (node) => node.tagName === 'astro-island')) {
+      const prefix = attribute(island, 'prefix');
+      if (!prefix) continue;
+      if (!used.has(prefix)) {
+        used.add(prefix);
+        continue;
+      }
+      const next = `${prefix}p${index}`;
+      used.add(next);
+      setAttribute(island, 'prefix', next);
+      const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+      const reactId = new RegExp(`(^|[^A-Za-z0-9])${escaped}R`, 'gu');
+      for (const node of elements(island)) {
+        if (node === island) continue;
+        for (const entry of node.attrs) {
+          if (entry.name === 'id' || ID_ATTRIBUTES.includes(entry.name) || ID_LIST_ATTRIBUTES.includes(entry.name)) {
+            entry.value = entry.value.replace(reactId, `$1${next}R`);
+          }
+        }
+      }
+    }
+  });
+}
+
+/** Whether a script runs: a classic or module script, not a data block. */
+function isExecutable(node: HtmlElement): boolean {
+  const type = (attribute(node, 'type') ?? '').trim().toLowerCase();
+  return type === '' || type === 'module' || type === 'text/javascript' || type === 'application/javascript';
+}
+
+/** The content panels a page's own `<main>` uses, so a generated panel looks like them. */
+function panelClasses(main: HtmlElement): { panel: string; container: string } {
+  const panel = elements(main, (node) => hasClass(node, 'content-panel'))[0];
+  const container = elements(main, (node) => hasClass(node, 'sl-container'))[0];
+  return {
+    panel: attribute(panel ?? main, 'class') ?? 'content-panel',
+    container: attribute(container ?? main, 'class') ?? 'sl-container',
+  };
+}
+
+function contentsList(
+  entries: readonly ContentsEntry[],
+  titles: ReadonlyMap<string, string>,
+): HtmlElement {
+  return element(
+    'ol',
+    {},
+    entries.map((entry) =>
+      element('li', {}, [
+        ...(entry.number
+          ? [element('span', { class: 'explico-combined-contents__number' }, [text(entry.number)]), text(' ')]
+          : []),
+        element('a', { href: `#${pageSectionId(entry.slug)}` }, [text(titles.get(entry.slug) ?? entry.slug)]),
+        ...(entry.children && entry.children.length > 0 ? [contentsList(entry.children, titles)] : []),
+      ]),
+    ),
+  );
+}
+
+/**
+ * The combined document's HTML: the first page's `<head>` and shell, each
+ * page's `<main>` content in a section of its own, the head's stylesheets
+ * and scripts the union of every page's.
+ */
+export function combinePages(input: CombinedDocumentInput): string {
+  if (input.pages.length === 0) throw new Error('A combined document needs at least one page.');
+  const documents = input.pages.map((page) => parse(page.html));
+  const shell = documents[0]!;
+  const base = inferBasePrefix(shell);
+
+  const parts: PageParts[] = input.pages.map((page, index) => {
+    const document = documents[index]!;
+    const partial = {
+      slug: page.slug,
+      route: exportPageRoute(page.slug),
+      key: pageKey(page.slug),
+      document,
+      main: firstElement(document, 'main'),
+    };
+    return { ...partial, ids: collectIds(partial, index === 0) };
+  });
+  const titles = new Map(
+    parts.map((page) => {
+      const heading = elements(page.main, (node) => node.tagName === 'h1')[0];
+      return [page.slug, heading ? textOf(heading).replace(/\s+/gu, ' ').trim() : page.slug];
+    }),
+  );
+  const byRoute = new Map(parts.map((page) => [page.route, page]));
+  uniqueIslandPrefixes(parts);
+  for (const page of parts) absolutizeUrls(page, base);
+  for (const page of parts) {
+    for (const node of elements(page.main)) {
+      const id = attribute(node, 'id');
+      const next = id ? page.ids.get(id) : undefined;
+      if (next) setAttribute(node, 'id', next);
+    }
+    rewriteReferences(page, byRoute, base);
+  }
+
+  // The head: the first page's, with any stylesheet or module script
+  // another page adds.
+  const head = firstElement(shell, 'head');
+  const headKeys = new Set(
+    elements(head).map((node) => `${node.tagName} ${attribute(node, 'href') ?? attribute(node, 'src') ?? ''}`),
+  );
+  for (const page of parts.slice(1)) {
+    for (const node of elements(firstElement(page.document, 'head'))) {
+      const isStylesheet = node.tagName === 'link' && (attribute(node, 'rel') ?? '').split(/\s+/u).includes('stylesheet');
+      const isModule = node.tagName === 'script' && !!attribute(node, 'src');
+      if (!isStylesheet && !isModule) continue;
+      const key = `${node.tagName} ${attribute(node, 'href') ?? attribute(node, 'src') ?? ''}`;
+      if (headKeys.has(key)) continue;
+      headKeys.add(key);
+      appendChild(head, node);
+    }
+  }
+  const title = elements(head, (node) => node.tagName === 'title')[0];
+  if (title) {
+    title.childNodes.splice(0, title.childNodes.length);
+    appendChild(title, text(input.title));
+  }
+  appendChild(head, element('style', { 'data-explico-combined-style': '' }, [text(COMBINED_STYLE)]));
+
+  // The body: one section per page. A script every page carries runs once,
+  // and a card template every page repeats is kept once.
+  const main = firstElement(shell, 'main');
+  const classes = panelClasses(main);
+  const seen = new Set<string>();
+  const sections = parts.map((page) => {
+    const heading = page.ids.get('_top');
+    const section = element('section', {
+      class: 'explico-combined-page',
+      id: pageSectionId(page.slug),
+      'data-explico-page': page.slug,
+      ...(heading ? { 'aria-labelledby': heading } : {}),
+    });
+    for (const child of [...page.main.childNodes]) appendChild(section, child);
+    for (const node of elements(section)) {
+      const id = attribute(node, 'id');
+      let key: string | undefined;
+      if (node.tagName === 'script' && !id && isExecutable(node)) {
+        key = `script ${attribute(node, 'src') ?? textOf(node)}`;
+      } else if (node.tagName === 'style' && !id) {
+        key = `style ${textOf(node)}`;
+      } else if (node.tagName === 'template' && id && SHARED_TEMPLATE_IDS.has(id)) {
+        key = `template ${id}`;
+      }
+      if (key === undefined) continue;
+      if (seen.has(key)) detach(node);
+      else seen.add(key);
+    }
+    return section;
+  });
+
+  main.childNodes.splice(0, main.childNodes.length);
+  sections.forEach((section, index) => {
+    appendChild(main, section);
+    if (index !== 0 || !input.contents || input.contents.length === 0) return;
+    appendChild(
+      main,
+      element('div', { class: `${classes.panel} explico-combined-contents` }, [
+        element('div', { class: classes.container }, [
+          element('nav', { class: 'sl-markdown-content', 'aria-labelledby': 'explico-contents' }, [
+            element('h2', { id: 'explico-contents' }, [text('Contents')]),
+            contentsList(input.contents, titles),
+          ]),
+        ]),
+      ]),
+    );
+  });
+  setAttribute(main, 'data-explico-combined', '');
+
+  return serialize(shell);
+}
+
+/** One combined download: where it goes, its title, its pages and contents. */
+export interface CombinedDownload {
+  /** Below `downloads/`: `part/projectiles.html`, `course.html`. */
+  readonly path: string;
+  readonly title: string;
+  readonly slugs: readonly string[];
+  readonly contents: readonly ContentsEntry[];
+}
+
+/**
+ * The part and course downloads of a course: each part is its overview page
+ * (when it has one), then its chapters; the course is the landing page, the
+ * front matter (the curriculum map, the figures and tables), every part, and
+ * the glossary last, as a book ends with its glossary.
+ */
+export function combinedDownloads(manifest: Pick<Manifest, 'lessons' | 'pages' | 'parts' | 'about'>): CombinedDownload[] {
+  const pageSlugs = new Set(manifest.pages.map((page) => page.slug));
+  const lessonsById = new Map(manifest.lessons.map((lesson) => [lesson.id, lesson]));
+  const partPages = manifest.parts.map((part) => {
+    const overview = pageSlugs.has(`${part.dir}/index`) ? `${part.dir}/index` : undefined;
+    const lessons = part.lessons.flatMap((id) => {
+      const lesson = lessonsById.get(id);
+      return lesson ? [lesson] : [];
+    });
+    return { part, overview, lessons };
+  });
+  const downloads: CombinedDownload[] = partPages.flatMap(({ part, overview, lessons }) => {
+    if (lessons.length === 0) return [];
+    return [
+      {
+        path: `part/${part.dir}.html`,
+        title: part.label,
+        slugs: [...(overview ? [overview] : []), ...lessons.map((lesson) => lesson.slug)],
+        contents: lessons.map((lesson) => ({ slug: lesson.slug, number: `${lesson.part}.${lesson.chapter}` })),
+      },
+    ];
+  });
+
+  const partSlugs = new Set(partPages.flatMap(({ overview }) => (overview ? [overview] : [])));
+  const front = ['curriculum-map', 'figures-and-tables'].filter((slug) => pageSlugs.has(slug));
+  const back = manifest.pages
+    .map((page) => page.slug)
+    .filter((slug) => slug !== 'index' && slug !== 'glossary' && !partSlugs.has(slug) && !front.includes(slug))
+    .concat(pageSlugs.has('glossary') ? ['glossary'] : []);
+  const parts = partPages.filter(({ lessons }) => lessons.length > 0);
+  const slugs = [
+    ...(pageSlugs.has('index') ? ['index'] : []),
+    ...front,
+    ...parts.flatMap(({ overview, lessons }) => [...(overview ? [overview] : []), ...lessons.map((lesson) => lesson.slug)]),
+    ...back,
+  ];
+  if (slugs.length > 0 && parts.length > 0) {
+    downloads.push({
+      path: 'course.html',
+      title: manifest.about.material.name,
+      slugs,
+      contents: [
+        ...front.map((slug) => ({ slug })),
+        ...parts.map(({ part, overview, lessons }) => ({
+          slug: overview ?? lessons[0]!.slug,
+          number: `Part ${part.ordinal}`,
+          children: lessons.map((lesson) => ({ slug: lesson.slug, number: `${lesson.part}.${lesson.chapter}` })),
+        })),
+        ...back.map((slug) => ({ slug })),
+      ],
+    });
+  }
+  return downloads;
+}
+
+/**
+ * Write every part's and the course's offline HTML file under `downloads/`
+ * (`lessonExports.standaloneHtml`), from Astro's finished output.
+ */
+export async function writeCombinedExports(directory: URL, manifest: Manifest): Promise<void> {
+  if (!manifest.lessonExports.standaloneHtml) return;
+  const outputRoot = fileURLToPath(directory);
+  const pending: { target: string; temporary: string; html: string }[] = [];
+  const sources = new Map<string, Promise<{ file: string; html: string }>>();
+  const source = (slug: string) => {
+    let read = sources.get(slug);
+    if (!read) {
+      read = pageSourceFile(outputRoot, slug).then(async (file) => ({ file, html: await readFile(file, 'utf8') }));
+      sources.set(slug, read);
+    }
+    return read;
+  };
+  for (const download of combinedDownloads(manifest)) {
+    const pages = await Promise.all(download.slugs.map(async (slug) => ({ slug, ...(await source(slug)) })));
+    const html = combinePages({
+      title: download.title,
+      pages: pages.map(({ slug, html: page }) => ({ slug, html: page })),
+      contents: download.contents,
+    });
+    const target = join(outputRoot, 'downloads', download.path);
+    pending.push({
+      target,
+      temporary: `${target}.tmp-${process.pid}`,
+      html: await buildStandaloneLessonHtml({
+        html,
+        sourceFile: pages[0]!.file,
+        outputRoot,
+        lessonSlug: pages[0]!.slug,
+        canonicalBaseUrl: manifest.lessonExports.canonicalBaseUrl,
+      }),
+    });
+  }
+
+  // Nothing is published until every file has passed the asset audit.
+  try {
+    for (const file of pending) {
+      await mkdir(dirname(file.target), { recursive: true });
+      await writeFile(file.temporary, file.html, 'utf8');
+    }
+    for (const file of pending) await rename(file.temporary, file.target);
+  } finally {
+    await Promise.all(pending.map((file) => rm(file.temporary, { force: true })));
+  }
+}

package/src/compiler/exports/download-index.ts

@@ -0,0 +1,36 @@
+import { readdir, stat, writeFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `downloads/index.json`: every file the exports wrote, by its path below
+ * `downloads/`, with its size in bytes. The Download menu
+ * (`LessonExportActions.astro`) reads it to show sizes and to hide a download
+ * the build did not write — a PDF on a machine without TeX, say.
+ */
+export async function writeDownloadIndex(directory: URL): Promise<void> {
+  const root = join(fileURLToPath(directory), 'downloads');
+  const files: [string, number][] = [];
+  const walk = async (folder: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(folder, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const path = join(folder, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile() && !(folder === root && entry.name === 'index.json')) {
+        files.push([relative(root, path).split(sep).join('/'), (await stat(path)).size]);
+      }
+    }
+  };
+  await walk(root);
+  if (files.length === 0) return;
+  files.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  await writeFile(
+    join(root, 'index.json'),
+    `${JSON.stringify({ files: Object.fromEntries(files) }, null, 2)}\n`,
+  );
+}