@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/dist/content-export.js

@@ -1,4 +1,4 @@
-import { documentKey, samePublication } from './publication-identity.js';
+import { documentKey, publicationKey, samePublication } from './publication-identity.js';
 import { pruneFeatureTree, profileSelection } from './deployment-profile.js';
 import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
@@ -31,7 +31,18 @@ import { resolveAuthoredChange, authoredChangeNotice } from './authored-change.j
 import { resolveSnippetValues } from './snippets.js';
 import { isolateExportTree, markExportSource, exportHeadingInventory, preserveExportHeadingIds } from './content-export-anchors.js';
 import { selectSection } from './section-identity.js';
+import { profileNavigation, resolveProjectNavigation } from './project-navigation.js';
+import { createCodeHighlighter } from './highlight.js';
+import { projectPdfSettings } from './pdf-project.js';
+import { renderPdf } from './pdf-renderer.js';
 import { compareContentManifests } from './content-export-comparison.js';
+/** Prepare passive, scoped print inputs without launching a browser or writing output. */
+export async function preparePdfExport(configFile, options = {}) {
+    const result = await exportContent(configFile, '', { ...options, formats: ['pdf'], preparePdfOnly: true });
+    if (!('preparedPdf' in result) || !result.preparedPdf)
+        throw new Error('PDF preparation failed');
+    return result.preparedPdf;
+}
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const keyFor = (doc) => documentKey(doc.frontmatter.id, doc.variant);
 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, ...(item.doc.variant.product === undefined ? [] : [item.doc.variant.product])]);
@@ -75,7 +86,22 @@ export async function exportContent(configFile, destination, options = {}) {
             throw new Error(`Unknown export target ${options.target}`);
         raw = config.exports[options.target];
     }
+    // Website buttons can reuse a target's print styling without inheriting its
+    // content selection, publication, asset roots, or API review approvals.
+    let styleTarget = raw;
+    const styleTargetName = options.pdfStyleTarget ?? options.target;
+    if (options.pdfStyleTarget) {
+        if (!isConfigMapping(config.exports) || !Object.hasOwn(config.exports, options.pdfStyleTarget))
+            throw new Error(`Unknown PDF style target ${options.pdfStyleTarget}`);
+        styleTarget = config.exports[options.pdfStyleTarget];
+        if (!isConfigMapping(styleTarget.pdf))
+            throw new Error(`PDF style target ${options.pdfStyleTarget} needs a pdf mapping`);
+    }
     const target = validateExportTarget({ ...raw, ...(options.formats ? { formats: options.formats } : {}), ...(options.documents ? { documents: options.documents } : {}), ...(options.publication ? { publication: options.publication } : {}), ...(options.publicBase ? { publicBase: options.publicBase } : {}) }, config.readerFilters);
+    const pdf = target.formats.includes('pdf');
+    if (pdf && (options.previousManifest || options.failOnRemoved))
+        throw new Error('PDF exports do not support content-reference manifest comparison; compare their PDF manifests separately');
+    const formats = pdf ? ['html'] : target.formats;
     const language = defaultLanguage(config);
     const enabled = config.publications.enabled;
     if (!Array.isArray(enabled) || !enabled.length || enabled.some(value => !isConfigMapping(value)))
@@ -88,6 +114,8 @@ export async function exportContent(configFile, destination, options = {}) {
     if (!unique.some(variant => sameVariant(variant, publication)))
         throw new Error('The selected export publication is not enabled');
     const readerFilters = validateReaderFilters(config.readerFilters);
+    const siteSelection = validateContentFilter(site.contentFilter, readerFilters);
+    const selection = target.contentFilter ?? (pdf ? siteSelection : undefined);
     if (config.metadata !== undefined && (!isConfigMapping(config.metadata) || Object.keys(config.metadata).some(key => key !== 'provider')))
         throw new Error('metadata accepts only provider');
     const providerSetting = configField(config.metadata, 'provider');
@@ -100,10 +128,10 @@ export async function exportContent(configFile, destination, options = {}) {
         const doc = [...eligible.values()].find(doc => doc.frontmatter.id === id);
         if (!doc)
             throw new Error(`Requested export document ${id} is missing, non-public, or unavailable in the selected publication`);
-        if (!matchesContentFilter(doc.readerFilters, target.contentFilter))
+        if (!matchesContentFilter(doc.readerFilters, selection))
             throw new Error(`Requested export document ${id} is excluded by the export contentFilter`);
     }
-    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))));
+    const docs = new Map([...eligible].filter(([, doc]) => (!(target.documents || target.resources) || ids.has(doc.frontmatter.id)) && matchesContentFilter(doc.readerFilters, selection)).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 });
@@ -196,6 +224,34 @@ export async function exportContent(configFile, destination, options = {}) {
         }
     }
     selected.sort((a, b) => compare(resourceIdentity(a), resourceIdentity(b)));
+    if (pdf) {
+        const order = [];
+        if (target.documents)
+            order.push(...target.documents);
+        else if (config.navigation !== undefined) {
+            // Validate against known identities before pruning this publication/edition.
+            const layout = profileNavigation(config.navigation, docs, workspace.knownDocumentIds, apiPlan.knownOperations, new Set(Object.keys(apiPlan.apiDefinitions)));
+            const navigation = resolveProjectNavigation(layout, publication, docs, materialized.navigationEntries.get(publicationKey(publication)) ?? [], materialized.navigationTagOrder.get(publicationKey(publication)) ?? new Map());
+            const byRoute = new Map([...docs.values()].map(doc => [doc.route, doc.frontmatter.id]));
+            const walk = (nodes) => { for (const node of nodes) {
+                if (node.route) {
+                    const id = byRoute.get(node.route);
+                    if (id && !order.includes(id))
+                        order.push(id);
+                }
+                if (node.items)
+                    walk(node.items);
+            } };
+            walk(navigation);
+            const unlisted = [...docs.values()].map(doc => doc.frontmatter.id).filter(id => !order.includes(id)).sort(compare);
+            if (unlisted.length)
+                diagnostics.push({ code: 'pdf-unlisted-pages', message: `${unlisted.length} eligible page(s) outside navigation were appended in stable document-ID order.` });
+            order.push(...unlisted);
+        }
+        else
+            order.push(...[...docs.values()].map(doc => doc.frontmatter.id).sort(compare));
+        selected.sort((a, b) => order.indexOf(a.doc.frontmatter.id) - order.indexOf(b.doc.frontmatter.id));
+    }
     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;
@@ -218,9 +274,13 @@ export async function exportContent(configFile, destination, options = {}) {
     const unreviewed = reviews.filter(review => (target.apiReview[review.apiId] ?? configField(apiPlan.apiDefinitions[review.apiId].publicReview, 'digest')) !== review.digest);
     if (unreviewed.length && !options.review)
         throw new Error(`Export API review required: ${unreviewed.map(row => `${row.apiId}=${row.digest}`).join(', ')}. Run export with --review, inspect the candidate, and pin these digests in exports.<target>.apiReview`);
-    const siteSelection = validateContentFilter(site.contentFilter, readerFilters);
     const website = [...eligible.values()].filter(doc => matchesContentFilter(doc.readerFilters, siteSelection));
     const canonicalDestination = (doc) => website.includes(doc) && website.filter(other => other.route.toLowerCase() === doc.route.toLowerCase()).length === 1;
+    const publishedAssetRoutes = new Map();
+    for (const route of materialized.focusedContracts.keys())
+        publishedAssetRoutes.set(route, route);
+    for (const asset of diagrams)
+        publishedAssetRoutes.set(asset.route, publicPath(asset.route));
     const byId = new Map([...eligible.values()].map(doc => [doc.frontmatter.id, doc]));
     const byRoute = (pathname) => {
         const matches = [...eligible.values()].filter(doc => doc.route === pathname.replace(/\/$/, '') || doc.route === pathname || doc.markdownRoute === pathname);
@@ -234,13 +294,13 @@ export async function exportContent(configFile, destination, options = {}) {
     const sourceInventories = new Map();
     const sourceAliases = new Map();
     for (const item of selected)
-        for (const format of target.formats) {
+        for (const format of formats) {
             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);
+                sourceInventories.set(sourceKey, exportHeadingInventory(portableTree(structuredClone(item.doc.tree), format, routes, basePath, { print: pdf })));
+            const tree = portableTree(structuredClone(item.tree), format, routes, basePath, { print: pdf });
             if (item.ref.kind !== 'page') {
-                const meaning = item.meaningTree ? portableTree(structuredClone(item.meaningTree), format, routes, basePath) : tree;
+                const meaning = item.meaningTree ? portableTree(structuredClone(item.meaningTree), format, routes, basePath, { print: pdf }) : 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}`);
@@ -249,7 +309,7 @@ export async function exportContent(configFile, destination, options = {}) {
             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);
+            anchors.set(`${resourceIdentity(item)}:${format}`, passiveHtml(tree, `sr-${resourceKey(item)}`, false, { print: pdf }).anchors);
         }
     const canonicalAnchors = new Map();
     const verifiedCanonicalAnchors = (destination, format) => {
@@ -278,130 +338,177 @@ export async function exportContent(configFile, destination, options = {}) {
     };
     const records = [];
     const artifacts = new Map();
-    for (const item of selected) {
-        const doc = item.doc;
-        const externalDependencies = new Map();
-        const usedAssets = new Set();
-        const representations = {};
-        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(`${resourceIdentity(item)}:${format}`);
-            const resolve = async (node) => {
-                // Native adapters can express ordinary links/images as semantic elements.
-                const properties = node.data?.hProperties;
-                const attr = node.data?.hName === 'a' ? 'href' : node.data?.hName === 'img' ? 'src' : undefined;
-                if (attr && typeof properties?.[attr] === 'string') {
-                    const virtual = { type: attr === 'src' ? 'image' : 'link', url: properties[attr], children: [] };
-                    await resolve(virtual);
-                    properties[attr] = virtual.url;
-                    if (virtual.data?.hProperties?.['data-export-link'])
-                        properties['data-export-link'] = virtual.data.hProperties['data-export-link'];
-                }
-                if (typeof node.url === 'string' && ['link', 'image', 'definition'].includes(node.type)) {
-                    const value = node.url;
-                    const parsed = new URL(value, `https://export.invalid${doc.route === basePath ? `${doc.route}/` : doc.route}`);
-                    if (!['http:', 'https:', ...(node.type !== 'image' ? ['mailto:', 'tel:'] : [])].includes(parsed.protocol) || parsed.username || parsed.password)
-                        throw new Error(`Unsafe export URL ${value}`);
-                    let destination;
-                    if (node.type !== 'image') {
-                        destination = node.exportDocumentId ? byId.get(node.exportDocumentId) : value.startsWith('#') || value.startsWith('?') ? doc : undefined;
-                        if (!destination && parsed.origin === 'https://export.invalid') {
-                            const pathUrl = outputUrl(value, doc.route, undefined, 'html', routes, basePath);
-                            destination = byRoute(new URL(pathUrl, 'https://export.invalid').pathname);
-                            if (!destination && /\.mdx?$/.test(parsed.pathname) && !value.startsWith('/')) {
-                                const file = path.resolve(path.dirname(doc.file), decodeURIComponent(value.split(/[?#]/)[0]));
-                                destination = [...eligible.values()].find(other => path.resolve(other.file) === file);
-                            }
-                        }
+    const printDocuments = [];
+    const highlightDependencies = new Set();
+    const highlighting = configField(configField(config.outputs, 'html'), 'highlighting');
+    // PDF has a light paper background, independent of the site's screen mode.
+    const printHighlighting = isConfigMapping(highlighting) && highlighting.provider !== 'custom' && highlighting.provider !== 'none' ? { ...highlighting, theme: 'github-light' } : highlighting ?? { theme: 'github-light' };
+    const highlighter = pdf ? await createCodeHighlighter(printHighlighting, highlighting ? explainSegments(loaded, ['outputs', 'html', 'highlighting']).source.file : configFile, {
+        grammarOrigin: index => explainSegments(loaded, ['outputs', 'html', 'highlighting', 'languages', String(index), 'grammar']).source.file,
+        onDependency: file => highlightDependencies.add(file)
+    }) : undefined;
+    if (highlighter?.dependency)
+        highlightDependencies.add(highlighter.dependency);
+    for (const file of highlighter?.dependencies ?? [])
+        highlightDependencies.add(file);
+    try {
+        for (const item of selected) {
+            const doc = item.doc;
+            const externalDependencies = new Map();
+            const usedAssets = new Set();
+            const representations = {};
+            const canonicalUrl = item.ref.kind !== 'snippet' && origin && canonicalDestination(doc) ? `${origin}${doc.route}` : undefined;
+            for (const format of formats) {
+                const links = [];
+                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;
+                    const attr = node.data?.hName === 'a' ? 'href' : node.data?.hName === 'img' ? 'src' : undefined;
+                    if (attr && typeof properties?.[attr] === 'string') {
+                        const virtual = { type: attr === 'src' ? 'image' : 'link', url: properties[attr], children: [] };
+                        await resolve(virtual);
+                        properties[attr] = virtual.url;
+                        if (virtual.data?.hProperties?.['data-export-link'])
+                            properties['data-export-link'] = virtual.data.hProperties['data-export-link'];
                     }
-                    if (destination) {
-                        let href;
-                        let kind;
-                        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];
+                    if (typeof node.url === 'string' && ['link', 'image', 'definition'].includes(node.type)) {
+                        const value = node.url;
+                        const parsed = new URL(value, `https://export.invalid${doc.route === basePath ? `${doc.route}/` : doc.route}`);
+                        if (!['http:', 'https:', ...(node.type !== 'image' ? ['mailto:', 'tel:'] : [])].includes(parsed.protocol) || parsed.username || parsed.password)
+                            throw new Error(`Unsafe export URL ${value}`);
+                        let destination;
+                        if (node.type !== 'image') {
+                            destination = node.exportDocumentId ? byId.get(node.exportDocumentId) : value.startsWith('#') || value.startsWith('?') ? doc : undefined;
+                            if (!destination && parsed.origin === 'https://export.invalid') {
+                                const pathUrl = outputUrl(value, doc.route, undefined, 'html', routes, basePath);
+                                destination = byRoute(new URL(pathUrl, 'https://export.invalid').pathname);
+                                if (!destination && /\.mdx?$/.test(parsed.pathname) && !value.startsWith('/')) {
+                                    const file = path.resolve(path.dirname(doc.file), decodeURIComponent(value.split(/[?#]/)[0]));
+                                    destination = [...eligible.values()].find(other => path.resolve(other.file) === file);
+                                }
+                            }
                         }
-                        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 (destination) {
+                            let href;
+                            let kind;
+                            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}`;
+                                if (pdf) {
+                                    if (options.pdfLinks === 'canonical' && chosen !== item) {
+                                        if (!origin || !canonicalDestination(destination))
+                                            throw new Error(`PDF page link to ${destination.frontmatter.id} requires site.origin and an eligible canonical website route`);
+                                        if (fragment && !verifiedCanonicalAnchors(destination, format).has(fragment))
+                                            throw new Error(`Cannot verify canonical anchor ${fragment} in ${destination.frontmatter.id}; use its page URL without a fragment`);
+                                        href = `${origin}${destination.route}${parsed.search}${parsed.hash}`;
+                                        kind = 'canonical';
+                                    }
+                                    else {
+                                        if (parsed.search)
+                                            throw new Error(`PDF internal links cannot retain query parameters: ${value}. Use an explicit canonical HTTPS link instead`);
+                                        href = `#${fragment ? anchor.exportedId : `pdf-document-${options.pdfLinks === 'canonical' ? 1 : selected.indexOf(chosen) + 1}`}`;
+                                        kind = 'resource';
+                                    }
+                                }
+                                else
+                                    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, ...(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 } };
                         }
-                        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 (parsed.origin !== 'https://export.invalid') {
+                            node.url = value.startsWith('//') ? `https:${value}` : value;
+                            if (node.type === 'image') {
+                                if (pdf)
+                                    throw new Error(`PDF images must be local staged assets: ${node.url}`);
+                                externalDependencies.set(node.url, { url: node.url, kind: 'image' });
+                            }
+                            else
+                                links.push({ key: `link-${links.length + 1}`, kind: 'external', href: node.url });
                         }
                         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`);
+                            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);
+                            node.url = `${target.publicBase}${asset.path}${parsed.search}${parsed.hash}`;
+                            if (node.type !== 'image') {
+                                if (pdf) {
+                                    if (!origin || !canonicalDestination(doc) || !publishedAssetRoutes.has(parsed.pathname))
+                                        throw new Error(`PDF cannot embed local download link ${value}; use an explicit canonical HTTPS download URL instead`);
+                                    node.url = `${origin}${publishedAssetRoutes.get(parsed.pathname)}${parsed.search}${parsed.hash}`;
+                                }
+                                links.push({ key: `link-${links.length + 1}`, kind: 'asset', href: node.url, asset: asset.path });
                             }
-                            href = `${origin}${destination.route}${parsed.search}${parsed.hash}`;
-                            kind = 'canonical';
                         }
-                        const key = `link-${links.length + 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 } };
-                    }
-                    else if (parsed.origin !== 'https://export.invalid') {
-                        node.url = value.startsWith('//') ? `https:${value}` : value;
-                        if (node.type === 'image')
-                            externalDependencies.set(node.url, { url: node.url, kind: 'image' });
-                        else
-                            links.push({ key: `link-${links.length + 1}`, kind: 'external', href: node.url });
-                    }
-                    else {
-                        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);
-                        node.url = `${target.publicBase}${asset.path}${parsed.search}${parsed.hash}`;
-                        if (node.type !== 'image')
-                            links.push({ key: `link-${links.length + 1}`, kind: 'asset', href: node.url, asset: asset.path });
                     }
-                }
-                for (const child of node.children ?? [])
-                    await resolve(child);
-            };
-            await resolve(tree);
-            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 };
+                    for (const child of node.children ?? [])
+                        await resolve(child);
+                };
+                await resolve(tree);
+                const filename = `content/${resourceKey(item)}.${format === 'html' ? 'html' : 'md'}`;
+                const rendered = format === 'html' ? passiveHtml(tree, `sr-${resourceKey(item)}`, !pdf, { print: pdf, highlighter }) : undefined;
+                const content = rendered?.html ?? portableMarkdown(tree);
+                if (pdf)
+                    printDocuments.push({ id: doc.frontmatter.id, title: item.title, html: content });
+                else
+                    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({ 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)) });
         }
-        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({ 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)) });
+    }
+    finally {
+        highlighter?.dispose?.();
     }
     for (const [filename, bytes] of assets.artifacts)
         artifacts.set(filename, bytes);
@@ -432,6 +539,42 @@ export async function exportContent(configFile, destination, options = {}) {
         notices += `\n${path.basename(file)}:\n${await readFile(resolvedNotice, 'utf8')}\n`;
     }
     artifacts.set('NOTICES.txt', notices);
+    if (pdf) {
+        const singlePage = target.documents?.length === 1;
+        const standalone = singlePage || options.pdfLinks === 'canonical';
+        const projectPdf = projectPdfSettings(loaded, configFile, styleTargetName);
+        const pdfConfig = { cover: !standalone, toc: !standalone, ...projectPdf.config };
+        const pdfInputs = projectPdf.files;
+        const inputs = [...noticeFiles, ...loaded.dependencies, ...metadataDependencies, ...plugins.dependencies, ...apiPlan.api.dependencies, ...[...eligible.values()].map(doc => doc.file), ...[...snippets.values()].map(snippet => snippet.file), ...highlightDependencies, ...pdfInputs];
+        const manifest = {
+            schemaVersion: 1, kind: 'shoalrun-pdf-export', publication, title: site.title,
+            review: { status: unreviewed.length ? 'required' : 'ok', apis: reviews.map(row => ({ apiId: row.apiId, digest: row.digest })) },
+            documents: records.map((record, index) => ({ id: selected[index].doc.frontmatter.id, title: record.title, contentDigest: exportDigest(printDocuments[index].html), anchors: record.representations.html.anchors, links: record.representations.html.links })), diagnostics
+        };
+        const input = { documents: printDocuments, title: selected.length === 1 ? selected[0].title : site.title, publication, assets: assets.artifacts, publicBase: target.publicBase, config: pdfConfig, configFile, assetRoots: [...roots, ...pdfInputs.map(file => path.dirname(file))] };
+        const preparedPdf = { input, manifest, inputs };
+        const common = { status: unreviewed.length ? 'needs-review' : 'ok', output: path.resolve(destination || base), publication, formats: target.formats, profileSelection: profileSelection(loaded.deployment), resources: records.length, documents: records.length, documentIds: selected.map(item => item.doc.frontmatter.id), comparison: { status: 'no-baseline', added: [], removed: [], diagnostics: [] }, assets: assets.records.size, apiReview: manifest.review.apis, diagnostics };
+        if (options.preparePdfOnly)
+            return { ...common, digest: exportDigest(JSON.stringify(manifest)), preparedPdf };
+        checkOutputDirectory(destination, base, workspace.contentDir, inputs);
+        // Style/font/logo files are protected by the explicit input list. Their
+        // parent directory can be the project root and isn't a content directory.
+        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');
+        }
+        const rendered = await renderPdf(input);
+        const filename = singlePage ? 'page.pdf' : 'publication.pdf';
+        const pdfArtifacts = new Map([[filename, rendered.bytes], ['NOTICES.txt', notices]]);
+        const payload = { ...manifest, renderer: rendered.metadata, files: [...pdfArtifacts].map(([file, bytes]) => ({ path: file, bytes: Buffer.byteLength(bytes), digest: exportDigest(bytes) })) };
+        const digest = exportDigest(JSON.stringify(payload));
+        pdfArtifacts.set('manifest.json', JSON.stringify({ ...payload, digest }, null, 2) + '\n');
+        await commitArtifacts(path.resolve(destination), pdfArtifacts, undefined, 'pdf');
+        return { ...common, digest, pdf: filename };
+    }
     const manifest = { schemaVersion: publication.product === undefined ? 1 : 2, kind: 'shoalrun-content-export', publicBase: target.publicBase, publication,
         review: { status: unreviewed.length ? 'required' : 'ok', apis: reviews.map(row => ({ apiId: row.apiId, digest: row.digest })) },
         resources: records, assets: [...assets.records.values()].sort((a, b) => compare(a.path, b.path)),

package/dist/content-source.d.ts

@@ -53,9 +53,11 @@ export type Frontmatter = {
     image?: string;
     showNavigationTabs?: boolean;
     showVerified?: boolean;
+    pdf?: boolean;
     [key: string]: unknown;
 };
 export type Document = {
+    codeReference?: import('./code-reference-model.js').CodeReference;
     featureContext?: import('./deployment-profile.js').FeatureContext;
     change?: ResolvedChange;
     subjectDeprecation?: ResolvedSubjectDeprecation;

package/dist/content-workspace.d.ts

@@ -12,6 +12,7 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
         snippets?: unknown;
         variables?: unknown;
         apis?: unknown;
+        codeReferences?: unknown;
     };
     loaded: Awaited<ReturnType<typeof loadConfig>>;
     variants: Variant[];

package/dist/content-workspace.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { parse } from './content.js';
 import { planAuthoredDocuments } from './publication-plan.js';
+import { materializeCodeReferences } from './code-references.js';
 import { materializeApiReferences } from './api-publication-plan.js';
 import { explainSegments } from './config.js';
 import { validateSnippetConfig } from './snippets.js';
@@ -13,6 +14,7 @@ export async function prepareContentWorkspace({ base, basePath, config, loaded,
     const { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir } = await planAuthoredDocuments({
         base, basePath, config, variants, language, readerFilters, contentFilter, featureContext: loaded.deployment?.context, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions
     });
+    await materializeCodeReferences({ config, loaded, plan: { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir }, base, basePath, variants, language, readerFilters, contentFilter, dependencies: metadataDependencies, allowRouteCollisions });
     if (config.snippets !== undefined && (!config.snippets || typeof config.snippets !== 'object' || Array.isArray(config.snippets)))
         throw new Error('snippets must be a mapping');
     const snippets = new Map();

package/dist/fonts.d.ts

@@ -6,12 +6,18 @@ export type FontFace = {
     style: 'normal' | 'italic';
     weight: string;
 };
+export type FontPreload = {
+    href: string;
+    type: string;
+};
 export type SiteFonts = {
     bundled: boolean;
     faces: FontFace[];
     tokens: Partial<Record<FontRole, string>>;
     preload?: string;
+    preloadFaces?: FontFace[];
 };
+export declare const fontMediaType: (file: string) => string | undefined;
 export declare const bundledFonts: readonly [{
     readonly family: "Inter";
     readonly file: "inter.woff2";
@@ -51,4 +57,7 @@ export declare const bundledFonts: readonly [{
 }];
 export declare const bundledFontLicenses: string[];
 export declare function resolveFonts(value: unknown, preset: string, declaringFile: string): SiteFonts;
+/** Pin project font URLs to the same bytes that will be emitted by this build. */
+export declare function prepareFontAssets(fonts: SiteFonts): Promise<Map<string, Buffer>>;
+export declare function customFontPreloads(fonts: SiteFonts): FontPreload[];
 export declare function fontsCss(fonts: SiteFonts): string | undefined;