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

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/representation-tree.js

@@ -53,7 +53,7 @@ export function publicTree(tree, representation, documentRoutes, mode = 'light',
         if (node.type === 'docReaderSection') {
             const children = node.children.flatMap(walk);
             return representation === 'markdown' ? [paragraph({ type: 'strong', children: [text(`For ${node.description}.`)] }), ...children]
-                : [element('section', { className: ['reader-section'], 'data-reader-filters': JSON.stringify(node.selection) }, children)];
+                : [element('section', { className: ['reader-section'], 'data-reader-filters': JSON.stringify(node.selection), 'data-reader-print-label': `For ${node.description}.` }, children)];
         }
         if (node.type === 'docReaderChoice') {
             if (representation === 'markdown') {

package/dist/server.d.ts

@@ -1,4 +1,6 @@
 import { type Server, type ServerResponse } from 'node:http';
+export declare function canonicalSitePath(url: string): string;
+export declare function privateSitePath(pathname: string): boolean;
 export type PreviewStatus = {
     profile?: string;
     profileDigest?: string;

package/dist/server.js

@@ -1,11 +1,22 @@
 import { loadMcpRuntime, createMcpHttpHandler } from './mcp-http.js';
 import { bridgeMcp } from './mcp-node.js';
+import { loadPdfRuntime, createPdfHttpHandler } from './pdf-http.js';
 import { notFoundPage, addNotFoundTwin } from './not-found.js';
 import { createServer } from 'node:http';
 import { readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { homeUrl, negotiatedDocument } from './negotiation.js';
-const types = { '.html': 'text/html; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.xml': 'application/xml; charset=utf-8', '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.txt': 'text/plain; charset=utf-8', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf' };
+export function canonicalSitePath(url) {
+    const decoded = decodeURIComponent(new URL(url, 'http://localhost').pathname).replace(/\\/g, '/');
+    if (decoded.includes('\0') || decoded.split('/').some(segment => segment === '..' || segment === '.'))
+        throw new Error('Invalid path');
+    return decoded.replace(/\/{2,}/g, '/');
+}
+export function privateSitePath(pathname) {
+    const internal = pathname.toLowerCase().replace(/\/+$/, '');
+    return ['/mcp-runtime.json', '/pdf-runtime.json', '/__shoalrun/mcp-data', '/__shoalrun/pdf-data'].some(privatePath => internal === privatePath || internal.startsWith(privatePath + '/'));
+}
+const types = { '.pdf': 'application/pdf', '.html': 'text/html; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.xml': 'application/xml; charset=utf-8', '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.txt': 'text/plain; charset=utf-8', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf' };
 const escapeHtml = (value) => value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character]));
 const scriptJson = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
 export function previewMarkup(basePath, preview) {
@@ -58,6 +69,9 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
     let mcp = await loadMcpRuntime(root);
     let mcpHandler = mcp ? createMcpHttpHandler(mcp) : undefined;
     let mcpBuild = mcp?.runtime.buildId;
+    let pdf = await loadPdfRuntime(root);
+    let pdfHandler = pdf ? createPdfHttpHandler(pdf) : undefined;
+    let pdfBuild = initialState.manifest.buildId;
     async function siteFile(route) {
         const file = path.resolve(root, `.${route}`);
         if (file !== root && !file.startsWith(`${root}${path.sep}`))
@@ -73,9 +87,7 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
         let pathname = '';
         let recoveryState = initialState;
         try {
-            pathname = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname);
-            if (pathname.includes('\0') || pathname.split('/').includes('..'))
-                throw new Error('Invalid path');
+            pathname = canonicalSitePath(request.url ?? '/');
             const { headers, manifest, redirects, search, errorHtml, home, routes } = liveClients ? await loadState() : initialState;
             recoveryState = { headers, manifest, redirects, search, errorHtml, home, routes };
             const basePath = manifest.basePath ?? '';
@@ -85,12 +97,28 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
                 mcpHandler = next ? createMcpHttpHandler(next) : undefined;
                 mcpBuild = manifest.buildId;
             }
-            const internalPath = pathname.toLowerCase().replace(/\/+$/, '');
-            if (internalPath === '/mcp-runtime.json' || internalPath === '/__shoalrun/mcp-data' || internalPath.startsWith('/__shoalrun/mcp-data/')) {
+            if (privateSitePath(pathname)) {
                 response.writeHead(404);
                 response.end();
                 return;
             }
+            if (liveClients && manifest.buildId !== pdfBuild) {
+                pdf = await loadPdfRuntime(root);
+                pdfHandler = pdf ? createPdfHttpHandler(pdf) : undefined;
+                pdfBuild = manifest.buildId;
+            }
+            if (pdf && pdfHandler && pathname === pdf.runtime.endpoint) {
+                try {
+                    await bridge(request, response, pdfHandler);
+                }
+                catch {
+                    if (!response.headersSent) {
+                        response.writeHead(503, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                        response.end('{"error":"PDF generation is unavailable."}');
+                    }
+                }
+                return;
+            }
             if (mcp && mcpHandler && pathname === mcp.runtime.path) {
                 await bridgeMcp(request, response, mcpHandler);
                 return;
@@ -201,8 +229,7 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
                 mcpHandler = next ? createMcpHttpHandler(next) : undefined;
                 mcpBuild = manifest.buildId;
             }
-            const internalPath = pathname.toLowerCase().replace(/\/+$/, '');
-            if (internalPath === '/mcp-runtime.json' || internalPath === '/__shoalrun/mcp-data' || internalPath.startsWith('/__shoalrun/mcp-data/')) {
+            if (privateSitePath(pathname)) {
                 response.writeHead(404);
                 response.end();
                 return;

package/dist/vercel.js

@@ -5,6 +5,9 @@ import path from 'node:path';
 import { compile } from './compiler.js';
 import { homeUrl } from './negotiation.js';
 import { addAskFunction } from './vercel-function.js';
+import { loadConfig } from './config.js';
+import { resolvedCompilerConfig } from './compiler-config.js';
+import { resolvePdfButton } from './pdf-button.js';
 function exact(route) {
     return route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -28,6 +31,9 @@ async function removeStaleFunctions(directory, keep = new Set()) {
     await visit(directory);
 }
 export async function buildVercel(configFile, outputDirectory, provenance = {}, options = {}) {
+    const settings = resolvedCompilerConfig((await loadConfig(configFile, { profile: options.profile })).value);
+    if (resolvePdfButton(settings.outputs)?.mode === 'endpoint')
+        throw new Error('On-demand PDF generation requires a Node server with an installed Chromium browser. Use outputs.html.pdf.mode: print for Vercel builds.');
     const output = path.resolve(outputDirectory);
     const staticDirectory = path.join(output, 'static');
     if (options.profile && options.chat)

package/examples/custom-language/README.md

@@ -0,0 +1,32 @@
+# Custom language highlighting
+
+Register a local TextMate JSON grammar under
+`outputs.html.highlighting.languages`, then use its `id` or an `aliases` entry
+as a fenced-code language. This example adds two illustrative keywords to
+Python's existing syntax-color rules.
+
+From this directory, with the CLI installed in your project:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8770
+```
+
+From the framework repository root:
+
+```sh
+node framework/dist/cli.js build framework/examples/custom-language/docs.config.yaml /tmp/shoalrun-custom-language
+node framework/dist/cli.js serve /tmp/shoalrun-custom-language --port 8770
+```
+
+Grammar paths resolve from the configuration file that declares them. The
+compiler tracks those files as build dependencies; edit the grammar and rebuild,
+or use `dev` for watched editing. Malformed or missing grammars fail the build
+and preserve existing output. IDs and aliases can't replace bundled languages;
+each grammar needs a distinct `scopeName`.
+
+The resulting HTML contains syntax colors without loading the grammar in the
+browser. Markdown keeps the original code and fence label. The grammar doesn't
+validate programs or add autocomplete, filename-based language inference, or
+editor integration. Replace this illustrative grammar with your language's
+grammar and retain its applicable license notices.

package/examples/custom-language/content/start.mdx

@@ -0,0 +1,28 @@
+---
+id: guide.custom-language
+title: Highlight a custom language
+summary: Register a local TextMate grammar and use its language ID or alias in fenced examples.
+type: guide
+slug: /
+channel: production
+version: current
+language: en
+access: { policy: public }
+---
+
+This illustrative Python-like language adds `publish` and `unless`. The grammar
+recognizes these keywords before falling back to the bundled Python grammar.
+
+```custompy title="Language ID"
+def welcome(name):
+    unless name is None:
+        publish "Hello, " + name
+```
+
+The alias selects the same grammar:
+
+```cpy title="Language alias"
+publish "The same syntax colors, with a shorter fence label."
+```
+
+This example only defines syntax colors. It doesn't implement an executable language.

package/examples/custom-language/docs.config.yaml

@@ -0,0 +1,18 @@
+schemaVersion: 1
+site:
+  title: Custom language example
+  contentDir: ./content
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels: { production: {} }
+  versions: { current: {} }
+  enabled: [{ channel: production, version: current, language: en }]
+outputs:
+  html:
+    shareImages: false
+    highlighting:
+      provider: shiki
+      languages:
+        - id: custompy
+          grammar: ./grammars/custompy.tmLanguage.json
+          aliases: [cpy]

package/examples/custom-language/grammars/custompy.tmLanguage.json

@@ -0,0 +1,7 @@
+{
+  "scopeName": "source.custompy",
+  "patterns": [
+    { "name": "keyword.control.custompy", "match": "\\b(?:publish|unless)\\b" },
+    { "include": "source.python" }
+  ]
+}

package/examples/pdf/README.md

@@ -0,0 +1,27 @@
+# Styled PDF export
+
+This project demonstrates browser page printing and optional CLI PDF exports. All configuration values and thresholds are examples.
+
+Build and preview the static site without a browser dependency:
+
+```sh
+shoalrun build docs.config.yaml site-dist
+shoalrun serve site-dist --port 8892
+```
+
+Open `/start` and choose **Print PDF**. The browser fills a separate print view using the shared PDF theme and opens its print dialog. Site builds add shared scripts, styling, settings, and configured print assets; they generate no page PDFs or extra print documents. This works on static hosting, including Vercel. Allow the print view to open if the browser blocks it. Without JavaScript, use the browser's own Print command.
+
+For a downloadable full manual, explicitly run the CLI export with an installed browser:
+
+```sh
+export SHOALRUN_PDF_BROWSER="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+shoalrun export docs.config.yaml --format pdf --out pdf/manual
+```
+
+Use the correct Chrome/Chromium executable path for your operating system. No browser is downloaded automatically. The command writes `pdf/manual/publication.pdf`. Publish that file and a deliberate download link only when wanted; it isn't added to the site automatically. Copy it into the static deployment after the site build, which replaces its output directory. Add `--document guide.start` to generate a single-page PDF explicitly.
+
+Change `print.css` for manual and browser print-view colors, typography, and page breaks. Set `outputs.pdf.fonts` to local licensed font files and reference their registered families in CSS. Use `outputs.pdf.logo` for a local cover image. Print CSS can't import files or load URLs; fonts and logo are registered explicitly. Optional `outputs.html.pdf.style` selects a named export target's PDF styling without changing page selection. Headers and footers accept `{title}`, `{page}`, and `{pages}`; browser views use CSS page-margin support. Use `site.customCss` with `@media print` for the ordinary browser Print fallback, which doesn't open a branded view.
+
+Inspect the actual PDF for spacing, math, long content, links, and bookmarks. The manual's table of contents is linked without printed page numbers. Chromium bookmark/tagging support is experimental; the output isn't certified PDF/UA. The `pdf` export manifest is separate from content REST representations.
+
+Explicit `outputs.html.pdf.mode: endpoint` supports direct page PDF downloads through a Node host with Chromium. It isn't for static hosting. Keep `pdf-runtime.json` and `__shoalrun/pdf-data` behind that server; don't expose them through a generic static host.