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

package/dist/highlight-languages.js

@@ -0,0 +1,52 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+const identifier = /^[a-z][a-z0-9_-]{0,63}$/;
+const mapping = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+export async function customHighlightLanguages(value, declaringFile, reserved, options, reservedScopes = new Set()) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('outputs.html.highlighting.languages must be a list');
+    const names = new Set(reserved);
+    const scopes = new Set(reservedScopes);
+    const result = [];
+    for (const [index, entry] of value.entries()) {
+        const setting = `outputs.html.highlighting.languages[${index}]`;
+        if (!mapping(entry) || Object.keys(entry).some(key => !['id', 'grammar', 'aliases'].includes(key)))
+            throw new Error(`${setting} accepts id, grammar, and aliases`);
+        if (typeof entry.id !== 'string' || !identifier.test(entry.id))
+            throw new Error(`${setting}.id must be a lowercase language ID, using letters, digits, underscores, or hyphens`);
+        const aliases = entry.aliases ?? [];
+        if (!Array.isArray(aliases) || aliases.some(alias => typeof alias !== 'string' || !identifier.test(alias)))
+            throw new Error(`${setting}.aliases must be a list of lowercase language IDs`);
+        for (const name of [entry.id, ...aliases]) {
+            if (names.has(name))
+                throw new Error(`${setting}: language ID or alias ${name} is already registered`);
+            names.add(name);
+        }
+        if (typeof entry.grammar !== 'string' || !entry.grammar || path.isAbsolute(entry.grammar) || /^[a-z][a-z0-9+.-]*:/i.test(entry.grammar) || path.extname(entry.grammar).toLowerCase() !== '.json')
+            throw new Error(`${setting}.grammar must be a relative path to a local TextMate JSON grammar`);
+        const origin = options.grammarOrigin?.(index) ?? declaringFile;
+        if (!origin)
+            throw new Error(`${setting}.grammar needs the declaring configuration file`);
+        const file = path.resolve(path.dirname(origin), entry.grammar);
+        options.onDependency?.(file);
+        const info = await stat(file).catch(() => { throw new Error(`${setting}: cannot read grammar ${file}`); });
+        if (!info.isFile() || info.size > 4 * 1024 * 1024)
+            throw new Error(`${setting}: grammar must be a regular JSON file no larger than 4 MiB: ${file}`);
+        let grammar;
+        try {
+            grammar = JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`${setting}: invalid TextMate JSON grammar ${file}: ${error.message}`);
+        }
+        if (!mapping(grammar) || typeof grammar.scopeName !== 'string' || !/^\S+$/.test(grammar.scopeName) || !Array.isArray(grammar.patterns))
+            throw new Error(`${setting}: grammar needs a scopeName and a patterns array: ${file}`);
+        if (scopes.has(grammar.scopeName))
+            throw new Error(`${setting}: grammar scopeName ${grammar.scopeName} is already registered`);
+        scopes.add(grammar.scopeName);
+        result.push({ file, grammar: { ...grammar, name: entry.id, aliases } });
+    }
+    return result;
+}

package/dist/highlight.d.ts

@@ -1,3 +1,4 @@
+import { type LanguageFiles } from './highlight-languages.js';
 export type HighlightToken = {
     text: string;
     color?: string;
@@ -8,7 +9,9 @@ export type CodeHighlighter = {
     foreground?: string;
     dark?: boolean;
     dependency?: string;
+    dependencies?: string[];
+    dispose?: () => void;
 };
-export declare function createCodeHighlighter(config?: any, declaringFile?: string): Promise<CodeHighlighter>;
+export declare function createCodeHighlighter(config?: any, declaringFile?: string, options?: LanguageFiles): Promise<CodeHighlighter>;
 export declare function highlightCode(highlighter?: CodeHighlighter): (tree: any) => void;
 export declare function highlightedExample(value: string, language: string, highlighter?: CodeHighlighter): string;

package/dist/highlight.js

@@ -2,16 +2,18 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { unified } from 'unified';
 import rehypeStringify from 'rehype-stringify';
+import { customHighlightLanguages } from './highlight-languages.js';
 const plain = { highlight: text => [{ text }] };
 const stringify = unified().use(rehypeStringify);
 const hex = /^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i;
 // The site theme colors tokens with CSS variables that each palette sets.
 const siteColor = /^var\(--code-(?:foreground|token-[a-z-]+)\)$/;
-export async function createCodeHighlighter(config = {}, declaringFile) {
+const defaultLanguages = ['json', 'yaml', 'bash', 'javascript', 'typescript', 'python', 'html', 'css', 'mdx', 'markdown', 'http', 'xml', 'sql', 'go', 'java', 'ruby', 'csharp', 'php', 'rust'];
+export async function createCodeHighlighter(config = {}, declaringFile, options = {}) {
     if (!config || typeof config !== 'object' || Array.isArray(config))
         throw new Error('outputs.html.highlighting must be a mapping');
     const provider = config.provider ?? 'shiki';
-    const allowed = provider === 'shiki' ? ['provider', 'theme'] : provider === 'custom' ? ['provider', 'module'] : ['provider'];
+    const allowed = provider === 'shiki' ? ['provider', 'theme', 'languages'] : provider === 'custom' ? ['provider', 'module'] : ['provider'];
     for (const key of Object.keys(config))
         if (!allowed.includes(key))
             throw new Error(`Unsupported highlighting setting ${key} for ${provider}`);
@@ -29,17 +31,30 @@ export async function createCodeHighlighter(config = {}, declaringFile) {
     if (provider !== 'shiki')
         throw new Error(`Unknown highlighting provider ${provider}`);
     // Load only when selected. Shiki caches its build-time instance and grammars.
-    const { getSingletonHighlighter, bundledThemes, createCssVariablesTheme } = await import('shiki');
+    const { getSingletonHighlighter, createHighlighter, bundledLanguages, bundledThemes, createCssVariablesTheme } = await import('shiki');
     const theme = config.theme ?? 'site';
     if (typeof theme !== 'string' || (theme !== 'site' && !Object.hasOwn(bundledThemes, theme)))
         throw new Error(`Unknown Shiki theme ${theme}; use site or a bundled Shiki theme name`);
-    const highlighter = await getSingletonHighlighter({
+    const builtinGrammars = Array.isArray(config.languages) && config.languages.length ? (await Promise.all(defaultLanguages.map(async (language) => (await bundledLanguages[language]()).default))).flat() : [];
+    const custom = await customHighlightLanguages(config.languages, declaringFile, new Set([...Object.keys(bundledLanguages), 'text', 'txt', 'plain', 'plaintext', 'ansi']), options, new Set(builtinGrammars.map(grammar => grammar.scopeName)));
+    // Custom grammars belong to this compilation, never Shiki's process-wide registry.
+    const create = custom.length ? createHighlighter : getSingletonHighlighter;
+    const highlighter = await create({
         themes: [theme === 'site' ? createCssVariablesTheme({ name: 'site', variablePrefix: '--code-' }) : theme],
-        langs: ['json', 'yaml', 'bash', 'javascript', 'typescript', 'python', 'html', 'css', 'mdx', 'markdown', 'http', 'xml', 'sql', 'go', 'java', 'ruby', 'csharp', 'php', 'rust']
+        langs: [...defaultLanguages]
     });
+    try {
+        if (custom.length)
+            await highlighter.loadLanguage(...custom.map(item => item.grammar));
+    }
+    catch (error) {
+        highlighter.dispose();
+        throw new Error(`Cannot load TextMate grammars ${custom.map(item => item.file).join(', ')}: ${error.message}`);
+    }
     const languages = new Set(highlighter.getLoadedLanguages());
     const colors = highlighter.getTheme(theme);
     return {
+        ...(custom.length ? { dependencies: custom.map(item => item.file), dispose: () => highlighter.dispose() } : {}),
         ...(theme === 'site' ? {} : { background: colors.bg, foreground: colors.fg, dark: colors.type === 'dark' }),
         highlight(value, language) {
             const lang = language?.toLowerCase();

package/dist/output-commit.d.ts

@@ -1 +1 @@
-export declare function commitArtifacts(target: string, artifacts: Map<string, string | Buffer>, prepare?: () => Promise<void>, kind?: 'site' | 'export'): Promise<void>;
+export declare function commitArtifacts(target: string, artifacts: Map<string, string | Buffer>, prepare?: () => Promise<void>, kind?: 'site' | 'export' | 'pdf'): Promise<void>;

package/dist/output-commit.js

@@ -65,9 +65,11 @@ async function checkReplaceable(target, kind) {
         return;
     if (kind === 'site' && entries.includes('documents.json') && entries.includes('resource-headers.json'))
         return;
-    if (kind === 'export' && entries.includes('manifest.json')) {
+    if ((kind === 'export' || kind === 'pdf') && entries.includes('manifest.json')) {
         const manifest = JSON.parse(await readFile(path.join(target, 'manifest.json'), 'utf8'));
-        if (manifest.kind === 'shoalrun-content-export' && manifest.schemaVersion === 1)
+        if (kind === 'export' && manifest.kind === 'shoalrun-content-export' && [1, 2].includes(manifest.schemaVersion))
+            return;
+        if (kind === 'pdf' && manifest.kind === 'shoalrun-pdf-export' && manifest.schemaVersion === 1)
             return;
     }
     throw new Error(`Output directory ${target} already exists and is not an earlier Shoalrun ${kind === 'site' ? 'build (it has no documents.json and resource-headers.json)' : 'content export'}. The build replaces its output directory, so it stopped instead of deleting it. Choose a new or empty directory`);

package/dist/page-renderer.js

@@ -1,3 +1,4 @@
+import { pdfPageAction } from './pdf-button.js';
 import { publicationKey } from './publication-identity.js';
 import { resolveAgentDiscovery } from './agent-discovery.js';
 import { navigationCounts, navigationHeading } from './compiler-config.js';
@@ -60,6 +61,10 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const sampleBlock = (list, fallbackCurl, idHint) => list?.length ? codeSamplesBlock(list, highlighter, esc, idHint) : fallbackCurl ? highlightedExample(fallbackCurl, 'bash', highlighter) : '';
     const subjectLifecycleLabel = (subjectLifecycle) => ({ deprecated: 'Deprecated', 'in-development': 'In development', beta: 'Beta', experimental: 'Experimental' })[subjectLifecycle];
     const badge = (subjectLifecycle) => subjectLifecycle ? `<span class="subject-lifecycle-badge subject-lifecycle-${subjectLifecycle}">${subjectLifecycleLabel(subjectLifecycle)}</span>` : '';
+    const pdfAction = pdfPageAction(doc, config.outputs, normalizeBasePath(config.site?.basePath));
+    const pdfLink = pdfAction ? pdfAction.mode === 'print'
+        ? `<button type="button" class="formats pdf-print" data-print-page data-print-settings="${esc(sitePath(normalizeBasePath(config.site?.basePath), '/assets/print/settings.json'))}" hidden>${esc(pdfAction.label)}</button><span role="status" data-print-status></span><script type="application/json" data-print-page-meta>${JSON.stringify({ title: doc.frontmatter.title, summary: doc.frontmatter.summary, publication: doc.variant }).replaceAll('<', '\\u003c')}</script>`
+        : `<a class="formats pdf-download" href="${esc(pdfAction.href)}">${esc(pdfAction.label)}</a>` : '';
     const readerConfig = config.readerFilters;
     const basePath = normalizeBasePath(config.site?.basePath);
     const agent = resolveAgentDiscovery(config.site?.agentDiscovery);
@@ -187,6 +192,6 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const menu = side || sectionNavigation ? `<a class="mobile-menu" href="#${side ? 'docs-navigation' : 'docs-sections'}">Menu</a>` : '';
     const rail = toc || panel ? `<aside class="page-rail">${doc.endpoint ? `${panel}${toc}` : `${toc}${panel}`}</aside>` : '';
     const breadcrumbs = (shell.breadcrumbs?.length ?? 0) > 1 && !hero ? `<nav class="doc-breadcrumbs" aria-label="Breadcrumb"><ol>${shell.breadcrumbs.map((item, index) => `<li>${index === shell.breadcrumbs.length - 1 ? `<span aria-current="page">${esc(item.label)}</span>` : item.url ? `<a href="${esc(item.url)}">${esc(item.label)}</a>` : `<span>${esc(item.label)}</span>`}</li>`).join('')}</ol></nav>` : '';
-    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="${brandClass}" href="/">${brand}</a>` : `<span class="${brandClass}">${brand}</span>`}${publicationPicker(shell, esc)}${editionLabel && !shell.publicationChoices?.length && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? '' : `<div class="page-formats"><a class="formats" href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span></div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
+    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="${brandClass}" href="/">${brand}</a>` : `<span class="${brandClass}">${brand}</span>`}${publicationPicker(shell, esc)}${editionLabel && !shell.publicationChoices?.length && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? (pdfLink ? `<div class="page-formats">${pdfLink}</div>` : '') : `<div class="page-formats">${pdfAction?.placement === 'before' ? pdfLink : ''}<a class="formats" data-markdown-link href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span>${pdfAction?.placement === 'after' ? pdfLink : ''}</div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}${pdfAction?.mode === 'print' ? '<script type="module" src="/assets/print.js"></script>' : ''}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
     return basePath ? markup.replace(/((?:href|src)=")\/(assets\/|llms(?:\.min)?\.txt|apple-touch-icon\.png)/g, `$1${basePath}/$2`).replace('href="/"', `href="${basePath}/"`) : markup;
 }

package/dist/pdf-button.d.ts

@@ -0,0 +1,22 @@
+import type { Document, Variant } from './content-source.js';
+export type PdfButtonConfig = {
+    mode: 'print' | 'endpoint';
+    label: string;
+    endpoint: string;
+    placement: 'before' | 'after';
+    style?: string;
+    include?: string[];
+    exclude?: string[];
+};
+export declare const pdfRuntimePath = "/pdf-runtime.json";
+export declare const pdfDataPath = "/__shoalrun/pdf-data";
+export declare function resolvePdfButton(outputs: unknown): PdfButtonConfig | undefined;
+export declare function validatePdfButtonStyle(button: PdfButtonConfig | undefined, exports: unknown): void;
+export declare function pdfPageKey(id: string, publication: Variant): string;
+export declare function pdfButtonIncludes(doc: Document, button: PdfButtonConfig): boolean;
+export declare function pdfPageAction(doc: Document, outputs: unknown, basePath?: string): {
+    mode: 'print' | 'endpoint';
+    href?: string;
+    label: string;
+    placement: 'before' | 'after';
+} | undefined;

package/dist/pdf-button.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { configField, isConfigMapping } from './compiler-config.js';
+import { documentKey } from './publication-identity.js';
+import { normalizeBasePath, sitePath } from './site-path.js';
+export const pdfRuntimePath = '/pdf-runtime.json';
+export const pdfDataPath = '/__shoalrun/pdf-data';
+export function resolvePdfButton(outputs) {
+    const value = configField(configField(outputs, 'html'), 'pdf');
+    if (value === undefined || value === false)
+        return undefined;
+    if (!isConfigMapping(value) || Object.keys(value).some(key => !['mode', 'label', 'endpoint', 'placement', 'style', 'include', 'exclude'].includes(key)))
+        throw new Error('outputs.html.pdf must be false or a mapping containing mode, label, endpoint, placement, style, include, and exclude');
+    const mode = value.mode ?? 'print';
+    if (mode !== 'print' && mode !== 'endpoint')
+        throw new Error('outputs.html.pdf.mode must be print or endpoint; site builds do not generate per-page PDFs');
+    const label = value.label ?? (mode === 'print' ? 'Print PDF' : 'Download PDF');
+    if (typeof label !== 'string' || !label.trim() || label.length > 128)
+        throw new Error('outputs.html.pdf.label must be 1–128 characters');
+    const endpoint = value.endpoint ?? '/__shoalrun/pdf';
+    if (typeof endpoint !== 'string' || !/^\/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(endpoint))
+        throw new Error('outputs.html.pdf.endpoint must be a same-origin absolute path without query, fragment, or encoded separators');
+    if (mode === 'print' && value.endpoint !== undefined)
+        throw new Error('outputs.html.pdf.endpoint requires mode: endpoint');
+    const normalizedEndpoint = endpoint.toLowerCase();
+    if (['/mcp-runtime.json', '/__shoalrun/mcp-data', pdfRuntimePath, pdfDataPath, '/__shoalrun/ask', '/__shoalrun/search', '/__shoalrun/reload'].some(reserved => normalizedEndpoint === reserved || normalizedEndpoint.startsWith(`${reserved}/`) || reserved.startsWith(`${normalizedEndpoint}/`)))
+        throw new Error('outputs.html.pdf.endpoint overlaps a reserved runtime path');
+    if (value.style !== undefined && (typeof value.style !== 'string' || !/^[a-z][a-z0-9-]*$/.test(value.style)))
+        throw new Error('outputs.html.pdf.style must name an export target containing PDF styling');
+    const placement = value.placement ?? 'after';
+    if (placement !== 'before' && placement !== 'after')
+        throw new Error('outputs.html.pdf.placement must be before or after');
+    for (const key of ['include', 'exclude'])
+        if (value[key] !== undefined && (!Array.isArray(value[key]) || value[key].some(id => typeof id !== 'string' || !id.trim()) || new Set(value[key]).size !== value[key].length))
+            throw new Error(`outputs.html.pdf.${key} must contain unique document IDs`);
+    return { mode, label: label.trim(), endpoint, placement, ...(value.style === undefined ? {} : { style: value.style }), ...(value.include === undefined ? {} : { include: value.include }), ...(value.exclude === undefined ? {} : { exclude: value.exclude }) };
+}
+export function validatePdfButtonStyle(button, exports) {
+    if (!button?.style)
+        return;
+    const target = isConfigMapping(exports) && Object.hasOwn(exports, button.style) ? exports[button.style] : undefined;
+    if (!isConfigMapping(target) || !isConfigMapping(target.pdf))
+        throw new Error(`Unknown PDF button style ${button.style}; define exports.${button.style}.pdf`);
+}
+export function pdfPageKey(id, publication) {
+    return createHash('sha256').update(documentKey(id, publication)).digest('hex');
+}
+export function pdfButtonIncludes(doc, button) {
+    return doc.frontmatter.pdf !== false && (!button.include || button.include.includes(doc.frontmatter.id)) && !button.exclude?.includes(doc.frontmatter.id);
+}
+export function pdfPageAction(doc, outputs, basePath = '') {
+    const button = resolvePdfButton(outputs);
+    if (!button || !pdfButtonIncludes(doc, button))
+        return undefined;
+    return { mode: button.mode, label: button.label, placement: button.placement, ...(button.mode === 'endpoint' ? { href: `${sitePath(normalizeBasePath(basePath), button.endpoint)}?key=${pdfPageKey(doc.frontmatter.id, doc.variant)}` } : {}) };
+}

package/dist/pdf-config.d.ts

@@ -0,0 +1,28 @@
+export type PdfFont = {
+    family: string;
+    source: string;
+    weight?: string;
+    style?: 'normal' | 'italic';
+};
+export type PdfConfig = {
+    stylesheet?: string;
+    logo?: string;
+    subtitle?: string;
+    fonts?: PdfFont[];
+    size?: 'A4' | 'Letter' | 'Legal' | 'A3' | 'A5';
+    margins?: {
+        top?: string;
+        right?: string;
+        bottom?: string;
+        left?: string;
+    };
+    header?: string;
+    footer?: string;
+    cover?: boolean;
+    toc?: boolean;
+    bookmarks?: boolean;
+    executablePath?: string;
+    timeout?: number;
+};
+export declare function validatePdfConfig(value: unknown): PdfConfig;
+export declare function mergePdfConfig(base: unknown, override: unknown): PdfConfig;

package/dist/pdf-config.js

@@ -0,0 +1,43 @@
+import { isConfigMapping } from './compiler-config.js';
+const localFile = (value) => typeof value === 'string' && value.trim() && !/^[a-z][a-z0-9+.-]*:|^\/\//i.test(value) && !value.includes('\0');
+export function validatePdfConfig(value) {
+    if (value === undefined)
+        return {};
+    const keys = ['stylesheet', 'logo', 'subtitle', 'fonts', 'size', 'margins', 'header', 'footer', 'cover', 'toc', 'bookmarks', 'executablePath', 'timeout'];
+    if (!isConfigMapping(value) || Object.keys(value).some(key => !keys.includes(key)))
+        throw new Error(`PDF settings accept ${keys.join(', ')}`);
+    for (const key of ['stylesheet', 'logo', 'executablePath'])
+        if (value[key] !== undefined && !localFile(value[key]))
+            throw new Error(`PDF ${key} must be a local file path`);
+    if (value.subtitle !== undefined && (typeof value.subtitle !== 'string' || value.subtitle.length > 1000))
+        throw new Error('PDF subtitle must be text of at most 1000 characters');
+    if (value.size !== undefined && !['A4', 'Letter', 'Legal', 'A3', 'A5'].includes(value.size))
+        throw new Error('PDF size must be A4, Letter, Legal, A3, or A5');
+    if (value.margins !== undefined) {
+        if (!isConfigMapping(value.margins) || Object.keys(value.margins).some(key => !['top', 'right', 'bottom', 'left'].includes(key)))
+            throw new Error('PDF margins accept top, right, bottom, left');
+        for (const margin of Object.values(value.margins))
+            if (typeof margin !== 'string' || !/^(?:\d+(?:\.\d+)?|\.\d+)(?:mm|cm|in|px)$/.test(margin) || parseFloat(margin) > 1000)
+                throw new Error('PDF margins need nonnegative dimensions with mm, cm, in, or px units');
+    }
+    for (const key of ['cover', 'toc', 'bookmarks'])
+        if (value[key] !== undefined && typeof value[key] !== 'boolean')
+            throw new Error(`PDF ${key} must be boolean`);
+    for (const key of ['header', 'footer'])
+        if (value[key] !== undefined && (typeof value[key] !== 'string' || value[key].length > 2000 || /\{(?!title\}|page\}|pages\})[^}]*\}/.test(value[key])))
+            throw new Error(`PDF ${key} accepts text and {title}, {page}, {pages} placeholders`);
+    if (value.timeout !== undefined && (!Number.isInteger(value.timeout) || Number(value.timeout) < 1000 || Number(value.timeout) > 120000))
+        throw new Error('PDF timeout must be 1000–120000 milliseconds');
+    if (value.fonts !== undefined) {
+        if (!Array.isArray(value.fonts) || value.fonts.length > 32)
+            throw new Error('PDF fonts must be an array of at most 32 local fonts');
+        for (const font of value.fonts)
+            if (!isConfigMapping(font) || Object.keys(font).some(key => !['family', 'source', 'weight', 'style'].includes(key)) || typeof font.family !== 'string' || !font.family.trim() || font.family.length > 100 || !localFile(font.source) || (font.weight !== undefined && (typeof font.weight !== 'string' || !/^(?:normal|bold|[1-9]00)$/.test(font.weight))) || (font.style !== undefined && !['normal', 'italic'].includes(font.style)))
+                throw new Error('Each PDF font needs family and local source, with optional weight and normal/italic style');
+    }
+    return structuredClone(value);
+}
+export function mergePdfConfig(base, override) {
+    const first = validatePdfConfig(base), second = validatePdfConfig(override);
+    return { ...first, ...second, ...(first.margins || second.margins ? { margins: { ...first.margins, ...second.margins } } : {}) };
+}

package/dist/pdf-http.d.ts

@@ -0,0 +1,36 @@
+import { type PreparedPdf } from './pdf-renderer.js';
+import { type PdfConfig } from './pdf-config.js';
+type Page = {
+    documentId: string;
+    publication: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
+    title: string;
+    file: string;
+    digest: string;
+};
+export type PdfRuntime = {
+    schemaVersion: 1;
+    endpoint: string;
+    config: PdfConfig;
+    pages: Record<string, Page>;
+    inventory: Record<string, string>;
+};
+export type LoadedPdfRuntime = {
+    runtime: PdfRuntime;
+    directory: string;
+};
+export declare function loadPdfRuntime(directory: string): Promise<LoadedPdfRuntime | undefined>;
+/** Mount behind the same authentication as the built site. This handler does not grant access to other profiles. */
+export declare function createPdfHttpHandler(input: LoadedPdfRuntime, options?: {
+    authorize?: (request: Request) => boolean | Promise<boolean>;
+    render?: (prepared: PreparedPdf, config: PdfConfig) => Promise<{
+        bytes: Buffer | Uint8Array;
+    }>;
+    now?: () => number;
+}): (request: Request) => Promise<Response>;
+export declare function hydratePreparedPdf(value: unknown): PreparedPdf;
+export {};

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>;