@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/dist/pdf-http.js

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pdfDataPath, pdfRuntimePath } from './pdf-button.js';
+import { renderPreparedPdf } from './pdf-renderer.js';
+import { validatePdfConfig } from './pdf-config.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const hex = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const maxPreparedBytes = 64 * 1024 * 1024;
+const safePath = (file) => !!file && !file.startsWith('/') && !/[\\\0:]/.test(file) && !file.split('/').some(part => !part || part === '.' || part === '..');
+const within = (root, file) => file.startsWith(root + path.sep);
+async function boundedRead(file, max) {
+    const info = await stat(file);
+    if (!info.isFile() || info.size > max)
+        throw new Error('Invalid or oversized PDF runtime resource');
+    const bytes = await readFile(file);
+    if (bytes.length > max)
+        throw new Error('Oversized PDF runtime resource');
+    return bytes;
+}
+export async function loadPdfRuntime(directory) {
+    const siteRoot = await realpath(directory);
+    const metadata = path.join(siteRoot, pdfRuntimePath.slice(1));
+    let file;
+    try {
+        file = await realpath(metadata);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!within(siteRoot, file))
+        throw new Error('PDF runtime escapes the built site');
+    const runtime = JSON.parse((await boundedRead(file, 4 * 1024 * 1024)).toString('utf8'));
+    if (!record(runtime) || runtime.schemaVersion !== 1 || typeof runtime.endpoint !== 'string' || !/^\/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(runtime.endpoint) || !record(runtime.pages) || !record(runtime.inventory))
+        throw new Error('Invalid PDF runtime metadata; rebuild the site');
+    runtime.config = validatePdfConfig(runtime.config);
+    const root = await realpath(path.join(siteRoot, pdfDataPath.slice(1)));
+    if (!within(siteRoot, root))
+        throw new Error('PDF runtime data escapes the built site');
+    for (const [key, page] of Object.entries(runtime.pages)) {
+        if (!hex(key) || !record(page) || typeof page.documentId !== 'string' || !page.documentId || typeof page.title !== 'string' || typeof page.file !== 'string' || !safePath(page.file) || !hex(page.digest) || runtime.inventory[page.file] !== page.digest || !record(page.publication) || ['channel', 'version', 'language'].some(name => typeof page.publication[name] !== 'string') || page.publication.product !== undefined && typeof page.publication.product !== 'string')
+            throw new Error('Invalid PDF page inventory');
+    }
+    for (const [name, hash] of Object.entries(runtime.inventory)) {
+        if (!safePath(name) || !hex(hash))
+            throw new Error('Invalid PDF inventory path');
+        const resource = await realpath(path.join(root, name));
+        if (!within(root, resource) || digest(await boundedRead(resource, maxPreparedBytes)) !== hash)
+            throw new Error('PDF resource integrity mismatch');
+    }
+    return { runtime, directory: root };
+}
+const failure = (status, message) => new Response(JSON.stringify({ error: message }), { status, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', ...(status === 429 ? { 'Retry-After': '60' } : {}) } });
+/** Mount behind the same authentication as the built site. This handler does not grant access to other profiles. */
+export function createPdfHttpHandler(input, options = {}) {
+    let active = false;
+    let windowStart = 0;
+    let attempts = 0;
+    const now = options.now ?? Date.now;
+    const render = options.render ?? renderPreparedPdf;
+    return async (request) => {
+        const url = new URL(request.url);
+        if (url.pathname !== input.runtime.endpoint)
+            return failure(404, 'Unknown PDF endpoint');
+        if (request.method !== 'GET' && request.method !== 'HEAD')
+            return new Response(null, { status: 405, headers: { Allow: 'GET, HEAD', 'Cache-Control': 'no-store' } });
+        if (request.headers.get('sec-fetch-site') === 'cross-site' || request.headers.has('origin') && request.headers.get('origin') !== url.origin)
+            return failure(403, 'PDF origin is not allowed');
+        try {
+            if (options.authorize && !await options.authorize(request))
+                return failure(403, 'PDF access is not allowed');
+        }
+        catch {
+            return failure(503, 'PDF authorization is unavailable');
+        }
+        const keys = [...url.searchParams.keys()];
+        const key = url.searchParams.get('key');
+        if (keys.length !== 1 || keys[0] !== 'key' || !hex(key) || !Object.hasOwn(input.runtime.pages, key))
+            return failure(404, 'Unknown PDF page');
+        const page = input.runtime.pages[key];
+        if (request.method === 'HEAD')
+            return new Response(null, { headers: { 'Content-Type': 'application/pdf', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' } });
+        const time = now();
+        if (time - windowStart >= 60_000) {
+            windowStart = time;
+            attempts = 0;
+        }
+        if (active || attempts >= 10)
+            return failure(429, 'PDF generation is busy. Try again shortly.');
+        attempts++;
+        active = true;
+        try {
+            const file = await realpath(path.join(input.directory, page.file));
+            if (!within(input.directory, file))
+                throw new Error('Invalid PDF resource');
+            const bytes = await boundedRead(file, maxPreparedBytes);
+            if (digest(bytes) !== page.digest)
+                throw new Error('PDF resource integrity mismatch');
+            const prepared = hydratePreparedPdf(JSON.parse(bytes.toString('utf8')));
+            const result = await render(prepared, input.runtime.config);
+            const filename = page.documentId.replace(/[^A-Za-z0-9_.-]/g, '-').slice(0, 100) || 'page';
+            return new Response(new Uint8Array(result.bytes), { headers: { 'Content-Type': 'application/pdf', 'Content-Disposition': `attachment; filename="${filename}.pdf"`, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' } });
+        }
+        catch {
+            return failure(503, 'PDF generation failed. Check the server browser setup and rebuild the PDF inputs if needed.');
+        }
+        finally {
+            active = false;
+        }
+    };
+}
+export function hydratePreparedPdf(value) {
+    if (!record(value) || typeof value.html !== 'string' || Buffer.byteLength(value.html) > maxPreparedBytes || !hex(value.styleDigest) || !Array.isArray(value.assets) || value.assets.length > 10000)
+        throw new Error('Invalid prepared PDF');
+    const assets = new Map();
+    let total = Buffer.byteLength(value.html);
+    for (const asset of value.assets) {
+        if (!record(asset) || typeof asset.path !== 'string' || !asset.path.startsWith('/') || !safePath(asset.path.slice(1)) || assets.has(asset.path) || !['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/avif', 'image/svg+xml', 'font/woff', 'font/woff2', 'font/ttf', 'font/otf'].includes(asset.mediaType) || typeof asset.base64 !== 'string' || /[^A-Za-z0-9+/=]/.test(asset.base64))
+            throw new Error('Invalid prepared PDF asset');
+        const bytes = Buffer.from(asset.base64, 'base64');
+        if (bytes.toString('base64') !== asset.base64)
+            throw new Error('Invalid prepared PDF asset encoding');
+        total += bytes.length;
+        if (bytes.length > 32 * 1024 * 1024 || total > maxPreparedBytes)
+            throw new Error('Prepared PDF assets exceed 64 MiB');
+        assets.set(asset.path, { bytes, mediaType: asset.mediaType });
+    }
+    return { html: value.html, assets, styleDigest: value.styleDigest };
+}

package/dist/pdf-project.d.ts

@@ -0,0 +1,6 @@
+import { type loadConfig } from './config.js';
+/** Resolve print assets from the configuration that declares each setting. */
+export declare function projectPdfSettings(loaded: Awaited<ReturnType<typeof loadConfig>>, configFile: string, targetName?: string): {
+    config: import("./pdf-config.js").PdfConfig;
+    files: string[];
+};

package/dist/pdf-project.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { explainSegments } from './config.js';
+import { configField, isConfigMapping, resolvedCompilerConfig } from './compiler-config.js';
+import { mergePdfConfig } from './pdf-config.js';
+/** Resolve print assets from the configuration that declares each setting. */
+export function projectPdfSettings(loaded, configFile, targetName) {
+    const resolved = resolvedCompilerConfig(loaded.value);
+    const target = targetName && isConfigMapping(resolved.exports) ? resolved.exports[targetName] : undefined;
+    const override = isConfigMapping(target) ? target.pdf : undefined;
+    const config = mergePdfConfig(configField(resolved.outputs, 'pdf'), override);
+    const files = [];
+    const owner = (field, index) => explainSegments(loaded, [
+        ...(targetName && isConfigMapping(override) && Object.hasOwn(override, field) ? ['exports', targetName, 'pdf'] : ['outputs', 'pdf']),
+        field, ...(index === undefined ? [] : [String(index), 'source'])
+    ]).source.file;
+    for (const field of ['stylesheet', 'logo'])
+        if (config[field]) {
+            config[field] = path.resolve(path.dirname(owner(field)), config[field]);
+            files.push(config[field]);
+        }
+    if (config.fonts)
+        config.fonts = config.fonts.map((font, index) => {
+            const source = path.resolve(path.dirname(owner('fonts', index)), font.source);
+            files.push(source);
+            return { ...font, source };
+        });
+    // The browser executable is a host tool, never an asset to publish or capture.
+    if (config.executablePath)
+        config.executablePath = path.resolve(path.dirname(owner('executablePath')), config.executablePath);
+    return { config, files };
+}

package/dist/pdf-renderer.d.ts

@@ -0,0 +1,45 @@
+import { type PdfConfig } from './pdf-config.js';
+export type PdfDocumentInput = {
+    documents: Array<{
+        id: string;
+        title: string;
+        html: string;
+    }>;
+    title: string;
+    publication?: Record<string, unknown>;
+    assets: Map<string, string | Buffer>;
+    publicBase: string;
+    config: PdfConfig;
+    configFile: string;
+    assetRoots?: string[];
+};
+export type PdfRenderInput = PdfDocumentInput;
+export type PreparedPdf = {
+    html: string;
+    assets: Map<string, {
+        bytes: Buffer;
+        mediaType: string;
+    }>;
+    styleDigest: string;
+};
+export type PdfResult = {
+    bytes: Buffer;
+    metadata: {
+        engine: string;
+        browserVersion: string;
+        styleDigest: string;
+        assets: Array<{
+            path: string;
+            digest: string;
+        }>;
+    };
+};
+export declare function preparePdfDocument(input: PdfDocumentInput): Promise<PreparedPdf>;
+/** Resolve only synthetic print resources; never continue a browser request. */
+export declare function pdfRequestResponse(prepared: PreparedPdf, address: string, type: string, navigation: boolean, method?: string): {
+    status: number;
+    contentType?: string;
+    body?: string | Buffer;
+} | undefined;
+export declare function renderPreparedPdf(prepared: PreparedPdf, settings: PdfConfig): Promise<PdfResult>;
+export declare function renderPdf(input: PdfDocumentInput): Promise<PdfResult>;

package/dist/pdf-renderer.js

@@ -0,0 +1,208 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import puppeteer from 'puppeteer-core';
+import { parseFragment } from 'parse5';
+import { validatePdfConfig } from './pdf-config.js';
+import { validateExportSvg } from './content-export-assets.js';
+import { validatePrintStylesheet } from './pdf-stylesheet.js';
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const escape = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+const cssText = (value) => JSON.stringify(value).replace(/</g, '\\3c ');
+const origin = 'https://pdf.shoalrun.invalid';
+const media = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.avif': 'image/avif', '.svg': 'image/svg+xml', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf' };
+const baseCss = `:root{--pdf-accent:#225449;--pdf-text:#172722;--pdf-muted:#53665e;--pdf-font:Arial,sans-serif;--pdf-code-font:monospace;--code-foreground:#172722;--code-token-comment:#53665e;--code-token-punctuation:#172722;--code-token-keyword:#7144a0;--code-token-string:#225449;--code-token-string-expression:#225449;--code-token-constant:#855b12;--code-token-function:#145880;--code-token-parameter:#644479;--code-token-link:#225449}*{box-sizing:border-box}body{margin:0;color:var(--pdf-text);font:11pt/1.5 var(--pdf-font)}h1,h2,h3,h4,h5,h6{color:var(--pdf-accent);line-height:1.2;break-after:avoid}h1{font-size:28pt}h2{font-size:20pt}h3{font-size:15pt}a{color:var(--pdf-accent);text-decoration:underline;overflow-wrap:anywhere}p,li{orphans:3;widows:3}img,svg{max-width:100%;height:auto}figure{margin:1em 0}pre{white-space:pre-wrap;overflow-wrap:anywhere;font:9pt/1.5 var(--pdf-code-font);background:#f1f4f2;padding:12pt;border:1px solid #d5dfd9}code{font-family:var(--pdf-code-font)}table{border-collapse:collapse;width:100%;font-size:9pt;table-layout:fixed;overflow-wrap:anywhere}th,td{border:1px solid #c7d2cb;padding:6pt;text-align:left;vertical-align:top}thead{display:table-header-group}tr{break-inside:avoid}blockquote{border-left:3pt solid var(--pdf-accent);margin:1em 0;padding-left:12pt}summary{font-weight:bold}details{display:block}.pdf-cover{break-after:page;padding-top:24%;min-height:60vh}.pdf-cover h1{font-size:38pt}.pdf-logo{display:block;max-width:180pt;max-height:80pt;object-fit:contain;margin-bottom:28pt}.pdf-subtitle{font-size:16pt;color:var(--pdf-muted)}.pdf-publication{color:var(--pdf-muted)}.pdf-toc{break-after:page}.pdf-toc li{margin:5pt 0}.pdf-chapter+.pdf-chapter{break-before:page}hr{border:0;border-top:1px solid #c7d2cb;margin:18pt 0}@media print{*{-webkit-print-color-adjust:exact;print-color-adjust:exact}}`;
+async function readLocal(file, roots, max) {
+    const resolved = await realpath(file);
+    if (!roots.some(root => resolved === root || resolved.startsWith(root + path.sep)))
+        throw new Error(`PDF file escapes asset roots: ${file}`);
+    if (resolved.split(path.sep).some(part => /^\.env(?:\.|$)|^\.git$|^(?:PROJECT|DEPLOYMENT)\.local\.md$|^AGENTS\.override\.md$/i.test(part)))
+        throw new Error('Private local files cannot be PDF assets');
+    const info = await stat(resolved);
+    if (!info.isFile() || info.size > max)
+        throw new Error(`PDF file must be regular and at most ${max} bytes: ${file}`);
+    return readFile(resolved);
+}
+export async function preparePdfDocument(input) {
+    const config = validatePdfConfig(input.config);
+    if (!input.documents.length || input.documents.length > 10000)
+        throw new Error('PDF export needs 1–10000 documents');
+    const base = path.dirname(path.resolve(input.configFile));
+    const roots = await Promise.all([base, ...(input.assetRoots ?? []).map(root => path.resolve(base, root))].map(root => realpath(root)));
+    const assets = new Map();
+    // A page preparation can share the publication's asset registry. Carry only
+    // resources referenced by the selected print content into its private payload.
+    const referencedImages = new Set();
+    const collectImages = (node) => {
+        if (node.tagName === 'img') {
+            const source = node.attrs?.find((attr) => attr.name === 'src')?.value;
+            if (source) {
+                const url = new URL(source, origin);
+                if (url.origin === origin)
+                    referencedImages.add(url.pathname);
+            }
+        }
+        for (const child of node.childNodes ?? [])
+            collectImages(child);
+    };
+    for (const doc of input.documents)
+        collectImages(parseFragment(doc.html));
+    for (const [file, content] of input.assets) {
+        const type = media[path.extname(file).toLowerCase()];
+        if (!type)
+            continue;
+        const url = new URL(`${input.publicBase}${file}`, origin);
+        if (url.origin !== origin)
+            throw new Error('PDF publicBase must be a local URL path');
+        if (!referencedImages.has(url.pathname))
+            continue;
+        const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content);
+        if (bytes.length > 32 * 1024 * 1024)
+            throw new Error(`PDF asset too large: ${file}`);
+        if (type === 'image/svg+xml')
+            validateExportSvg(bytes.toString('utf8'));
+        assets.set(url.pathname, { bytes, mediaType: type });
+    }
+    let css = baseCss;
+    for (const font of config.fonts ?? []) {
+        const extension = path.extname(font.source).toLowerCase();
+        if (!['.woff', '.woff2', '.ttf', '.otf'].includes(extension))
+            throw new Error('PDF fonts must use woff, woff2, ttf, or otf files');
+        const bytes = await readLocal(path.resolve(base, font.source), roots, 16 * 1024 * 1024);
+        const url = `/__pdf_fonts/${digest(bytes)}${extension}`;
+        assets.set(url, { bytes, mediaType: media[extension] });
+        css += `\n@font-face{font-family:${cssText(font.family)};src:url("${url}");font-weight:${font.weight ?? 'normal'};font-style:${font.style ?? 'normal'};font-display:block}`;
+    }
+    if (config.stylesheet) {
+        const custom = (await readLocal(path.resolve(base, config.stylesheet), roots, 1024 * 1024)).toString('utf8');
+        // CSS is local styling, not a resource loader. Fonts have explicit registrations.
+        validatePrintStylesheet(custom);
+        css += '\n' + custom;
+    }
+    let logo = '';
+    if (config.logo) {
+        const extension = path.extname(config.logo).toLowerCase();
+        const type = media[extension];
+        if (!type?.startsWith('image/'))
+            throw new Error('PDF logo must be a local image');
+        const bytes = await readLocal(path.resolve(base, config.logo), roots, 32 * 1024 * 1024);
+        if (type === 'image/svg+xml')
+            validateExportSvg(bytes.toString('utf8'));
+        const url = `/__pdf_logo/${digest(bytes)}${extension}`;
+        assets.set(url, { bytes, mediaType: type });
+        logo = `<img class="pdf-logo" src="${url}" alt="">`;
+    }
+    const title = escape(input.title);
+    const publication = input.publication ? escape(Object.entries(input.publication).filter(([, value]) => value !== undefined).map(([key, value]) => `${key}: ${String(value)}`).join(' · ')) : '';
+    const cover = config.cover ? `<section class="pdf-cover">${logo}<h1>${title}</h1>${config.subtitle ? `<p class="pdf-subtitle">${escape(config.subtitle)}</p>` : ''}${publication ? `<p class="pdf-publication">${publication}</p>` : ''}</section>` : '';
+    const toc = config.toc ? `<nav class="pdf-toc" aria-label="Contents"><h1>Contents</h1><ol>${input.documents.map((doc, index) => `<li><a href="#pdf-document-${index + 1}">${escape(doc.title)}</a></li>`).join('')}</ol></nav>` : '';
+    // Validate resource references before CSP can silently suppress a missing image.
+    for (const doc of input.documents) {
+        const check = (node) => {
+            if (['script', 'iframe', 'object', 'embed', 'link', 'base', 'form', 'style', 'meta', 'audio', 'video'].includes(node.tagName))
+                throw new Error('PDF input must be passive HTML');
+            for (const attr of node.attrs ?? []) {
+                if (/^on/i.test(attr.name))
+                    throw new Error('PDF input must not contain event handlers');
+                if (attr.name === 'src' || attr.name === 'srcset') {
+                    if (attr.name === 'srcset')
+                        throw new Error('PDF images must use one explicit local src');
+                    const url = new URL(attr.value, origin);
+                    if (url.origin !== origin || !assets.has(url.pathname) || url.search || url.hash)
+                        throw new Error(`PDF requires a registered offline asset: ${attr.value}`);
+                }
+            }
+            for (const child of node.childNodes ?? [])
+                check(child);
+        };
+        check(parseFragment(doc.html));
+    }
+    if ([...assets.values()].reduce((total, asset) => total + asset.bytes.length, 0) > 64 * 1024 * 1024)
+        throw new Error('PDF assets exceed 64 MiB');
+    const body = input.documents.map((doc, index) => `<article class="pdf-chapter" id="pdf-document-${index + 1}" data-document-id="${escape(doc.id)}">${doc.html}</article>`).join('\n');
+    const html = `<!doctype html><html lang="${escape(String(input.publication?.language ?? 'en'))}"><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src 'self'; font-src 'self'; style-src 'unsafe-inline'; script-src 'none'; base-uri 'none'"><link rel="icon" href="/favicon.ico"><title>${title}</title><style>${css}</style></head><body>${cover}${toc}${body}</body></html>`;
+    if (Buffer.byteLength(html) > 64 * 1024 * 1024)
+        throw new Error('PDF print document exceeds 64 MiB');
+    return { html, assets, styleDigest: digest(css) };
+}
+function template(value) {
+    if (!value)
+        return '<span></span>';
+    return `<div style="width:100%;font:9px Arial,sans-serif;color:#555;padding:0 36px;text-align:center">${escape(value).replace(/\{title\}/g, '<span class="title"></span>').replace(/\{page\}/g, '<span class="pageNumber"></span>').replace(/\{pages\}/g, '<span class="totalPages"></span>')}</div>`;
+}
+/** Resolve only synthetic print resources; never continue a browser request. */
+export function pdfRequestResponse(prepared, address, type, navigation, method = 'GET') {
+    const url = new URL(address);
+    if (method !== 'GET' || url.origin !== origin || url.username || url.password || url.search || url.hash)
+        return undefined;
+    if (url.pathname === '/__print' && navigation && type === 'document')
+        return { status: 200, contentType: 'text/html', body: prepared.html };
+    // Chromium may request its favicon automatically after navigation. Fulfill only
+    // this exact synthetic route without granting access to any external resource.
+    if (url.pathname === '/favicon.ico' && !navigation && ['image', 'other'].includes(type))
+        return { status: 204, body: '' };
+    const resource = !navigation ? prepared.assets.get(url.pathname) : undefined;
+    if (resource && (type === 'image' && resource.mediaType.startsWith('image/') || type === 'font' && resource.mediaType.startsWith('font/')))
+        return { status: 200, contentType: resource.mediaType, body: resource.bytes };
+    return undefined;
+}
+export async function renderPreparedPdf(prepared, settings) {
+    const config = validatePdfConfig(settings);
+    const executablePath = config.executablePath ?? process.env.SHOALRUN_PDF_BROWSER ?? process.env.PUPPETEER_EXECUTABLE_PATH;
+    if (!executablePath)
+        throw new Error('PDF export needs Chrome/Chromium. Set SHOALRUN_PDF_BROWSER or pdf.executablePath to its executable; no browser is downloaded automatically.');
+    const timeout = config.timeout ?? 30000;
+    const browser = await puppeteer.launch({ executablePath, headless: true, timeout, protocolTimeout: timeout });
+    let timedOut = false;
+    const deadline = setTimeout(() => { timedOut = true; void browser.close().catch(() => { }); }, timeout);
+    deadline.unref();
+    try {
+        const page = await browser.newPage();
+        await page.setJavaScriptEnabled(false);
+        await page.setBypassServiceWorker(true);
+        await page.setRequestInterception(true);
+        const rejected = new Set();
+        page.on('request', request => {
+            const response = pdfRequestResponse(prepared, request.url(), request.resourceType(), request.isNavigationRequest(), request.method());
+            if (response)
+                void request.respond(response).catch(() => { });
+            else {
+                rejected.add(request.url());
+                void request.abort('blockedbyclient').catch(() => { });
+            }
+        });
+        await page.goto(`${origin}/__print`, { waitUntil: 'networkidle0', timeout });
+        if (rejected.size)
+            throw new Error(`PDF requires offline assets; blocked resource: ${[...rejected][0]}`);
+        const missingImages = await page.evaluate(() => [...document.images].some(image => !image.complete || !image.naturalWidth));
+        if (missingImages)
+            throw new Error('PDF image could not be decoded');
+        const fontsReady = await page.evaluate(async () => {
+            try {
+                const faces = [];
+                document.fonts.forEach(face => faces.push(face));
+                await Promise.all(faces.map(face => face.load()));
+                return faces.every(face => face.status === 'loaded');
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!fontsReady)
+            throw new Error('PDF font could not be decoded or loaded');
+        const bytes = await page.pdf({ format: config.size ?? 'A4', margin: { top: '18mm', right: '18mm', bottom: '18mm', left: '18mm', ...config.margins }, printBackground: true, preferCSSPageSize: true, displayHeaderFooter: !!(config.header || config.footer), headerTemplate: template(config.header), footerTemplate: template(config.footer), outline: config.bookmarks ?? true, tagged: true, waitForFonts: true, timeout });
+        if (rejected.size)
+            throw new Error(`PDF requires offline assets; blocked resource: ${[...rejected][0]}`);
+        return { bytes: Buffer.from(bytes), metadata: { engine: 'chromium', browserVersion: await browser.version(), styleDigest: prepared.styleDigest, assets: [...prepared.assets].map(([file, asset]) => ({ path: file, digest: digest(asset.bytes) })) } };
+    }
+    catch (error) {
+        if (timedOut)
+            throw new Error(`PDF rendering exceeded ${timeout} milliseconds`);
+        throw error;
+    }
+    finally {
+        clearTimeout(deadline);
+        await browser.close();
+    }
+}
+export async function renderPdf(input) { return renderPreparedPdf(await preparePdfDocument(input), input.config); }

package/dist/pdf-site.d.ts

@@ -0,0 +1,37 @@
+import type { Document, Variant } from './content-source.js';
+import { type PreparedPdf } from './pdf-renderer.js';
+import { type PdfConfig } from './pdf-config.js';
+export type SerializedPreparedPdf = {
+    html: string;
+    assets: Array<{
+        path: string;
+        mediaType: string;
+        base64: string;
+    }>;
+    styleDigest: string;
+};
+export type PdfSiteRuntime = {
+    schemaVersion: 1;
+    endpoint: string;
+    config: PdfConfig;
+    pages: Record<string, {
+        documentId: string;
+        publication: Variant;
+        title: string;
+        file: string;
+        digest: string;
+    }>;
+    inventory: Record<string, string>;
+};
+export declare const serializePreparedPdf: (prepared: PreparedPdf) => SerializedPreparedPdf;
+export declare function buildPdfSiteArtifacts(configFile: string, options: {
+    outputs: unknown;
+    exports?: unknown;
+    documents: Document[];
+    knownDocumentIds?: ReadonlySet<string>;
+    basePath: string;
+    profile?: string;
+}): Promise<{
+    artifacts: Map<string, string | Buffer<ArrayBufferLike>>;
+    dependencies: Set<string>;
+}>;

package/dist/pdf-site.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { publicationKey } from './publication-identity.js';
+import { preparePdfExport } from './content-export.js';
+import { preparePdfDocument } from './pdf-renderer.js';
+import { pdfButtonIncludes, pdfDataPath, pdfPageKey, pdfRuntimePath, resolvePdfButton, validatePdfButtonStyle } from './pdf-button.js';
+import { sitePath } from './site-path.js';
+import { browserPrintAssets } from './browser-print-assets.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export const serializePreparedPdf = (prepared) => ({ html: prepared.html, styleDigest: prepared.styleDigest, assets: [...prepared.assets].map(([path, asset]) => ({ path, mediaType: asset.mediaType, base64: asset.bytes.toString('base64') })) });
+export async function buildPdfSiteArtifacts(configFile, options) {
+    const artifacts = new Map();
+    const dependencies = new Set();
+    const button = resolvePdfButton(options.outputs);
+    if (!button)
+        return { artifacts, dependencies };
+    validatePdfButtonStyle(button, options.exports);
+    const knownIds = options.knownDocumentIds ?? new Set(options.documents.map(doc => doc.frontmatter.id));
+    for (const id of [...button.include ?? [], ...button.exclude ?? []])
+        if (!knownIds.has(id))
+            throw new Error(`PDF button selects unknown document ${id}`);
+    if (button.mode === 'print') {
+        if (!options.documents.some(doc => pdfButtonIncludes(doc, button)))
+            return { artifacts, dependencies };
+        return browserPrintAssets(configFile, { basePath: options.basePath, profile: options.profile, style: button.style });
+    }
+    const selected = options.documents.filter(doc => pdfButtonIncludes(doc, button));
+    if (!selected.length)
+        return { artifacts, dependencies };
+    const groups = new Map();
+    for (const doc of selected) {
+        const key = publicationKey(doc.variant);
+        groups.set(key, [...groups.get(key) ?? [], doc]);
+    }
+    const runtime = { schemaVersion: 1, endpoint: sitePath(options.basePath, button.endpoint), config: {}, pages: {}, inventory: {} };
+    for (const docs of groups.values()) {
+        const exported = await preparePdfExport(configFile, { profile: options.profile, documents: docs.map(doc => doc.frontmatter.id), publication: docs[0].variant, pdfLinks: 'canonical', pdfStyleTarget: button.style });
+        for (const file of exported.inputs)
+            dependencies.add(file);
+        const { stylesheet, fonts, logo, ...renderConfig } = exported.input.config;
+        runtime.config = renderConfig;
+        for (const doc of docs) {
+            const document = exported.input.documents.find(item => item.id === doc.frontmatter.id);
+            if (!document)
+                throw new Error(`PDF preparation omitted selected document ${doc.frontmatter.id}`);
+            const input = { ...exported.input, documents: [document], title: doc.frontmatter.title, config: { ...exported.input.config, cover: false, toc: false } };
+            const prepared = await preparePdfDocument(input);
+            const key = pdfPageKey(doc.frontmatter.id, doc.variant);
+            const file = `${key}.json`;
+            const bytes = JSON.stringify(serializePreparedPdf(prepared));
+            if (Buffer.byteLength(bytes) > 64 * 1024 * 1024)
+                throw new Error(`Prepared page PDF exceeds 64 MiB: ${doc.frontmatter.id}`);
+            const hash = digest(bytes);
+            artifacts.set(`${pdfDataPath}/${file}`, bytes);
+            runtime.inventory[file] = hash;
+            runtime.pages[key] = { documentId: doc.frontmatter.id, publication: doc.variant, title: doc.frontmatter.title, file, digest: hash };
+        }
+    }
+    if (button.mode === 'endpoint') {
+        const metadata = JSON.stringify(runtime);
+        if (Buffer.byteLength(metadata) > 4 * 1024 * 1024)
+            throw new Error('PDF runtime metadata exceeds 4 MiB');
+        artifacts.set(pdfRuntimePath, metadata);
+    }
+    return { artifacts, dependencies };
+}

package/dist/pdf-stylesheet.d.ts

@@ -0,0 +1 @@
+export declare function validatePrintStylesheet(css: string): void;

package/dist/pdf-stylesheet.js

@@ -0,0 +1,57 @@
+// Print CSS may control layout, but resource loading uses explicit asset registrations.
+// Allow known non-loading functions rather than trying to enumerate every CSS loader.
+const functions = new Set(`
+  var env calc min max clamp round mod rem abs sign hypot sqrt pow exp log
+  sin cos tan asin acos atan atan2
+  rgb rgba hsl hsla hwb lab lch oklab oklch color color-mix light-dark contrast-color
+  linear-gradient repeating-linear-gradient radial-gradient repeating-radial-gradient
+  conic-gradient repeating-conic-gradient
+  counter counters attr symbols
+  translate translatex translatey translatez translate3d scale scalex scaley scalez scale3d
+  rotate rotatex rotatey rotatez rotate3d skew skewx skewy matrix matrix3d perspective
+  blur brightness contrast drop-shadow grayscale hue-rotate invert opacity saturate sepia
+  cubic-bezier steps linear
+  repeat minmax fit-content anchor anchor-size
+  circle ellipse inset polygon path rect xywh
+  is where not has nth-child nth-last-child nth-of-type nth-last-of-type lang dir
+  selector supports style scroll-state
+`.trim().split(/\s+/));
+export function validatePrintStylesheet(css) {
+    const fail = () => { throw new Error('PDF stylesheet must not import files, use CSS escapes, or load URLs; use supported layout/color functions and register local fonts with pdf.fonts'); };
+    if (/@import\b|<\/style|\\/i.test(css))
+        fail();
+    // Lex comments and quoted text separately so content strings aren't interpreted
+    // as functions. CSS escapes are already disallowed, including in identifiers.
+    for (let index = 0; index < css.length;) {
+        if (css.startsWith('/*', index)) {
+            const end = css.indexOf('*/', index + 2);
+            if (end === -1)
+                fail();
+            index = end + 2;
+        }
+        else if (css[index] === '"' || css[index] === "'") {
+            const quote = css[index++];
+            while (index < css.length && css[index] !== quote) {
+                if (/[\r\n\f]/.test(css[index]))
+                    fail();
+                index++;
+            }
+            if (index === css.length)
+                fail();
+            index++;
+        }
+        else if (/[a-z_-]/i.test(css[index])) {
+            const start = index++;
+            while (index < css.length && /[a-z0-9_-]/i.test(css[index]))
+                index++;
+            const name = css.slice(start, index).toLowerCase();
+            let next = index;
+            while (next < css.length && /\s/.test(css[next]))
+                next++;
+            if (css[next] === '(' && !functions.has(name))
+                fail();
+        }
+        else
+            index++;
+    }
+}

package/dist/publication-render.d.ts

@@ -8,7 +8,7 @@ import type { ReaderFiltersConfig } from './reader-filters.js';
 import type { CodeHighlighter } from './highlight.js';
 import type { MaterializedPage } from './page-materialization.js';
 import type { ResolvedCompilerConfig, CompilerSiteConfig, CompilerPublicationsConfig } from './compiler-config.js';
-export declare function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }: {
+export declare function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, customFontPreloads, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }: {
     freshness?: Freshness;
     rendered: MaterializedPage[];
     docs: Map<string, Document>;
@@ -41,6 +41,7 @@ export declare function renderPublicationPages({ rendered, docs, relationships,
     themeSwitcherData?: string;
     generatedFontsCss?: string;
     fontsPreload?: string;
+    customFontPreloads?: import('./fonts.js').FontPreload[];
     shareFor: (doc: Document) => {
         route: string;
         generated: boolean;

package/dist/publication-render.js

@@ -12,7 +12,7 @@ import { navigationPath, navigationTab, navigationTabRecord, resolveProjectNavig
 import { outputUrl, publicTree, resolveOutputLinks } from './representation-tree.js';
 import { presetCatalog } from './palettes.js';
 const keyFor = documentKey;
-export function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
+export function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, customFontPreloads, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
     const resolvedNavigation = new Map();
     const selector = config.site.publicationSelector;
     if (selector !== undefined && (!isConfigMapping(selector) || Object.keys(selector).some(key => key !== 'showLanguage') || (selector.showLanguage !== undefined && typeof selector.showLanguage !== 'boolean')))
@@ -102,7 +102,7 @@ export function renderPublicationPages({ rendered, docs, relationships, knownOpe
             const group = variant.product === undefined ? config.site.title : config.publications.products?.[variant.product]?.label ?? variant.product;
             return [{ group, label: `${group} · ${variant.channel} · ${variant.version}${showLanguage ? ` · ${variant.language}` : ''}`, url: target.route, current: samePublication(page.doc.variant, variant) }];
         }) : [];
-        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, logo: logoRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationChoices, publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
+        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, preloadFonts: customFontPreloads, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, logo: logoRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationChoices, publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
     }
     return resolvedNavigation;
 }