explico 0.11.1 → 0.13.0

package/dist/compiler/course-config.js

@@ -73,11 +73,30 @@ function normalizeBlockLabels(config) {
   }
   return labels;
 }
+const CARDS_DEFAULTS = { carry: false };
+function normalizeCards(config) {
+  const carry = config.cards?.carry ?? CARDS_DEFAULTS.carry;
+  if (typeof carry !== "boolean") {
+    throw new Error(
+      `CourseConfig cards.carry must be true or false; received ${JSON.stringify(carry)}.`
+    );
+  }
+  return { carry };
+}
 function normalizeLessonExports(config) {
   const standaloneHtml = config.lessonExports?.standaloneHtml === true;
   const print = config.lessonExports?.print === true;
+  const latex = config.lessonExports?.latex === true;
+  const rawPaper = config.lessonExports?.latexPaper ?? "letter";
+  if (rawPaper !== "letter" && rawPaper !== "a4") {
+    throw new Error(
+      `CourseConfig lessonExports.latexPaper must be "letter" or "a4"; received ${JSON.stringify(rawPaper)}.`
+    );
+  }
+  const latexPaper = rawPaper;
+  const markdown = config.lessonExports?.markdown === true;
   const rawBase = config.lessonExports?.canonicalBaseUrl;
-  if (rawBase === void 0) return { standaloneHtml, print };
+  if (rawBase === void 0) return { standaloneHtml, print, latex, latexPaper, markdown };
   let parsed;
   try {
     parsed = new URL(rawBase);
@@ -97,7 +116,14 @@ function normalizeLessonExports(config) {
     );
   }
   if (!parsed.pathname.endsWith("/")) parsed.pathname += "/";
-  return { standaloneHtml, print, canonicalBaseUrl: parsed.toString() };
+  return {
+    standaloneHtml,
+    print,
+    latex,
+    latexPaper,
+    markdown,
+    canonicalBaseUrl: parsed.toString()
+  };
 }
 function coursePartsOf(config) {
   const parts = config.parts ?? config.sections;
@@ -110,9 +136,11 @@ function coursePartsOf(config) {
 }
 export {
   BLOCK_LABELS_DEFAULT,
+  CARDS_DEFAULTS,
   DISCLOSURE_DEFAULTS,
   coursePartsOf,
   normalizeBlockLabels,
+  normalizeCards,
   normalizeDisclosure,
   normalizeLessonExports,
   normalizeNumbering

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

@@ -0,0 +1,97 @@
+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';
+
+/**
+ * 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.
+ */
+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>`. */
+interface ContentsEntry {
+    readonly slug: string;
+    /** `Part 2`, `2.1`; none for a page outside the numbered parts. */
+    readonly number?: string;
+    readonly children?: readonly ContentsEntry[];
+}
+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[];
+}
+/** The suffix a page's ids gain: its route, `/` as `-`; the landing page is `home`. */
+declare function pageKey(slug: string): string;
+/** The id of a page's section in the combined document. */
+declare function pageSectionId(slug: string): string;
+/**
+ * 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.
+ */
+declare function combinePages(input: CombinedDocumentInput): string;
+/** One combined download: where it goes, its title, its pages and contents. */
+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.
+ */
+declare function combinedDownloads(manifest: Pick<Manifest, 'lessons' | 'pages' | 'parts' | 'about'>): CombinedDownload[];
+/**
+ * Write every part's and the course's offline HTML file under `downloads/`
+ * (`lessonExports.standaloneHtml`), from Astro's finished output.
+ */
+declare function writeCombinedExports(directory: URL, manifest: Manifest): Promise<void>;
+
+export { type CombinedDocumentInput, type CombinedDownload, type CombinedPage, type ContentsEntry, combinePages, combinedDownloads, pageKey, pageSectionId, writeCombinedExports };

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

@@ -0,0 +1,492 @@
+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 { exportPageRoute } from "./export-pages.js";
+import {
+  attribute,
+  childrenOf,
+  elements,
+  hasClass,
+  inferBasePrefix
+} from "./html-tree.js";
+import { buildStandaloneLessonHtml, pageSourceFile } from "./standalone-html.js";
+const ID_ATTRIBUTES = [
+  "for",
+  "list",
+  "form",
+  "popovertarget",
+  "commandfor",
+  "aria-activedescendant",
+  "data-notation-layer-id"
+];
+const ID_LIST_ATTRIBUTES = [
+  "aria-controls",
+  "aria-describedby",
+  "aria-details",
+  "aria-errormessage",
+  "aria-flowto",
+  "aria-labelledby",
+  "aria-owns",
+  "headers"
+];
+const URL_ATTRIBUTES = ["href", "xlink:href", "data-notation-href"];
+const SHARED_TEMPLATE_IDS = /* @__PURE__ */ 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;
+  }
+}
+`;
+function pageKey(slug) {
+  return exportPageRoute(slug).replace(/\//gu, "-") || "home";
+}
+function pageSectionId(slug) {
+  return `page--${pageKey(slug)}`;
+}
+function setAttribute(node, name, value) {
+  const existing = node.attrs.find((entry) => entry.name === name);
+  if (existing) existing.value = value;
+  else node.attrs.push({ name, value });
+}
+function firstElement(root, tagName) {
+  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) {
+  const parent = node.parentNode;
+  if (!parent) return;
+  const index = parent.childNodes.indexOf(node);
+  if (index !== -1) parent.childNodes.splice(index, 1);
+  node.parentNode = null;
+}
+function appendChild(parent, child) {
+  detach(child);
+  parent.childNodes.push(child);
+  child.parentNode = parent;
+}
+function element(tagName, attrs, children = []) {
+  const node = {
+    nodeName: tagName,
+    tagName,
+    attrs: Object.entries(attrs).map(([name, value]) => ({ name, value })),
+    namespaceURI: "http://www.w3.org/1999/xhtml",
+    parentNode: null,
+    childNodes: []
+  };
+  for (const child of children) appendChild(node, child);
+  return node;
+}
+function text(value) {
+  return { nodeName: "#text", value, parentNode: null };
+}
+function textOf(node) {
+  if ("value" in node && node.nodeName === "#text") return String(node.value);
+  return childrenOf(node).map((child) => textOf(child)).join("");
+}
+function routeOfPath(pathname, base) {
+  if (!pathname.startsWith(base)) return void 0;
+  let route;
+  try {
+    route = decodeURIComponent(pathname.slice(base.length));
+  } catch {
+    return void 0;
+  }
+  return route.replace(/(?:^|\/)index\.html$/u, "").replace(/\.html$/u, "").replace(/^\/+|\/+$/gu, "");
+}
+function absolutizeUrls(page, base) {
+  const location = new URL(`https://explico.invalid${base}${page.route ? `${page.route}/` : ""}`);
+  const absolute = (value) => {
+    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(", ")
+      );
+    }
+  }
+}
+function rewriteCssFragments(value, ids) {
+  return value.replace(/url\(\s*(["']?)#([^"')\s]+)\1\s*\)/gu, (match, quote, id) => {
+    const next = ids.get(id);
+    return next ? `url(${quote}#${next}${quote})` : match;
+  });
+}
+function rewriteUrl(value, page, pages, base) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("#")) {
+    let id2;
+    try {
+      id2 = decodeURIComponent(trimmed.slice(1));
+    } catch {
+      return value;
+    }
+    const next2 = page.ids.get(id2);
+    return next2 ? `#${next2}` : 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 === void 0 ? void 0 : pages.get(route);
+  if (!target) return value;
+  if (!url.hash) return `#${pageSectionId(target.slug)}`;
+  let id;
+  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, pages, base) {
+  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) : void 0;
+      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);
+      }
+    }
+  }
+}
+function islandContents(root) {
+  const inside = /* @__PURE__ */ new Set();
+  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;
+}
+function collectIds(page, first) {
+  const ids = /* @__PURE__ */ new Map();
+  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;
+}
+function uniqueIslandPrefixes(pages) {
+  const used = /* @__PURE__ */ new Set();
+  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`);
+          }
+        }
+      }
+    }
+  });
+}
+function isExecutable(node) {
+  const type = (attribute(node, "type") ?? "").trim().toLowerCase();
+  return type === "" || type === "module" || type === "text/javascript" || type === "application/javascript";
+}
+function panelClasses(main) {
+  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, titles) {
+  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)] : []
+      ])
+    )
+  );
+}
+function combinePages(input) {
+  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 = 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) : void 0;
+      if (next) setAttribute(node, "id", next);
+    }
+    rewriteReferences(page, byRoute, base);
+  }
+  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)]));
+  const main = firstElement(shell, "main");
+  const classes = panelClasses(main);
+  const seen = /* @__PURE__ */ new Set();
+  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;
+      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 === void 0) 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);
+}
+function combinedDownloads(manifest) {
+  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` : void 0;
+    const lessons = part.lessons.flatMap((id) => {
+      const lesson = lessonsById.get(id);
+      return lesson ? [lesson] : [];
+    });
+    return { part, overview, lessons };
+  });
+  const downloads = 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;
+}
+async function writeCombinedExports(directory, manifest) {
+  if (!manifest.lessonExports.standaloneHtml) return;
+  const outputRoot = fileURLToPath(directory);
+  const pending = [];
+  const sources = /* @__PURE__ */ new Map();
+  const source = (slug) => {
+    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
+      })
+    });
+  }
+  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 })));
+  }
+}
+export {
+  combinePages,
+  combinedDownloads,
+  pageKey,
+  pageSectionId,
+  writeCombinedExports
+};

package/dist/compiler/exports/download-index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `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.
+ */
+declare function writeDownloadIndex(directory: URL): Promise<void>;
+
+export { writeDownloadIndex };

package/dist/compiler/exports/download-index.js

@@ -0,0 +1,33 @@
+import { readdir, stat, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+async function writeDownloadIndex(directory) {
+  const root = join(fileURLToPath(directory), "downloads");
+  const files = [];
+  const walk = async (folder) => {
+    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)}
+`
+  );
+}
+export {
+  writeDownloadIndex
+};