@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.14

package/dist/content-export.js

@@ -22,13 +22,21 @@ import { ExportAssets, exportDigest } from './content-export-assets.js';
 import { portableTree, passiveHtml, portableMarkdown } from './content-export-render.js';
 import { checkOutputDirectory } from './output-location.js';
 import { commitArtifacts } from './output-commit.js';
-import { heading, root } from './content.js';
-import { outputUrl } from './representation-tree.js';
+import { heading, root, parse, transformMdx } from './content.js';
+import { outputUrl, publicTree } from './representation-tree.js';
 import { resolveSubjectDeprecation, subjectDeprecationNotice } from './subject-deprecation.js';
 import { resolveAuthoredChange, authoredChangeNotice } from './authored-change.js';
+import { resolveSnippetValues } from './snippets.js';
+import { isolateExportTree, markExportSource, exportHeadingInventory, preserveExportHeadingIds } from './content-export-anchors.js';
+import { selectSection } from './section-identity.js';
+import { compareContentManifests } from './content-export-comparison.js';
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const keyFor = (doc) => `${doc.frontmatter.id}|${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`;
-const resourceKey = (doc) => `${doc.frontmatter.id.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 60) || 'document'}-${exportDigest(keyFor(doc)).slice(0, 16)}`;
+const resourceIdentity = (item) => JSON.stringify([item.ref.kind, item.ref.kind === 'snippet' ? item.ref.id : item.ref.documentId, item.ref.kind === 'section' ? item.ref.sectionId : null, item.doc.variant.channel, item.doc.variant.version, item.doc.variant.language]);
+// Pages and their sections share a source; named snippet instances do not.
+const sourceKeyFor = (doc, kind = 'document') => JSON.stringify([kind, doc.frontmatter.id, doc.variant.channel, doc.variant.version, doc.variant.language]);
+const selectedSourceKey = (item) => sourceKeyFor(item.doc, item.ref.kind === 'snippet' ? 'snippet' : 'document');
+const resourceKey = (item) => `resource-${exportDigest(resourceIdentity(item)).slice(0, 24)}`;
 const sameVariant = (a, b) => ['channel', 'version', 'language'].every(key => a[key] === b[key]);
 const visitTree = (node, visit) => {
     if (!node || typeof node !== 'object')
@@ -85,7 +93,7 @@ export async function exportContent(configFile, destination, options = {}) {
     const metadataDependencies = new Set();
     const workspace = await prepareContentWorkspace({ base, basePath, config, loaded, variants: [publication], language, readerFilters, metadataProvider, metadataDependencies, allowRouteCollisions: true });
     const { docs: eligible, apiPlan, snippets, sourceForOperation } = workspace;
-    const ids = new Set(target.documents);
+    const ids = new Set(target.resources ? target.resources.filter(item => item.kind !== 'snippet').map(item => item.documentId) : target.documents);
     for (const id of ids) {
         const doc = [...eligible.values()].find(doc => doc.frontmatter.id === id);
         if (!doc)
@@ -93,8 +101,8 @@ export async function exportContent(configFile, destination, options = {}) {
         if (!matchesContentFilter(doc.readerFilters, target.contentFilter))
             throw new Error(`Requested export document ${id} is excluded by the export contentFilter`);
     }
-    const docs = new Map([...eligible].filter(([, doc]) => (!target.documents || ids.has(doc.frontmatter.id)) && matchesContentFilter(doc.readerFilters, target.contentFilter)).sort(([, a], [, b]) => compare(keyFor(a), keyFor(b))));
-    if (!docs.size)
+    const docs = new Map([...eligible].filter(([, doc]) => (!(target.documents || target.resources) || ids.has(doc.frontmatter.id)) && matchesContentFilter(doc.readerFilters, target.contentFilter)).sort(([, a], [, b]) => compare(keyFor(a), keyFor(b))));
+    if (!docs.size && !target.resources?.some(item => item.kind === 'snippet'))
         throw new Error('Export selection matched no eligible pages');
     const plugins = await loadComponentPlugins(loaded, { browser: false });
     const materialized = await materializePages({ variables: isConfigMapping(config.variables) ? config.variables : {}, frontmatterConfig: config.frontmatter, publications, docs, linkDocuments: eligible, apiPlan, sourceForOperation,
@@ -106,6 +114,7 @@ export async function exportContent(configFile, destination, options = {}) {
     const cookbooks = validateCookbooks(config.cookbooks, configFile);
     const local = new Map([...eligible.values()].map(doc => [doc.frontmatter.id, doc]));
     const diagnostics = [];
+    const requiredNotices = new Map();
     for (const page of materialized.rendered) {
         const use = { targets: [], queries: [] };
         page.doc.tree = resolveCardTree(page.doc.tree, page.doc, eligible, publicationRelationships(edges, local), new Set(apiPlan.knownOperations.keys()), use, config);
@@ -114,18 +123,78 @@ export async function exportContent(configFile, destination, options = {}) {
         const change = resolveAuthoredChange(page.doc, eligible);
         const existing = page.doc.tree;
         // Preserve authored notices in both output representations.
-        page.doc.tree = root([
+        const notices = [
             { type: 'docRepresentation', representation: 'html', children: [...subjectDeprecationNotice(deprecation, 'html').children, ...authoredChangeNotice(change, 'html').children] },
-            { type: 'docRepresentation', representation: 'markdown', children: [...subjectDeprecationNotice(deprecation, 'markdown').children, ...authoredChangeNotice(change, 'markdown').children] },
-            ...existing.children
-        ]);
+            { type: 'docRepresentation', representation: 'markdown', children: [...subjectDeprecationNotice(deprecation, 'markdown').children, ...authoredChangeNotice(change, 'markdown').children] }
+        ];
+        requiredNotices.set(keyFor(page.doc), notices);
+        page.doc.tree = root([...notices, ...existing.children]);
         const found = new Set();
         visitTree(page.doc.tree, node => { if (['docTabs', 'docWalkthrough', 'docReaderSection', 'docCollapsible', 'docTooltip', 'docInfoHint', 'docCookbookChooser'].includes(node.type))
             found.add(node.type); });
         if (found.size)
             diagnostics.push({ code: 'static-content', documentId: page.doc.frontmatter.id, message: 'Interactions and reader sections are exported as complete labeled content.' });
     }
-    const diagrams = await resolveDiagramTrees(materialized.rendered.map(page => page.doc.tree));
+    // Materialized snippets can share nodes with their registry definition.
+    // Isolate each document before assigning source provenance.
+    for (const doc of docs.values()) {
+        doc.tree = isolateExportTree(doc.tree);
+        markExportSource(doc.tree);
+    }
+    const selected = [];
+    const selections = target.resources ?? [...docs.values()].map(doc => ({ kind: 'page', documentId: doc.frontmatter.id }));
+    for (const selection of selections) {
+        if (selection.kind === 'snippet') {
+            const definition = snippets.get(selection.snippetId);
+            if (!definition)
+                throw new Error(`Unknown export snippet ${selection.snippetId}`);
+            // This is an explicit isolated context. It has no containing page, operations,
+            // relationships, page variables, or inherited publication/access metadata.
+            const snippetDocument = { file: definition.file, body: '', tree: root([]), variant: publication,
+                route: `/__content_snippets/${encodeURIComponent(selection.id)}`, markdownRoute: '',
+                frontmatter: { id: selection.id, title: selection.title, summary: selection.summary, type: 'snippet', slug: '/', access: { policy: 'public' } } };
+            const checkSnippet = (id, seen = new Set()) => {
+                if (seen.has(id))
+                    return;
+                seen.add(id);
+                const source = snippets.get(id);
+                if (!source)
+                    throw new Error(`Unknown snippet ${id}`);
+                visitTree(source.tree, node => {
+                    if (['RelatedReading', 'DocCard', 'DocCards', 'DocCollection', 'CookbookChooser', 'ApiExample', 'ApiSchema', 'FrontmatterReference', 'Anchor'].includes(node.name))
+                        throw new Error(`Snippet instance ${selection.id}: <${node.name}> needs page context`);
+                    if (node.name === 'Snippet') {
+                        const child = node.attributes?.find((a) => a.name === 'id')?.value;
+                        if (typeof child === 'string')
+                            checkSnippet(child, seen);
+                    }
+                });
+            };
+            checkSnippet(selection.snippetId);
+            const invocation = parse.parse(`<Snippet id=${JSON.stringify(selection.snippetId)} values={${JSON.stringify(selection.values ?? {})}} />`);
+            snippetDocument.tree = transformMdx(invocation, snippetDocument, new Map([...eligible.values()].map(doc => [doc.frontmatter.id, doc])), snippets, isConfigMapping(config.variables) ? config.variables : {}, [], resolveCalloutTypes(config.callouts, configFile), base, readerFilters, {}, publications, resolveBadgeVariants(config.badges, configFile), plugins.registry);
+            visitTree(snippetDocument.tree, node => { if (/^doc(?:Card|Collection|Related|Cookbook|Api)/.test(node.type))
+                throw new Error(`Snippet instance ${selection.id} needs page context`); });
+            snippetDocument.tree = isolateExportTree(snippetDocument.tree);
+            markExportSource(snippetDocument.tree);
+            selected.push({ ref: { kind: 'snippet', id: selection.id }, doc: snippetDocument, tree: snippetDocument.tree,
+                title: selection.title, summary: selection.summary, type: 'snippet', source: { snippetId: selection.snippetId, valuesDigest: exportDigest(JSON.stringify(resolveSnippetValues(selection.snippetId, definition, config.variables, undefined, selection.values ?? {}))) } });
+        }
+        else {
+            const doc = [...docs.values()].find(doc => doc.frontmatter.id === selection.documentId);
+            if (selection.kind === 'page')
+                selected.push({ ref: { kind: 'page', documentId: doc.frontmatter.id }, doc,
+                    tree: root([heading(1, doc.frontmatter.title), ...doc.tree.children]), title: doc.frontmatter.title, summary: doc.frontmatter.summary, type: doc.frontmatter.type });
+            else {
+                const slice = selectSection(doc.tree, selection.sectionId, doc.frontmatter.standaloneSections ?? [], doc.frontmatter.id);
+                selected.push({ ref: { kind: 'section', documentId: doc.frontmatter.id, sectionId: selection.sectionId }, doc,
+                    tree: root([...(requiredNotices.get(keyFor(doc)) ?? []), ...slice.tree.children]), meaningTree: slice.tree, title: slice.section.title,
+                    summary: doc.frontmatter.summary, type: 'section', source: { documentId: doc.frontmatter.id } });
+            }
+        }
+    }
+    selected.sort((a, b) => compare(resourceIdentity(a), resourceIdentity(b)));
+    const diagrams = await resolveDiagramTrees(selected.map(item => item.tree));
     const assets = new ExportAssets(target.publicBase);
     const assetRootsOrigin = options.target && target.assetRoots.length ? explainSegments(loaded, ['exports', options.target, 'assetRoots']).source.file : configFile;
     const roots = [workspace.contentDir, ...target.assetRoots.map(root => path.resolve(path.dirname(assetRootsOrigin), root))];
@@ -134,13 +203,15 @@ export async function exportContent(configFile, destination, options = {}) {
         assets.register(asset.route, { content: asset.svg });
     for (const [url, contract] of materialized.focusedContracts)
         assets.register(url, { content: contract.content });
-    for (const doc of docs.values())
-        visitTree(doc.tree, node => {
+    for (const item of selected) {
+        const doc = item.doc;
+        visitTree(item.tree, node => {
             if (typeof node.file === 'string' && typeof node.url === 'string' && ['docImage', 'image', 'definition'].includes(node.type))
-                assets.register(node.url, { file: node.file }, keyFor(doc));
+                assets.register(node.url, { file: node.file }, selectedSourceKey(item));
             if (node.type === 'docHero' && node.image?.file)
-                assets.register(node.image.url, { file: node.image.file }, keyFor(doc));
+                assets.register(node.image.url, { file: node.image.file }, selectedSourceKey(item));
         });
+    }
     const reviews = await reviewApiPublication(configFile, apiPlan, materialized.rendered, materialized.apiEmbedUses, materialized.focusedContracts, [...materialized.apiPublications.values()].map(source => ({ apiId: source.apiId, sourceUrl: source.sourceUrl })), sourceForOperation, 'report');
     const unreviewed = reviews.filter(review => (target.apiReview[review.apiId] ?? configField(apiPlan.apiDefinitions[review.apiId].publicReview, 'digest')) !== review.digest);
     if (unreviewed.length && !options.review)
@@ -158,24 +229,62 @@ export async function exportContent(configFile, destination, options = {}) {
     const trees = new Map();
     const anchors = new Map();
     const routes = new Set([...eligible.values()].map(doc => doc.route));
-    for (const doc of docs.values())
+    const sourceInventories = new Map();
+    const sourceAliases = new Map();
+    for (const item of selected)
         for (const format of target.formats) {
-            const tree = portableTree(root([heading(1, doc.frontmatter.title), ...doc.tree.children]), format, routes, basePath);
-            trees.set(`${keyFor(doc)}:${format}`, tree);
-            // Markdown anchors are renderer-dependent. HTML is generated and scoped here.
-            if (format === 'html')
-                anchors.set(keyFor(doc), passiveHtml(tree, `sr-${resourceKey(doc)}`, false).anchors);
+            const sourceKey = `${selectedSourceKey(item)}:${format}`;
+            if (!sourceInventories.has(sourceKey))
+                sourceInventories.set(sourceKey, exportHeadingInventory(portableTree(structuredClone(item.doc.tree), format, routes, basePath)));
+            const tree = portableTree(structuredClone(item.tree), format, routes, basePath);
+            if (item.ref.kind !== 'page') {
+                const meaning = item.meaningTree ? portableTree(structuredClone(item.meaningTree), format, routes, basePath) : tree;
+                const body = (meaning.children ?? []).filter((node) => node.type !== 'heading' && node.type !== 'definition' && node.type !== 'footnoteDefinition');
+                if (!portableMarkdown(root(body)).trim())
+                    throw new Error(`Resource ${resourceIdentity(item)} has no content in ${format}`);
+            }
+            const aliases = preserveExportHeadingIds(tree, sourceInventories.get(sourceKey), format);
+            sourceAliases.set(`${resourceIdentity(item)}:${format}`, aliases);
+            trees.set(`${resourceIdentity(item)}:${format}`, tree);
+            // Resolve anchors independently in each representation, before URL rewriting.
+            anchors.set(`${resourceIdentity(item)}:${format}`, passiveHtml(tree, `sr-${resourceKey(item)}`, false).anchors);
         }
+    const canonicalAnchors = new Map();
+    const verifiedCanonicalAnchors = (destination, format) => {
+        const key = `${sourceKeyFor(destination)}:${format}`;
+        if (canonicalAnchors.has(key))
+            return canonicalAnchors.get(key);
+        const source = sourceInventories.get(key);
+        if (!source || destination.endpoint)
+            throw new Error(`Cannot validate canonical fragments in ${destination.frontmatter.id}; select the target resource explicitly`);
+        const reserved = ['main', 'docs-navigation', 'docs-sections', 'documentation-menu', 'page-outline', 'nav-filter', 'examples-title', 'api-view-select'];
+        const explicit = new Set();
+        visitTree(destination.tree, node => {
+            if (node.type === 'docSection' && node.sectionId)
+                reserved.push(node.sectionId);
+            const alias = node.data?.hProperties?.['data-shoalrun-section-id'];
+            if (typeof alias === 'string')
+                explicit.add(alias);
+        });
+        const native = exportHeadingInventory(publicTree(structuredClone(destination.tree), 'html', routes, 'light', basePath), reserved);
+        const verified = new Set([...explicit].filter(id => native.ids.has(id)));
+        for (const [headingKey, id] of source.headings)
+            if (native.headings.get(headingKey) === id)
+                verified.add(id);
+        canonicalAnchors.set(key, verified);
+        return verified;
+    };
     const records = [];
     const artifacts = new Map();
-    for (const doc of docs.values()) {
+    for (const item of selected) {
+        const doc = item.doc;
         const externalDependencies = new Map();
         const usedAssets = new Set();
         const representations = {};
-        const canonicalUrl = origin && canonicalDestination(doc) ? `${origin}${doc.route}` : undefined;
+        const canonicalUrl = item.ref.kind !== 'snippet' && origin && canonicalDestination(doc) ? `${origin}${doc.route}` : undefined;
         for (const format of target.formats) {
             const links = [];
-            const tree = trees.get(`${keyFor(doc)}:${format}`);
+            const tree = trees.get(`${resourceIdentity(item)}:${format}`);
             const resolve = async (node) => {
                 // Native adapters can express ordinary links/images as semantic elements.
                 const properties = node.data?.hProperties;
@@ -207,24 +316,56 @@ export async function exportContent(configFile, destination, options = {}) {
                     if (destination) {
                         let href;
                         let kind;
-                        if (docs.has(keyFor(destination))) {
-                            const fragment = decodeURIComponent(parsed.hash.slice(1));
-                            const targetAnchors = anchors.get(keyFor(destination));
-                            const anchor = fragment && format === 'html' ? targetAnchors?.find(item => item.id === fragment || item.exportedId === fragment) : undefined;
-                            if (fragment && format === 'html' && !anchor)
-                                throw new Error(`Missing export anchor ${fragment} in ${destination.frontmatter.id}`);
-                            const suffix = parsed.search + (fragment ? `#${format === 'html' ? anchor.exportedId : parsed.hash.slice(1)}` : '');
-                            href = destination === doc && !parsed.search && fragment ? suffix : `${target.publicBase}content/${resourceKey(destination)}.${format === 'html' ? 'html' : 'md'}${suffix}`;
-                            kind = 'document';
+                        const fragment = decodeURIComponent(parsed.hash.slice(1));
+                        const candidates = selected.filter(candidate => candidate.ref.kind !== 'snippet' && keyFor(candidate.doc) === keyFor(destination));
+                        const hasAnchor = (candidate) => sourceAliases.get(`${resourceIdentity(candidate)}:${format}`)?.has(fragment);
+                        let chosen = destination === doc && fragment && hasAnchor(item) ? item : undefined;
+                        if (!chosen && fragment) {
+                            const matching = candidates.filter(candidate => candidate.ref.kind === 'section' && hasAnchor(candidate));
+                            if (matching.length > 1)
+                                throw new Error(`Ambiguous fragment ${fragment} in ${destination.frontmatter.id}`);
+                            chosen = matching[0];
+                        }
+                        chosen ??= candidates.find(candidate => candidate.ref.kind === 'page');
+                        // Clean Markdown has no explicit alias anchors. Prefer an actual
+                        // section resource for those references, otherwise the canonical HTML.
+                        if (chosen && format === 'markdown' && fragment && chosen.ref.kind === 'page') {
+                            const targetId = sourceAliases.get(`${resourceIdentity(chosen)}:${format}`)?.get(fragment);
+                            const target = anchors.get(`${resourceIdentity(chosen)}:${format}`)?.find(entry => entry.id === targetId);
+                            if (target && !target.title)
+                                chosen = candidates.find(candidate => candidate.ref.kind === 'section' && candidate.ref.sectionId === fragment);
+                        }
+                        if (chosen) {
+                            const targetAnchors = anchors.get(`${resourceIdentity(chosen)}:${format}`);
+                            const targetId = sourceAliases.get(`${resourceIdentity(chosen)}:${format}`)?.get(fragment);
+                            const anchor = fragment ? targetAnchors.find(entry => entry.id === targetId) : undefined;
+                            if (fragment && !anchor)
+                                throw new Error(`Missing export anchor ${fragment} in ${destination.frontmatter.id} (${format})`);
+                            // A section-resource URL is sufficient when addressing its leading
+                            // section; clean Markdown does not publish explicit HTML anchors.
+                            const leadingSection = chosen.ref.kind === 'section' && chosen.ref.sectionId === fragment;
+                            const markdownAnchor = anchor?.id ?? fragment;
+                            const suffix = parsed.search + (fragment && !(format === 'markdown' && leadingSection) ? `#${format === 'html' ? anchor.exportedId : markdownAnchor}` : '');
+                            href = chosen === item && !parsed.search && fragment && format === 'html' ? suffix : `${target.publicBase}content/${resourceKey(chosen)}.${format === 'html' ? 'html' : 'md'}${suffix}`;
+                            kind = 'resource';
                         }
                         else {
                             if (!origin || !canonicalDestination(destination))
                                 throw new Error(`Document ${destination.frontmatter.id} is outside the export and has no eligible canonical website fallback`);
+                            if (fragment) {
+                                const inventory = sourceInventories.get(`${sourceKeyFor(destination)}:${format}`);
+                                if (!inventory)
+                                    throw new Error(`Cannot validate canonical anchor ${fragment} in unselected document ${destination.frontmatter.id}; select that page or section explicitly`);
+                                if (!inventory.ids.has(fragment))
+                                    throw new Error(`Missing source anchor ${fragment} in ${destination.frontmatter.id} (${format})`);
+                                if (!verifiedCanonicalAnchors(destination, format).has(fragment))
+                                    throw new Error(`Cannot verify canonical anchor ${fragment} in ${destination.frontmatter.id}; select its target resource explicitly`);
+                            }
                             href = `${origin}${destination.route}${parsed.search}${parsed.hash}`;
                             kind = 'canonical';
                         }
                         const key = `link-${links.length + 1}`;
-                        links.push({ key, kind, href, documentId: destination.frontmatter.id, ...(parsed.hash ? { fragment: decodeURIComponent(parsed.hash.slice(1)) } : {}), ...(parsed.search ? { query: parsed.search.slice(1) } : {}) });
+                        links.push({ key, kind, href, ...(chosen ? { ref: chosen.ref } : {}), ...(fragment ? { fragment } : {}), ...(parsed.search ? { query: parsed.search.slice(1) } : {}) });
                         node.url = href;
                         if (format === 'html' && node.type === 'link')
                             node.data = { ...node.data, hProperties: { ...node.data?.hProperties, 'data-export-link': key } };
@@ -237,7 +378,7 @@ export async function exportContent(configFile, destination, options = {}) {
                             links.push({ key: `link-${links.length + 1}`, kind: 'external', href: node.url });
                     }
                     else {
-                        const asset = await assets.resolve(value, doc.file, keyFor(doc));
+                        const asset = await assets.resolve(value, doc.file, selectedSourceKey(item));
                         if (!asset)
                             throw new Error(`Unresolved local export ${node.type === 'image' ? 'image' : 'link'} ${value} in ${doc.frontmatter.id}`);
                         usedAssets.add(asset.path);
@@ -250,15 +391,15 @@ export async function exportContent(configFile, destination, options = {}) {
                     await resolve(child);
             };
             await resolve(tree);
-            const filename = `content/${resourceKey(doc)}.${format === 'html' ? 'html' : 'md'}`;
-            const rendered = format === 'html' ? passiveHtml(tree, `sr-${resourceKey(doc)}`) : undefined;
+            const filename = `content/${resourceKey(item)}.${format === 'html' ? 'html' : 'md'}`;
+            const rendered = format === 'html' ? passiveHtml(tree, `sr-${resourceKey(item)}`) : undefined;
             const content = rendered?.html ?? portableMarkdown(tree);
             artifacts.set(filename, content);
             representations[format] = { path: filename, mediaType: format === 'html' ? 'text/html' : 'text/markdown', bytes: Buffer.byteLength(content), digest: exportDigest(content), anchors: rendered?.anchors ?? [], links };
         }
         if (externalDependencies.size)
             diagnostics.push({ code: 'external-render-dependencies', documentId: doc.frontmatter.id, message: `${externalDependencies.size} remote image(s) remain external; this document is not offline-complete.` });
-        records.push({ id: doc.frontmatter.id, publication, title: doc.frontmatter.title, summary: doc.frontmatter.summary, type: doc.frontmatter.type, ...(canonicalUrl ? { canonicalUrl } : {}), representations, assets: [...usedAssets].sort(), externalDependencies: [...externalDependencies.values()].sort((a, b) => compare(a.url, b.url)) });
+        records.push({ ref: item.ref, publication, title: item.title, summary: item.summary, type: item.type, ...(item.source ? { source: item.source } : {}), ...(canonicalUrl ? { canonicalUrl } : {}), representations, assets: [...usedAssets].sort(), externalDependencies: [...externalDependencies.values()].sort((a, b) => compare(a.url, b.url)) });
     }
     for (const [filename, bytes] of assets.artifacts)
         artifacts.set(filename, bytes);
@@ -291,8 +432,15 @@ export async function exportContent(configFile, destination, options = {}) {
     artifacts.set('NOTICES.txt', notices);
     const manifest = { schemaVersion: 1, kind: 'shoalrun-content-export', publicBase: target.publicBase, publication,
         review: { status: unreviewed.length ? 'required' : 'ok', apis: reviews.map(row => ({ apiId: row.apiId, digest: row.digest })) },
-        documents: records, assets: [...assets.records.values()].sort((a, b) => compare(a.path, b.path)),
+        resources: records, assets: [...assets.records.values()].sort((a, b) => compare(a.path, b.path)),
         files: [...artifacts].map(([filename, content]) => ({ path: filename, bytes: Buffer.byteLength(content), digest: exportDigest(content) })).sort((a, b) => compare(a.path, b.path)), diagnostics };
+    const previous = options.previousManifest ? JSON.parse(await readFile(options.previousManifest, 'utf8')) : undefined;
+    const comparison = compareContentManifests(previous, manifest);
+    if (options.failOnRemoved && !options.previousManifest)
+        throw new Error('failOnRemoved requires previousManifest');
+    if (options.failOnRemoved && comparison.removed.length)
+        throw new Error(`Export removes ${comparison.removed.length} previously exported resource(s)`);
+    diagnostics.push(...comparison.diagnostics);
     const bundleDigest = exportDigest(JSON.stringify(manifest));
     artifacts.set('manifest.json', JSON.stringify({ ...manifest, digest: bundleDigest }, null, 2) + '\n');
     const inputs = [...noticeFiles, ...loaded.dependencies, ...metadataDependencies, ...plugins.dependencies, ...apiPlan.api.dependencies, ...[...eligible.values()].map(doc => doc.file), ...[...snippets.values()].map(snippet => snippet.file)];
@@ -300,8 +448,13 @@ export async function exportContent(configFile, destination, options = {}) {
     // No export can replace a directory containing an allowed asset root.
     for (const directory of roots)
         checkOutputDirectory(destination, base, directory, inputs);
+    if (unreviewed.length) {
+        const prior = await readFile(path.join(destination, 'manifest.json'), 'utf8').then(JSON.parse).catch(() => undefined);
+        if (prior?.review?.status === 'ok')
+            throw new Error('Review candidate cannot overwrite an approved export; choose a separate review destination');
+    }
     await commitArtifacts(path.resolve(destination), artifacts, undefined, 'export');
     return { status: unreviewed.length ? 'needs-review' : 'ok', output: path.resolve(destination), publication, formats: target.formats,
-        documents: records.length, documentIds: records.map(doc => doc.id), assets: assets.records.size, digest: bundleDigest,
+        resources: records.length, documents: records.filter(item => item.ref.kind === 'page').length, documentIds: records.flatMap(item => item.ref.kind === 'page' ? [item.ref.documentId] : []), comparison, assets: assets.records.size, digest: bundleDigest,
         apiReview: reviews.map(row => ({ apiId: row.apiId, digest: row.digest })), diagnostics };
 }

package/dist/content-mount.d.ts

@@ -0,0 +1,11 @@
+import type { ContentAnchor, ContentLink, ContentResult } from './content-delivery-contract.js';
+export type ContentMount = {
+    anchors: readonly ContentAnchor[];
+    links: readonly ContentLink[];
+    unmount(): void;
+};
+/** Mount trusted compiler output, not arbitrary HTML. This is not a sanitizer. */
+export declare function mountContent(container: Element, result: ContentResult, options?: {
+    instanceId?: string;
+    signal?: AbortSignal;
+}): ContentMount;

package/dist/content-mount.js

@@ -0,0 +1,73 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+/** Mount trusted compiler output, not arbitrary HTML. This is not a sanitizer. */
+export function mountContent(container, result, options = {}) {
+    options.signal?.throwIfAborted();
+    if (result.format !== 'html')
+        throw new ContentDeliveryError('unsupported_format', 'Mounting requires HTML content.');
+    const instance = options.instanceId ?? `content-${globalThis.crypto.randomUUID()}`;
+    if (!/^[A-Za-z][A-Za-z0-9_-]{0,127}$/.test(instance))
+        throw new ContentDeliveryError('invalid_content', 'Invalid mount instance ID.');
+    const document = container.ownerDocument;
+    const template = document.createElement('template');
+    template.innerHTML = result.content;
+    const ids = new Map();
+    for (const element of template.content.querySelectorAll('[id]')) {
+        const old = element.id;
+        const next = `${instance}-${old}`;
+        if (!old || ids.has(old))
+            throw new ContentDeliveryError('invalid_content', 'Duplicate or empty content ID.');
+        const existing = document.getElementById(next);
+        if (existing && (existing === container || !container.contains(existing)))
+            throw new ContentDeliveryError('invalid_content', 'Mount instance ID is already in use.');
+        ids.set(old, next);
+        element.id = next;
+    }
+    const tokenAttributes = ['aria-labelledby', 'aria-describedby', 'aria-controls', 'aria-owns', 'aria-flowto', 'headers'];
+    const singleAttributes = ['aria-activedescendant', 'aria-details', 'aria-errormessage', 'for', 'list', 'form'];
+    const rewrite = (id) => ids.get(id) ?? id;
+    const links = result.representation.links.map(link => ({ ...link }));
+    for (const element of template.content.querySelectorAll('*')) {
+        for (const attribute of tokenAttributes)
+            if (element.hasAttribute(attribute))
+                element.setAttribute(attribute, element.getAttribute(attribute).split(/\s+/).map(rewrite).join(' '));
+        for (const attribute of singleAttributes)
+            if (element.hasAttribute(attribute))
+                element.setAttribute(attribute, rewrite(element.getAttribute(attribute)));
+        const href = element.getAttribute('href');
+        if (href?.startsWith('#')) {
+            let id;
+            try {
+                id = decodeURIComponent(href.slice(1));
+            }
+            catch {
+                throw new ContentDeliveryError('invalid_content', 'Malformed content fragment.');
+            }
+            if (ids.has(id))
+                element.setAttribute('href', '#' + ids.get(id));
+        }
+        const key = element.getAttribute('data-export-link');
+        const link = key ? links.find(link => link.key === key) : undefined;
+        if (link?.kind === 'resource' && link.ref && contentRefKey(link.ref) === contentRefKey(result.resource.ref) && link.fragment && !link.query) {
+            const anchor = result.representation.anchors.find(anchor => anchor.id === link.fragment || anchor.exportedId === link.fragment);
+            const id = anchor && ids.get(anchor.exportedId);
+            if (id) {
+                element.setAttribute('href', '#' + id);
+                link.href = '#' + id;
+            }
+        }
+    }
+    const anchors = result.representation.anchors.map(anchor => {
+        const exportedId = ids.get(anchor.exportedId);
+        if (!exportedId)
+            throw new ContentDeliveryError('invalid_content', 'Declared anchor is absent from HTML.');
+        return Object.freeze({ ...anchor, exportedId });
+    });
+    options.signal?.throwIfAborted();
+    const mounted = [...template.content.childNodes];
+    container.replaceChildren(template.content);
+    return Object.freeze({ anchors: Object.freeze(anchors), links: Object.freeze(links.map(link => Object.freeze(link))),
+        unmount() { for (const node of mounted)
+            if (node.parentNode === container)
+                node.remove(); },
+    });
+}

package/dist/content-rest-client.d.ts

@@ -0,0 +1,12 @@
+import type { ContentSnapshot, ContentPublication } from './content-delivery-contract.js';
+import type { ContentDeliveryLimits } from './content-delivery.js';
+export type RestContentSourceOptions = {
+    baseUrl: string | URL;
+    publication: ContentPublication;
+    revision?: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+    limits?: ContentDeliveryLimits;
+};
+/** Preloads a REST inventory and pins all subsequent reads to that revision. */
+export declare function openRestContentSource(options: RestContentSourceOptions): Promise<ContentSnapshot>;

package/dist/content-rest-client.js

@@ -0,0 +1,162 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+import { contentResourceKey } from './content-rest-contract.js';
+import { validContentPublication, validContentRef, validateContentResources, safeContentPath } from './content-delivery-validation.js';
+import { freeze, sha256, readBounded } from './content-delivery-transport.js';
+const digestPattern = /^[a-f0-9]{64}$/;
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const exactKeys = (value, keys) => record(value) && Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
+const samePublication = (left, right) => left.channel === right.channel && left.version === right.version && left.language === right.language;
+const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
+/** Preloads a REST inventory and pins all subsequent reads to that revision. */
+export async function openRestContentSource(options) {
+    let baseUrl;
+    try {
+        baseUrl = new URL(options.baseUrl, typeof location === 'undefined' ? undefined : location.href);
+    }
+    catch {
+        return invalid('REST base URL must be a valid HTTP(S) URL.');
+    }
+    if (!['http:', 'https:'].includes(baseUrl.protocol) || baseUrl.username || baseUrl.password || baseUrl.search || baseUrl.hash || !/^\/(?:[A-Za-z0-9_-]+\/?)*$/.test(baseUrl.pathname))
+        invalid('Invalid REST base URL.');
+    if (typeof location !== 'undefined' && baseUrl.origin !== location.origin)
+        invalid('Browser content must be served from the application origin.');
+    if (!validContentPublication(options.publication) || options.revision !== undefined && !digestPattern.test(options.revision))
+        invalid('Invalid REST publication or revision.');
+    const publication = { ...options.publication };
+    const requestedRevision = options.revision;
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const manifestBytes = options.limits?.manifestBytes ?? 5_000_000;
+    const resourceBytes = options.limits?.resourceBytes ?? 8_000_000;
+    const maxResources = options.limits?.resources ?? 10_000;
+    for (const limit of [manifestBytes, resourceBytes, maxResources])
+        if (!Number.isSafeInteger(limit) || limit <= 0)
+            invalid('Limits must be positive safe integers.');
+    const lifetime = new AbortController();
+    let disposed = false;
+    const openSignal = options.signal ? AbortSignal.any([options.signal, lifetime.signal]) : lifetime.signal;
+    const urlFor = (suffix, revision) => {
+        const url = new URL(baseUrl.href);
+        url.pathname = baseUrl.pathname.replace(/\/$/, '') + '/resources' + suffix;
+        for (const key of ['channel', 'version', 'language'])
+            url.searchParams.set(key, publication[key]);
+        if (revision !== undefined)
+            url.searchParams.set('revision', revision);
+        return url;
+    };
+    async function request(url, mediaType, limit, signal) {
+        signal.throwIfAborted();
+        let response;
+        try {
+            response = await fetcher(url.href, { signal, redirect: 'error', credentials: 'same-origin', cache: 'no-store', headers: { Accept: mediaType } });
+        }
+        catch {
+            signal.throwIfAborted();
+            throw new ContentDeliveryError('network_error', 'Cannot fetch REST content.');
+        }
+        const reject = async (code, message) => {
+            // Cancelling releases the body without consuming an arbitrary host error.
+            // A custom stream's cancellation promise must not delay the failure.
+            void response.body?.cancel().catch(() => { });
+            signal.throwIfAborted();
+            throw new ContentDeliveryError(code, message);
+        };
+        if (response.redirected || response.url && response.url !== url.href)
+            return reject('invalid_content', 'Redirected content is not accepted.');
+        const actualType = response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+        try {
+            if (!response.ok) {
+                const codes = { 400: 'invalid_request', 404: 'not_found', 406: 'unsupported_format', 409: 'stale_revision', 405: 'method_not_allowed', 500: 'internal_error' };
+                if (!(response.status in codes))
+                    return reject('network_error', `Content request failed (${response.status}).`);
+                if (actualType !== 'application/json')
+                    return reject('invalid_content', 'REST error must be JSON.');
+                const bytes = await readBounded(response, Math.min(manifestBytes, 65_536), signal);
+                let envelope;
+                try {
+                    envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+                }
+                catch {
+                    throw new ContentDeliveryError('invalid_content', 'Malformed REST error.');
+                }
+                if (!exactKeys(envelope, ['error']) || !exactKeys(envelope.error, ['code', 'message']) || codes[response.status] !== envelope.error.code || typeof envelope.error.message !== 'string')
+                    throw new ContentDeliveryError('invalid_content', 'Malformed REST error.');
+                const code = response.status === 404 ? 'not_found' : response.status === 406 ? 'unsupported_format' : response.status === 409 ? 'stale_revision' : 'network_error';
+                throw new ContentDeliveryError(code, envelope.error.message);
+            }
+            if (actualType !== mediaType)
+                return reject('invalid_content', 'Unexpected content type.');
+            return await readBounded(response, limit, signal);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (error instanceof ContentDeliveryError)
+                throw error;
+            throw new ContentDeliveryError('network_error', 'Content response was interrupted.');
+        }
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await request(urlFor('', requestedRevision), 'application/json', manifestBytes, openSignal)));
+    }
+    catch (error) {
+        if (error instanceof ContentDeliveryError || openSignal.aborted)
+            throw error;
+        return invalid('REST inventory is not valid UTF-8 JSON.');
+    }
+    if (!exactKeys(envelope, ['schemaVersion', 'revision', 'publication', 'resources']) || envelope.schemaVersion !== 1 || !digestPattern.test(envelope.revision ?? '') || !validContentPublication(envelope.publication) || !samePublication(envelope.publication, publication))
+        invalid('Invalid REST inventory identity.');
+    if (requestedRevision !== undefined && requestedRevision !== envelope.revision)
+        throw new ContentDeliveryError('stale_revision', 'REST inventory differs from the requested revision.');
+    if (!Array.isArray(envelope.resources) || envelope.resources.length > maxResources)
+        invalid('Invalid REST resource inventory.');
+    const resources = [];
+    const assets = new Set();
+    for (const item of envelope.resources) {
+        if (!exactKeys(item, ['key', 'resource']) || !record(item.resource) || !validContentRef(item.resource.ref) || item.key !== contentResourceKey(item.resource.ref))
+            invalid('Invalid REST resource key.');
+        if (!Array.isArray(item.resource.assets) || item.resource.assets.some((asset) => !safeContentPath(asset) || !asset.startsWith('assets/')))
+            invalid('Invalid REST resource assets.');
+        item.resource.assets.forEach((asset) => assets.add(asset));
+        resources.push(item.resource);
+    }
+    validateContentResources(resources, publication, assets, rep => record(rep) && safeContentPath(rep.path) && Number.isSafeInteger(rep.bytes) && rep.bytes >= 0 && rep.bytes <= resourceBytes && digestPattern.test(rep.digest ?? ''));
+    const revision = envelope.revision;
+    freeze(resources);
+    freeze(publication);
+    const byRef = new Map(resources.map(resource => [contentRefKey(resource.ref), resource]));
+    openSignal.throwIfAborted();
+    const active = () => { if (disposed)
+        throw new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'); };
+    return Object.freeze({ revision, publication,
+        list() { active(); return resources; },
+        async get(ref, getOptions) {
+            active();
+            if (!validContentRef(ref))
+                throw new ContentDeliveryError('not_found', 'Invalid content reference.');
+            const resource = byRef.get(contentRefKey(ref));
+            if (!resource)
+                throw new ContentDeliveryError('not_found', 'No matching content in this publication.');
+            const format = getOptions?.format;
+            if (!['html', 'markdown'].includes(format) || !resource.representations[format])
+                throw new ContentDeliveryError('unsupported_format', 'The requested representation is unavailable.');
+            const representation = resource.representations[format];
+            const signal = getOptions.signal ? AbortSignal.any([lifetime.signal, getOptions.signal]) : lifetime.signal;
+            const bytes = await request(urlFor('/' + contentResourceKey(resource.ref) + '/representations/' + format, revision), representation.mediaType, resourceBytes, signal);
+            if (bytes.byteLength !== representation.bytes || await sha256(bytes) !== representation.digest)
+                throw new ContentDeliveryError('stale_revision', 'Representation differs from the opened revision.');
+            signal.throwIfAborted();
+            active();
+            let content;
+            try {
+                content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new ContentDeliveryError('invalid_content', 'Content is not valid UTF-8.');
+            }
+            return Object.freeze({ resource, representation, format, content, revision });
+        },
+        dispose() { if (!disposed) {
+            disposed = true;
+            lifetime.abort(new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'));
+        } }, });
+}