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

package/dist/browser-print-assets.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { parse } from 'parse5';
+import { loadConfig } from './config.js';
+import { projectPdfSettings } from './pdf-project.js';
+import { preparePdfDocument } from './pdf-renderer.js';
+import { sitePath } from './site-path.js';
+/** One shared print theme for the entire build; no page content is materialized. */
+export async function browserPrintAssets(configFile, options) {
+    const loaded = await loadConfig(configFile, { profile: options.profile });
+    const { config, files } = projectPdfSettings(loaded, configFile, options.style);
+    const prepared = await preparePdfDocument({
+        documents: [{ id: 'print-theme', title: '', html: '' }], title: '', assets: new Map(), publicBase: '/',
+        config: { ...config, cover: false, toc: false }, configFile,
+        assetRoots: files.map(file => path.dirname(file))
+    });
+    let css = '';
+    const findStyle = (node) => { if (node.tagName === 'style')
+        css += (node.childNodes ?? []).map((child) => child.value ?? '').join(''); for (const child of node.childNodes ?? [])
+        findStyle(child); };
+    findStyle(parse(prepared.html));
+    const artifacts = new Map();
+    let logo;
+    for (const [original, asset] of prepared.assets) {
+        const route = sitePath(options.basePath, `/assets/print/${path.posix.basename(original)}`);
+        artifacts.set(route, asset.bytes);
+        css = css.replaceAll(original, route);
+        if (original.startsWith('/__pdf_logo/'))
+            logo = route;
+    }
+    const margins = { top: '18mm', right: '18mm', bottom: '18mm', left: '18mm', ...config.margins };
+    css = `@page{size:${config.size ?? 'A4'};margin:${margins.top} ${margins.right} ${margins.bottom} ${margins.left}}\n` + css;
+    css += '\n.pdf-print-tools{display:flex;gap:10px;align-items:center;padding:12px 0;margin-bottom:24px;font:14px Arial,sans-serif}.pdf-print-tools button{font:inherit;padding:8px 12px;border:1px solid #89998e;border-radius:4px;cursor:pointer}.pdf-print-tools .pdf-print-note{margin-left:auto;color:#53665e;font-size:12px}.pdf-chapter .page-head h1{margin-bottom:8pt}.pdf-chapter .page-head .summary{font-size:10pt;line-height:1.5;margin:0 0 8pt}.pdf-chapter .page-head .pdf-page-meta{font-size:8pt;margin:5pt 0 12pt}.pdf-page-meta{color:var(--pdf-muted);font-size:9pt;margin-bottom:14pt}.pdf-chapter .eyebrow{color:var(--pdf-muted);font-size:9pt}.pdf-chapter .page-dates{display:flex;flex-wrap:wrap;gap:4pt 10pt;font-size:9pt;color:var(--pdf-muted)}.pdf-chapter .doc-callout{border-left:3pt solid var(--pdf-accent);padding:10pt 14pt;background:#f1f4ee;margin:14pt 0}.pdf-chapter details{display:block}.pdf-reader-label{font-weight:bold;margin-top:14pt}@media screen{html{background:#dfe5de}body{max-width:210mm;margin:24px auto;padding:18mm;background:white;box-shadow:0 8px 40px #173c3520}}@media print{.pdf-print-tools{display:none!important}}';
+    // A manual theme may start every chapter on a new page. When no cover or
+    // contents precede this chapter, that break can produce a blank first sheet.
+    css += '\n.pdf-print-tools + .pdf-chapter{break-before:auto}';
+    const stylesheet = sitePath(options.basePath, '/assets/print/theme.css');
+    artifacts.set(stylesheet, css);
+    const settings = {
+        schemaVersion: 1, stylesheet, ...(logo ? { logo } : {}), cover: config.cover ?? false,
+        toc: config.toc ?? false, subtitle: config.subtitle ?? '', header: config.header ?? '', footer: config.footer ?? '',
+        fonts: (config.fonts ?? []).map(({ family, weight, style }) => ({ family, weight, style }))
+    };
+    artifacts.set(sitePath(options.basePath, '/assets/print/settings.json'), JSON.stringify(settings));
+    return { artifacts, dependencies: new Set([...loaded.dependencies, ...files]) };
+}

package/dist/chat-config.d.ts

@@ -31,6 +31,8 @@ export type ChatChallenge = {
     provider: 'turnstile';
     siteKey: string;
     secretEnv: string;
+    hostnames?: string[];
+    action?: string;
     when: 'adaptive' | 'always';
     freeQuestions: number;
     busyShare: number;

package/dist/chat-config.js

@@ -1,5 +1,6 @@
 import { reservedBodyFields } from './chat.js';
 import { validateReaderSelection } from './reader-filters.js';
+import { turnstileHostnames } from './turnstile-policy.js';
 export const escalateReasons = ['unsupported-claim', 'unsupported-code', 'uncited'];
 export const defaultLogNotice = 'Questions are recorded, with personal details removed, to improve these docs.';
 const mapping = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -305,9 +306,9 @@ export function validateChat(value, readerFilters) {
         if (!mapping(challenge))
             throw new Error('chat.challenge must be a mapping with provider, siteKey, and secretEnv');
         for (const key of Object.keys(challenge)) {
-            if (['provider', 'siteKey', 'secretEnv', 'when', 'freeQuestions', 'busyShare'].includes(key))
+            if (['provider', 'siteKey', 'secretEnv', 'hostnames', 'action', 'when', 'freeQuestions', 'busyShare'].includes(key))
                 continue;
-            throw new Error(/key|secret|token|password/i.test(key) ? `chat.challenge.${key} is not a setting. The config never holds a secret; name the environment variable that does with secretEnv` : `chat.challenge has an unknown setting ${key}; it accepts provider, siteKey, secretEnv, when, freeQuestions, and busyShare`);
+            throw new Error(/key|secret|token|password/i.test(key) ? `chat.challenge.${key} is not a setting. The config never holds a secret; name the environment variable that does with secretEnv` : `chat.challenge has an unknown setting ${key}; it accepts provider, siteKey, secretEnv, hostnames, action, when, freeQuestions, and busyShare`);
         }
         if (challenge.provider !== 'turnstile')
             throw new Error('chat.challenge.provider must be turnstile');
@@ -322,6 +323,13 @@ export function validateChat(value, readerFilters) {
         if (challenge.busyShare !== undefined && (typeof challenge.busyShare !== 'number' || !(challenge.busyShare > 0 && challenge.busyShare <= 1)))
             throw new Error('chat.challenge.busyShare must be a number above 0 and at most 1');
         result.challenge = { provider: 'turnstile', siteKey, secretEnv, when: challenge.when ?? 'adaptive', freeQuestions: challenge.freeQuestions === undefined ? 3 : integer(challenge.freeQuestions, 'chat.challenge.freeQuestions', 0, 1000), busyShare: challenge.busyShare ?? 0.5 };
+        if (challenge.hostnames !== undefined)
+            result.challenge.hostnames = turnstileHostnames(challenge.hostnames, 'chat.challenge.hostnames');
+        if (challenge.action !== undefined) {
+            if (typeof challenge.action !== 'string' || !/^[A-Za-z0-9_-]{1,32}$/.test(challenge.action))
+                throw new Error('chat.challenge.action must contain 1 to 32 letters, numbers, underscores, or hyphens');
+            result.challenge.action = challenge.action;
+        }
     }
     if (value.budget !== undefined) {
         if (!mapping(value.budget))

package/dist/cli.js

@@ -40,7 +40,7 @@ import { buildChunkIndex, embeddingInput } from './index-build.js';
 import { createProvider, embedChunkIndex, readEmbeddings } from './embeddings.js';
 import { embeddingProviderConfig, queryProviderConfig, validateRetrieval } from './retrieval-config.js';
 import { defaultLogNotice, validateChat } from './chat-config.js';
-import { createSession, turnstileVerifier } from './turnstile.js';
+import { createSession, turnstilePreviewVerifier } from './turnstile.js';
 import { adaptiveChallenge } from './budget.js';
 import { validateReaderFilters } from './reader-filters.js';
 import { askQuestion } from './ask.js';
@@ -269,7 +269,7 @@ try {
             if (publicPreview) {
                 chatConfigForPreview = chatConfig;
                 publicSettings = { siteKey: '1x00000000000000000000AA', ...(chatConfig?.challenge?.when === 'always' ? { prewarm: true } : {}), notice: chatConfig?.log?.notice ?? defaultLogNotice, ...(chatConfig?.panel ? { panel: chatConfig.panel } : {}) };
-                const verify = turnstileVerifier({ secret: '1x0000000000000000000000000000000AA' });
+                const verify = turnstilePreviewVerifier();
                 challenge = ({ token, ip }) => verify({ token, ip });
             }
             const handler = createAskHandler({ hosts, exposeErrors: true, ...(publicPreview ? { response: 'public', challenge, session: createSession({ secret: '1x0000000000000000000000000000000AA' }), ...(chatConfigForPreview?.challenge?.when === 'always' || !setup.budget ? {} : { challengeNeeded: adaptiveChallenge(setup.budget, { freeQuestions: chatConfigForPreview?.challenge?.freeQuestions, busyShare: chatConfigForPreview?.challenge?.busyShare }) }) } : {}), ...(log ? { record: event => log.write(event) } : {}), ...(setup.budget ? { budget: setup.budget } : {}), answer: (question, history, context) => askQuestion({ question, history, ...setup.options, modelAllowed: context.modelAllowed, signal: context.signal, ...(publicPreview ? { requireCitations: true } : {}) }) });

package/dist/compiler.d.ts

@@ -6,13 +6,14 @@ export declare function checkThemeContrast(configFile: string): Promise<{
     modes: Mode[];
     palette: string;
 }>;
-export declare function compile(configFile: string, destination?: string, provenance?: BuildProvenance, options?: {
+type CompileOptions = {
     apiReview?: 'report';
     sourceOverrides?: ReadonlyMap<string, string>;
     authoringFiles?: ReadonlySet<string>;
     profile?: string;
     onDependency?: (file: string) => void;
-}): Promise<{
+};
+export declare function compile(configFile: string, destination?: string, provenance?: BuildProvenance, options?: CompileOptions): Promise<{
     authoringSources?: {
         id: string;
         file: string;
@@ -240,3 +241,4 @@ export declare function compile(configFile: string, destination?: string, proven
     schemaVersion: number;
     configDigest: string;
 }>;
+export {};

package/dist/compiler.js

@@ -1,3 +1,5 @@
+import { buildPdfSiteArtifacts } from './pdf-site.js';
+import { resolvePdfButton, validatePdfButtonStyle } from './pdf-button.js';
 import { documentKey, publicationKey, samePublication } from './publication-identity.js';
 import { validateHeader, validateFooter } from './site-identity.js';
 import { profileSelection } from './deployment-profile.js';
@@ -102,6 +104,15 @@ export async function checkThemeContrast(configFile) {
     return { modes, palette: palette.name };
 }
 export async function compile(configFile, destination, provenance = {}, options = {}) {
+    let dispose;
+    try {
+        return await compileProject(configFile, destination, provenance, options, release => { dispose = release; });
+    }
+    finally {
+        dispose?.();
+    }
+}
+async function compileProject(configFile, destination, provenance, options, ownHighlighter) {
     const loaded = await loadConfig(configFile, { profile: options.profile, onDependency: options.onDependency });
     const componentPlugins = await loadComponentPlugins(loaded);
     const provenanceRecord = buildInfo(loaded.digest, provenance);
@@ -118,9 +129,15 @@ export async function compile(configFile, destination, provenance = {}, options
     const calloutTypes = resolveCalloutTypes(config.callouts, configFile);
     const badgeVariants = resolveBadgeVariants(config.badges, configFile);
     const htmlOptions = configField(config.outputs, 'html');
+    const pdfButton = resolvePdfButton(config.outputs);
+    validatePdfButtonStyle(pdfButton, config.exports);
     const highlighting = configField(htmlOptions, 'highlighting');
     const highlightingOrigin = configField(highlighting, 'module') === undefined ? configFile : explainSegments(loaded, ['outputs', 'html', 'highlighting', 'module']).source.file;
-    const highlighter = await createCodeHighlighter(highlighting, highlightingOrigin);
+    const highlighter = await createCodeHighlighter(highlighting, highlightingOrigin, {
+        grammarOrigin: index => explainSegments(loaded, ['outputs', 'html', 'highlighting', 'languages', String(index), 'grammar']).source.file,
+        onDependency: options.onDependency
+    });
+    ownHighlighter(highlighter.dispose);
     const base = path.dirname(path.resolve(configFile));
     if (config.site.customCss !== undefined && (typeof config.site.customCss !== 'string' || !config.site.customCss.endsWith('.css')))
         throw new Error('site.customCss must be a local .css path');
@@ -313,7 +330,7 @@ export async function compile(configFile, destination, provenance = {}, options
     const cardUses = new Map();
     const publishedRelationships = [];
     const styleFiles = ['site.css', 'tokens.css', 'header.css'].map(name => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../styles', name));
-    const scriptFiles = [...(analyticsModule ? ['analytics.js'] : []), 'code-samples.js', 'cookbook-chooser.js', 'example-panel.js', 'mode.js', 'copy-markdown.js', 'components.js', 'navigation.js', 'reader.js', ...(readerFilters ? ['reader-filters.js'] : []), 'search-highlight.js', 'search.js', 'table-filter.js', 'tabs.js', 'tooltips.js', 'file-tree.js', 'image-viewer.js', 'walkthrough.js'].map(name => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../assets', name));
+    const scriptFiles = [...(analyticsModule ? ['analytics.js'] : []), 'code-samples.js', 'cookbook-chooser.js', 'example-panel.js', 'mode.js', ...(pdfButton?.mode === 'print' ? ['print.js', 'print-view.js'] : []), 'copy-markdown.js', 'components.js', 'navigation.js', 'reader.js', ...(readerFilters ? ['reader-filters.js'] : []), 'search-highlight.js', 'search.js', 'table-filter.js', 'tabs.js', 'tooltips.js', 'file-tree.js', 'image-viewer.js', 'walkthrough.js'].map(name => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../assets', name));
     const documentRoutes = new Set([...docs.values()].map(doc => doc.route));
     const { apiPublications, focusedContracts, navigationEntries, navigationTagOrder, rendered, snippetUses, apiEmbedUses, operations } = await materializePages({
         variables: isConfigMapping(config.variables) ? config.variables : {}, frontmatterConfig: config.frontmatter,
@@ -379,7 +396,7 @@ export async function compile(configFile, destination, provenance = {}, options
     const resolvedNavigation = renderPublicationPages({
         freshness,
         rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes,
-        basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette,
+        basePath, siteOrigin, colorMode, config: options.authoringFiles ? { ...config, outputs: { ...config.outputs, html: { ...htmlOptions, pdf: false } } } : config, highlighter, editionLabel, customStyleFile, themePreset, palette,
         themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload: fonts.preload,
         shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments,
         externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder
@@ -442,7 +459,14 @@ export async function compile(configFile, destination, provenance = {}, options
             ] };
     }
     const apiPublicationReview = await reviewApiPublication(configFile, apiPlan, rendered, apiEmbedUses, focusedContracts, apiSources, sourceForOperation, options.apiReview);
-    const manifestDependencies = [...new Set([...loaded.dependencies, ...componentPlugins.dependencies, ...externalManifestFiles, ...api.dependencies, ...(metadataProvider ? [metadataProvider.module] : []), ...metadataDependencies, ...(highlighter.dependency ? [highlighter.dependency] : []), ...styleFiles, ...(themeStyleFile ? [themeStyleFile] : []), ...palette.files, ...(search.module ? [search.module] : []), ...previewFiles, ...(customStyleFile ? [customStyleFile] : []), ...(customReaderModule ? [customReaderModule] : []), ...(analyticsModule ? [analyticsModule] : []), ...(mcpAnalyticsModule ? [mcpAnalyticsModule] : []), ...(shareImages.template ? [shareImages.template] : []), ...shareImages.fonts, ...(faviconFile ? [faviconFile] : []), ...heroImages.values(), ...walkthroughSources, ...fontFiles, ...fonts.faces.map(face => face.file), ...scriptFiles, iconLicenseFile, ...[...snippets.values()].map(s => s.file), ...[...docs.values()].map(d => d.file)])].sort();
+    if (pdfButton?.mode === 'endpoint') {
+        const endpoint = publicPath(pdfButton.endpoint);
+        const mcpEndpoint = configField(config.mcp, 'path') ?? '/mcp';
+        if (rendered.some(({ doc }) => doc.route === endpoint || endpoint.startsWith(`${doc.route}/`)) || redirects.some(rule => rule.from === endpoint) || endpoint === publicPath(String(mcpEndpoint)))
+            throw new Error(`PDF endpoint shadows an existing route: ${endpoint}`);
+    }
+    const sitePdfs = options.authoringFiles ? { artifacts: new Map(), dependencies: new Set() } : await buildPdfSiteArtifacts(configFile, { outputs: config.outputs, exports: config.exports, documents: rendered.map(page => page.doc), knownDocumentIds, basePath, profile: options.profile });
+    const manifestDependencies = [...new Set([...sitePdfs.dependencies, ...loaded.dependencies, ...componentPlugins.dependencies, ...externalManifestFiles, ...api.dependencies, ...(metadataProvider ? [metadataProvider.module] : []), ...metadataDependencies, ...(highlighter.dependency ? [highlighter.dependency] : []), ...(highlighter.dependencies ?? []), ...styleFiles, ...(themeStyleFile ? [themeStyleFile] : []), ...palette.files, ...(search.module ? [search.module] : []), ...previewFiles, ...(customStyleFile ? [customStyleFile] : []), ...(customReaderModule ? [customReaderModule] : []), ...(analyticsModule ? [analyticsModule] : []), ...(mcpAnalyticsModule ? [mcpAnalyticsModule] : []), ...(shareImages.template ? [shareImages.template] : []), ...shareImages.fonts, ...(faviconFile ? [faviconFile] : []), ...heroImages.values(), ...walkthroughSources, ...fontFiles, ...fonts.faces.map(face => face.file), ...scriptFiles, iconLicenseFile, ...[...snippets.values()].map(s => s.file), ...[...docs.values()].map(d => d.file)])].sort();
     const llmsDiscovery = resolveLlmsDiscovery(configField(config.outputs, 'llms'));
     const { manifest, headers, sitemaps } = buildPublicationManifest({
         configPublications: config.publications,
@@ -454,6 +478,7 @@ export async function compile(configFile, destination, provenance = {}, options
     });
     const artifactConfig = options.authoringFiles ? { ...config, mcp: false } : config;
     const { artifacts, buildId } = await assembleArtifacts({
+        extraArtifacts: sitePdfs.artifacts,
         base, basePath, publicPath, canonical, siteOrigin, manifest, provenanceRecord, rendered, sitemaps,
         privateDependencies: new Set([...(loaded.deployment?.file ? [loaded.deployment.file] : []), ...(loaded.deployment?.assetFiles ?? [])]),
         diagramAssets, heroImages, focusedContracts, styleFiles, themeStyleFile, generatedPaletteCss,

package/dist/content-export-command.d.ts

@@ -1,5 +1,81 @@
-export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both] [--document ID]...\n       [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]\n       [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]\n\nExport selected pages, sections, and named snippets as Markdown and passive HTML.\nConfigure typed resources in an export target; --document selects whole pages.\nNavigation, facets, and a prior website build are not required.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n--previous-manifest compares public references with an earlier reviewed export.\n--fail-on-removed requires that baseline and refuses to replace output if references disappear.\n";
+export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both|pdf] [--document ID]...\n       [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]\n       [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]\n\nExport selected pages, sections, and named snippets as Markdown and passive HTML.\nConfigure typed resources in an export target; --document selects whole pages.\nNavigation, facets, and a prior website build are not required.\n--format pdf exports one publication, or the selected whole pages, as a styled PDF.\nPDF uses outputs.pdf defaults and target pdf overrides; it follows navigation order\nand appends eligible unlisted pages. PDF defaults to the site's contentFilter.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n--previous-manifest compares public references with an earlier reviewed export.\n--fail-on-removed requires that baseline and refuses to replace output if references disappear.\n";
 export declare function runExportCommand(args: string[]): Promise<{
+    digest: string;
+    preparedPdf: import("./content-export.js").PdfExportPreparation;
+    status: string;
+    output: string;
+    publication: import("./content-source.js").Variant;
+    formats: import("./content-export-config.js").ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
+    digest: string;
+    pdf: string;
+    status: string;
+    output: string;
+    publication: import("./content-source.js").Variant;
+    formats: import("./content-export-config.js").ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
     status: string;
     output: string;
     publication: import("./content-source.js").Variant;

package/dist/content-export-command.js

@@ -1,12 +1,15 @@
 import { exportContent } from './content-export.js';
 export const exportHelp = `Usage: shoalrun export [config] --out DIRECTORY [--target NAME]
-       [--format markdown|html|both] [--document ID]...
+       [--format markdown|html|both|pdf] [--document ID]...
        [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]
        [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]
 
 Export selected pages, sections, and named snippets as Markdown and passive HTML.
 Configure typed resources in an export target; --document selects whole pages.
 Navigation, facets, and a prior website build are not required.
+--format pdf exports one publication, or the selected whole pages, as a styled PDF.
+PDF uses outputs.pdf defaults and target pdf overrides; it follows navigation order
+and appends eligible unlisted pages. PDF defaults to the site's contentFilter.
 --review writes an API-review candidate; status needs-review exits 2 until pinned.
 --previous-manifest compares public references with an earlier reviewed export.
 --fail-on-removed requires that baseline and refuses to replace output if references disappear.
@@ -51,7 +54,7 @@ export async function runExportCommand(args) {
     if (!output)
         throw new Error(exportHelp);
     const format = values.get('--format');
-    if (format && !['html', 'markdown', 'both'].includes(format))
+    if (format && !['html', 'markdown', 'both', 'pdf'].includes(format))
         throw new Error(exportHelp);
     if (format)
         options.formats = format === 'both' ? ['markdown', 'html'] : [format];

package/dist/content-export-config.d.ts

@@ -1,6 +1,8 @@
 import { type ReaderSelection } from './reader-filters.js';
 import type { Variant } from './content.js';
-export type ExportFormat = 'markdown' | 'html';
+import { type PdfConfig } from './pdf-config.js';
+export type ExportFormat = 'markdown' | 'html' | 'pdf';
+export type PortableExportFormat = Exclude<ExportFormat, 'pdf'>;
 export type ExportResourceSelector = {
     kind: 'page';
     documentId: string;
@@ -26,6 +28,7 @@ export type ExportTarget = {
     assetRoots: string[];
     apiReview: Record<string, string>;
     notices: string[];
+    pdf?: PdfConfig;
 };
 export declare function validateExportResources(value: unknown): ExportResourceSelector[];
 export declare function exportPublicBase(value: unknown): string;

package/dist/content-export-config.js

@@ -2,6 +2,7 @@ import { isConfigMapping } from './compiler-config.js';
 import { validateContentFilter } from './content-filter.js';
 import { validateReaderFilters } from './reader-filters.js';
 import { validSectionId } from './section-identity.js';
+import { validatePdfConfig } from './pdf-config.js';
 const nonempty = (value) => typeof value === 'string' && value.trim() === value && value.length > 0;
 const snippetId = (value) => nonempty(value) && /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(value)
     && value.split('.').every(part => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(part) && !['__proto__', 'prototype', 'constructor'].includes(part));
@@ -50,13 +51,17 @@ export function exportPublicBase(value) {
     return value;
 }
 export function validateExportTarget(value, readerFilters) {
-    if (!isConfigMapping(value) || Object.keys(value).some(key => !['formats', 'documents', 'resources', 'publication', 'contentFilter', 'publicBase', 'assetRoots', 'apiReview', 'notices'].includes(key)))
-        throw new Error('Export target accepts formats, documents or resources, publication, contentFilter, publicBase, assetRoots, apiReview, and notices');
+    if (!isConfigMapping(value) || Object.keys(value).some(key => !['formats', 'documents', 'resources', 'publication', 'contentFilter', 'publicBase', 'assetRoots', 'apiReview', 'notices', 'pdf'].includes(key)))
+        throw new Error('Export target accepts formats, documents or resources, publication, contentFilter, publicBase, assetRoots, apiReview, notices, and pdf');
     if (value.documents !== undefined && value.resources !== undefined)
         throw new Error('Export documents and resources are mutually exclusive');
     const formats = value.formats ?? ['markdown', 'html'];
-    if (!Array.isArray(formats) || !formats.length || formats.some(format => !['markdown', 'html'].includes(format)) || new Set(formats).size !== formats.length)
-        throw new Error('Export formats must be a nonempty unique list of markdown and/or html');
+    if (!Array.isArray(formats) || !formats.length || formats.some(format => !['markdown', 'html', 'pdf'].includes(format)) || new Set(formats).size !== formats.length)
+        throw new Error('Export formats must be a nonempty unique list of markdown, html, or pdf');
+    if (formats.includes('pdf') && formats.length !== 1)
+        throw new Error('PDF exports use their own bundle; select pdf alone, or export HTML/Markdown separately');
+    if (formats.includes('pdf') && value.resources !== undefined)
+        throw new Error('PDF exports select whole pages with documents; section and snippet resources are not supported');
     const strings = (raw, field) => {
         if (raw === undefined)
             return undefined;
@@ -76,7 +81,7 @@ export function validateExportTarget(value, readerFilters) {
         throw new Error('Export apiReview must map API IDs to lowercase SHA-256 digests');
     return { formats: [...formats].sort(), ...(value.documents !== undefined ? { documents: strings(value.documents, 'documents') } : {}), ...(value.resources !== undefined ? { resources: validateExportResources(value.resources) } : {}), ...(publication ? { publication } : {}),
         ...(value.contentFilter !== undefined ? { contentFilter: validateContentFilter(value.contentFilter, validateReaderFilters(readerFilters)) } : {}),
-        publicBase: exportPublicBase(value.publicBase ?? '/'), assetRoots: strings(value.assetRoots, 'assetRoots') ?? [], apiReview: (value.apiReview ?? {}), notices: strings(value.notices, 'notices') ?? [] };
+        publicBase: exportPublicBase(value.publicBase ?? '/'), assetRoots: strings(value.assetRoots, 'assetRoots') ?? [], apiReview: (value.apiReview ?? {}), notices: strings(value.notices, 'notices') ?? [], ...(value.pdf !== undefined ? { pdf: validatePdfConfig(value.pdf) } : {}) };
 }
 export function validateExports(value, readerFilters) {
     if (value === undefined)

package/dist/content-export-render.d.ts

@@ -1,7 +1,13 @@
-import type { ExportFormat } from './content-export-config.js';
+import type { PortableExportFormat } from './content-export-config.js';
+import type { CodeHighlighter } from './highlight.js';
 /** Lower interactions while representation-specific source blocks still exist. */
-export declare function portableTree(tree: any, format: ExportFormat, routes: Set<string>, basePath: string): any;
-export declare function passiveHtml(tree: any, prefix: string, checkAnchors?: boolean): {
+export declare function portableTree(tree: any, format: PortableExportFormat, routes: Set<string>, basePath: string, options?: {
+    print?: boolean;
+}): any;
+export declare function passiveHtml(tree: any, prefix: string, checkAnchors?: boolean, options?: {
+    print?: boolean;
+    highlighter?: CodeHighlighter;
+}): {
     html: string;
     anchors: Array<{
         id: string;

package/dist/content-export-render.js

@@ -4,7 +4,7 @@ import { renderHtmlWithHeadings } from './html-renderer.js';
 import { heading, link, paragraph, root, text, renderMarkdown } from './content.js';
 import { walkthroughMarkdown } from './walkthrough.js';
 /** Lower interactions while representation-specific source blocks still exist. */
-export function portableTree(tree, format, routes, basePath) {
+export function portableTree(tree, format, routes, basePath, options = {}) {
     // Provenance is internal export metadata. Keep it when component lowering
     // synthesizes headings so a slice can retain its full-source identities.
     const inherit = (node, key) => {
@@ -37,7 +37,7 @@ export function portableTree(tree, format, routes, basePath) {
             return [heading(3, node.title), ...node.children.flatMap(walk)];
         if (['docTooltip', 'docInfoHint'].includes(node.type))
             return [node.inline ? text(`${node.label} (${node.definition})`) : paragraph(text(`${node.label}: ${node.definition}`))];
-        if (node.type === 'docMath')
+        if (node.type === 'docMath' && !options.print)
             return [node.display ? { type: 'code', lang: 'latex', value: node.expression } : { type: 'inlineCode', value: node.expression }];
         if (node.type === 'docDiagram')
             return [paragraph({ type: 'image', url: node.url, alt: node.title }), paragraph(text(`${node.title}: ${node.summary}`)), ...(format === 'markdown' ? [{ type: 'code', lang: node.engine, value: node.source }] : [])];
@@ -78,7 +78,8 @@ export function portableTree(tree, format, routes, basePath) {
         const data = node.data ? { ...node.data } : undefined;
         if (data) {
             delete data.hChildren;
-            delete data.mathMarkup;
+            if (!options.print)
+                delete data.mathMarkup;
         }
         return { ...node, ...(data ? { data } : {}), ...(node.children ? { children: node.children.filter((child) => child.type !== 'definition').map(clean) } : {}) };
     };
@@ -86,8 +87,10 @@ export function portableTree(tree, format, routes, basePath) {
 }
 const tags = new Set('a abbr article b blockquote br caption code col colgroup dd del details div dl dt em figcaption figure h1 h2 h3 h4 h5 h6 hr i img input kbd li ol p pre progress s section small span strong sub summary sup table tbody td th thead time tr ul'.split(' '));
 const attrs = new Set(['id', 'href', 'src', 'alt', 'title', 'colspan', 'rowspan', 'start', 'reversed', 'value', 'max', 'datetime', 'scope', 'align', 'type', 'checked', 'disabled', 'aria-label', 'aria-labelledby', 'aria-describedby', 'aria-hidden', 'role', 'tabindex', 'data-footnote-ref', 'data-footnote-backref', 'data-export-link']);
-export function passiveHtml(tree, prefix, checkAnchors = true) {
-    const rendered = renderHtmlWithHeadings(tree);
+const mathTags = new Set('math semantics annotation mrow mi mn mo mtext mspace ms mfrac msqrt mroot mstyle merror mpadded mphantom mfenced menclose msub msup msubsup munder mover munderover mmultiscripts mprescripts none mtable mtr mtd mlabeledtr'.split(' '));
+const mathAttrs = new Set('xmlns display mathvariant encoding stretchy fence separator accent accentunder form lspace rspace minsize maxsize symmetric largeop movablelimits scriptlevel displaystyle linethickness notation columnalign columnspacing rowalign rowspacing columnspan rowspan width height depth voffset'.split(' '));
+export function passiveHtml(tree, prefix, checkAnchors = true, options = {}) {
+    const rendered = renderHtmlWithHeadings(tree, options.highlighter);
     const fragment = parseFragment(rendered.html);
     const anchors = [];
     const ids = new Set();
@@ -95,7 +98,7 @@ export function passiveHtml(tree, prefix, checkAnchors = true) {
         if (node.nodeName === '#text')
             return;
         if (node.tagName) {
-            if (!tags.has(node.tagName))
+            if (!tags.has(node.tagName) && !(options.print && mathTags.has(node.tagName)))
                 throw new Error(`Unsupported passive HTML element <${node.tagName}>`);
             const original = node.attrs ?? [];
             for (const attr of original) {
@@ -107,7 +110,8 @@ export function passiveHtml(tree, prefix, checkAnchors = true) {
                         throw new Error(`Unsafe exported URL: ${attr.value}`);
                 }
             }
-            node.attrs = original.filter((attr) => attrs.has(attr.name));
+            node.attrs = original.filter((attr) => attrs.has(attr.name) || options.print && (attr.name === 'class' || mathTags.has(node.tagName) && mathAttrs.has(attr.name)
+                || attr.name === 'style' && /^(?:(?:color|background-color):(?:#[a-f\d]{3,8}|var\(--code-(?:foreground|token-[a-z-]+)\));?)+$/i.test(attr.value)));
             const id = node.attrs.find((attr) => attr.name === 'id');
             if (id) {
                 if (ids.has(id.value))

package/dist/content-export.d.ts

@@ -1,5 +1,7 @@
 import { type ExportFormat } from './content-export-config.js';
 import { type Variant } from './content.js';
+import { type PdfRenderInput } from './pdf-renderer.js';
+import type { ContentLink } from './content-delivery-contract.js';
 export type ContentExportOptions = {
     profile?: string;
     target?: string;
@@ -10,9 +12,132 @@ export type ContentExportOptions = {
     review?: boolean;
     previousManifest?: string;
     failOnRemoved?: boolean;
+    preparePdfOnly?: boolean;
+    pdfLinks?: 'internal' | 'canonical';
+    pdfStyleTarget?: string;
+};
+export type PdfExportPreparation = {
+    input: PdfRenderInput;
+    manifest: {
+        schemaVersion: number;
+        kind: string;
+        publication: Variant;
+        title: string;
+        documents: Array<{
+            id: string;
+            title: string;
+            contentDigest: string;
+            anchors: Representation['anchors'];
+            links: ExportLink[];
+        }>;
+        review: {
+            status: string;
+            apis: Array<{
+                apiId: string;
+                digest: string;
+            }>;
+        };
+        diagnostics: Array<{
+            code: string;
+            documentId?: string;
+            message: string;
+        }>;
+    };
+    inputs: string[];
+};
+/** Prepare passive, scoped print inputs without launching a browser or writing output. */
+export declare function preparePdfExport(configFile: string, options?: Omit<ContentExportOptions, 'formats' | 'preparePdfOnly'>): Promise<PdfExportPreparation>;
+type ExportLink = ContentLink;
+type Representation = {
+    path: string;
+    mediaType: string;
+    bytes: number;
+    digest: string;
+    anchors: Array<{
+        id: string;
+        exportedId: string;
+        title?: string;
+    }>;
+    links: ExportLink[];
 };
 /** Export selected source content; never invoke the website shell/compiler. */
 export declare function exportContent(configFile: string, destination: string, options?: ContentExportOptions): Promise<{
+    digest: string;
+    preparedPdf: PdfExportPreparation;
+    status: string;
+    output: string;
+    publication: Variant;
+    formats: ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
+    digest: string;
+    pdf: string;
+    status: string;
+    output: string;
+    publication: Variant;
+    formats: ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
     status: string;
     output: string;
     publication: Variant;
@@ -45,3 +170,4 @@ export declare function exportContent(configFile: string, destination: string, o
         message: string;
     }[];
 }>;
+export {};