@pieceful/ravel-host-node 0.1.1 → 0.3.0

package/src/index.js

@@ -1,5 +1,6 @@
 import { lstat, readFile, readdir, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
+import { deflateRawSync } from "node:zlib";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import {
@@ -8,10 +9,25 @@ import {
   createDeliverableProvenanceMap,
   provenanceMapVersion
 } from "@pieceful/ravel-core";
-import { markdownToMap } from "@pieceful/ravel-markdown";
+import { asciidocToMap } from "@pieceful/ravel-asciidoc";
+import { htmlToMap } from "@pieceful/ravel-html";
+import { markdownToMap, parseFrontMatter } from "@pieceful/ravel-markdown";
+import { isLitproMarkdown, litproMarkdownToMap } from "@pieceful/ravel-markdown-litpro";
 import { assertRavelMap } from "@pieceful/ravel-map";
+import { mystToMap } from "@pieceful/ravel-myst";
+import { nowebToMap } from "@pieceful/ravel-noweb";
+import { orgToMap } from "@pieceful/ravel-org";
+import { builtinTransforms } from "@pieceful/ravel-transforms";
+import { pathToFileURL } from "node:url";
 
 const missing = (error) => error?.code === "ENOENT";
+const componentPattern = /^[a-z][a-z0-9-]*$/;
+
+const throwIfAborted = (signal) => {
+  if (!signal?.aborted) return;
+  if (signal.reason instanceof Error) throw signal.reason;
+  throw new DOMException("The Ravel input operation was cancelled.", "AbortError");
+};
 
 const inputSource = (uri) => ({
   uri: typeof uri === "string" && uri.length ? uri : "<ravel-input>",
@@ -37,7 +53,25 @@ const inputError = (code, message, uri) => new RavelInputError([{
   source: inputSource(uri)
 }]);
 
-const readInputText = async (path, description, code) => {
+const overlayText = (overlays, path) => {
+  if (!overlays) return undefined;
+  const key = resolve(path);
+  const entry = overlays instanceof Map ? overlays.get(key) : overlays[key];
+  if (typeof entry === "string") return entry;
+  return typeof entry?.text === "string" ? entry.text : undefined;
+};
+
+const overlaysWithText = (overlays, path, text) => {
+  const captured = overlays instanceof Map
+    ? new Map(overlays)
+    : new Map(Object.entries(overlays ?? {}).map(([key, value]) => [resolve(key), value]));
+  captured.set(resolve(path), { text });
+  return captured;
+};
+
+const readInputText = async (path, description, code, overlays) => {
+  const overlay = overlayText(overlays, path);
+  if (overlay !== undefined) return overlay;
   try {
     return await readFile(path, "utf8");
   } catch (error) {
@@ -170,8 +204,8 @@ const createOutputScope = async (outputDirectory, rootDirectory) => {
   return { root: output, path: (path, description) => scopedPath(output, path, description) };
 };
 
-const readMap = async (path) => {
-  const text = await readInputText(path, "Ravel Map", "RM201");
+const readMap = async (path, overlays) => {
+  const text = await readInputText(path, "Ravel Map", "RM201", overlays);
   let map;
   try {
     map = JSON.parse(text);
@@ -181,56 +215,238 @@ const readMap = async (path) => {
   return assertRavelMap(map, { uri: path });
 };
 
-const loadMarkdownFile = async (path, options = {}) => markdownToMap(
-  await readInputText(path, "Markdown input", "RM201"),
-  { uri: path, document: options.document, mode: options.mode }
-);
+const loadMarkdownFile = async (path, options = {}, overlays) => {
+  const text = await readInputText(path, "Markdown input", "RM201", overlays);
+  if (options.adapter === "markdown-litpro" || options.profile === "litpro" ||
+      (options.adapter === undefined && options.profile === undefined && isLitproMarkdown(text))) {
+    return litproMarkdownToMap(text, {
+      uri: path,
+      document: options.document,
+      dialect: options.dialect,
+      headings: options.headings
+    });
+  }
+  return markdownToMap(text, {
+    uri: path,
+    document: options.document,
+    mode: options.mode,
+    profile: options.profile
+  });
+};
+
+const loadNowebFile = async (path, options = {}, overlays) => {
+  const text = await readInputText(path, "noweb input", "RM201", overlays);
+  return nowebToMap(text, {
+    uri: path,
+    document: options.document,
+    dialect: options.dialect,
+    references: options.references,
+    language: options.language,
+    run: options.run,
+    provider: options.provider
+  });
+};
+
+const loadOrgFile = async (path, options = {}, overlays) => {
+  const text = await readInputText(path, "Org input", "RM201", overlays);
+  return orgToMap(text, {
+    uri: path,
+    document: options.document,
+    references: options.references,
+    nowebPipes: options.nowebPipes,
+    executionOwner: options.executionOwner,
+    run: options.run,
+    provider: options.provider
+  });
+};
+
+const loadMystFile = async (path, options = {}, overlays) => {
+  const text = await readInputText(path, "MyST input", "RM201", overlays);
+  return mystToMap(text, {
+    uri: path,
+    document: options.document,
+    executionOwner: options.executionOwner,
+    run: options.run,
+    provider: options.provider
+  });
+};
 
-const collectPretransformMaps = async (entryPath, entryOptions = {}, scope) => {
+const loadAsciiDocFile = async (path, options = {}, overlays) => {
+  const text = await readInputText(path, "AsciiDoc input", "RM201", overlays);
+  return asciidocToMap(text, {
+    uri: path,
+    document: options.document,
+    run: options.run,
+    provider: options.provider
+  });
+};
+
+const loadHtmlFile = async (path, options = {}, overlays) => {
+  const text = await readInputText(path, "HTML input", "RM201", overlays);
+  return htmlToMap(text, {
+    uri: path,
+    document: options.document,
+    run: options.run,
+    provider: options.provider
+  });
+};
+
+const collectPretransformMaps = async (
+  entryPath,
+  entryOptions = {},
+  scope,
+  overlays = entryOptions.overlays
+) => {
+  const signal = entryOptions.signal;
+  throwIfAborted(signal);
   const activeScope = scope ?? await createInputScope(dirname(resolve(entryPath)));
   const visited = new Set();
   const maps = [];
+  const mapPaths = [];
   const diagnostics = [];
+  const authoredSourcePaths = new Set();
+  const authoredSourceTexts = new Map();
+  let containsJsonMaps = false;
 
   const visit = async (path, options = {}) => {
+    throwIfAborted(signal);
     const absolutePath = await activeScope.path(path, "Ravel input");
     if (visited.has(absolutePath)) return;
     visited.add(absolutePath);
 
     const extension = extname(absolutePath).toLowerCase();
     let map;
+    let sourceOverlays = overlays;
+    let sourceText;
+    const mystExtension = absolutePath.toLowerCase().endsWith(".myst.md");
     if (extension === ".json") {
-      map = await readMap(absolutePath);
-    } else if (extension === ".md" || extension === ".markdown" || extension === ".mdown") {
-      const result = await loadMarkdownFile(absolutePath, options);
+      containsJsonMaps = true;
+      map = await readMap(absolutePath, overlays);
+    } else if (mystExtension || options.adapter === "myst") {
+      authoredSourcePaths.add(absolutePath);
+      sourceText = await readInputText(absolutePath, "MyST input", "RM201", overlays);
+      sourceOverlays = overlaysWithText(overlays, absolutePath, sourceText);
+      const result = await loadMystFile(absolutePath, options, sourceOverlays);
+      map = result.map;
+      diagnostics.push(...result.diagnostics);
+      assertRavelMap(map, { uri: absolutePath });
+    } else if (extension === ".adoc" || extension === ".asciidoc" ||
+        options.adapter === "asciidoc") {
+      authoredSourcePaths.add(absolutePath);
+      sourceText = await readInputText(absolutePath, "AsciiDoc input", "RM201", overlays);
+      sourceOverlays = overlaysWithText(overlays, absolutePath, sourceText);
+      const result = await loadAsciiDocFile(absolutePath, options, sourceOverlays);
+      map = result.map;
+      diagnostics.push(...result.diagnostics);
+      assertRavelMap(map, { uri: absolutePath });
+    } else if (extension === ".html" || extension === ".htm" ||
+        options.adapter === "html") {
+      authoredSourcePaths.add(absolutePath);
+      sourceText = await readInputText(absolutePath, "HTML input", "RM201", overlays);
+      sourceOverlays = overlaysWithText(overlays, absolutePath, sourceText);
+      const result = await loadHtmlFile(absolutePath, options, sourceOverlays);
+      map = result.map;
+      diagnostics.push(...result.diagnostics);
+      assertRavelMap(map, { uri: absolutePath });
+    } else if (extension === ".org" || options.adapter === "org") {
+      authoredSourcePaths.add(absolutePath);
+      sourceText = await readInputText(absolutePath, "Org input", "RM201", overlays);
+      sourceOverlays = overlaysWithText(overlays, absolutePath, sourceText);
+      const result = await loadOrgFile(absolutePath, options, sourceOverlays);
+      map = result.map;
+      diagnostics.push(...result.diagnostics);
+      assertRavelMap(map, { uri: absolutePath });
+    } else if (extension === ".nw" || extension === ".noweb" || options.adapter === "noweb") {
+      authoredSourcePaths.add(absolutePath);
+      sourceText = await readInputText(absolutePath, "noweb input", "RM201", overlays);
+      sourceOverlays = overlaysWithText(overlays, absolutePath, sourceText);
+      const result = await loadNowebFile(absolutePath, options, sourceOverlays);
+      map = result.map;
+      diagnostics.push(...result.diagnostics);
+      assertRavelMap(map, { uri: absolutePath });
+    } else if (extension === ".md" || extension === ".markdown" || extension === ".mdown" || extension === ".qmd") {
+      authoredSourcePaths.add(absolutePath);
+      sourceText = await readInputText(absolutePath, "Markdown input", "RM201", overlays);
+      sourceOverlays = overlaysWithText(overlays, absolutePath, sourceText);
+      const result = await loadMarkdownFile(absolutePath, {
+        ...options,
+        profile: options.profile ?? (extension === ".qmd" ? "modern" : undefined)
+      }, sourceOverlays);
       map = result.map;
       diagnostics.push(...result.diagnostics);
       assertRavelMap(map, { uri: absolutePath });
     } else {
-      throw inputError("RH101", "Ravel input must be a .json map or Markdown file.", absolutePath);
+      throw inputError("RH101", "Ravel input must be a .json map or supported markup source.", absolutePath);
     }
+    if (sourceText !== undefined) authoredSourceTexts.set(absolutePath, sourceText);
+    throwIfAborted(signal);
     for (const directive of map.directives ?? []) {
       if (directive.kind !== "in") continue;
       const target = directive.target ?? directive.name;
       if (typeof target !== "string" || !target) {
         throw inputError("RH102", "in directive requires a target path.", directive.source?.uri ?? absolutePath);
       }
-      await visit(resolve(dirname(absolutePath), target));
+      const adapter = directive.metadata?.adapter;
+      const alias = directive.metadata?.legacy?.alias;
+      await visit(resolve(dirname(absolutePath), target), {
+        ...(adapter ? { adapter } : {}),
+        ...(directive.metadata?.dialect ? { dialect: directive.metadata.dialect } : {}),
+        ...(typeof alias === "string" && alias ? { document: alias } : {})
+      });
     }
     maps.push(map);
+    mapPaths.push(absolutePath);
   };
 
   await visit(entryPath, entryOptions);
-  return { maps, diagnostics, rootDirectory: activeScope.root };
+  throwIfAborted(signal);
+  return {
+    maps,
+    mapPaths,
+    diagnostics,
+    rootDirectory: activeScope.root,
+    authoredSourcePaths: [...authoredSourcePaths].sort(),
+    authoredSourceTexts,
+    loadedInputPaths: [...visited].sort(),
+    containsJsonMaps
+  };
 };
 
-export const loadPretransformGraph = async (entryPath, options = {}) => {
-  const collected = await collectPretransformMaps(resolve(entryPath), options);
+const graphFromCollectedMaps = (collected) => {
   const graph = combineMaps(collected.maps);
   graph.diagnostics.push(...collected.diagnostics);
   return relativizeSourceUris(graph, collected.rootDirectory);
 };
 
+const authoredSourceUris = (collected) => collected.authoredSourcePaths
+  .map((path) => relative(collected.rootDirectory, path).split(sep).join("/"))
+  .sort();
+
+const loadedInputUris = (collected) => collected.loadedInputPaths
+  .map((path) => relative(collected.rootDirectory, path).split(sep).join("/"))
+  .sort();
+
+const authoredSourceTexts = (collected) => Object.fromEntries(
+  [...collected.authoredSourceTexts.entries()]
+    .map(([path, text]) => [
+      relative(collected.rootDirectory, path).split(sep).join("/"),
+      text
+    ])
+    .sort(([left], [right]) => left.localeCompare(right))
+);
+
+export const loadPretransformGraph = async (entryPath, options = {}) => {
+  throwIfAborted(options.signal);
+  const collected = await collectPretransformMaps(
+    resolve(entryPath),
+    options,
+    undefined,
+    options.overlays
+  );
+  throwIfAborted(options.signal);
+  return graphFromCollectedMaps(collected);
+};
+
 const configSource = inputSource;
 
 const requireConfigString = (value, description, configPath) => {
@@ -246,49 +462,472 @@ const reportUnknownKeys = (value, allowed, description, configPath) => {
   }
 };
 
-export const loadTomlBuild = async (configPath) => {
+// Names core evaluates itself; a project transform cannot replace them.
+const coreTransformNames = new Set([
+  "concat", "trim", "normalize-eol", "indent", "dedent", "replace", "quote-reference",
+  "jsontext", "emit", "text", "ch", "delay"
+]);
+
+/**
+ * Load `[[transforms]]` entries: project-local ES modules whose export is a
+ * `(value, context) => string` function. These run as ordinary Node code with
+ * the host's privileges, so they are configured only in the TOML file, never by
+ * a document. Ravel's built-in transforms are always available and a project
+ * module may replace one of them (for example to use another Markdown engine).
+ */
+const loadProjectTransforms = async (entries, scope, absoluteConfig) => {
+  const transforms = { ...builtinTransforms };
+  if (entries === undefined) return transforms;
+  if (!Array.isArray(entries)) throw inputError("RC102", "transforms must contain [[transforms]] entries.", absoluteConfig);
+  const seen = new Set();
+  for (const [index, entry] of entries.entries()) {
+    const path = "transforms[" + index + "]";
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw inputError("RC102", path + " must be a table.", absoluteConfig);
+    reportUnknownKeys(entry, new Set(["name", "module", "export"]), path, absoluteConfig);
+    const name = requireConfigString(entry.name, path + ".name", absoluteConfig);
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) throw inputError("RC102", path + ".name must be a lowercase transform name such as \"markdown-it\".", absoluteConfig);
+    if (coreTransformNames.has(name)) throw inputError("RC102", path + ".name " + JSON.stringify(name) + " is a core command and cannot be replaced.", absoluteConfig);
+    if (seen.has(name)) throw inputError("RC102", path + ".name " + JSON.stringify(name) + " is defined more than once.", absoluteConfig);
+    seen.add(name);
+    const modulePath = await scope.path(requireConfigString(entry.module, path + ".module", absoluteConfig), path + ".module");
+    const exportName = entry.export === undefined ? "default" : requireConfigString(entry.export, path + ".export", absoluteConfig);
+    let namespace;
+    try {
+      // The content hash keeps a long-lived host (an editor) from reusing a
+      // stale module after the file changes.
+      const url = pathToFileURL(modulePath);
+      url.search = "ravel=" + contentHash(await readFile(modulePath, "utf8")).slice(0, 16);
+      namespace = await import(url.href);
+    } catch (error) {
+      throw inputError("RC103", path + " could not load " + modulePath + ": " + (error?.message ?? String(error)), absoluteConfig);
+    }
+    const transform = namespace[exportName];
+    if (typeof transform !== "function") {
+      throw inputError("RC103", path + " module " + modulePath + " has no function export " + JSON.stringify(exportName) + ".", absoluteConfig);
+    }
+    transforms[name] = transform;
+  }
+  return transforms;
+};
+
+const escapeRegExp = (value) => value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+
+/** Translate a `/`-separated glob (`*`, `**`, `?`) into an anchored RegExp. */
+const globPattern = (glob) => {
+  let pattern = "";
+  for (let index = 0; index < glob.length; index += 1) {
+    const character = glob[index];
+    if (character === "*" && glob[index + 1] === "*") {
+      const slash = glob[index + 2] === "/";
+      pattern += slash ? "(?:[^/]+/)*" : ".*";
+      index += slash ? 2 : 1;
+    } else if (character === "*") pattern += "[^/]*";
+    else if (character === "?") pattern += "[^/]";
+    else pattern += escapeRegExp(character);
+  }
+  return new RegExp("^" + pattern + "$");
+};
+
+/**
+ * List files under `root` matching `glob`, in a deterministic code-point
+ * order. Dot-files and dot-directories are skipped; a symbolic link anywhere
+ * in the walk is an error, as everywhere else in the Node host.
+ */
+const globFiles = async (root, glob, description) => {
+  if (isAbsolute(glob) || glob.split("/").includes("..")) {
+    throw new Error(description + " must be a relative glob inside the Ravel root: " + glob);
+  }
+  const segments = glob.split("/");
+  const firstWild = segments.findIndex((segment) => /[*?]/.test(segment));
+  const base = firstWild === -1 ? segments.slice(0, -1) : segments.slice(0, firstWild);
+  const start = join(root, ...base);
+  const matcher = globPattern(glob);
+  const matches = [];
+  const walk = async (directory) => {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (missing(error)) return;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(description + " must not traverse a symbolic link: " + path);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile() && matcher.test(portableRelative(root, path))) matches.push(path);
+    }
+  };
+  await assertNoSymlinks(root, start, description);
+  await walk(start);
+  return matches.sort((left, right) => {
+    const a = portableRelative(root, left);
+    const b = portableRelative(root, right);
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+};
+
+const positionAt = (text, offset) => {
+  let line = 0;
+  let lineStart = 0;
+  for (let index = text.indexOf("\n"); index !== -1 && index < offset; index = text.indexOf("\n", index + 1)) {
+    line += 1;
+    lineStart = index + 1;
+  }
+  return { line, column: offset - lineStart, offset };
+};
+
+const slugify = (value) => String(value).toLowerCase().normalize("NFKD")
+  .replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+const fillPattern = (pattern, values, description, configPath) => pattern.replace(/\{([a-z][a-z0-9_-]*)\}/gi, (match, key) => {
+  const value = values[key];
+  if (value === undefined || value === null || typeof value === "object") {
+    throw inputError("RC104", description + " uses {" + key + "}, which is not a text value for this item.", configPath);
+  }
+  return String(value);
+});
+
+/**
+ * Expand `[[collections]]`: every file matching `glob` becomes an item
+ * document with a `body` chunk (the text after any front matter, mapped to its
+ * exact source range), a `data.json` chunk (front matter plus slug, name, path,
+ * and output), and a `page` chunk that pipes the body through `pipe` and, when
+ * `layout` names a chunk, fills that layout with `template`. Each item gets one
+ * `out` directive from the `out` pattern. A `<name>::index.json` chunk lists
+ * every item's data, in order, for index pages.
+ */
+const loadCollections = async (entries, scope, absoluteConfig, overlays) => {
+  const empty = { maps: [], inputPaths: [], texts: new Map() };
+  if (entries === undefined) return empty;
+  if (!Array.isArray(entries)) throw inputError("RC102", "collections must contain [[collections]] entries.", absoluteConfig);
+  const maps = [];
+  const inputPaths = [];
+  const texts = new Map();
+  const names = new Set();
+  const configUri = portableRelative(scope.root, absoluteConfig);
+  for (const [index, entry] of entries.entries()) {
+    const path = "collections[" + index + "]";
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw inputError("RC102", path + " must be a table.", absoluteConfig);
+    reportUnknownKeys(entry, new Set(["name", "glob", "out", "layout", "pipe", "references"]), path, absoluteConfig);
+    const name = requireConfigString(entry.name, path + ".name", absoluteConfig);
+    if (!componentPattern.test(name)) throw inputError("RC102", path + ".name must be a lowercase identifier such as \"pages\".", absoluteConfig);
+    if (names.has(name)) throw inputError("RC102", path + ".name " + JSON.stringify(name) + " is used by more than one collection.", absoluteConfig);
+    names.add(name);
+    const glob = requireConfigString(entry.glob, path + ".glob", absoluteConfig);
+    const outPattern = requireConfigString(entry.out, path + ".out", absoluteConfig);
+    const layout = entry.layout === undefined ? null : requireConfigString(entry.layout, path + ".layout", absoluteConfig);
+    const pipe = entry.pipe === undefined ? "markdown" : entry.pipe;
+    if (typeof pipe !== "string") throw inputError("RC102", path + ".pipe must be a pipeline string such as \"markdown\" or \"\".", absoluteConfig);
+    if (entry.references !== undefined && typeof entry.references !== "boolean") {
+      throw inputError("RC102", path + ".references must be true or false.", absoluteConfig);
+    }
+    for (const [field, value] of [["layout", layout ?? ""], ["pipe", pipe]]) {
+      if (value.includes("`")) throw inputError("RC102", path + "." + field + " must not contain a backtick.", absoluteConfig);
+    }
+    let files;
+    try {
+      files = await globFiles(scope.root, glob, path + ".glob");
+    } catch (error) {
+      throw inputError("RC104", error.message, absoluteConfig);
+    }
+    const items = [];
+    const slugs = new Map();
+    for (const file of files) {
+      const uri = portableRelative(scope.root, file);
+      const text = await readInputText(file, "collection item", "RC101", overlays);
+      let front;
+      try {
+        front = parseFrontMatter(text);
+      } catch (error) {
+        throw inputError("RC104", "Invalid front matter in " + uri + ": " + (error?.message ?? String(error)), file);
+      }
+      const data = front.data ?? {};
+      if (typeof data !== "object" || Array.isArray(data)) throw inputError("RC104", "Front matter in " + uri + " must be a mapping.", file);
+      const stem = basename(uri, extname(uri));
+      const slug = slugify(typeof data.slug === "string" ? data.slug : stem);
+      if (!slug) throw inputError("RC104", "Could not derive a slug for " + uri + "; add a `slug` to its front matter.", file);
+      if (slugs.has(slug)) throw inputError("RC104", uri + " and " + slugs.get(slug) + " both produce the slug " + JSON.stringify(slug) + " in collection " + name + ".", file);
+      slugs.set(slug, uri);
+      const dir = dirname(uri) === "." ? "" : dirname(uri);
+      const values = { ...data, slug, name: stem, dir, path: uri.slice(0, uri.length - extname(uri).length) };
+      const output = fillPattern(outPattern, values, path + ".out", absoluteConfig);
+      items.push({ file, uri, text, front, data: { ...data, slug, name: stem, dir, path: uri, out: output, collection: name }, output });
+    }
+    const sourceAt = (uri, text, start, end) => ({ uri, range: { start: positionAt(text, start), end: positionAt(text, end) } });
+    const literalSyntax = (enabled) => ({ data: { ravel: { referenceSyntax: { underscore: enabled } } } });
+    for (const item of items) {
+      const document = name + "-" + item.data.slug;
+      if (!componentPattern.test(document)) throw inputError("RC104", "Collection item " + item.uri + " produces the invalid document id " + document + ".", item.file);
+      const chunk = (chunkName, type, body, source, metadata) => ({
+        id: document + "::" + chunkName + (type ? "." + type : ""),
+        identity: { document, chunk: chunkName, minor: null, type },
+        name: chunkName,
+        body,
+        definitionPipeline: [],
+        metadata,
+        source
+      });
+      const bodySource = sourceAt(item.uri, item.text, item.front.bodyStart, item.text.length);
+      const frontSource = sourceAt(item.uri, item.text, 0, item.front.end);
+      const content = "ch('" + document + "::body" + (pipe.trim() ? " | " + pipe.trim() : "") + "')";
+      const page = layout
+        ? "_`" + layout + " | template(ch('" + document + "::data.json'), 'content', " + content + ")`"
+        : "_`" + document + "::body" + (pipe.trim() ? " | " + pipe.trim() : "") + "`";
+      maps.push({
+        version: 1,
+        document: { id: document, uri: item.uri, format: "ravel-collection-item-v1" },
+        chunks: [
+          chunk("body", null, item.text.slice(item.front.bodyStart), bodySource, { language: "markdown", tags: ["collection"], ...literalSyntax(entry.references === true) }),
+          chunk("data", "json", JSON.stringify(item.data, null, 2) + "\n", frontSource, { language: "json", tags: ["collection"], ...literalSyntax(false) })
+        ],
+        directives: [
+          { kind: "create", document, name: "page", body: page, source: configSource(absoluteConfig) },
+          { kind: "out", name: item.output, from: document + "::page", source: configSource(absoluteConfig) }
+        ]
+      });
+      inputPaths.push(item.file);
+      texts.set(item.file, item.text);
+    }
+    maps.push({
+      version: 1,
+      document: { id: name, uri: configUri, format: "ravel-collection-index-v1" },
+      chunks: [{
+        id: name + "::index.json",
+        identity: { document: name, chunk: "index", minor: null, type: "json" },
+        name: "index",
+        body: JSON.stringify(items.map((item) => item.data), null, 2) + "\n",
+        definitionPipeline: [],
+        metadata: { language: "json", tags: ["collection"], ...literalSyntax(false) },
+        source: configSource(absoluteConfig)
+      }],
+      directives: []
+    });
+  }
+  return { maps, inputPaths, texts };
+};
+
+const loadLiveConfiguration = async (
+  live,
+  scope,
+  configPath,
+  overlays,
+  { readResources = true } = {}
+) => {
+  if (live === undefined) return undefined;
+  if (!live || typeof live !== "object" || Array.isArray(live)) {
+    throw inputError("RC102", "live must be a [live] table.", configPath);
+  }
+  reportUnknownKeys(live, new Set(["modules", "resources"]), "live", configPath);
+  if (live.modules !== undefined && !Array.isArray(live.modules)) {
+    throw inputError("RC102", "live.modules must contain [[live.modules]] entries.", configPath);
+  }
+  if (live.resources !== undefined && !Array.isArray(live.resources)) {
+    throw inputError("RC102", "live.resources must contain [[live.resources]] entries.", configPath);
+  }
+
+  const moduleSpecifiers = new Set();
+  const modules = (live.modules ?? []).map((entry, index) => {
+    const description = "live.modules[" + index + "]";
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw inputError("RC102", description + " must be a table.", configPath);
+    }
+    reportUnknownKeys(entry, new Set(["specifier", "from"]), description, configPath);
+    const specifier = requireConfigString(entry.specifier, description + ".specifier", configPath);
+    const from = requireConfigString(entry.from, description + ".from", configPath);
+    if (moduleSpecifiers.has(specifier)) {
+      throw inputError("RC102", "Duplicate live module specifier: " + specifier, configPath);
+    }
+    moduleSpecifiers.add(specifier);
+    return { specifier, from, source: configSource(configPath) };
+  });
+
+  const resourceNames = new Set();
+  const resourceResults = await Promise.all((live.resources ?? []).map(async (entry, index) => {
+    const description = "live.resources[" + index + "]";
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw inputError("RC102", description + " must be a table.", configPath);
+    }
+    reportUnknownKeys(entry, new Set(["name", "path"]), description, configPath);
+    const name = requireConfigString(entry.name, description + ".name", configPath);
+    const path = requireConfigString(entry.path, description + ".path", configPath);
+    if (resourceNames.has(name)) {
+      throw inputError("RC102", "Duplicate live resource name: " + name, configPath);
+    }
+    resourceNames.add(name);
+    const absolutePath = await scope.path(path, description + ".path");
+    const declaration = { name, path, source: configSource(configPath) };
+    if (!readResources) return { declaration };
+    return {
+      declaration,
+      entry: [name, await readInputText(
+        absolutePath,
+        "live resource",
+        "RC103",
+        overlays
+      )]
+    };
+  }));
+
+  return {
+    modules,
+    resources: Object.fromEntries(resourceResults.flatMap((result) =>
+      result.entry ? [result.entry] : []
+    )),
+    resourceDeclarations: resourceResults.map(({ declaration }) => declaration)
+  };
+};
+
+export const loadTomlBuild = async (configPath, options = {}) => {
+  throwIfAborted(options.signal);
   const absoluteConfig = resolve(configPath);
   const scope = await createInputScope(dirname(absoluteConfig));
   const configFile = await scope.path(absoluteConfig, "Ravel TOML config");
   let config;
   try {
-    config = parseToml(await readInputText(configFile, "Ravel TOML config", "RC101"));
+    config = parseToml(await readInputText(
+      configFile,
+      "Ravel TOML config",
+      "RC101",
+      options.overlays
+    ));
+    throwIfAborted(options.signal);
   } catch (error) {
     if (Array.isArray(error?.diagnostics)) throw error;
     throw inputError("RC101", "Invalid Ravel TOML config: " + (error?.message ?? String(error)), absoluteConfig);
   }
-  reportUnknownKeys(config, new Set(["version", "files", "build", "outputs"]), "config", absoluteConfig);
+  reportUnknownKeys(config, new Set(["version", "files", "collections", "build", "outputs", "live", "transforms"]), "config", absoluteConfig);
   if (config.version !== 1) throw inputError("RC102", "version must be 1.", absoluteConfig);
-  if (!Array.isArray(config.files) || config.files.length === 0) {
-    throw inputError("RC102", "files must contain one or more [[files]] entries.", absoluteConfig);
+  if (config.files !== undefined && !Array.isArray(config.files)) {
+    throw inputError("RC102", "files must contain [[files]] entries.", absoluteConfig);
+  }
+  if (!config.files?.length && !config.collections?.length) {
+    throw inputError("RC102", "files must contain one or more [[files]] entries, or the config must define [[collections]].", absoluteConfig);
   }
-  if (!config.build || typeof config.build !== "object") {
+  if (config.build !== undefined && (!config.build || typeof config.build !== "object" || Array.isArray(config.build))) {
     throw inputError("RC102", "build must be a [build] table.", absoluteConfig);
   }
-  reportUnknownKeys(config.build, new Set(["name", "out_dir", "clean", "backup"]), "build", absoluteConfig);
-  if (config.build.name !== undefined) requireConfigString(config.build.name, "build.name", absoluteConfig);
-  if (config.build.clean !== undefined && typeof config.build.clean !== "boolean") {
+  const build = config.build ?? {};
+  reportUnknownKeys(build, new Set(["name", "out_dir", "clean", "backup"]), "build", absoluteConfig);
+  if (build.name !== undefined) requireConfigString(build.name, "build.name", absoluteConfig);
+  if (build.clean !== undefined && typeof build.clean !== "boolean") {
     throw inputError("RC102", "build.clean must be true or false.", absoluteConfig);
   }
-  if (config.build.backup !== undefined && typeof config.build.backup !== "boolean" &&
-      (typeof config.build.backup !== "string" || config.build.backup.length === 0)) {
+  if (build.backup !== undefined && typeof build.backup !== "boolean" &&
+      (typeof build.backup !== "string" || build.backup.length === 0)) {
     throw inputError("RC102", "build.backup must be true, false, or a non-empty .zip path.", absoluteConfig);
   }
-  if (typeof config.build.backup === "string" && extname(config.build.backup).toLowerCase() !== ".zip") {
+  if (typeof build.backup === "string" && extname(build.backup).toLowerCase() !== ".zip") {
     throw inputError("RC102", "build.backup must name a .zip file.", absoluteConfig);
   }
-  const outDirectory = requireConfigString(config.build.out_dir, "build.out_dir", absoluteConfig);
+  const outDirectory = build.out_dir === undefined
+    ? undefined
+    : requireConfigString(build.out_dir, "build.out_dir", absoluteConfig);
   const baseDirectory = scope.root;
-  const results = await Promise.all(config.files.map(async (file, index) => {
+  const live = await loadLiveConfiguration(
+    config.live,
+    scope,
+    absoluteConfig,
+    options.overlays,
+    { readResources: options.readLiveResources !== false }
+  );
+  const results = await Promise.all((config.files ?? []).map(async (file, index) => {
     if (!file || typeof file !== "object") throw inputError("RC102", "files[" + index + "] must be a table.", absoluteConfig);
-    reportUnknownKeys(file, new Set(["path", "document", "mode"]), "files[" + index + "]", absoluteConfig);
+    reportUnknownKeys(file, new Set([
+      "path", "document", "mode", "profile", "adapter", "dialect",
+      "references", "language", "noweb_pipes", "execution_owner", "run", "provider"
+    ]), "files[" + index + "]", absoluteConfig);
     const path = requireConfigString(file.path, "files[" + index + "].path", absoluteConfig);
     if (file.document !== undefined) requireConfigString(file.document, "files[" + index + "].document", absoluteConfig);
     const mode = file.mode ?? "opt-in";
     if (!["opt-in", "primary"].includes(mode)) throw inputError("RC102", "files[" + index + "].mode must be opt-in or primary.", absoluteConfig);
-    return collectPretransformMaps(resolve(baseDirectory, path), { document: file.document, mode }, scope);
+    const profile = file.profile;
+    if (profile !== undefined && !["fences", "modern", "litpro"].includes(profile)) {
+      throw inputError("RC102", "files[" + index + "].profile must be fences, modern, or litpro.", absoluteConfig);
+    }
+    const adapter = file.adapter;
+    if (adapter !== undefined && !["asciidoc", "html", "markdown", "markdown-litpro", "myst", "noweb", "org"].includes(adapter)) {
+      throw inputError("RC102", "files[" + index + "].adapter must be asciidoc, html, markdown, markdown-litpro, myst, noweb, or org.", absoluteConfig);
+    }
+    const dialect = file.dialect;
+    const supportedDialects = adapter === "noweb"
+      ? ["noweb", "noweb-plus"]
+      : adapter === "asciidoc" || adapter === "html" ||
+          adapter === "org" || adapter === "myst"
+        ? []
+        : ["litpro-2017", "pieceful-2020", "litpro-plus"];
+    if (dialect !== undefined && !supportedDialects.includes(dialect)) {
+      throw inputError("RC102", "files[" + index + "].dialect is not supported by its adapter.", absoluteConfig);
+    }
+    const references = file.references;
+    const supportedReferences = adapter === "org"
+      ? ["org-noweb", "underscore-quote", "both"]
+      : ["noweb", "underscore-quote", "both"];
+    if (references !== undefined && !supportedReferences.includes(references)) {
+      throw inputError("RC102", "files[" + index + "].references is not supported by its adapter.", absoluteConfig);
+    }
+    if (file.language !== undefined) requireConfigString(file.language, "files[" + index + "].language", absoluteConfig);
+    if (file.noweb_pipes !== undefined && typeof file.noweb_pipes !== "boolean") {
+      throw inputError("RC102", "files[" + index + "].noweb_pipes must be true or false.", absoluteConfig);
+    }
+    const executionOwner = file.execution_owner;
+    const supportedExecutionOwners = adapter === "myst"
+      ? ["myst", "ravel"]
+      : ["org", "ravel"];
+    if (executionOwner !== undefined && !supportedExecutionOwners.includes(executionOwner)) {
+      throw inputError(
+        "RC102",
+        "files[" + index + "].execution_owner is not supported by its adapter.",
+        absoluteConfig
+      );
+    }
+    if (file.run !== undefined && typeof file.run !== "boolean") {
+      throw inputError("RC102", "files[" + index + "].run must be true or false.", absoluteConfig);
+    }
+    if (file.provider !== undefined) requireConfigString(file.provider, "files[" + index + "].provider", absoluteConfig);
+    if (file.language !== undefined && adapter !== "noweb") {
+      throw inputError("RC102", "files[" + index + "].language currently requires adapter = \"noweb\".", absoluteConfig);
+    }
+    if (file.noweb_pipes !== undefined && adapter !== "org") {
+      throw inputError("RC102", "noweb_pipes requires adapter = \"org\".", absoluteConfig);
+    }
+    if (executionOwner !== undefined && !["org", "myst"].includes(adapter)) {
+      throw inputError("RC102", "execution_owner requires adapter = \"org\" or \"myst\".", absoluteConfig);
+    }
+    if (references !== undefined && !["noweb", "org"].includes(adapter)) {
+      throw inputError("RC102", "references requires adapter = \"noweb\" or \"org\".", absoluteConfig);
+    }
+    if ((file.run !== undefined || file.provider !== undefined) &&
+        !["asciidoc", "html", "noweb", "org", "myst"].includes(adapter)) {
+      throw inputError("RC102", "run and provider settings require adapter = \"asciidoc\", \"html\", \"noweb\", \"org\", or \"myst\".", absoluteConfig);
+    }
+    return collectPretransformMaps(resolve(baseDirectory, path), {
+      document: file.document,
+      mode,
+      profile,
+      adapter,
+      dialect,
+      references,
+      language: file.language,
+      nowebPipes: file.noweb_pipes,
+      executionOwner,
+      run: file.run,
+      provider: file.provider,
+      signal: options.signal
+    }, scope, options.overlays);
   }));
-  const pretransform = combineMaps(results.flatMap((result) => result.maps));
+  throwIfAborted(options.signal);
+  // Several [[files]] may import the same document; load it once, keeping the
+  // first occurrence in configuration order.
+  const seenMapPaths = new Set();
+  const collections = await loadCollections(config.collections, scope, absoluteConfig, options.overlays);
+  const pretransform = combineMaps([...results.flatMap((result) => result.maps.filter((_, index) => {
+    const path = result.mapPaths[index];
+    if (seenMapPaths.has(path)) return false;
+    seenMapPaths.add(path);
+    return true;
+  })), ...collections.maps]);
   pretransform.diagnostics.push(...results.flatMap((result) => result.diagnostics));
   for (const output of config.outputs ?? []) {
     if (!output || typeof output !== "object") throw inputError("RC102", "Each [[outputs]] entry must be a table.", absoluteConfig);
@@ -302,35 +941,58 @@ export const loadTomlBuild = async (configPath) => {
   }
   return {
     pretransform: relativizeSourceUris(pretransform, scope.root),
-    outputDirectory: await scope.path(outDirectory, "build.out_dir"),
+    authoredSourceUris: [...new Set([
+      ...results.flatMap(authoredSourceUris),
+      ...collections.inputPaths.map((path) => portableRelative(scope.root, path))
+    ])].sort(),
+    authoredSourceTexts: Object.assign({}, ...results.map(authoredSourceTexts), Object.fromEntries(
+      [...collections.texts.entries()].map(([path, text]) => [portableRelative(scope.root, path), text])
+    )),
+    loadedInputUris: [...new Set([
+      relative(scope.root, absoluteConfig).split(sep).join("/"),
+      ...results.flatMap(loadedInputUris),
+      ...collections.inputPaths.map((path) => portableRelative(scope.root, path))
+    ])].sort(),
+    sourceEditsAllowed: results.every((result) => !result.containsJsonMaps),
+    ...(outDirectory === undefined ? {} : { outputDirectory: await scope.path(outDirectory, "build.out_dir") }),
     rootDirectory: scope.root,
     buildOptions: {
-      clean: config.build.clean === true,
-      backup: config.build.backup ?? false
-    }
+      clean: build.clean === true,
+      backup: build.backup ?? false
+    },
+    transforms: await loadProjectTransforms(config.transforms, scope, absoluteConfig),
+    ...(live ? { live } : {})
   };
 };
 
-/** Load a JSON map, one Markdown document, or a single Ravel TOML build run. */
+/** Load a JSON map, one markup source document, or a Ravel TOML build run. */
 export const loadBuildInput = async (inputPath, options = {}) => {
+  throwIfAborted(options.signal);
   const extension = extname(inputPath).toLowerCase();
-  if (extension === ".toml") return loadTomlBuild(inputPath);
-  if (extension === ".md" || extension === ".markdown" || extension === ".mdown") {
-    const rootDirectory = dirname(resolve(inputPath));
-    return {
-      pretransform: await loadPretransformGraph(resolve(inputPath), options),
-      outputDirectory: undefined,
-      rootDirectory
-    };
-  }
-  if (extension === ".json") {
+  if (extension === ".toml") return loadTomlBuild(inputPath, options);
+  if (extension === ".md" || extension === ".markdown" || extension === ".mdown" || extension === ".qmd" ||
+      extension === ".nw" || extension === ".noweb" || extension === ".org" ||
+      extension === ".adoc" || extension === ".asciidoc" ||
+      extension === ".html" || extension === ".htm" || extension === ".json") {
+    const collected = await collectPretransformMaps(
+      resolve(inputPath),
+      options,
+      undefined,
+      options.overlays
+    );
+    throwIfAborted(options.signal);
     return {
-      pretransform: await loadPretransformGraph(inputPath),
+      pretransform: graphFromCollectedMaps(collected),
       outputDirectory: undefined,
-      rootDirectory: dirname(resolve(inputPath))
+      rootDirectory: collected.rootDirectory,
+      authoredSourceUris: authoredSourceUris(collected),
+      authoredSourceTexts: authoredSourceTexts(collected),
+      loadedInputUris: loadedInputUris(collected),
+      sourceEditsAllowed: !collected.containsJsonMaps,
+      transforms: { ...builtinTransforms }
     };
   }
-  throw inputError("RH101", "Ravel input must be a .json map, Markdown document, or .toml build config.", inputPath);
+  throw inputError("RH101", "Ravel input must be a .json map, supported markup document, or .toml build config.", inputPath);
 };
 
 const safeDestination = (outputDirectory, name) => {
@@ -359,19 +1021,21 @@ const sidecarName = (name) => name + ".ravelmap";
 /** Build a deterministic, non-writing description of artifact output. */
 export const planDeliverables = (program, outputDirectory) => {
   const root = resolve(outputDirectory);
-  const destinations = new Set();
+  // Compare case-insensitively so a plan is portable to macOS and Windows,
+  // where `README.md` and `readme.md` name the same file.
+  const destinations = new Set([manifestName, textManifestName].map((name) => safeDestination(root, name).toLowerCase()));
+  const claim = (destination, message) => {
+    const key = destination.toLowerCase();
+    if (destinations.has(key)) throw new Error(message);
+    destinations.add(key);
+  };
   const deliverables = orderedDeliverables(program).map((deliverable) => {
     const destination = safeDestination(root, deliverable.name);
-    if (destinations.has(destination)) throw new Error("Multiple deliverables resolve to the same destination: " + deliverable.name);
-    destinations.add(destination);
+    claim(destination, "Deliverable collides with another output or Ravel's manifest (names are compared case-insensitively): " + deliverable.name);
     const hasProvenance = Array.isArray(deliverable.segments);
     const ravelmap = hasProvenance ? sidecarName(deliverable.name) : null;
     if (ravelmap) {
-      const mapDestination = safeDestination(root, ravelmap);
-      if (destinations.has(mapDestination)) {
-        throw new Error("A deliverable provenance map collides with another output: " + ravelmap);
-      }
-      destinations.add(mapDestination);
+      claim(safeDestination(root, ravelmap), "A deliverable provenance map collides with another output: " + ravelmap);
     }
     return {
       name: deliverable.name,
@@ -383,10 +1047,7 @@ export const planDeliverables = (program, outputDirectory) => {
     };
   });
   if (deliverables.some((deliverable) => deliverable.ravelmap)) {
-    const aggregateDestination = safeDestination(root, aggregateProvenanceName);
-    if (destinations.has(aggregateDestination)) {
-      throw new Error("The aggregate provenance map collides with another output: " + aggregateProvenanceName);
-    }
+    claim(safeDestination(root, aggregateProvenanceName), "The aggregate provenance map collides with another output: " + aggregateProvenanceName);
   }
   return {
     version: 1,
@@ -498,8 +1159,9 @@ const writeFilesAtomically = async (scope, entries, description) => {
       const token = randomUUID();
       const temporary = join(dirname(entry.destination), "." + basename(entry.destination) + ".ravel-stage-" + token);
       const backup = join(dirname(entry.destination), "." + basename(entry.destination) + ".ravel-backup-" + token);
-      await writeFile(temporary, entry.value, "utf8");
+      // Record the entry before writing so a failed write still removes its temporary file.
       staged.push({ ...entry, exists, temporary, backup, committed: false, backedUp: false });
+      await writeFile(temporary, entry.value, "utf8");
     }
 
     for (const entry of staged) {
@@ -522,16 +1184,25 @@ const writeFilesAtomically = async (scope, entries, description) => {
       }
     }
   } catch (error) {
+    // Restore every entry even if one restoration fails, then report the
+    // original failure with any rollback problems attached.
+    const rollbackErrors = [];
     for (const entry of staged.slice().reverse()) {
-      if (entry.committed) await removeIfPresent(entry.destination);
-      if (entry.backedUp) {
+      for (const step of [
+        () => entry.committed && removeIfPresent(entry.destination),
+        () => entry.backedUp && rename(entry.backup, entry.destination),
+        () => removeIfPresent(entry.temporary)
+      ]) {
         try {
-          await rename(entry.backup, entry.destination);
+          await step();
         } catch (rollbackError) {
-          if (!missing(rollbackError)) throw rollbackError;
+          if (!missing(rollbackError)) rollbackErrors.push(rollbackError);
         }
       }
-      await removeIfPresent(entry.temporary);
+    }
+    if (rollbackErrors.length) {
+      error.message += " (rollback incomplete: " + rollbackErrors.map((entry) => entry.message).join("; ") + ")";
+      error.rollbackErrors = rollbackErrors;
     }
     throw error;
   }
@@ -622,10 +1293,14 @@ export const writeBuildManifest = async (program, outputDirectory, {
 export const writeBuildArtifacts = async (program, outputDirectory, {
   rootDirectory = outputDirectory,
   stale = [],
+  clean = false,
   generatedAt = new Date().toISOString()
 } = {}) => {
   const scope = await createOutputScope(outputDirectory, rootDirectory);
   const plan = planDeliverables(program, scope.root);
+  // With `clean`, previously managed files are removed only after the new
+  // build has committed, so a failed write keeps the last good output.
+  const previous = clean ? await readManifest(scope.root, rootDirectory) : null;
   const manifest = createBuildManifest(program, scope.root, { stale, builtAt: generatedAt });
   const deliverableEntries = plan.deliverables.map((deliverable) => ({
     destination: safeDestination(scope.root, deliverable.name),
@@ -654,8 +1329,27 @@ export const writeBuildArtifacts = async (program, outputDirectory, {
     { destination: manifestDestination, value: JSON.stringify(manifest, null, 2) + "\n" },
     { destination: textManifestDestination, value: formatTextManifest(manifest, generatedAt) }
   ], "Build artifact path");
+  // Remove previously managed deliverables (and their sidecars) that this
+  // build no longer produces; files it rewrote were already replaced.
+  const active = new Set(plan.deliverables.map((deliverable) => deliverable.name));
+  const supersededDeliverables = previous
+    ? managedDeliverables(previous.manifest).filter((deliverable) => !active.has(deliverable.name))
+    : [];
+  const superseded = supersededDeliverables.flatMap((deliverable) => [
+    safeDestination(scope.root, deliverable.name),
+    ...(deliverable.ravelmap ? [safeDestination(scope.root, deliverable.ravelmap)] : [])
+  ]);
+  if (previous?.manifest.provenance?.aggregate && !aggregateEntry.length) {
+    superseded.push(safeDestination(scope.root, previous.manifest.provenance.aggregate));
+  }
+  await removeManagedTargets(scope, superseded);
   return {
     written: deliverableEntries.map((entry) => entry.destination),
+    removed: supersededDeliverables.map((deliverable) => ({
+      name: deliverable.name,
+      path: portableRelative(scope.root, safeDestination(scope.root, deliverable.name)),
+      from: deliverable.from ?? null
+    })).sort((left, right) => left.name.localeCompare(right.name)),
     provenance: {
       sidecars: provenanceEntries.map((entry) => entry.destination),
       aggregate: aggregateEntry[0]?.destination ?? null
@@ -687,6 +1381,23 @@ const planManagedRemoval = async (outputDirectory, rootDirectory, staleOnly) =>
   };
 };
 
+/** Delete managed files only after every path component passes the symlink policy. */
+const removeManagedTargets = async (scope, targets) => {
+  for (const target of targets) {
+    await assertNoSymlinks(scope.root, target, "Managed output path");
+    await existingFile(target, "Managed output path");
+  }
+  for (const target of targets) await removeIfPresent(target);
+};
+
+const managedTargets = (root, manifest) => [
+  ...managedDeliverables(manifest).flatMap((deliverable) => [
+    safeDestination(root, deliverable.name),
+    ...(deliverable.ravelmap ? [safeDestination(root, deliverable.ravelmap)] : [])
+  ]),
+  ...(manifest.provenance?.aggregate ? [safeDestination(root, manifest.provenance.aggregate)] : [])
+];
+
 const removeManagedFiles = async (plan, rootDirectory, dryRun, removeManifest) => {
   if (!plan.manifest || dryRun) return { removed: plan.deliverables, manifestRemoved: false };
   const scope = await createOutputScope(plan.outputDirectory, rootDirectory);
@@ -698,8 +1409,7 @@ const removeManagedFiles = async (plan, rootDirectory, dryRun, removeManifest) =
     ...(plan.aggregate ? [safeDestination(scope.root, plan.aggregate)] : []),
     ...(removeManifest ? [safeDestination(scope.root, manifestName), safeDestination(scope.root, textManifestName)] : [])
   ];
-  for (const target of targets) await existingFile(target, "Managed output path");
-  for (const target of targets) await removeIfPresent(target);
+  await removeManagedTargets(scope, targets);
   return { removed: plan.deliverables, manifestRemoved: removeManifest };
 };
 
@@ -765,30 +1475,34 @@ const zipArchive = (files) => {
     }
     const { date, time } = zipDateTime(file.mtime);
     const crc = crc32(file.value);
+    // Deflate when it helps; tiny or incompressible files stay stored.
+    const deflated = deflateRawSync(file.value);
+    const method = deflated.length < size ? 8 : 0;
+    const data = method === 8 ? deflated : file.value;
     const local = Buffer.alloc(30);
     local.writeUInt32LE(0x04034b50, 0);
     local.writeUInt16LE(20, 4);
     local.writeUInt16LE(0x0800, 6);
-    local.writeUInt16LE(0, 8);
+    local.writeUInt16LE(method, 8);
     local.writeUInt16LE(time, 10);
     local.writeUInt16LE(date, 12);
     local.writeUInt32LE(crc, 14);
-    local.writeUInt32LE(size, 18);
+    local.writeUInt32LE(data.length, 18);
     local.writeUInt32LE(size, 22);
     local.writeUInt16LE(name.length, 26);
     local.writeUInt16LE(0, 28);
-    locals.push(local, name, file.value);
+    locals.push(local, name, data);
 
     const directory = Buffer.alloc(46);
     directory.writeUInt32LE(0x02014b50, 0);
     directory.writeUInt16LE(20, 4);
     directory.writeUInt16LE(20, 6);
     directory.writeUInt16LE(0x0800, 8);
-    directory.writeUInt16LE(0, 10);
+    directory.writeUInt16LE(method, 10);
     directory.writeUInt16LE(time, 12);
     directory.writeUInt16LE(date, 14);
     directory.writeUInt32LE(crc, 16);
-    directory.writeUInt32LE(size, 20);
+    directory.writeUInt32LE(data.length, 20);
     directory.writeUInt32LE(size, 24);
     directory.writeUInt16LE(name.length, 28);
     directory.writeUInt16LE(0, 30);
@@ -798,7 +1512,7 @@ const zipArchive = (files) => {
     directory.writeUInt32LE(0, 38);
     directory.writeUInt32LE(offset, 42);
     central.push(directory, name);
-    offset += local.length + name.length + size;
+    offset += local.length + name.length + data.length;
   }
   const centralSize = central.reduce((size, value) => size + value.length, 0);
   if (offset + centralSize > 0xffffffff) throw new Error("Backup archive is too large for ZIP without ZIP64 support.");
@@ -814,20 +1528,25 @@ const zipArchive = (files) => {
   return Buffer.concat([...locals, ...central, end]);
 };
 
-const collectBackupFiles = async (root, directory = root) => {
+/** Read the files named by the previous manifest; unmanaged neighbors are never archived. */
+const collectBackupFiles = async (root, manifest) => {
+  const targets = [
+    ...managedTargets(root, manifest),
+    safeDestination(root, manifestName),
+    safeDestination(root, textManifestName)
+  ];
   const files = [];
-  const entries = await readdir(directory, { withFileTypes: true });
-  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-    const path = join(directory, entry.name);
-    const stat = await lstat(path);
-    if (stat.isSymbolicLink()) throw new Error("Backup output must not traverse a symbolic link: " + path);
-    if (stat.isDirectory()) files.push(...await collectBackupFiles(root, path));
-    else if (stat.isFile()) files.push({
-      name: relative(root, path).split(sep).join("/"),
-      value: await readFile(path),
-      mtime: stat.mtime
-    });
-    else throw new Error("Backup output must contain only files and directories: " + path);
+  for (const path of [...new Set(targets)].sort()) {
+    await assertNoSymlinks(root, path, "Backup output");
+    let stat;
+    try {
+      stat = await lstat(path);
+    } catch (error) {
+      if (missing(error)) continue;
+      throw error;
+    }
+    if (!stat.isFile()) throw new Error("Backup output must be a file: " + path);
+    files.push({ name: portableRelative(root, path), value: await readFile(path), mtime: stat.mtime });
   }
   return files;
 };
@@ -836,33 +1555,47 @@ const collectBackupFiles = async (root, directory = root) => {
 export const planOutputBackup = async (outputDirectory, {
   outputRootDirectory = outputDirectory,
   backupRootDirectory = outputRootDirectory,
-  backupPath
+  backupPath,
+  timestampName = false
 } = {}) => {
   const output = resolve(outputDirectory);
   const previous = await readManifest(output, outputRootDirectory);
-  if (!previous) throw new Error("Cannot create a backup without an existing Ravel build manifest: " + output);
+  // A first build has nothing to protect, so there is nothing to archive.
+  if (!previous) return { outputDirectory: output, path: null, skipped: "no previous Ravel build" };
   const builtAt = previous.manifest.builtAt;
   const timestamp = Date.parse(builtAt);
   if (!Number.isFinite(timestamp)) throw new Error("Build manifest has no valid build timestamp for backup: " + previous.path);
   const backupRoot = resolve(backupRootDirectory);
   await assertDirectory(backupRoot, "Backup root");
-  const path = backupPath === undefined
-    ? join(backupRoot, "backups", basename(output) + "-" + Math.floor(timestamp / 1000) + ".zip")
-    : await scopedPath(backupRoot, backupPath, "Backup path");
-  if (extname(path).toLowerCase() !== ".zip") throw new Error("Backup file must have a .zip extension: " + path);
-  if (!containedIn(backupRoot, path)) throw new Error("Backup path escapes the Ravel root: " + path);
-  await assertNoSymlinks(backupRoot, path, "Backup path");
-  if (await existingFile(path, "Backup file")) throw new Error("Backup file already exists: " + path);
+  const seconds = Math.floor(timestamp / 1000);
+  const named = backupPath === undefined ? null : await scopedPath(backupRoot, backupPath, "Backup path");
+  if (named && extname(named).toLowerCase() !== ".zip") throw new Error("Backup file must have a .zip extension: " + named);
+  // A derived name is reused by every build, so it never blocks one: when the
+  // name is taken (two builds in one second, or a retry after a failed write),
+  // a numeric suffix keeps every archive. An explicit name must be new.
+  const derived = named === null || timestampName;
+  const base = named === null
+    ? join(backupRoot, "backups", basename(output) + "-" + seconds)
+    : timestampName ? named.slice(0, -extname(named).length) + "-" + seconds : named.slice(0, -extname(named).length);
+  let path = base + ".zip";
+  for (let attempt = 2; ; attempt += 1) {
+    if (!containedIn(backupRoot, path)) throw new Error("Backup path escapes the Ravel root: " + path);
+    await assertNoSymlinks(backupRoot, path, "Backup path");
+    if (!await existingFile(path, "Backup file")) break;
+    if (!derived) throw new Error("Backup file already exists: " + path);
+    path = base + "-" + attempt + ".zip";
+  }
   return { outputDirectory: output, path, manifest: previous, builtAt };
 };
 
 /** Archive the complete current output tree before it is cleaned or replaced. */
 export const createOutputBackup = async (outputDirectory, options = {}) => {
   const plan = await planOutputBackup(outputDirectory, options);
+  if (!plan.path) return { path: null, files: [], skipped: plan.skipped };
   const backupRoot = resolve(options.backupRootDirectory ?? options.outputRootDirectory ?? outputDirectory);
   await ensureDirectoryTree(backupRoot, dirname(plan.path), "Backup path");
   if (await existingFile(plan.path, "Backup file")) throw new Error("Backup file already exists: " + plan.path);
-  const files = await collectBackupFiles(plan.outputDirectory);
+  const files = await collectBackupFiles(plan.outputDirectory, plan.manifest.manifest);
   const temporary = join(dirname(plan.path), "." + basename(plan.path) + ".ravel-stage-" + randomUUID());
   try {
     await writeFile(temporary, zipArchive(files));