@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/dist/fonts.js

@@ -1,4 +1,7 @@
 import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+export const fontMediaType = (file) => ({ '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf' }[path.extname(file).toLowerCase()]);
 // Latin variable fonts from Fontsource, all under the SIL Open Font License. Readers download only the faces a page uses.
 export const bundledFonts = [
     { family: 'Inter', file: 'inter.woff2', style: 'normal' },
@@ -22,7 +25,7 @@ const fallbackFaces = [
     { family: 'Jost', src: localSans, size: '95.84%', ascent: '111.65%', descent: '39.13%' }
 ];
 export const bundledFontLicenses = ['inter', 'figtree', 'source-serif-4', 'jetbrains-mono', 'jost'].map(name => `${name}-LICENSE.txt`);
-// The body font each preset preloads so the first paint uses it.
+// Begin fetching the preset's body font before the browser discovers its CSS rule.
 const presetBodyFont = { shoal: 'inter.woff2', reef: 'figtree.woff2', ledger: 'source-serif-4.woff2', vice: 'figtree.woff2' };
 const fallbacks = {
     body: 'ui-sans-serif, system-ui, sans-serif',
@@ -45,6 +48,8 @@ export function resolveFonts(value, preset, declaringFile) {
     if (unknown.length)
         throw new Error(`theme.fonts accepts only body, headings, and code; remove ${unknown.join(', ')}`);
     const faces = [];
+    const preloadFaces = [];
+    const families = {};
     const tokens = {};
     for (const role of roles) {
         const entry = value[role];
@@ -56,6 +61,7 @@ export function resolveFonts(value, preset, declaringFile) {
         if (typeof spec.family !== 'string' || !familyName.test(spec.family))
             throw new Error(`theme.fonts.${role}.family must be a font name using letters, numbers, spaces, dots, dashes, or underscores`);
         const files = spec.files ?? [];
+        families[role] = spec.family;
         if (!Array.isArray(files))
             throw new Error(`theme.fonts.${role}.files must be a list`);
         for (const [index, item] of files.entries()) {
@@ -74,11 +80,60 @@ export function resolveFonts(value, preset, declaringFile) {
             const file = path.resolve(path.dirname(declaringFile), face.file);
             if (!/^[\w.-]+$/.test(path.basename(file)))
                 throw new Error(`${where} file name may use only letters, numbers, dots, dashes, and underscores`);
-            faces.push({ family: spec.family, file, route: `/assets/fonts/project/${path.basename(file)}`, style, weight });
+            const registration = { family: spec.family, file, route: `/assets/fonts/project/${path.basename(file)}`, style, weight };
+            faces.push(registration);
         }
         tokens[role] = `"${spec.family}", ${fallbacks[role]}`;
     }
-    return { bundled: true, faces, tokens, preload: tokens.body ? undefined : presetBodyFont[preset] };
+    // CSS resolves style before weight and prefers the last equivalent registration.
+    const registrations = [...bundledFonts.map(font => ({ family: font.family, file: font.file, route: `/assets/fonts/${font.file}`, style: font.style, weight: '100 900' })), ...faces];
+    for (const role of ['body', 'headings']) {
+        if (!families[role])
+            continue;
+        const target = role === 'body' ? 400 : preset === 'vice' ? 800 : 700;
+        const style = role === 'headings' && preset === 'vice' ? 'italic' : 'normal';
+        const family = registrations.filter(face => face.family === families[role]);
+        const exactStyle = family.filter(face => face.style === style);
+        const rank = (face) => {
+            const [min, max = min] = face.weight.split(' ').map(Number);
+            if (min <= target && max >= target)
+                return [0, 0];
+            if (target >= 400 && target <= 500) {
+                if (min > target && min <= 500)
+                    return [1, min - target];
+                return max < target ? [2, target - max] : [3, min - target];
+            }
+            if (target < 400)
+                return max < target ? [1, target - max] : [2, min - target];
+            return min > target ? [1, min - target] : [2, target - max];
+        };
+        const candidates = (exactStyle.length ? exactStyle : family).map((face, index) => ({ face, index, rank: rank(face) }));
+        candidates.sort((a, b) => a.rank[0] - b.rank[0] || a.rank[1] - b.rank[1] || b.index - a.index);
+        if (candidates[0])
+            preloadFaces.push(candidates[0].face);
+    }
+    return { bundled: true, faces, tokens, preload: tokens.body ? undefined : presetBodyFont[preset], preloadFaces };
+}
+/** Pin project font URLs to the same bytes that will be emitted by this build. */
+export async function prepareFontAssets(fonts) {
+    const files = new Map();
+    const assets = new Map();
+    for (const face of fonts.faces) {
+        let bytes = files.get(face.file);
+        if (!bytes) {
+            bytes = await readFile(face.file);
+            files.set(face.file, bytes);
+        }
+        const extension = path.extname(face.file).toLowerCase();
+        const name = path.basename(face.file, path.extname(face.file));
+        const hash = createHash('sha256').update(bytes).digest('hex');
+        face.route = `/assets/fonts/project/${name}-${hash}${extension}`;
+        assets.set(face.route, bytes);
+    }
+    return assets;
+}
+export function customFontPreloads(fonts) {
+    return [...new Map((fonts.preloadFaces ?? []).map(face => [face.route, { href: face.route, type: fontMediaType(face.file) }])).values()];
 }
 const face = (family, url, style, weight, format) => `@font-face{font-family:"${family}";src:url("${url}") format("${format}");font-style:${style};font-weight:${weight};font-display:swap}`;
 export function fontsCss(fonts) {

package/dist/frontmatter.js

@@ -4,7 +4,7 @@ import { validateCardMetadata } from './cards.js';
 import { resolveTaxonomy, validateTaxonomy, taxonomySchema } from './taxonomy.js';
 import { validateStandaloneSectionDeclarations } from './section-identity.js';
 export const nativePublicFields = new Set(['id', 'title', 'type', 'summary', 'description', 'language', 'locale', 'date', 'updated', 'verified', 'releaseVersion', 'availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'audiences', 'readerFilters', 'tags', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle']);
-export const protectedMetadataRoots = new Set(['shared', 'requires', 'standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
+export const protectedMetadataRoots = new Set(['shared', 'requires', 'standaloneSections', 'access', 'seo', 'markdownMetadata', 'variables', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'pdf', 'image', 'private', 'internal', 'card', 'displayText', 'publications']);
 const fieldTypes = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array']);
 const safePath = (value) => /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(value);
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -118,6 +118,8 @@ export function validateFrontmatter(frontmatter, config, file, source) {
         throw new Error(`${file}: shared must be true; use requires for restricted content`);
     if (frontmatter.shared === true && frontmatter.requires !== undefined)
         throw new Error(`${file}: declare shared: true or requires, not both`);
+    if (frontmatter.pdf !== undefined && typeof frontmatter.pdf !== 'boolean')
+        throw new Error(`${file}: pdf must be true or false`);
     validateCardMetadata(frontmatter.card, file);
     validateSubjectDeprecation(frontmatter.subjectDeprecation, file);
     validateAuthoredChange(frontmatter, file);
@@ -259,6 +261,7 @@ export function frontmatterSchema(config) {
         lifecycle: { type: 'string', minLength: 1, description: 'Editorial lifecycle of the document; validated by an opted-in external vocabulary.' },
         standaloneSections: { type: 'array', items: { oneOf: [{ type: 'string', minLength: 1 }, { type: 'object', additionalProperties: false, required: ['id', 'context'], properties: { id: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]{0,511}$' }, context: { const: 'section' } } }] }, uniqueItems: true, description: 'Page-specific standalone approval: a heading title approves contextual discovery with the page introduction; {id, context: section} approves the root level-two section slice for content export. IDs may be derived or explicitly anchored. Omitted means full-page reads.' },
         tocDepth: { type: 'integer', enum: [0, 2, 3, 4, 5, 6], description: 'Deepest heading shown in the page table of contents; 0 hides it. Defaults to 3.' },
+        pdf: { type: 'boolean', description: 'Controls the optional page print/PDF action. False suppresses its control and endpoint inputs; true follows the site setting. Site builds do not generate per-page PDFs.' },
         showVerified: { type: 'boolean', description: 'Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.' },
         showNavigationTabs: { type: 'boolean', description: 'Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.' },
         image: { type: 'string', pattern: '\\.(?:png|jpe?g)$', description: 'Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.' },
@@ -332,7 +335,7 @@ export function frontmatterReference(config, sectionsOnly = false) {
         'Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.', '',
         '## Categorize, connect, and present the page', '',
         'By default, `product`, `area`, and `subarea` are optional, nonempty string categories. They can come from project defaults and appear in the document manifest and search index. A matching configured reader facet makes each category a page filter; without that facet it remains taxonomy only. `operations` links a guide or reference to stable API operation IDs. On a guide or how-to page, `relatedApiReferences` names API reference page IDs to add cross links in both directions within the same publication. Tags help document collections find the page. Card settings change its preview when another page links to it; they do not change the destination. `subjectLifecycle` displays the status of the documented API or feature; `lifecycle` is available for the document\'s editorial state. `tocDepth` limits the HTML page table of contents; use 0 to hide it. `layout` picks the HTML page layout: `docs`, `wide`, `landing`, or `splash`. `showNavigationTabs` overrides the navigation tab bar for this page; landing and splash pages hide it by default. `image` replaces the generated link-preview image. `date` and `releaseVersion` can identify a changelog entry under the project\'s `frontmatter.changelogIdentifier` rule.', '',
-        ...table, ...nativeRows(['availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'image']), '',
+        ...table, ...nativeRows(['availability', 'product', 'area', 'subarea', 'operations', 'relatedApiReferences', 'tags', 'date', 'releaseVersion', 'subjectLifecycle', 'subjectDeprecation', 'change', 'lifecycle', 'card', 'standaloneSections', 'tocDepth', 'layout', 'showNavigationTabs', 'showVerified', 'pdf', 'image']), '',
         'Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.', '',
         'With `profiles.requireClassification: true`, every public source page in the shared enabled publications needs an explicit `shared: true` or `requires` declaration before customer selection. Defaults do not count. Shared pages may contain feature-specific sections wrapped in `<ForFeature>`; unwrapped text remains shared.', '',
         '## Control output details', '',

package/dist/highlight-languages.d.ts

@@ -0,0 +1,9 @@
+import type { LanguageRegistration } from 'shiki';
+export type LanguageFiles = {
+    grammarOrigin?: (index: number) => string;
+    onDependency?: (file: string) => void;
+};
+export declare function customHighlightLanguages(value: unknown, declaringFile: string | undefined, reserved: ReadonlySet<string>, options: LanguageFiles, reservedScopes?: ReadonlySet<string>): Promise<{
+    file: string;
+    grammar: LanguageRegistration;
+}[]>;

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-materialization.js

@@ -1,3 +1,4 @@
+import { renderCodeReference } from './code-references.js';
 import { documentKey, publicationKey } from './publication-identity.js';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
@@ -28,8 +29,8 @@ export async function materializePages({ variables, frontmatterConfig, publicati
         for (const other of linkDocuments.values())
             if (keyFor(other.frontmatter.id, doc.variant) === keyFor(other.frontmatter.id, other.variant))
                 local.set(other.frontmatter.id, other);
-        const parsed = parse.parse(doc.body);
-        const tree = await resolveApiEmbedTree(transformMdx(parsed, doc, local, snippets, variables, snippetUses, calloutTypes, base, readerFilters, frontmatterConfig, publications, badgeVariants, componentPlugins, linkDocuments), api, operationId => sourceForOperation(operationId, doc.variant), apiId => {
+        const parsed = doc.codeReference ? null : parse.parse(doc.body);
+        const tree = doc.codeReference ? renderCodeReference(doc.codeReference, doc, linkDocuments) : await resolveApiEmbedTree(transformMdx(parsed, doc, local, snippets, variables, snippetUses, calloutTypes, base, readerFilters, frontmatterConfig, publications, badgeVariants, componentPlugins, linkDocuments), api, operationId => sourceForOperation(operationId, doc.variant), apiId => {
             if (doc.featureContext?.grants)
                 throw new Error('Standalone API schema embeds require an explicitly scoped source and are not supported in profiled builds; select an operation instead');
             const definition = apiPlan.apiDefinitions[apiId];

package/dist/page-renderer.d.ts

@@ -36,6 +36,7 @@ export type PageShell = {
     themeSwitcher?: string;
     fontsCss?: boolean;
     preloadFont?: string;
+    preloadFonts?: import('./fonts.js').FontPreload[];
     masthead?: string;
     share?: {
         route: string;

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';
@@ -37,6 +38,8 @@ export function shareCardText(doc, config) {
     return { title, summary: String(summary), type: typeLabel(doc.frontmatter.type) };
 }
 export function typeLabel(type) {
+    if (type === 'code-reference')
+        return 'Code API reference';
     const words = String(type).split('-').filter(Boolean).map(word => word === 'api' ? 'API' : word);
     const label = words.join(' ');
     return label.charAt(0).toUpperCase() + label.slice(1);
@@ -60,6 +63,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 +194,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>` : ''}${(shell.preloadFonts ?? []).map(font => `<link rel="preload" href="${esc(font.href)}" as="font" type="${esc(font.type)}" crossorigin>`).join('')}<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 {};