@cudoment/cudoc 0.5.0 → 0.7.0

package/dist/node/resolve-embed.js

@@ -1,12 +1,28 @@
 import path from "node:path";
 import { fromHtml } from "hast-util-from-html";
 import { parse as parseYaml } from "yaml";
-import { collectSections } from "../sections.js";
-import { nodeText, visibleHeadingText } from "../document.js";
-import { compileDocument } from "../markdown.js";
+import { collectSections, } from "../sections.js";
+import { idToken, nodeText, visibleHeadingText, } from "../document.js";
 import { findHeadingByAnchorId, findParentHeading, getHeadingAnchorId, } from "../internal/core/query/sections.js";
+import { TREE_CLASS, TREE_KIND, TREE_PRINT_ATTRIBUTE } from "../paged.js";
 import { sourceFileOf } from "./roots.js";
+import { compareCodePoints, compareNames, documentName, hierarchyOf, nfc, } from "./tree.js";
+import { parseSrcSet } from "./local-target.js";
+import { transformedSection } from "./replace.js";
+import { EXTERNAL_URL, decodeComponent, declaredIds, documentIndex, idsInNode, } from "./references.js";
 const SPEC_KEYS = ["sources", "select", "render", "replace"];
+const TABLE_KEYS = ["type", "columns"];
+const TREE_KEYS = [
+    "type",
+    "open",
+    "print",
+    "depth",
+    "headings",
+    "order",
+    "columns",
+];
+/** The `order` entry that stands for every name the list does not give. */
+const REST = "...";
 const SELECTION_KEYS = ["anchors", "titles", "depth", "includeChildren"];
 const REPLACEMENT_KEYS = ["find", "replace", "regex", "flags"];
 const COLUMN_KEYS = ["header", "value", "link", "minWidth"];
@@ -62,6 +78,38 @@ const validateColumn = (column, at) => {
             cell.skipTablesWithHeaders.some((h) => typeof h !== "string")))
         throw new Error(`cudoc: ${at}.value.skipTablesWithHeaders must be strings`);
 };
+const validateTree = (render) => {
+    const count = (key, least, most) => {
+        const value = render[key];
+        if (value === undefined)
+            return;
+        if (!Number.isInteger(value) ||
+            value < least ||
+            (most !== undefined && value > most))
+            throw new Error(`cudoc: render.${key} must be ${most === undefined
+                ? `an integer of at least ${least}`
+                : `an integer from ${least} to ${most}`}`);
+    };
+    count("open", 0);
+    count("print", 1);
+    count("depth", 1);
+    count("headings", 0, 5);
+    const order = render.order;
+    if (order === undefined)
+        return;
+    if (!Array.isArray(order) ||
+        order.some((name) => typeof name !== "string" || !name.trim()))
+        throw new Error("cudoc: render.order must be a list of names");
+    const seen = new Set();
+    for (const name of order) {
+        const key = nfc(name);
+        if (seen.has(key))
+            throw new Error(name === REST
+                ? `cudoc: render.order has ${REST} twice; it stands for every name not listed, once`
+                : `cudoc: render.order names "${name}" twice`);
+        seen.add(key);
+    }
+};
 export function parseEmbedSpec(value) {
     const spec = parseYaml(value, { maxAliasCount: 100 });
     if (!spec || typeof spec !== "object" || Array.isArray(spec))
@@ -77,16 +125,26 @@ export function parseEmbedSpec(value) {
         if (!spec.render ||
             typeof spec.render !== "object" ||
             Array.isArray(spec.render) ||
-            spec.render.type !== "table")
-            throw new Error('cudoc: render must be "section" or a mapping with type: table');
+            !["table", "tree"].includes(spec.render.type))
+            throw new Error('cudoc: render must be "section" or a mapping with type: table or type: tree');
+        const known = spec.render.type === "tree" ? TREE_KEYS : TABLE_KEYS;
         for (const key of Object.keys(spec.render))
-            if (!["type", "columns"].includes(key))
-                throw new Error(`cudoc: render: unknown key "${key}". Known keys: type, columns`);
+            if (!known.includes(key))
+                throw new Error(`cudoc: render: unknown key "${key}". Known keys: ${known.join(", ")}`);
         if (spec.render.columns !== undefined) {
             if (!Array.isArray(spec.render.columns) || !spec.render.columns.length)
                 throw new Error("cudoc: render.columns must be a non-empty array");
             spec.render.columns.forEach((column, index) => validateColumn(column, `render.columns[${index}]`));
         }
+        if (spec.render.type === "tree") {
+            validateTree(spec.render);
+            // A tree copies no section text, so neither would change anything,
+            // and an author who wrote one expects it to.
+            if (spec.select !== undefined)
+                throw new Error("cudoc: select does not apply to a tree; its levels come from folders, and render.headings adds sections");
+            if (spec.replace !== undefined)
+                throw new Error("cudoc: replace does not apply to a tree, which copies no section text");
+        }
     }
     if (spec.select) {
         if (typeof spec.select !== "object" || Array.isArray(spec.select))
@@ -163,77 +221,84 @@ export function parseEmbedBlock(value, documentId, number) {
         throw new Error(`cudoc: ${where}: ${message}`, { cause });
     }
 }
-export function resolveDocumentReference(library, reference, from) {
+/**
+ * What a source names, read without looking anything up: the library path it
+ * spells, relative to `from` or from the top with a leading `/`, and its
+ * anchor, percent-decoded. A URL, a backslash and a climb out of the library
+ * fail here.
+ */
+const sourcePath = (reference, from) => {
     const hash = reference.indexOf("#");
     const pathname = hash < 0 ? reference : reference.slice(0, hash);
-    const anchor = hash < 0 ? undefined : decodeURIComponent(reference.slice(hash + 1));
+    let anchor;
+    try {
+        anchor =
+            hash < 0 ? undefined : decodeURIComponent(reference.slice(hash + 1));
+    }
+    catch {
+        throw new Error(`cudoc: embed source has a malformed percent-escape: ${reference}`);
+    }
     if (/^[a-z][\w+.-]*:/i.test(pathname) || pathname.includes("\\"))
         throw new Error(`cudoc: embed source must be a local document: ${reference}`);
-    const id = (pathname
+    const target = pathname
         ? pathname.startsWith("/")
             ? pathname.slice(1)
             : path.posix.join(path.posix.dirname(from), pathname)
-        : from).replace(/\.mdx?$/i, "");
+        : from;
+    const id = target.replace(/\.mdx?$/i, "");
     if (id === ".." || id.startsWith("../"))
         throw new Error(`cudoc: embed source escapes root: ${reference}`);
-    const document = library.documents.find((d) => d.id === id);
+    return { pathname, target, ...(anchor === undefined ? {} : { anchor }) };
+};
+export function resolveDocumentReference(library, reference, from) {
+    const { target, anchor } = sourcePath(reference, from);
+    const id = target.replace(/\.mdx?$/i, "");
+    const document = documentIndex(library).byId.get(id);
     if (!document)
         throw new Error(`cudoc: missing document ${reference} referenced from ${from}`);
     return { document, anchor };
 }
-function replaceSource(source, rules, documentId) {
-    return rules.reduce((value, rule, index) => {
-        try {
-            return rule.regex
-                ? value.replace(new RegExp(rule.find, rule.flags ?? "g"), rule.replace)
-                : value.split(rule.find).join(rule.replace);
-        }
-        catch (cause) {
-            throw new Error(`cudoc: invalid replacement ${index + 1} in ${documentId}`, { cause });
-        }
-    }, source);
-}
-function transformedSection(document, anchor, tree, rules, library, includeChildren = true) {
-    if (!rules.length)
-        return structuredClone(tree);
-    if (!document.source)
-        throw new Error(`cudoc: rebuild ${document.id} with source snapshots before replacing Markdown`);
-    const range = anchor ? document.source.sections[anchor] : undefined;
-    if (anchor && !range)
-        throw new Error(`cudoc: missing source range for ${document.id}#${anchor}; rebuild documents`);
-    const end = range
-        ? includeChildren
-            ? range.end
-            : (range.ownEnd ?? range.end)
-        : undefined;
-    const original = range
-        ? document.source.text.slice(range.start, end)
-        : document.source.text;
-    const dependencies = range?.dependencies
-        .filter(([start, stop]) => start < range.start || stop > end)
-        .map(([start, end]) => document.source.text.slice(start, end))
-        .join("\n\n");
-    const source = replaceSource(original, rules, document.id) +
-        (dependencies ? `\n\n${dependencies}` : "");
-    const options = { ...library.options, format: document.source.format };
-    if (!library.compiler &&
-        options.host &&
-        !["markdown", "next", "html"].includes(options.host))
-        throw new Error(`cudoc: replacing ${options.host} Markdown requires the original host compiler`);
-    try {
-        return library.compiler
-            ? library.compiler(source, {
-                id: document.id,
-                filePath: (library.roots &&
-                    sourceFileOf(library.roots, document.sourcePath)) ??
-                    document.sourcePath,
-                options,
-            }).tree
-            : compileDocument(source, options).tree;
-    }
-    catch (cause) {
-        throw new Error(`cudoc: replaced Markdown could not compile in ${document.id} at source offset ${range?.start ?? 0}`, { cause });
+/**
+ * Whether a tree on `page` lists private documents: only when the page is
+ * private itself. One that names no collected document counts as public.
+ */
+const listsPrivate = (library, page) => documentIndex(library).byId.get(page)?.private === true;
+/**
+ * Reads one source of a tree. A path ending in `/` names a folder, and the
+ * documents directly below it become the tree's first level; any other path
+ * names a document, or with `#anchor` one of its sections, as for any embed.
+ * Ids are matched in NFC, so a source names a document whose file name is
+ * stored in NFD. A folder holding no document fails, and so does a document
+ * path that is really a folder, with a hint to add the `/`. Given `page`,
+ * the document the tree lands on, a folder whose documents are all private
+ * fails too unless that page is private, since the tree leaves them out.
+ */
+export function resolveTreeSource(library, reference, from, page) {
+    const { pathname, target, anchor } = sourcePath(reference, from);
+    const hierarchy = hierarchyOf(library);
+    if (pathname.endsWith("/")) {
+        if (anchor !== undefined)
+            throw new Error(`cudoc: a folder source takes no anchor: ${reference}`);
+        const normal = path.posix.normalize(target || ".").replace(/\/+$/, "");
+        if (normal === ".." || normal.startsWith("../"))
+            throw new Error(`cudoc: embed source escapes root: ${reference}`);
+        const folder = normal === "." ? "" : normal;
+        const documents = hierarchy.below(folder);
+        if (!documents.length)
+            throw new Error(`cudoc: no documents in folder ${reference} referenced from ${from}`);
+        if (page !== undefined &&
+            !listsPrivate(library, page) &&
+            documents.every((document) => document.private))
+            throw new Error(`cudoc: folder ${reference} referenced from ${from} holds only private documents, which a tree on ${page} leaves out`);
+        return { folder, documents };
     }
+    const id = target.replace(/\.mdx?$/i, "");
+    const document = documentIndex(library).byId.get(id) ?? hierarchy.document(id);
+    if (document)
+        return { document, ...(anchor === undefined ? {} : { anchor }) };
+    throw new Error(`cudoc: missing document ${reference} referenced from ${from}${hierarchy.below(path.posix.normalize(id)).length
+        ? `; a folder source ends with /, as in ${pathname}/`
+        : ""}`);
 }
 const visitNodes = (node, fn) => {
     fn(node);
@@ -248,56 +313,237 @@ const htmlAttribute = (value, quote) => {
         ? String(element.properties.dataValue ?? value)
         : value;
 };
-const idsInNode = (node) => {
-    const ids = [];
-    const id = node.data?.hProperties?.id;
-    if (typeof id === "string")
-        ids.push(id);
-    if (node.type === "html" && node.value) {
-        const tree = fromHtml(node.value, { fragment: true });
-        const walk = (value) => {
-            if (value.type === "element" && typeof value.properties.id === "string")
-                ids.push(value.properties.id);
-            if ("children" in value)
-                value.children.forEach(walk);
-        };
-        walk(tree);
+/**
+ * A relative module an attribute's expression requires first thing, after any
+ * webpack loaders: Docusaurus writes a Markdown image, and a link to a local
+ * file, as `require("<loaders>!./<path from the page's directory>").default`.
+ * Only an expression that starts with the call is read, so text that merely
+ * looks like one inside an authored string is left alone. The string runs to
+ * its own closing quote, so the other quote may be in a name.
+ */
+const REQUIRED_MODULE = /^(\s*require\(\s*(["'])(?:(?:(?!\2)[^\\\n]|\\[\s\S])*!)?)(\.{1,2}\/(?:(?!\2)[^\\\n]|\\[\s\S])*)(\2\s*\))/;
+/**
+ * The directory a document's file sits in, which is what a relative module
+ * path starts from; the library path's own directory when the library was
+ * loaded without its roots, which is the file's only where every root's base
+ * mirrors its directory.
+ */
+const fileDirectory = (library, document) => path.dirname((library.roots?.length
+    ? sourceFileOf(library.roots, document.sourcePath)
+    : undefined) ?? path.join("/", document.sourcePath));
+/**
+ * `to` from `from`, both relative library paths that may climb above the
+ * root, worked out on the paths alone: resolved against the working
+ * directory, a climb above it would be clamped again.
+ */
+const climbingRelative = (from, to) => {
+    const depth = [...from.split("/"), ...to.split("/")].filter((part) => part === "..")
+        .length + 1;
+    const base = `/${Array.from({ length: depth }, (_, i) => `_${i}`).join("/")}`;
+    return path.posix.relative(path.posix.join(base, from), path.posix.join(base, to));
+};
+/** What a JavaScript string literal holds between its quotes, escapes read. */
+const stringValue = (written) => written.replace(/\\(?:u\{([0-9a-fA-F]+)\}|u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2})|(\r\n|[\s\S]))/g, (_match, braced, unicode, hex, other = "") => {
+    const code = braced ?? unicode ?? hex;
+    if (code) {
+        const point = parseInt(code, 16);
+        // Past the last code point the escape is not JavaScript at all.
+        return point > 0x10ffff ? _match : String.fromCodePoint(point);
+    }
+    // A backslash before a line break continues the string on the next line.
+    if (/^(?:\r\n|[\n\r\u2028\u2029])$/.test(other))
+        return "";
+    const named = {
+        n: "\n",
+        r: "\r",
+        t: "\t",
+        b: "\b",
+        f: "\f",
+        v: "\v",
+        "0": "\0",
+    };
+    return named[other] ?? other;
+});
+/** `value` written between `quote`s as a JavaScript string literal. */
+const stringLiteral = (value, quote) => value.replace(/[\\\n\r\u2028\u2029"']/g, (character) => {
+    if (character === "\\")
+        return "\\\\";
+    if (character === "\n")
+        return "\\n";
+    if (character === "\r")
+        return "\\r";
+    if (character === "\u2028")
+        return "\\u2028";
+    if (character === "\u2029")
+        return "\\u2029";
+    return character === quote ? `\\${character}` : character;
+});
+/**
+ * Re-expresses the modules a JSX element's attributes require from the
+ * directory of the document the copy lands in: a page in another directory
+ * would resolve the path from its own. The path is read as the string it is
+ * and written back as one, so a directory named with a quote or a backslash
+ * still gives an expression that parses.
+ */
+const moveRequiredModules = (node, from, to) => {
+    if (!Array.isArray(node.attributes))
+        return;
+    for (const attribute of node.attributes) {
+        const value = attribute.value;
+        if (attribute.type !== "mdxJsxAttribute" ||
+            typeof value !== "object" ||
+            value?.type !== "mdxJsxAttributeValueExpression" ||
+            typeof value.value !== "string")
+            continue;
+        value.value = value.value.replace(REQUIRED_MODULE, (match, head, quote, module, tail) => {
+            // A query the host appended stays as written: it is not part of
+            // the path, and joining it would normalize its slashes too.
+            const [, file = "", query = ""] = /^([^?]*)(.*)$/s.exec(stringValue(module));
+            const relative = path.relative(to, path.join(from, file));
+            // Another drive has no relative path; the copy keeps the original.
+            if (path.isAbsolute(relative))
+                return match;
+            const moved = relative.split(path.sep).join("/");
+            return `${head}${stringLiteral(`./${moved}${query}`, quote)}${tail}`;
+        });
+    }
+};
+/** The raw HTML attributes that name a path: a link and every resource. */
+const REBASED_ATTRIBUTES = new Set([
+    "href",
+    "src",
+    "poster",
+    "data",
+    "xlink:href",
+]);
+/**
+ * One attribute of a tag, read in order after the tag name as HTML reads it:
+ * what separates it from the one before, white space or a stray `/` and
+ * nothing at all after a quoted value, its name, and a value quoted either
+ * way, which may span lines, or bare, which runs to white space or `>`.
+ */
+const ATTRIBUTE = /([\s/]*)([^\s"'>/=]+)(?:(\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/y;
+/**
+ * The tag with the values `rewrite` returns in place of the ones it has, the
+ * attributes it returns nothing for left exactly as written. The attributes
+ * are walked in order, so text inside one value is never read as another.
+ */
+const rewriteAttributes = (tag, rewrite) => {
+    const opening = /^<\/?[^\s/>]+/.exec(tag);
+    if (!opening)
+        return tag;
+    let result = opening[0];
+    let index = opening[0].length;
+    for (;;) {
+        ATTRIBUTE.lastIndex = index;
+        const match = ATTRIBUTE.exec(tag);
+        if (!match)
+            break;
+        index = ATTRIBUTE.lastIndex;
+        const [whole, space, name, equals, double, single, bare] = match;
+        const written = double ?? single ?? bare;
+        const delimiter = single === undefined ? '"' : "'";
+        const replacement = written === undefined
+            ? undefined
+            : rewrite(name.toLowerCase(), htmlAttribute(written, delimiter));
+        result +=
+            replacement === undefined
+                ? whole
+                : `${space}${name}${equals}${delimiter}${replacement
+                    .replace(/&/g, "&amp;")
+                    .replace(new RegExp(delimiter, "g"), delimiter === '"' ? "&quot;" : "&#39;")}${delimiter}`;
     }
-    return ids;
+    return result + tag.slice(index);
 };
-function rebase(tree, document, library, prefix) {
+function rebase(tree, document, library, prefix, destination, placed) {
     const ids = new Set();
     visitNodes(tree, (node) => {
         idsInNode(node).forEach((id) => ids.add(id));
     });
+    // Worked out once, and only when the copy has an element to move.
+    let directories;
     const sourceUrl = (url) => {
-        if (/^(?:[a-z][\w+.-]*:|\/\/)/i.test(url))
+        if (EXTERNAL_URL.test(url))
             return url;
         if (url.startsWith("#")) {
-            let id = url.slice(1);
-            try {
-                id = decodeURIComponent(id);
-            }
-            catch {
-                /* Preserve malformed URL. */
-            }
+            const id = decodeComponent(url.slice(1));
             return ids.has(id) ? `#${prefix}${id}` : `${document.route}${url}`;
         }
         const match = url.match(/^([^?#]*)(.*)$/);
-        const absolute = path.posix.normalize(match[1].startsWith("/")
+        // No path means the page the link sits on, which in a copy is the
+        // document it was copied from, not the directory that document is in.
+        if (!match[1])
+            return `${document.route}${match[2]}`;
+        const joined = match[1].startsWith("/")
             ? match[1]
-            : `/${path.posix.join(path.posix.dirname(document.sourcePath), match[1])}`);
-        const target = library.documents.find((d) => `/${d.sourcePath}` === absolute ||
-            `/${d.id}` === absolute ||
-            `/${d.id}/` === absolute);
+            : path.posix.join(path.posix.dirname(document.sourcePath), match[1]);
+        // A relative path that climbs out of the collection names no library
+        // path, and clamped at the root it would name another file. It is spelled
+        // from the page the copy lands on instead, which reaches the same place:
+        // from the files' own directories when the library has its roots, and
+        // from the library paths otherwise.
+        if (joined === ".." || joined.startsWith("../")) {
+            if (!destination)
+                return url;
+            // A directory keeps its trailing slash, which names its index.
+            const slash = /(?:^|\/)\.{0,2}$/.test(match[1]) ? "/" : "";
+            if (!library.roots?.length)
+                return `${climbingRelative(path.posix.dirname(destination.sourcePath), joined) || "."}${slash}${match[2]}`;
+            directories ??= {
+                from: fileDirectory(library, document),
+                to: fileDirectory(library, destination),
+            };
+            const relative = path.relative(directories.to, path.join(directories.from, decodeComponent(match[1])));
+            // Written back as a URL path: only what would end or change one is
+            // escaped, as the path was decoded to reach the file.
+            return `${relative
+                .split(path.sep)
+                .map((part) => part.replace(/[%\s#?]/g, encodeURIComponent))
+                .join("/") || "."}${slash}${match[2]}`;
+        }
+        let absolute = path.posix.normalize(joined.startsWith("/") ? joined : `/${joined}`);
+        // `.` and `..` name a directory, as a browser reads them.
+        if (/(?:^|\/)\.\.?$/.test(match[1]) && !absolute.endsWith("/"))
+            absolute += "/";
+        const target = documentIndex(library).byPath.get(absolute);
         return `${target?.route ?? absolute}${match[2]}`;
     };
+    // A node an inner copy already placed holds the page's addresses, and read
+    // as source paths again they could name another document, or climb from
+    // the wrong directory. Only a fragment naming an id this copy renames
+    // follows the new name.
+    const pageUrl = (url) => {
+        if (!url.startsWith("#"))
+            return url;
+        const id = decodeComponent(url.slice(1));
+        return ids.has(id) ? `#${prefix}${id}` : url;
+    };
     visitNodes(tree, (node) => {
+        const url = placed.has(node) ? pageUrl : sourceUrl;
+        // Every candidate of a responsive image is a path of its own; the width
+        // or density after it stays as written.
+        const srcSet = (value) => parseSrcSet(value)
+            .map(({ url: candidate, descriptor }) => [url(candidate), descriptor].filter(Boolean).join(" "))
+            .join(", ");
         const id = node.data?.hProperties?.id;
         if (typeof id === "string")
             node.data.hProperties.id = `${prefix}${id}`;
         if (typeof node.url === "string")
-            node.url = sourceUrl(node.url);
+            node.url = url(node.url);
+        // An image a host made a component of is still an image of the source.
+        const image = node.data?.cudocImage;
+        if (image && typeof image.url === "string")
+            node.data.cudocImage = { ...image, url: url(image.url) };
+        // Once per element, however deeply the copy was nested: an inner embed
+        // already moved it from its own source to `destination`.
+        if (destination && Array.isArray(node.attributes) && !placed.has(node)) {
+            directories ??= {
+                from: fileDirectory(library, document),
+                to: fileDirectory(library, destination),
+            };
+            if (directories.from !== directories.to)
+                moveRequiredModules(node, directories.from, directories.to);
+        }
         if ([
             "linkReference",
             "imageReference",
@@ -310,18 +556,21 @@ function rebase(tree, document, library, prefix) {
         if (node.type === "html" && node.value)
             node.value = node.value.replace(/<!--[\s\S]*?-->|<(?:[^"'<>]|"[^"]*"|'[^']*')*>/g, (tag) => tag.startsWith("<!--")
                 ? tag
-                : tag.replace(/(\s(href|src|id)\s*=\s*)(?:(["'])(.*?)\3|([^\s>]+))/gi, (_match, before, attribute, quote, quoted, unquoted) => {
-                    const delimiter = quote ?? '"';
-                    const value = htmlAttribute(quoted ?? unquoted, delimiter);
-                    const replacement = attribute.toLowerCase() === "id"
-                        ? `${prefix}${value}`
-                        : sourceUrl(value);
-                    return `${before}${delimiter}${replacement.replace(/&/g, "&amp;").replace(new RegExp(delimiter, "g"), delimiter === '"' ? "&quot;" : "&#39;")}${delimiter}`;
-                }));
+                : rewriteAttributes(tag, (name, value) => name === "id"
+                    ? `${prefix}${value}`
+                    : name === "srcset"
+                        ? srcSet(value)
+                        : REBASED_ATTRIBUTES.has(name)
+                            ? url(value)
+                            : undefined));
         const attrs = node.data?.hProperties;
-        for (const key of ["href", "src"])
+        for (const key of ["href", "src", "poster", "data", "xLinkHref"])
+            if (typeof attrs?.[key] === "string")
+                attrs[key] = url(attrs[key]);
+        for (const key of ["srcSet", "srcset"])
             if (typeof attrs?.[key] === "string")
-                attrs[key] = sourceUrl(attrs[key]);
+                attrs[key] = srcSet(attrs[key]);
+        placed.add(node);
     });
 }
 /** The default columns of a summary table, as they have always been. */
@@ -386,7 +635,9 @@ const sectionTables = (tree, skipHeaders) => {
  * problem, which is worded as what the column asked for and what the section
  * has, so an author can tell a wrong coordinate from a missing table.
  */
-export function extractCell(library, column, row, context) {
+export function extractCell(library, column, row, context, 
+/** The tree line the cell is for, handed to an extractor. */
+node) {
     const spec = columnSpec(column);
     const where = `${row.document.id}${row.section.anchorId ? `#${row.section.anchorId}` : ""}`;
     const linkTo = () => {
@@ -428,6 +679,7 @@ export function extractCell(library, column, row, context) {
             library,
             documentId: context.documentId,
             column,
+            ...(node ? { node } : {}),
         });
         const text = typeof result === "string" ? result : result?.text;
         if (!text)
@@ -488,21 +740,309 @@ export function buildEmbedTable(library, columns, rows, context) {
         ],
     };
 }
+/** The default line of a tree: the title linked to its node, then the summary. */
+export const DEFAULT_TREE_COLUMNS = ["link", "summary"];
+/** Whether a column is computed by a registered function, which may read anything. */
+const usesExtractor = (columns) => columns.some((column) => typeof column === "object" &&
+    typeof column.value === "object" &&
+    "extractor" in column.value);
+/** Whether an `order` entry names a node: its name, or its title, in NFC. */
+export const namesTreeNode = (entry, node) => {
+    const name = nfc(entry);
+    return node.name === name || nfc(node.title) === name;
+};
+/**
+ * A document's `#` title, from the top-level block at `from` on: a `#`
+ * heading there, or one inside a top-level `header` element, where Docusaurus
+ * puts the heading it reads the page title from.
+ */
+const titleHeading = (tree, from = 0) => {
+    for (let index = from; index < tree.children.length; index++) {
+        const node = tree.children[index];
+        const heading = node.type === "heading"
+            ? node
+            : node.data?.hName === "header"
+                ? node.children?.find((child) => child.type === "heading")
+                : undefined;
+        if (heading?.depth === 1)
+            return {
+                heading: heading,
+                index,
+            };
+    }
+    return undefined;
+};
+/** Heading depths from `from` to the deepest `headings` reaches, `##` being 2. */
+const headingDepths = (from, headings) => {
+    const depths = [];
+    for (let depth = Math.max(from, 2); depth <= headings + 1; depth++)
+        depths.push(depth);
+    return depths;
+};
+/**
+ * The lines of a tree, without cells when `cells` is false, and every
+ * document they were read from.
+ */
+function buildTree(library, sources, render, from, context, cells = true) {
+    const hierarchy = hierarchyOf(library);
+    const depth = render.depth ?? Infinity;
+    const headings = render.headings ?? 0;
+    const columns = render.columns ?? DEFAULT_TREE_COLUMNS;
+    const rows = new Map();
+    const documents = new Set();
+    // A page that is not private lists no private document it was not asked
+    // for by name: a folder or a parent would otherwise put one on it, and the
+    // export, which leaves private documents out, could not link to it.
+    const privateListed = listsPrivate(library, context.documentId);
+    const listed = (document) => !document.private || privateListed;
+    const create = (row, kind, name, level) => {
+        documents.add(row.document.id);
+        const node = {
+            id: `${row.document.id}${row.section.anchorId ? `#${row.section.anchorId}` : ""}`,
+            kind,
+            documentId: row.document.id,
+            ...(row.section.anchorId ? { anchorId: row.section.anchorId } : {}),
+            name,
+            title: row.section.title,
+            url: row.url,
+            sourcePath: row.document.sourcePath,
+            level,
+            cells: [],
+            children: [],
+        };
+        rows.set(node, row);
+        return node;
+    };
+    /** The headings of `sections` nested by depth under a line at `level`. */
+    const nest = (document, sections, level) => {
+        const top = [];
+        // A heading past `depth` is still pushed, without a node, so the ones
+        // under it are left out with it rather than moved up a level.
+        const stack = [];
+        for (const section of sections) {
+            while (stack.length && stack.at(-1).depth >= section.heading.depth)
+                stack.pop();
+            const above = stack.at(-1);
+            const at = (above?.level ?? level) + 1;
+            const node = at <= depth && (!above || above.node)
+                ? headingNode(document, section, at)
+                : undefined;
+            stack.push({ depth: section.heading.depth, level: at, node });
+            if (node)
+                (above ? above.node.children : top).push(node);
+        }
+        return top;
+    };
+    const headingNode = (document, section, level) => {
+        const row = buildEmbedRow(document, section.anchorId, section.tree);
+        return create(row, "heading", nfc(row.section.title), level);
+    };
+    /** A section a source names, with the headings of its own below it. */
+    const sectionNode = (document, section) => {
+        const node = headingNode(document, section, 1);
+        const depths = headingDepths(section.heading.depth + 1, headings);
+        if (1 < depth && depths.length)
+            node.children = nest(document, collectSections(section.tree, { depth: depths }), 1);
+        return node;
+    };
+    const documentNode = (document, level) => {
+        // The `#` title is the line's title, and what follows it, up to the next
+        // `#`, is what the line summarizes; anything above it, such as an
+        // outliner's property lines, is not.
+        const tree = document.tree;
+        const found = titleHeading(tree);
+        const name = documentName(document.id);
+        const named = typeof document.frontmatter.title === "string"
+            ? document.frontmatter.title.trim()
+            : "";
+        const title = (found && visibleHeadingText(found.heading)) ||
+            named ||
+            name;
+        const node = create({
+            document,
+            section: {
+                title,
+                tree: found
+                    ? {
+                        ...tree,
+                        children: tree.children.slice(found.index, titleHeading(tree, found.index + 1)?.index),
+                    }
+                    : tree,
+            },
+            url: document.route,
+        }, "document", name, level);
+        if (level >= depth)
+            return node;
+        const sections = headings
+            ? nest(document, collectSections(tree, { depth: headingDepths(2, headings) }), level)
+            : [];
+        node.children = [
+            ...sections,
+            ...sorted(hierarchy
+                .children(document)
+                .filter(listed)
+                .map((child) => documentNode(child, level + 1))),
+        ];
+        return node;
+    };
+    const first = [];
+    for (const reference of sources) {
+        const source = resolveTreeSource(library, reference, from, context.documentId);
+        if ("folder" in source)
+            first.push(...sorted(source.documents
+                .filter(listed)
+                .map((document) => documentNode(document, 1))));
+        else if (source.anchor === undefined)
+            first.push(documentNode(source.document, 1));
+        else
+            first.push(...collectSections(source.document.tree, {
+                anchors: [source.anchor],
+            }).map((section) => sectionNode(source.document, section)));
+    }
+    let nodes = first;
+    if (render.order?.length) {
+        const order = render.order;
+        const rest = order.indexOf(REST);
+        const rank = (node) => {
+            const at = order.findIndex((entry, index) => index !== rest && namesTreeNode(entry, node));
+            return at >= 0 ? at : rest >= 0 ? rest : order.length;
+        };
+        nodes = first
+            .map((node, index) => ({ node, index, rank: rank(node) }))
+            .sort((a, b) => a.rank - b.rank || a.index - b.index)
+            .map(({ node }) => node);
+    }
+    if (cells) {
+        // Deepest first, so an extractor finds the lines below complete.
+        const fill = (node) => {
+            node.children.forEach(fill);
+            const row = rows.get(node);
+            node.cells = columns.map((column) => extractCell(library, column, row, context, node).cell);
+        };
+        nodes.forEach(fill);
+    }
+    return { nodes, documents };
+}
+/** Documents in the order a tree lists them: by title, then name, then id. */
+const sorted = (nodes) => nodes.sort((a, b) => compareNames(a.title, b.title) ||
+    compareNames(a.name, b.name) ||
+    compareCodePoints(a.id, b.id));
+/**
+ * The lines of a tree embed as data, the same lines the renderer draws, for
+ * a program that writes the tree in a form of its own, such as an outliner's
+ * blocks. `spec` is an embed whose render is a tree; sources resolve from
+ * `context.documentId`, which extractors also receive. Nodes come in the
+ * order the tree shows them, every level down to `depth`, whatever `open`
+ * and `print` say; equal input gives equal output, order and all.
+ */
+export function resolveTree(library, input, context) {
+    const spec = parseEmbedSpec(JSON.stringify(input));
+    if (typeof spec.render !== "object" || spec.render.type !== "tree")
+        throw new Error("cudoc: resolveTree needs an embed whose render is a tree");
+    return buildTree(library, spec.sources, spec.render, context.documentId, context).nodes;
+}
+/**
+ * The mdast a tree renders to: nested lists, an item with children wrapped
+ * in a `details` element whose `summary` is the item's line, open down to
+ * `open` levels. Portable elements only, so it works without a script on
+ * every host. The outer list carries the `cudoc-tree` class, `data.cudoc.kind`
+ * `tree` and, when `print` is set, `data-cudoc-print`, which the print HTML
+ * and Word read.
+ */
+export function buildEmbedTree(nodes, render) {
+    const open = render.open ?? 1;
+    const text = (value) => ({ type: "text", value });
+    const line = (node) => {
+        const shown = node.cells.filter((cell) => cell.text);
+        // A line has to say something: with every column empty, the title.
+        return {
+            type: "paragraph",
+            children: (shown.length ? shown : [{ text: node.title }]).flatMap((cell, index) => [
+                ...(index ? [text(" · ")] : []),
+                cell.url
+                    ? { type: "link", url: cell.url, children: [text(cell.text)] }
+                    : text(cell.text),
+            ]),
+        };
+    };
+    const list = (items, outer) => ({
+        type: "list",
+        ordered: false,
+        spread: false,
+        ...(outer
+            ? {
+                data: {
+                    hProperties: {
+                        className: [TREE_CLASS],
+                        ...(render.print ? { [TREE_PRINT_ATTRIBUTE]: render.print } : {}),
+                    },
+                    cudoc: { kind: TREE_KIND },
+                },
+            }
+            : {}),
+        children: items.map((node) => node.children.length
+            ? {
+                type: "listItem",
+                spread: false,
+                children: [
+                    {
+                        type: "blockquote",
+                        data: {
+                            hName: "details",
+                            ...(node.level <= open
+                                ? { hProperties: { open: true } }
+                                : {}),
+                        },
+                        children: [
+                            { ...line(node), data: { hName: "summary" } },
+                            list(node.children, false),
+                        ],
+                    },
+                ],
+            }
+            : {
+                type: "listItem",
+                spread: false,
+                data: { hProperties: { className: [`${TREE_CLASS}-leaf`] } },
+                children: [line(node)],
+            }),
+    });
+    return { type: "root", children: [list(nodes, true)] };
+}
 /** Resolve a configured embed from immutable persisted documents. */
 export function resolveEmbed(library, input, context) {
     const spec = parseEmbedSpec(JSON.stringify(input));
     let occurrence = 0;
     const reserved = new Set();
-    const destination = library.documents.find((d) => d.id === context.documentId);
-    if (destination)
-        visitNodes(destination.tree, (node) => {
-            idsInNode(node).forEach((id) => reserved.add(id));
+    const destination = documentIndex(library).byId.get(context.documentId);
+    // Nodes already on the page: those a copy rebased, whose paths and
+    // required modules now start from `destination`, and those a table or a
+    // tree wrote there. A copy around them renames their ids, and leaves the
+    // rest as it is.
+    const placed = new WeakSet();
+    const place = (root) => {
+        visitNodes(root, (node) => {
+            placed.add(node);
         });
+        return root;
+    };
+    if (destination)
+        for (const id of declaredIds(destination.tree))
+            reserved.add(id);
     const active = [];
     // Every document a block read, so a later preparation can tell whether the
     // block is still current; `*` when an extractor ran, which may read anything.
     const dependencies = new Set();
     const expand = (spec, from) => {
+        // A tree copies no section, so nothing in it expands or cycles; what it
+        // depends on is every document a line was read from.
+        if (typeof spec.render === "object" && spec.render.type === "tree") {
+            const tree = buildTree(library, spec.sources, spec.render, from, context);
+            tree.documents.forEach((id) => dependencies.add(id));
+            if (usesExtractor(spec.render.columns ?? DEFAULT_TREE_COLUMNS))
+                dependencies.add("*");
+            return place(buildEmbedTree(tree.nodes, spec.render));
+        }
         const children = [];
         const rows = [];
         for (const source of spec.sources) {
@@ -551,7 +1091,7 @@ export function resolveEmbed(library, input, context) {
                     do {
                         prefix = `${context.prefix ?? "embed"}-${++occurrence}-`;
                     } while (sectionIds.some((id) => reserved.has(`${prefix}${id}`)));
-                    rebase(section, document, library, prefix);
+                    rebase(section, document, library, prefix, destination, placed);
                     sectionIds.forEach((id) => reserved.add(`${prefix}${id}`));
                     children.push(...section.children);
                 }
@@ -562,24 +1102,22 @@ export function resolveEmbed(library, input, context) {
         }
         if (spec.render && spec.render !== "section") {
             const columns = spec.render.columns ?? DEFAULT_TABLE_COLUMNS;
-            if (columns.some((column) => typeof column === "object" &&
-                typeof column.value === "object" &&
-                "extractor" in column.value))
+            if (usesExtractor(columns))
                 dependencies.add("*");
-            return buildEmbedTable(library, columns, rows, context);
+            return place(buildEmbedTable(library, columns, rows, context));
         }
         return { type: "root", children };
     };
     const result = expand(spec, context.documentId);
     result.data = {
         ...result.data,
-        cudocEmbedPrefix: `cudoc-${encodeURIComponent(context.documentId)}-${context.prefix ?? "embed"}-`,
+        cudocEmbedPrefix: `cudoc-${idToken(context.documentId)}-${context.prefix ?? "embed"}-`,
         cudocDependencies: [...dependencies].sort(),
     };
     return result;
 }
 export function resolveDocumentEmbeds(library, documentId) {
-    const document = library.documents.find((d) => d.id === documentId);
+    const document = documentIndex(library).byId.get(documentId);
     if (!document)
         throw new Error(`cudoc: missing document ${documentId}`);
     const tree = structuredClone(document.tree);