@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/dist/content-workspace.js

@@ -1,18 +1,22 @@
+import { createSectionSelection } from './section-selection.js';
 import { documentKey } from './publication-identity.js';
 import { matchesFeatures } from './deployment-profile.js';
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { parse } from './content.js';
 import { planAuthoredDocuments } from './publication-plan.js';
+import { materializeCodeReferences } from './code-references.js';
 import { materializeApiReferences } from './api-publication-plan.js';
 import { explainSegments } from './config.js';
 import { validateSnippetConfig } from './snippets.js';
 const keyFor = documentKey;
 /** Shared source resolution. No website navigation, styles, hosting or provider setup. */
-export async function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }) {
+export async function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions, sectionSelection: suppliedSectionSelection }) {
+    const sectionSelection = suppliedSectionSelection ?? createSectionSelection(readerFilters, contentFilter, config.publications);
     const { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir } = await planAuthoredDocuments({
         base, basePath, config, variants, language, readerFilters, contentFilter, featureContext: loaded.deployment?.context, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions
     });
+    await materializeCodeReferences({ config, loaded, plan: { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir }, base, basePath, variants, language, readerFilters, contentFilter, dependencies: metadataDependencies, allowRouteCollisions });
     if (config.snippets !== undefined && (!config.snippets || typeof config.snippets !== 'object' || Array.isArray(config.snippets)))
         throw new Error('snippets must be a mapping');
     const snippets = new Map();
@@ -32,6 +36,7 @@ export async function prepareContentWorkspace({ base, basePath, config, loaded,
     });
     const { api, sourceForVariant, knownOperations } = apiPlan;
     for (const [key, doc] of docs) {
+        doc.sectionSelection = sectionSelection;
         doc.featureContext = loaded.deployment?.context;
         for (const operationId of doc.frontmatter.operations ?? []) {
             const known = knownOperations.get(operationId);
@@ -82,6 +87,6 @@ export async function prepareContentWorkspace({ base, basePath, config, loaded,
             throw new Error(`no OpenAPI source for ${variant.channel}/${variant.version} (${operationId})`);
         return { ...binding, sourceOperationId: operation.sourceOperationId };
     };
-    return { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir, snippets,
+    return { sectionSelection, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir, snippets,
         apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation };
 }

package/dist/deployment-profile.d.ts

@@ -34,7 +34,9 @@ export type ProfileResolution = {
 export declare function validateFeatureClassification(source: Record<string, unknown>, context: FeatureContext | undefined, label: string): void;
 export declare function featureRequirements(value: unknown, context: FeatureContext | undefined, label: string): FeatureRequirements | undefined;
 export declare function matchesFeatures(value: unknown, context: FeatureContext | undefined, label: string, kind?: 'page' | 'section'): boolean;
-/** Validate every condition, but never resolve a dependency in an excluded branch. */
+/** Evaluate a feature guard without expanding its children. */
+export declare function evaluateFeatureGuard(node: any, context: FeatureContext | undefined, file: string, ancestorIncluded?: boolean, record?: boolean): boolean | undefined;
+/** Compatibility entry point for consumers that only select feature grants. */
 export declare function pruneFeatureTree(tree: any, context: FeatureContext | undefined, file: string): any;
 /** Returned to the caller or written under .shoalrun, never a served artifact. */
 export declare function profileSelection(resolution: ProfileResolution | undefined): {

package/dist/deployment-profile.js

@@ -1,3 +1,4 @@
+import { pruneConditionalTree } from './conditional-tree.js';
 import { resolvePublication } from './compiler-config.js';
 import { publicationKey } from './publication-identity.js';
 import { readFile, lstat, realpath } from 'node:fs/promises';
@@ -69,26 +70,24 @@ export function matchesFeatures(value, context, label, kind = 'page') {
     context?.decisions.push({ kind, id: label, included, ...(requirement ? { requires: requirement } : {}) });
     return included;
 }
-/** Validate every condition, but never resolve a dependency in an excluded branch. */
+/** Evaluate a feature guard without expanding its children. */
+export function evaluateFeatureGuard(node, context, file, ancestorIncluded = true, record = true) {
+    if (node.name !== 'ForFeature')
+        return;
+    const label = `${file}:${node.position?.start?.line ?? 1}: <ForFeature>`;
+    const attributes = node.attributes ?? [];
+    if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || !attributes.length || attributes.some((item) => item.type !== 'mdxJsxAttribute' || !['allOf', 'anyOf'].includes(item.name) || typeof item.value !== 'string') || new Set(attributes.map((item) => item.name)).size !== attributes.length)
+        throw new Error(`${label} needs block content and distinct literal allOf/anyOf attributes`);
+    const requirements = Object.fromEntries(attributes.map((item) => [item.name, item.value.trim().split(/\s+/).filter(Boolean)]));
+    const target = !record && context ? { ...context, decisions: [] } : context;
+    const included = matchesFeatures(requirements, target, label, 'section');
+    if (!ancestorIncluded && target?.decisions.length)
+        target.decisions[target.decisions.length - 1].included = false;
+    return included;
+}
+/** Compatibility entry point for consumers that only select feature grants. */
 export function pruneFeatureTree(tree, context, file) {
-    const walk = (node, parentIncluded = true) => {
-        if (!node || typeof node !== 'object')
-            return [node];
-        if (node.name === 'ForFeature') {
-            const label = `${file}:${node.position?.start?.line ?? 1}: <ForFeature>`;
-            const attributes = node.attributes ?? [];
-            if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || !attributes.length || attributes.some((item) => item.type !== 'mdxJsxAttribute' || !['allOf', 'anyOf'].includes(item.name) || typeof item.value !== 'string') || new Set(attributes.map((item) => item.name)).size !== attributes.length)
-                throw new Error(`${label} needs block content and distinct literal allOf/anyOf attributes`);
-            const requirements = Object.fromEntries(attributes.map((item) => [item.name, item.value.trim().split(/\s+/).filter(Boolean)]));
-            const included = matchesFeatures(requirements, context, label, 'section');
-            if (!parentIncluded && context?.decisions.length)
-                context.decisions[context.decisions.length - 1].included = false;
-            const children = node.children.flatMap((child) => walk(child, parentIncluded && included));
-            return included && parentIncluded ? children : [];
-        }
-        return [{ ...node, ...(node.children ? { children: node.children.flatMap((child) => walk(child, parentIncluded)) } : {}) }];
-    };
-    return walk(tree)[0];
+    return pruneConditionalTree(tree, (node, ancestorIncluded) => evaluateFeatureGuard(node, context, file, ancestorIncluded));
 }
 /** Returned to the caller or written under .shoalrun, never a served artifact. */
 export function profileSelection(resolution) {

package/dist/fonts.d.ts

@@ -6,12 +6,18 @@ export type FontFace = {
     style: 'normal' | 'italic';
     weight: string;
 };
+export type FontPreload = {
+    href: string;
+    type: string;
+};
 export type SiteFonts = {
     bundled: boolean;
     faces: FontFace[];
     tokens: Partial<Record<FontRole, string>>;
     preload?: string;
+    preloadFaces?: FontFace[];
 };
+export declare const fontMediaType: (file: string) => string | undefined;
 export declare const bundledFonts: readonly [{
     readonly family: "Inter";
     readonly file: "inter.woff2";
@@ -51,4 +57,7 @@ export declare const bundledFonts: readonly [{
 }];
 export declare const bundledFontLicenses: string[];
 export declare function resolveFonts(value: unknown, preset: string, declaringFile: string): SiteFonts;
+/** Pin project font URLs to the same bytes that will be emitted by this build. */
+export declare function prepareFontAssets(fonts: SiteFonts): Promise<Map<string, Buffer>>;
+export declare function customFontPreloads(fonts: SiteFonts): FontPreload[];
 export declare function fontsCss(fonts: SiteFonts): string | undefined;

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

@@ -38,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);
@@ -192,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 ? (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>`;
+    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/palettes.d.ts

@@ -1,4 +1,4 @@
-export declare const paletteTokens: readonly ["text", "page", "surface", "link", "link-hover", "focus", "ink", "accent", "accent-contrast", "header-muted", "header-border", "border", "border-soft", "border-nested", "field-surface", "field-border", "field-accent", "presence-bg", "presence-text", "optional-bg", "optional-text", "muted", "nav-heading", "section-heading", "nav-text", "nav-hover", "nav-active", "nav-active-text", "deprecated-bg", "deprecated-text", "beta-bg", "beta-text", "development-bg", "development-text", "experimental-bg", "experimental-text", "emphasis", "summary", "code-bg", "code-text", "code-muted", "code-border", "code-block", "callout-line", "callout-bg", ...("callout-note-line" | "callout-tip-line" | "callout-important-line" | "callout-warning-line" | "callout-caution-line" | "callout-note-bg" | "callout-tip-bg" | "callout-important-bg" | "callout-warning-bg" | "callout-caution-bg" | "callout-note-text" | "callout-tip-text" | "callout-important-text" | "callout-warning-text" | "callout-caution-text")[], "strong-surface", "strong-text"];
+export declare const paletteTokens: readonly ["text", "page", "surface", "link", "link-hover", "focus", "ink", "accent", "accent-contrast", "header-muted", "header-border", "border", "border-soft", "border-nested", "field-surface", "field-border", "field-accent", "presence-bg", "presence-text", "optional-bg", "optional-text", "muted", "nav-heading", "section-heading", "nav-text", "nav-hover", "nav-active", "nav-active-text", "deprecated-bg", "deprecated-text", "beta-bg", "beta-text", "development-bg", "development-text", "experimental-bg", "experimental-text", "emphasis", "summary", "code-bg", "code-text", "code-muted", "code-border", "code-block", "callout-line", "callout-bg", ...("callout-warning-line" | "callout-note-line" | "callout-tip-line" | "callout-important-line" | "callout-caution-line" | "callout-warning-bg" | "callout-note-bg" | "callout-tip-bg" | "callout-important-bg" | "callout-caution-bg" | "callout-warning-text" | "callout-note-text" | "callout-tip-text" | "callout-important-text" | "callout-caution-text")[], "strong-surface", "strong-text"];
 export type Token = typeof paletteTokens[number];
 export type Mode = 'light' | 'dark';
 export type Palette = {

package/dist/publication-manifest.js

@@ -34,7 +34,7 @@ export function buildPublicationManifest({ configPublications, fictionalDocument
         ...(taxonomy ? { taxonomy } : {}),
         dependencies,
         ...(tabs.length ? { navigationTabs: tabs } : {}),
-        documents: rendered.map(({ doc, markdown, sections }) => ({ id: doc.frontmatter.id, demo: fictionalDocuments.has(doc), type: doc.frontmatter.type, title: doc.frontmatter.title, summary: doc.frontmatter.summary, subjectLifecycle: doc.frontmatter.subjectLifecycle ?? null, ...(doc.change ? { change: doc.change } : {}), ...(doc.subjectDeprecation ? { subjectDeprecation: doc.subjectDeprecation } : {}), variant: doc.variant, url: doc.route, markdownUrl: doc.markdownRoute, ...tabFor(doc), indexable: indexable(doc), ...(updatedFor(doc) ? { updated: updatedFor(doc) } : {}), ...(doc.frontmatter.availability ? { availability: doc.frontmatter.availability } : {}), ...(doc.frontmatter.verified ? { verified: doc.frontmatter.verified } : {}), contentDigest: doc.contentDigest, breadcrumbs: navigationPath(resolvedNavigation.get(publicationKey(doc.variant)) ?? [], doc.route), ...(doc.frontmatter.product !== undefined ? { product: doc.frontmatter.product } : {}), ...(doc.frontmatter.area !== undefined ? { area: doc.frontmatter.area } : {}), ...(doc.frontmatter.subarea !== undefined ? { subarea: doc.frontmatter.subarea } : {}), ...(readerFilters ? { readerFilters: doc.readerFilters ?? {} } : {}), cardTargets: cardUses.get(doc)?.targets ?? [], cardQueries: cardUses.get(doc)?.queries ?? [], snippets: [...new Set(snippetUses.filter(use => use.documentId === doc.frontmatter.id).map(use => use.id))], apiEmbeds: apiEmbedUses.filter(use => use.documentKey === keyFor(doc.frontmatter.id, doc.variant)).map(({ sourceFile, documentKey, ...request }) => request), focusedContractUrl: doc.focusedContractUrl ?? null, focusedContractBytes: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.bytes : null, focusedContractDigest: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.digest : null, sections: (sections ?? []).map(({ content, ...record }) => record), ...markdownSize(markdown), digest: digest(markdown) })),
+        documents: rendered.map(({ doc, markdown, sections }) => ({ id: doc.frontmatter.id, demo: fictionalDocuments.has(doc), type: doc.frontmatter.type, title: doc.frontmatter.title, summary: doc.frontmatter.summary, subjectLifecycle: doc.frontmatter.subjectLifecycle ?? null, ...(doc.change ? { change: doc.change } : {}), ...(doc.subjectDeprecation ? { subjectDeprecation: doc.subjectDeprecation } : {}), variant: doc.variant, url: doc.route, markdownUrl: doc.markdownRoute, ...tabFor(doc), indexable: indexable(doc), ...(updatedFor(doc) ? { updated: updatedFor(doc) } : {}), ...(doc.frontmatter.availability ? { availability: doc.frontmatter.availability } : {}), ...(doc.frontmatter.verified ? { verified: doc.frontmatter.verified } : {}), contentDigest: doc.contentDigest, breadcrumbs: navigationPath(resolvedNavigation.get(publicationKey(doc.variant)) ?? [], doc.route), ...(doc.frontmatter.product !== undefined ? { product: doc.frontmatter.product } : {}), ...(doc.frontmatter.area !== undefined ? { area: doc.frontmatter.area } : {}), ...(doc.frontmatter.subarea !== undefined ? { subarea: doc.frontmatter.subarea } : {}), ...(readerFilters ? { readerFilters: doc.readerFilters ?? {} } : {}), cardTargets: cardUses.get(doc)?.targets ?? [], cardQueries: cardUses.get(doc)?.queries ?? [], snippets: [...new Set(snippetUses.filter(use => (use.documentKey ? use.documentKey === keyFor(doc.frontmatter.id, doc.variant) : use.documentId === doc.frontmatter.id)).map(use => use.id))], apiEmbeds: apiEmbedUses.filter(use => use.documentKey === keyFor(doc.frontmatter.id, doc.variant)).map(({ sourceFile, documentKey, ...request }) => request), focusedContractUrl: doc.focusedContractUrl ?? null, focusedContractBytes: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.bytes : null, focusedContractDigest: doc.focusedContractUrl ? focusedContracts.get(doc.focusedContractUrl)?.digest : null, sections: (sections ?? []).map(({ content, ...record }) => record), ...markdownSize(markdown), digest: digest(markdown) })),
         operations,
         relationships: publishedRelationships,
         redirects,

package/dist/publication-render.d.ts

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

package/dist/publication-render.js

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

package/dist/representation-tree.js

@@ -20,8 +20,14 @@ export function publicTree(tree, representation, documentRoutes, mode = 'light',
                     element('div', { 'data-component-content': '' }, children)
                 ])];
         }
-        if (node.type === 'docRepresentation')
-            return node.representation === representation ? node.children.flatMap(walk) : [];
+        if (node.type === 'docRepresentation') {
+            if (node.representation !== representation)
+                return [];
+            const children = node.children.flatMap(walk);
+            // Mark HTML-only content so agent-parity checks can distinguish intentional
+            // format-specific prose from accidental content loss in the Markdown twin.
+            return representation === 'html' ? [element('div', { 'data-markdown-ignore': '' }, children)] : children;
+        }
         if (node.type === 'docCookbookChooser') {
             const prompt = node.mode === 'single' ? 'Choose one recipe.' : 'Choose one or more recipes.';
             const details = (option) => [option.when ? `Use when: ${option.when}` : option.summary, option.needs ? `You need: ${option.needs}` : '', option.outcome ? `You will have: ${option.outcome}` : ''].filter(Boolean);
@@ -66,6 +72,10 @@ export function publicTree(tree, representation, documentRoutes, mode = 'light',
         if (node.type === 'docReaderFilter') {
             return representation === 'markdown' ? [] : [element('div', { className: ['reader-filter-slot'], 'data-reader-filter': JSON.stringify(node.control) }, [])];
         }
+        if (node.type === 'table' && node.data?.referenceTableLabel && representation === 'html') {
+            const table = { ...node, children: node.children.flatMap(walk) };
+            return [element('div', { className: ['code-reference-table-scroll'], role: 'region', 'aria-label': node.data.referenceTableLabel, tabIndex: 0 }, [table])];
+        }
         if (node.type === 'docTable') {
             const table = node.children.flatMap(walk);
             if (representation === 'markdown')

package/dist/search-query.js

@@ -64,7 +64,7 @@ export async function queryBuiltSite(directory, query, options = {}) {
             return [];
         const termScore = (term) => weight(title, term, title.startsWith(term.term) ? 12 : 8, true) || weight(summary, term, 4) || (headings.some(heading => match(heading, term)) ? 3 : 0) || weight(body, term, 1);
         let score = terms.reduce((total, term) => total + termScore(term), 0);
-        const contentScore = terms.filter(term => !fallbackStopWords.has(term.term)).reduce((total, term) => total + termScore(term), 0);
+        let contentScore = terms.filter(term => !fallbackStopWords.has(term.term)).reduce((total, term) => total + termScore(term), 0);
         const prominentMatches = terms.filter(term => !fallbackStopWords.has(term.term) && (matchTitle(title, term) || match(summary, term) || headings.some(heading => match(heading, term)))).length;
         const section = terms.every(term => matchTitle(title, term)) ? undefined : doc.headings.find((heading, at) => terms.every(term => match(headings[at], term)));
         // Use only query terms with meaning, and require a unique matching section.
@@ -77,8 +77,10 @@ export async function queryBuiltSite(directory, query, options = {}) {
         // older indexes and unreviewed sections conservatively retain the full page.
         const selected = candidates.length === 1 && candidates[0].standalone === true ? candidates[0] : undefined;
         // A complete multiword section-title match outranks incidental page-title words.
-        if (meaningful.length >= 2 && candidates.some(candidate => meaningful.every(term => match(candidate.title.toLocaleLowerCase(), term))))
+        if (meaningful.length >= 2 && candidates.some(candidate => meaningful.every(term => match(candidate.title.toLocaleLowerCase(), term)))) {
             score += 20;
+            contentScore += 20;
+        }
         const { product, channel, version, language } = parsePublicationKey(doc.variant);
         const tokens = selected?.markdownTokens ?? doc.markdownTokens;
         const read = { tool: selected ? 'get_section' : 'get_page', arguments: {
@@ -87,15 +89,20 @@ export async function queryBuiltSite(directory, query, options = {}) {
             } };
         return [{ score, contentScore, prominentMatches, matched: matched.length, partialMatched: matched.filter(term => !fallbackStopWords.has(term.term)).length, id: doc.id, type: doc.type, title: doc.title, summary: doc.summary, url: section ? `${doc.url}#${section.id}` : doc.url, markdownUrl: selected?.markdownUrl ?? doc.markdownUrl, pageMarkdownUrl: doc.markdownUrl, read, ...(tokens !== undefined ? { markdownTokens: tokens, markdownBytes: selected?.markdownBytes ?? doc.markdownBytes, markdownTokenEncoding: doc.markdownTokenEncoding } : {}), ...(selected || section ? { section: selected?.title ?? section?.title } : {}), snippet: excerpt(doc.text, terms.flatMap(unit => [unit.term, ...unit.alternatives])) }];
     });
-    const complete = hits.filter(hit => hit.matched === terms.length);
+    const contentTerms = terms.filter(term => !fallbackStopWords.has(term.term)).length;
+    // Filler words shape the sentence, not the subject. A page that covers every
+    // content term is complete even when it omits "how", "do", or "the"; otherwise
+    // a page that happens to repeat filler words can hide the focused result.
+    const complete = contentTerms === 0
+        ? hits.filter(hit => hit.matched === terms.length)
+        : hits.filter(hit => hit.partialMatched === contentTerms);
     // Relax the all-words gate only when complete matches are entirely incidental
     // body matches. A near-complete result must cover all but one content term and
     // have a stronger non-filler field score. Title/summary/heading matches on any
     // complete result preserve the original preference; filler cannot earn promotion.
-    const contentTerms = terms.filter(term => !fallbackStopWords.has(term.term)).length;
     const bestCompleteContent = Math.max(...complete.map(hit => hit.contentScore));
     const stronger = complete.length && contentTerms >= 3 && complete.every(hit => hit.prominentMatches === 0)
-        ? hits.filter(hit => hit.matched < terms.length && hit.partialMatched >= contentTerms - 1
+        ? hits.filter(hit => hit.partialMatched < contentTerms && hit.partialMatched >= contentTerms - 1
             && hit.prominentMatches > 0 && hit.contentScore > bestCompleteContent) : [];
     const ranked = complete.length ? [...complete, ...stronger] : hits.filter(hit => hit.partialMatched > 0);
     // In partial fallback, one extra incidental word must not outweigh a focused
@@ -114,7 +121,7 @@ export async function queryBuiltSite(directory, query, options = {}) {
             if (aNear && a.contentScore !== b.contentScore)
                 return b.contentScore - a.contentScore;
         }
-        return (complete.length ? b.matched - a.matched : b.partialMatched - a.partialMatched) || b.score - a.score || a.title.localeCompare(b.title) || a.id.localeCompare(b.id);
+        return (complete.length ? b.contentScore - a.contentScore : b.partialMatched - a.partialMatched) || b.score - a.score || a.title.localeCompare(b.title) || a.id.localeCompare(b.id);
     });
     const publication = parsePublicationKey(variants[0]);
     return { status: 'ok', query: query.trim(), publication, total: ranked.length, matchMode: stronger.length ? 'mixed' : complete.length ? 'all' : 'partial', results: ranked.slice(0, limit).map(({ matched, partialMatched, contentScore, prominentMatches, ...result }) => result) };

package/dist/section-selection.d.ts

@@ -0,0 +1,29 @@
+import { type ReaderFiltersConfig, type ReaderSelection } from './reader-filters.js';
+import type { CompilerPublicationsConfig } from './compiler-config.js';
+import type { Document } from './content-source.js';
+export type SectionSelection = {
+    facets?: ReaderFiltersConfig;
+    selection?: ReaderSelection;
+    decisions: Map<string, Record<string, unknown>>;
+    warnings: Map<string, {
+        code: string;
+        message: string;
+    }>;
+    hasConditions: boolean;
+    publications?: CompilerPublicationsConfig;
+};
+export declare function createSectionSelection(facets?: ReaderFiltersConfig, selection?: ReaderSelection, publications?: CompilerPublicationsConfig): SectionSelection;
+/** Share publication validation with pruning so receipts reflect every build-time ancestor. */
+export declare function evaluatePublicationGuard(node: any, doc: Document, file: string, publications?: CompilerPublicationsConfig): boolean | undefined;
+export declare function pruneSelectedTree(tree: any, doc: Document, file?: string, record?: boolean): any;
+export declare function warnReaderSection(doc: Document, file: string, line: number, requirements: ReaderSelection): void;
+export declare function sectionSelectionReport(context: SectionSelection): {
+    selection: ReaderSelection | null;
+    decisions: Record<string, unknown>[];
+    warnings: {
+        code: string;
+        message: string;
+    }[];
+};
+/** Keep receipts private, atomic, and keyed by artifact so nested exports can't replace a site's record. */
+export declare function writeSectionSelectionReport(base: string, context: SectionSelection, artifact: Record<string, unknown>): Promise<void>;

package/dist/section-selection.js

@@ -0,0 +1,92 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, writeFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { pruneConditionalTree } from './conditional-tree.js';
+import { evaluateFeatureGuard } from './deployment-profile.js';
+import { matchesSectionContentFilter } from './content-filter.js';
+import { validateReaderSelection } from './reader-filters.js';
+import { documentKey } from './publication-identity.js';
+export function createSectionSelection(facets, selection, publications) {
+    return { facets, selection, publications, decisions: new Map(), warnings: new Map(), hasConditions: false };
+}
+/** Share publication validation with pruning so receipts reflect every build-time ancestor. */
+export function evaluatePublicationGuard(node, doc, file, publications) {
+    if (node.name !== 'ForPublication')
+        return;
+    const attributes = node.attributes ?? [];
+    const allowed = ['product', 'channel', 'version', 'language'];
+    if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || !attributes.length || attributes.some((item) => item.type !== 'mdxJsxAttribute' || typeof item.value !== 'string' || !allowed.includes(item.name) || !item.value.trim()) || new Set(attributes.map((item) => item.name)).size !== attributes.length)
+        throw new Error(`${file}: <ForPublication> needs block content and distinct literal product, channel, version, or language attributes`);
+    const product = attributes.find((item) => item.name === 'product')?.value ?? doc.variant.product;
+    for (const item of attributes) {
+        const catalog = item.name === 'product' ? publications?.products : item.name === 'channel' ? publications?.channels : item.name === 'version' ? (product ? publications?.products?.[product]?.versions : publications?.versions) : undefined;
+        if (publications && item.name !== 'language' && (!catalog || !Object.hasOwn(catalog, item.value)))
+            throw new Error(`${file}: <ForPublication> names unknown ${item.name} ${item.value}`);
+    }
+    return !attributes.some((item) => doc.variant[item.name] !== item.value);
+}
+export function pruneSelectedTree(tree, doc, file = doc.file, record = true) {
+    const context = doc.sectionSelection;
+    return pruneConditionalTree(tree, (node, ancestorIncluded) => {
+        if (node.name === 'ForPublication')
+            return evaluatePublicationGuard(node, doc, file, context?.publications);
+        if (node.name === 'ForFeature')
+            return evaluateFeatureGuard(node, doc.featureContext, file, ancestorIncluded, record);
+        if (node.name !== 'ForFacet')
+            return;
+        const label = `${file}:${node.position?.start?.line ?? 1}: <ForFacet>`;
+        const attributes = node.attributes ?? [];
+        if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || !attributes.length || attributes.some((item) => item.type !== 'mdxJsxAttribute' || typeof item.value !== 'string' || !item.value.trim()) || new Set(attributes.map((item) => item.name)).size !== attributes.length)
+            throw new Error(`${label} needs block content and distinct nonempty literal facet attributes`);
+        if (!context?.facets)
+            throw new Error(`${label} needs configured readerFilters.facets`);
+        const requirements = validateReaderSelection(Object.fromEntries(attributes.map((item) => [item.name, item.value.trim().split(/\s+/)])), context.facets, label);
+        context.hasConditions = true;
+        const match = matchesSectionContentFilter(requirements, context.selection);
+        if (record) {
+            const line = node.position?.start?.line ?? 1;
+            const key = JSON.stringify([documentKey(doc.frontmatter.id, doc.variant), file, line, requirements, ancestorIncluded]);
+            context.decisions.set(key, { documentId: doc.frontmatter.id, publication: doc.variant, source: file, line, requirements, localMatch: match, included: ancestorIncluded && match, reason: !ancestorIncluded ? 'ancestor-excluded' : match ? 'matched' : 'facet-mismatch' });
+        }
+        return match;
+    });
+}
+export function warnReaderSection(doc, file, line, requirements) {
+    const context = doc.sectionSelection;
+    if (!context?.selection)
+        return;
+    const overlap = Object.keys(requirements).filter(facet => context.selection?.[facet]);
+    if (!overlap.length)
+        return;
+    const key = JSON.stringify([file, line, overlap]);
+    if (context.warnings.has(key))
+        return;
+    const message = `${file}:${line}: <ReaderSection> uses build-selected facet(s) ${overlap.join(', ')} but only changes reader visibility; its content remains in the output. Use <ForFacet> to omit unmatched content during this build.`;
+    context.warnings.set(key, { code: 'reader-section-build-facet', message });
+    process.stderr.write(`warning [reader-section-build-facet] ${message}\n`);
+}
+export function sectionSelectionReport(context) {
+    return { selection: context.selection ?? null, decisions: [...context.decisions.values()], warnings: [...context.warnings.values()] };
+}
+/** Keep receipts private, atomic, and keyed by artifact so nested exports can't replace a site's record. */
+export async function writeSectionSelectionReport(base, context, artifact) {
+    const folder = path.join(base, '.shoalrun');
+    await mkdir(folder, { recursive: true });
+    const file = path.join(folder, 'content-selection.json');
+    const key = createHash('sha256').update(JSON.stringify(artifact.target)).digest('hex');
+    const receipt = { schemaVersion: 1, ...artifact, ...sectionSelectionReport(context) };
+    const receipts = path.join(folder, 'content-selection');
+    await mkdir(receipts, { recursive: true });
+    const atomic = async (destination, value) => {
+        const temporary = path.join(folder, `.content-selection-${randomUUID()}.json`);
+        try {
+            await writeFile(temporary, JSON.stringify(value, null, 2) + '\n');
+            await rename(temporary, destination);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    };
+    await atomic(path.join(receipts, key + '.json'), receipt);
+    await atomic(file, { ...receipt, receipt: `content-selection/${key}.json` });
+}

package/dist/snippets.d.ts

@@ -13,6 +13,7 @@ export type SnippetUse = {
     id: string;
     file: string;
     documentId: string;
+    documentKey?: string;
 };
 export declare function validateSnippetConfig(id: string, definition: any): Record<string, SnippetVariable>;
 export declare function snippetAttribute(attribute: any, label: string): unknown;