@shoalrun/cli 0.1.0-alpha.18 → 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/turnstile-policy.d.ts

@@ -0,0 +1,2 @@
+export declare function turnstileHostname(value: unknown): string | undefined;
+export declare function turnstileHostnames(value: unknown, setting: string): string[];

package/dist/turnstile-policy.js

@@ -0,0 +1,23 @@
+// Canonical, exact hostnames only: no wildcard, URL, credentials, or port.
+export function turnstileHostname(value) {
+    if (typeof value !== 'string' || !value || value.length > 253 || /[\s*]/.test(value))
+        return;
+    const hostname = value.toLowerCase().replace(/\.$/, '');
+    try {
+        const url = new URL(`https://${hostname}`);
+        if (url.host !== hostname || url.pathname !== '/' || url.search || url.hash || url.username || url.password)
+            return;
+        return hostname;
+    }
+    catch {
+        return;
+    }
+}
+export function turnstileHostnames(value, setting) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 100)
+        throw new Error(`${setting} must be a nonempty list of at most 100 exact hostnames`);
+    const names = value.map(turnstileHostname);
+    if (names.some(name => name === undefined))
+        throw new Error(`${setting} must contain exact hostnames without wildcards, URLs, or ports`);
+    return [...new Set(names)];
+}

package/dist/turnstile.d.ts

@@ -1,15 +1,22 @@
 export type TurnstileOptions = {
     secret: string;
+    allowedHostnames: readonly string[];
+    action?: string;
     timeoutMs?: number;
     fetch?: typeof fetch;
 };
 export declare const turnstileVerifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+export declare function turnstilePreviewVerifier(options?: Pick<TurnstileOptions, 'fetch' | 'timeoutMs'>): (input: {
+    token?: string;
+    ip?: string;
+}) => Promise<boolean>;
 export declare function turnstileVerifier(options: TurnstileOptions): (input: {
     token?: string;
     ip?: string;
 }) => Promise<boolean>;
 export type SessionOptions = {
     secret: string;
+    context?: string;
     maxAgeSeconds?: number;
     now?: () => number;
 };

package/dist/turnstile.js

@@ -1,8 +1,31 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { turnstileHostname, turnstileHostnames } from './turnstile-policy.js';
 export const turnstileVerifyUrl = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+const previewSecret = '1x0000000000000000000000000000000AA';
+const previewToken = 'XXXX.DUMMY.TOKEN.XXXX';
+// Cloudflare's published test pair returns synthetic hostname metadata rather
+// than a real browser hostname. This helper is used only by loopback preview.
+export function turnstilePreviewVerifier(options = {}) {
+    const send = options.fetch ?? fetch;
+    const verify = turnstileVerifier({ ...options, secret: previewSecret, allowedHostnames: ['example.com'], fetch: async (url, init) => {
+            const response = await send(url, init);
+            if (!response.ok)
+                return response;
+            const result = await response.json();
+            return Response.json({ success: result.success === true && result.metadata?.result_with_testing_key === true, hostname: result.hostname });
+        } });
+    return async (input) => {
+        if (input.token !== previewToken)
+            return false;
+        return verify(input);
+    };
+}
 export function turnstileVerifier(options) {
     if (!options.secret)
         throw new Error('Turnstile needs a secret key');
+    const allowed = new Set(turnstileHostnames(options.allowedHostnames, 'Turnstile allowedHostnames'));
+    if (options.action !== undefined && !/^[A-Za-z0-9_-]{1,32}$/.test(options.action))
+        throw new Error('Turnstile action must contain 1 to 32 letters, numbers, underscores, or hyphens');
     const send = options.fetch ?? fetch;
     return async ({ token, ip }) => {
         // Tokens are short. A missing or oversized one is refused without asking Cloudflare.
@@ -16,7 +39,8 @@ export function turnstileVerifier(options) {
             if (!response.ok)
                 return false;
             const body = await response.json();
-            return body?.success === true;
+            const hostname = turnstileHostname(body?.hostname);
+            return body?.success === true && hostname !== undefined && allowed.has(hostname) && (options.action === undefined || body.action === options.action);
         }
         catch {
             return false;
@@ -30,7 +54,10 @@ export function createSession(options) {
     const maxAge = options.maxAgeSeconds ?? 900;
     const name = 'sr_ask';
     // A separate key, so the cookie signature is never the Turnstile secret itself.
-    const key = createHmac('sha256', options.secret).update('shoalrun-ask-session').digest();
+    const derivation = createHmac('sha256', options.secret).update('shoalrun-ask-session');
+    if (options.context !== undefined)
+        derivation.update('\0').update(options.context);
+    const key = derivation.digest();
     const sign = (expires, caller) => createHmac('sha256', key).update(`${expires}.${caller}`).digest('base64url');
     return {
         name,

package/dist/vercel-function.js

@@ -83,7 +83,7 @@ export async function addAskFunction(input) {
     await mkdir(shoalrun, { recursive: true });
     const assets = path.join(input.distDirectory ?? path.dirname(fileURLToPath(import.meta.url)), '..', 'assets');
     await cp(path.join(assets, 'ask-widget.js'), path.join(shoalrun, 'ask.js'));
-    await writeFile(path.join(shoalrun, 'chat.json'), JSON.stringify({ ...(chat.challenge ? { siteKey: chat.challenge.siteKey, ...(chat.challenge.when === 'always' ? { prewarm: true } : {}) } : {}), ...(chat.log ? { notice: chat.log.notice } : {}), ...(chat.panel ? { panel: chat.panel } : {}) }, null, 2) + '\n');
+    await writeFile(path.join(shoalrun, 'chat.json'), JSON.stringify({ ...(chat.challenge ? { siteKey: chat.challenge.siteKey, ...(chat.challenge.action ? { action: chat.challenge.action } : {}), ...(chat.challenge.when === 'always' ? { prewarm: true } : {}) } : {}), ...(chat.log ? { notice: chat.log.notice } : {}), ...(chat.panel ? { panel: chat.panel } : {}) }, null, 2) + '\n');
     await addPanelToPages(input.staticDirectory, basePath);
     const publications = settings.publications?.defaults;
     const origin = settings.site?.origin;

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)