@pieceful/ravel-host-node 0.1.0 → 0.2.0

package/LICENSE

@@ -2,8 +2,20 @@ MIT License
 
 Copyright (c) 2026 James Taylor
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# @pieceful/ravel-host-node
+
+The Node.js host for [Ravel](https://github.com/jostylr/ravel) projects. It loads Markdown, JSON Ravel Maps, and
+TOML project configuration; confines project filesystem access; and safely
+writes planned deliverables, manifests, provenance maps, cleanups, and backups.
+
+```sh
+npm install @pieceful/ravel-host-node
+```
+
+Use `loadBuildInput` to load a project and `writeBuildArtifacts` to write a
+completed program, or use the higher-level `@pieceful/ravel` CLI. Inputs and
+outputs are contained beneath an explicit project root; path escapes and
+symlink traversal are rejected.
+
+Editor hosts can evaluate unsaved project state by supplying absolute,
+normalized in-memory overlays. Imported inputs and configuration consult the
+overlay before disk:
+
+```js
+const loaded = await loadBuildInput("ravel.toml", {
+  overlays: new Map([
+    [absoluteMarkdownPath, { text: dirtyEditorText, version: 12 }],
+  ]),
+});
+```
+
+Loading overlays never writes source, deliverables, manifests, provenance
+sidecars, backups, or stale-output changes. Artifact writes remain separate,
+explicit host operations.
+
+`loadBuildInput` reports `loadedInputUris` for invalidation and separately
+reports `authoredSourceUris` plus `authoredSourceTexts`. The text record contains
+the exact overlay or disk text consumed for each authored non-JSON input, keyed
+relative to the project root. Editor hosts can use it to prove that a newly
+opened clean navigation destination still matches the evaluated snapshot; it
+does not supply an editor version or write permission. A source path merely
+asserted by JSON Ravel Map data is not added to the authored set, and a load
+containing JSON map provenance reports `sourceEditsAllowed: false` for the
+current conservative automatic-edit policy.
+
+Version-1 TOML projects may declare text `[[live.resources]]` and installed
+package exports in `[[live.modules]]`. The host validates and loads those
+declarations; provider-specific package preparation remains outside this
+general filesystem host.
+
+`.qmd` inputs are parsed through the modern Markdown adapter before any Quarto
+execution stage. Markdown entries in `ravel.toml` may select
+`profile = "modern"` or retain the compatibility profile with
+`profile = "fences"`.
+
+Historical projects select the independent LitPro adapter with
+`adapter = "markdown-litpro"` and may choose `dialect = "litpro-2017"`,
+`"pieceful-2020"`, or `"litpro-plus"`. Legacy `load:` directives retain the
+adapter and dialect while loading their declared input; parsing never performs
+other legacy effects.
+
+Noweb sources use `.nw` or `.noweb`, or may be selected explicitly with
+`adapter = "noweb"`. TOML accepts `dialect = "noweb"` or `"noweb-plus"`,
+`references = "noweb"`, `"underscore-quote"`, or `"both"`, and an optional
+`language`. `run = true` and `provider = "..."` retain live execution intent
+as chunk metadata; loading never executes a noweb chunk or writes tangled
+output.
+
+AsciiDoc sources use `.adoc`, `.asciidoc`, or `adapter = "asciidoc"`.
+Section and block pieces retain exact source bodies, pipelines, native
+cross-reference navigation, and `ravel::` graph directives. Loading does not
+invoke Asciidoctor or expand includes.
+
+HTML sources use `.html`, `.htm`, or `adapter = "html"`. Semantic sections and
+figures retain visible names, decoded code, native navigation, pipelines, and
+directive links. Loading uses authored source with scripting disabled; it
+never constructs a browser DOM or observes runtime mutations.
+
+Org sources use `.org` or `adapter = "org"`. TOML can select
+`references = "org-noweb"`, `"underscore-quote"`, or `"both"`, enable
+Ravel-only use-site pipes with `noweb_pipes = true`, and assign Babel
+authority with `execution_owner = "org"` or `"ravel"`. The host retains
+Babel header arguments, result artifacts, and tangle requests as data; loading
+does not invoke Emacs or Babel.
+
+MyST sources use `.myst.md` or `adapter = "myst"`. Labeled `{ravel:piece}`,
+`{code}`, `{code-block}`, and `{code-cell}` directives retain visible
+captions, anchors, exact bodies, cross-reference navigation, front matter, and
+notebook tags. TOML may assign cell authority with
+`execution_owner = "myst"` or `"ravel"`; loading invokes neither MyST nor
+Jupyter.
+
+Requires Node.js 22 or newer. This package is intentionally Node-specific;
+browser and Bun hosts should supply their own I/O boundary around
+`@pieceful/ravel-core`.
+
+See the [Ravel documentation](https://ravel.jostylr.com/) for TOML configuration,
+filesystem safety, manifests, cleanup, and backup behavior.
+
+MIT © James Taylor

package/package.json

@@ -1,25 +1,50 @@
 {
   "name": "@pieceful/ravel-host-node",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Node host capabilities for Ravel.",
   "license": "MIT",
   "author": "James Taylor",
-  "repository": { "type": "git", "url": "git+https://github.com/jostylr/ravel.git", "directory": "packages/host-node" },
-  "bugs": { "url": "https://github.com/jostylr/ravel/issues" },
-  "homepage": "https://github.com/jostylr/ravel#readme",
-  "engines": { "node": ">=22" },
-  "keywords": ["ravel", "literate-programming", "node", "build"],
-  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jostylr/ravel.git",
+    "directory": "packages/host-node"
+  },
+  "bugs": {
+    "url": "https://github.com/jostylr/ravel/issues"
+  },
+  "homepage": "https://ravel.jostylr.com/",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ravel",
+    "literate-programming",
+    "node",
+    "build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": "./src/index.js"
   },
   "types": "./src/index.d.ts",
-  "files": ["src", "LICENSE"],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
-    "@pieceful/ravel-core": "0.1.0",
-    "@pieceful/ravel-markdown": "0.1.0",
-    "@pieceful/ravel-map": "0.1.0",
+    "@pieceful/ravel-asciidoc": "0.2.0",
+    "@pieceful/ravel-core": "0.2.0",
+    "@pieceful/ravel-html": "0.2.0",
+    "@pieceful/ravel-markdown": "0.2.0",
+    "@pieceful/ravel-markdown-litpro": "0.2.0",
+    "@pieceful/ravel-map": "0.2.0",
+    "@pieceful/ravel-myst": "0.2.0",
+    "@pieceful/ravel-noweb": "0.2.0",
+    "@pieceful/ravel-org": "0.2.0",
     "smol-toml": "^1.7.0"
   }
 }

package/src/index.d.ts

@@ -3,11 +3,45 @@ export interface SourceRange { start: SourcePosition; end: SourcePosition; }
 export interface SourceLocation { uri: string; range: SourceRange; }
 export interface Diagnostic { code: string; severity: "error" | "warning" | "info"; message: string; source: SourceLocation; }
 export interface RavelProgram { version?: number; deliverables: Record<string, { name: string; from: string; value: string; segments?: unknown[] }>; }
-export interface BuildInput { pretransform: unknown; outputDirectory?: string; rootDirectory: string; buildOptions?: { clean: boolean; backup: boolean | string }; }
+export interface LiveModuleDeclaration { specifier: string; from: string; source?: SourceLocation; }
+export interface LiveResourceDeclaration { name: string; path: string; source?: SourceLocation; }
+export interface LiveConfiguration { modules: LiveModuleDeclaration[]; resources: Record<string, string>; resourceDeclarations?: LiveResourceDeclaration[]; }
+export interface BuildInput {
+  pretransform: unknown;
+  outputDirectory?: string;
+  rootDirectory: string;
+  /** Relative source documents actually parsed through a source adapter. */
+  authoredSourceUris: string[];
+  /** Exact authored text consumed by source adapters for this evaluation. */
+  authoredSourceTexts: Record<string, string>;
+  /** Relative JSON/markup/config inputs whose overlays invalidate analysis. */
+  loadedInputUris: string[];
+  /** False when any supplied JSON map makes automatic edit provenance unverified. */
+  sourceEditsAllowed: boolean;
+  buildOptions?: { clean: boolean; backup: boolean | string };
+  live?: LiveConfiguration;
+}
+export interface SourceAdapterOptions {
+  document?: string;
+  mode?: "opt-in" | "primary";
+  profile?: "fences" | "modern" | "litpro";
+  adapter?: "asciidoc" | "html" | "markdown" | "markdown-litpro" | "myst" | "noweb" | "org";
+  dialect?: "litpro-2017" | "pieceful-2020" | "litpro-plus" | "noweb" | "noweb-plus";
+  references?: "noweb" | "org-noweb" | "underscore-quote" | "both";
+  language?: string;
+  nowebPipes?: boolean;
+  executionOwner?: "org" | "myst" | "ravel";
+  run?: boolean;
+  provider?: string;
+  overlays?: Map<string, string | { text: string; version?: number }> | Record<string, string | { text: string; version?: number }>;
+  /** Keep live resource declarations but do not read their contents. Intended for editor analysis. */
+  readLiveResources?: boolean;
+  signal?: AbortSignal;
+}
 export class RavelInputError extends Error { diagnostics: Diagnostic[]; }
-export function loadPretransformGraph(entryPath: string, options?: { document?: string; mode?: "opt-in" | "primary" }): Promise<unknown>;
-export function loadTomlBuild(configPath: string): Promise<BuildInput>;
-export function loadBuildInput(inputPath: string, options?: { document?: string; mode?: "opt-in" | "primary" }): Promise<BuildInput>;
+export function loadPretransformGraph(entryPath: string, options?: SourceAdapterOptions): Promise<unknown>;
+export function loadTomlBuild(configPath: string, options?: SourceAdapterOptions): Promise<BuildInput>;
+export function loadBuildInput(inputPath: string, options?: SourceAdapterOptions): Promise<BuildInput>;
 export function planDeliverables(program: RavelProgram, outputDirectory: string): { version: 1; outputDirectory: string; manifest: string; deliverables: Array<Record<string, unknown>> };
 export function planStaleDeliverables(program: RavelProgram, outputDirectory: string, options?: { rootDirectory?: string; staleSince?: string }): Promise<Array<Record<string, unknown>>>;
 export function writeDeliverables(program: RavelProgram, outputDirectory: string, options?: { rootDirectory?: string }): Promise<string[]>;

package/src/index.js

@@ -8,11 +8,23 @@ import {
   createDeliverableProvenanceMap,
   provenanceMapVersion
 } from "@pieceful/ravel-core";
+import { asciidocToMap } from "@pieceful/ravel-asciidoc";
+import { htmlToMap } from "@pieceful/ravel-html";
 import { markdownToMap } 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";
 
 const missing = (error) => error?.code === "ENOENT";
 
+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>",
   range: {
@@ -37,7 +49,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 +200,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 +211,235 @@ 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 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) => {
+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 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);
   };
 
   await visit(entryPath, entryOptions);
-  return { maps, diagnostics, rootDirectory: activeScope.root };
+  throwIfAborted(signal);
+  return {
+    maps,
+    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,48 +455,213 @@ const reportUnknownKeys = (value, allowed, description, configPath) => {
   }
 };
 
-export const loadTomlBuild = async (configPath) => {
+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", "build", "outputs", "live"]), "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.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 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);
   }));
+  throwIfAborted(options.signal);
   const pretransform = combineMaps(results.flatMap((result) => result.maps));
   pretransform.diagnostics.push(...results.flatMap((result) => result.diagnostics));
   for (const output of config.outputs ?? []) {
@@ -302,35 +676,50 @@ 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))].sort(),
+    authoredSourceTexts: Object.assign({}, ...results.map(authoredSourceTexts)),
+    loadedInputUris: [...new Set([
+      relative(scope.root, absoluteConfig).split(sep).join("/"),
+      ...results.flatMap(loadedInputUris)
+    ])].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
+    },
+    ...(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
     };
   }
-  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) => {