@shoalrun/cli 0.1.0-alpha.18 → 0.1.0-beta.1

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,6 +53,7 @@ export type Frontmatter = {
     image?: string;
     showNavigationTabs?: boolean;
     showVerified?: boolean;
+    pdf?: boolean;
     [key: string]: unknown;
 };
 export type Document = {

package/dist/frontmatter.js

@@ -4,7 +4,7 @@ import { validateCardMetadata } from './cards.js';
 import { resolveTaxonomy, validateTaxonomy, taxonomySchema } from './taxonomy.js';
 import { validateStandaloneSectionDeclarations } from './section-identity.js';
 export const nativePublicFields = new Set(['id', 'title', 'type', 'summary', 'description', 'language', 'locale', 'date', 'updated', 'verified', 'releaseVersion', 'availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'audiences', 'readerFilters', 'tags', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle']);
-export const protectedMetadataRoots = new Set(['shared', 'requires', 'standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
+export const protectedMetadataRoots = new Set(['shared', 'requires', 'standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'pdf', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
 const fieldTypes = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array']);
 const safePath = (value) => /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(value);
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -118,6 +118,8 @@ export function validateFrontmatter(frontmatter, config, file, source) {
         throw new Error(`${file}: shared must be true; use requires for restricted content`);
     if (frontmatter.shared === true && frontmatter.requires !== undefined)
         throw new Error(`${file}: declare shared: true or requires, not both`);
+    if (frontmatter.pdf !== undefined && typeof frontmatter.pdf !== 'boolean')
+        throw new Error(`${file}: pdf must be true or false`);
     validateCardMetadata(frontmatter.card, file);
     validateSubjectDeprecation(frontmatter.subjectDeprecation, file);
     validateAuthoredChange(frontmatter, file);
@@ -259,6 +261,7 @@ export function frontmatterSchema(config) {
         lifecycle: { type: 'string', minLength: 1, description: 'Editorial lifecycle of the document; validated by an opted-in external vocabulary.' },
         standaloneSections: { type: 'array', items: { oneOf: [{ type: 'string', minLength: 1 }, { type: 'object', additionalProperties: false, required: ['id', 'context'], properties: { id: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]{0,511}$' }, context: { const: 'section' } } }] }, uniqueItems: true, description: 'Page-specific standalone approval: a heading title approves contextual discovery with the page introduction; {id, context: section} approves the root level-two section slice for content export. IDs may be derived or explicitly anchored. Omitted means full-page reads.' },
         tocDepth: { type: 'integer', enum: [0, 2, 3, 4, 5, 6], description: 'Deepest heading shown in the page table of contents; 0 hides it. Defaults to 3.' },
+        pdf: { type: 'boolean', description: 'Controls the optional page print/PDF action. False suppresses its control and endpoint inputs; true follows the site setting. Site builds do not generate per-page PDFs.' },
         showVerified: { type: 'boolean', description: 'Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.' },
         showNavigationTabs: { type: 'boolean', description: 'Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.' },
         image: { type: 'string', pattern: '\\.(?:png|jpe?g)$', description: 'Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.' },
@@ -332,7 +335,7 @@ export function frontmatterReference(config, sectionsOnly = false) {
         'Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.', '',
         '## Categorize, connect, and present the page', '',
         'By default, `product`, `area`, and `subarea` are optional, nonempty string categories. They can come from project defaults and appear in the document manifest and search index. A matching configured reader facet makes each category a page filter; without that facet it remains taxonomy only. `operations` links a guide or reference to stable API operation IDs. On a guide or how-to page, `relatedApiReferences` names API reference page IDs to add cross links in both directions within the same publication. Tags help document collections find the page. Card settings change its preview when another page links to it; they do not change the destination. `subjectLifecycle` displays the status of the documented API or feature; `lifecycle` is available for the document\'s editorial state. `tocDepth` limits the HTML page table of contents; use 0 to hide it. `layout` picks the HTML page layout: `docs`, `wide`, `landing`, or `splash`. `showNavigationTabs` overrides the navigation tab bar for this page; landing and splash pages hide it by default. `image` replaces the generated link-preview image. `date` and `releaseVersion` can identify a changelog entry under the project\'s `frontmatter.changelogIdentifier` rule.', '',
-        ...table, ...nativeRows(['availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image']), '',
+        ...table, ...nativeRows(['availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'pdf', 'image']), '',
         'Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.', '',
         'With `profiles.requireClassification: true`, every public source page in the shared enabled publications needs an explicit `shared: true` or `requires` declaration before customer selection. Defaults do not count. Shared pages may contain feature-specific sections wrapped in `<ForFeature>`; unwrapped text remains shared.', '',
         '## Control output details', '',

package/dist/highlight-languages.d.ts

@@ -0,0 +1,9 @@
+import type { LanguageRegistration } from 'shiki';
+export type LanguageFiles = {
+    grammarOrigin?: (index: number) => string;
+    onDependency?: (file: string) => void;
+};
+export declare function customHighlightLanguages(value: unknown, declaringFile: string | undefined, reserved: ReadonlySet<string>, options: LanguageFiles, reservedScopes?: ReadonlySet<string>): Promise<{
+    file: string;
+    grammar: LanguageRegistration;
+}[]>;