@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/dist/publication-manifest.d.ts

@@ -0,0 +1,229 @@
+import type { ApiEmbedUse } from './api-embeds.js';
+import type { CardUse, validateRelationships } from './cards.js';
+import type { Document, Variant } from './content.js';
+import type { DiagramAsset } from './diagrams.js';
+import type { materializePages } from './page-materialization.js';
+import { type resolveProjectNavigation } from './project-navigation.js';
+import type { ReaderFiltersConfig } from './reader-filters.js';
+import type { Taxonomy } from './taxonomy.js';
+import type { SnippetUse } from './snippets.js';
+export declare function buildPublicationManifest({ fictionalDocuments, configDigest, synonyms, basePath, publicPath, readerFilters, taxonomy, dependencies, rendered, resolvedNavigation, cardUses, snippetUses, apiEmbedUses, focusedContracts, operations, publishedRelationships, redirects, apiSources, siteOrigin, siteIndexing, siteUpdated, diagramAssets, heroImages, faviconRoute, catalog }: {
+    fictionalDocuments: Set<Document>;
+    configDigest: string;
+    synonyms: unknown[];
+    basePath: string;
+    publicPath: (route: string) => string;
+    readerFilters?: ReaderFiltersConfig;
+    taxonomy?: Taxonomy;
+    dependencies: string[];
+    rendered: Awaited<ReturnType<typeof materializePages>>['rendered'];
+    resolvedNavigation: Map<string, ReturnType<typeof resolveProjectNavigation>>;
+    cardUses: Map<Document, CardUse>;
+    snippetUses: SnippetUse[];
+    apiEmbedUses: ApiEmbedUse[];
+    focusedContracts: Map<string, {
+        bytes: number;
+        digest: string;
+    }>;
+    operations: Awaited<ReturnType<typeof materializePages>>['operations'];
+    publishedRelationships: Array<ReturnType<typeof validateRelationships>[number] & {
+        variant: Variant;
+    }>;
+    redirects: Array<{
+        from: string;
+        to: string;
+        markdownFrom: string;
+        markdownTo: string;
+        status: number;
+    }>;
+    apiSources: Array<{
+        apiId: string;
+        channel: string;
+        version: string;
+        endpoint: string | null;
+        referenceUrl: string;
+        sourceUrl: string;
+        mediaType: string;
+    }>;
+    siteOrigin?: string;
+    siteIndexing: boolean;
+    siteUpdated?: string;
+    diagramAssets: DiagramAsset[];
+    heroImages: Map<string, string>;
+    faviconRoute: string;
+    catalog: unknown;
+}): {
+    manifest: {
+        documents: ({
+            digest: string;
+            markdownBytes: number;
+            markdownTokens: number;
+            markdownTokenEncoding: string;
+            cardTargets: string[];
+            cardQueries: import("./cards.js").CardRequest[];
+            snippets: string[];
+            apiEmbeds: {
+                component: "ApiExample" | "ApiSchema";
+                operation?: string;
+                api?: string;
+                kind?: "request" | "response";
+                mediaType?: string;
+                status?: string;
+                example?: string;
+                schema?: string;
+            }[];
+            focusedContractUrl: string | null;
+            focusedContractBytes: number | null | undefined;
+            focusedContractDigest: string | null | undefined;
+            sections: {
+                id: string;
+                title: string;
+                depth: 2;
+                standalone?: true;
+                markdownUrl: string;
+                parentMarkdownUrl: string;
+                parentDigest: string;
+                digest: string;
+                markdownBytes: number;
+                markdownTokens: number;
+                markdownTokenEncoding: string;
+            }[];
+            readerFilters?: import("./reader-filters.js").ReaderSelection | undefined;
+            subarea?: string | string[] | undefined;
+            area?: string | string[] | undefined;
+            product?: string | undefined;
+            contentDigest: string | undefined;
+            breadcrumbs: {
+                label: string;
+                url?: string;
+            }[];
+            verified?: string | undefined;
+            updated?: string | undefined;
+            indexable: boolean;
+            navigationTab: {
+                id: string;
+                label: string;
+                variant: Variant;
+                url: string;
+                markdownUrl: string;
+                indexUrl: string;
+            };
+            variant: Variant;
+            url: string;
+            markdownUrl: string;
+            subjectDeprecation?: import("./subject-deprecation.js").ResolvedSubjectDeprecation | undefined;
+            change?: import("./authored-change.js").ResolvedChange | undefined;
+            id: string;
+            demo: boolean;
+            type: string;
+            title: string;
+            summary: string;
+            subjectLifecycle: "deprecated" | "in-development" | "beta" | "experimental" | null;
+        } | {
+            digest: string;
+            markdownBytes: number;
+            markdownTokens: number;
+            markdownTokenEncoding: string;
+            cardTargets: string[];
+            cardQueries: import("./cards.js").CardRequest[];
+            snippets: string[];
+            apiEmbeds: {
+                component: "ApiExample" | "ApiSchema";
+                operation?: string;
+                api?: string;
+                kind?: "request" | "response";
+                mediaType?: string;
+                status?: string;
+                example?: string;
+                schema?: string;
+            }[];
+            focusedContractUrl: string | null;
+            focusedContractBytes: number | null | undefined;
+            focusedContractDigest: string | null | undefined;
+            sections: {
+                id: string;
+                title: string;
+                depth: 2;
+                standalone?: true;
+                markdownUrl: string;
+                parentMarkdownUrl: string;
+                parentDigest: string;
+                digest: string;
+                markdownBytes: number;
+                markdownTokens: number;
+                markdownTokenEncoding: string;
+            }[];
+            readerFilters?: import("./reader-filters.js").ReaderSelection | undefined;
+            subarea?: string | string[] | undefined;
+            area?: string | string[] | undefined;
+            product?: string | undefined;
+            contentDigest: string | undefined;
+            breadcrumbs: {
+                label: string;
+                url?: string;
+            }[];
+            verified?: string | undefined;
+            updated?: string | undefined;
+            indexable: boolean;
+            navigationTab?: undefined;
+            variant: Variant;
+            url: string;
+            markdownUrl: string;
+            subjectDeprecation?: import("./subject-deprecation.js").ResolvedSubjectDeprecation | undefined;
+            change?: import("./authored-change.js").ResolvedChange | undefined;
+            id: string;
+            demo: boolean;
+            type: string;
+            title: string;
+            summary: string;
+            subjectLifecycle: "deprecated" | "in-development" | "beta" | "experimental" | null;
+        })[];
+        operations: Record<string, {
+            id: string;
+            type: string;
+            channel: string;
+            version: string;
+            language: string;
+            url: string;
+            markdownUrl: string;
+            focusedContractUrl?: string;
+        }[]>;
+        relationships: (import("./cards.js").Relationship & {
+            variant: Variant;
+        })[];
+        redirects: {
+            from: string;
+            to: string;
+            markdownFrom: string;
+            markdownTo: string;
+            status: number;
+        }[];
+        apiSources: {
+            apiId: string;
+            channel: string;
+            version: string;
+            endpoint: string | null;
+            referenceUrl: string;
+            sourceUrl: string;
+            mediaType: string;
+        }[];
+        navigationTabs?: {
+            id: string;
+            label: string;
+            variant: Variant;
+            url: string;
+            markdownUrl: string;
+            indexUrl: string;
+        }[] | undefined;
+        dependencies: string[];
+        taxonomy?: Taxonomy | undefined;
+        readerFacets?: Record<string, import("./reader-filters.js").ReaderFacet> | undefined;
+        sitemap?: string | undefined;
+        basePath: string;
+        searchSynonyms?: unknown[] | undefined;
+        schemaVersion: number;
+        configDigest: string;
+    };
+    headers: Record<string, Record<string, string>>;
+    sitemaps: Map<string, string>;
+};

package/dist/publication-manifest.js

@@ -0,0 +1,53 @@
+import { markdownSize } from './markdown-size.js';
+import { createHash } from 'node:crypto';
+import { navigationPath, navigationTab, navigationTabRecord } from './project-navigation.js';
+import { sitemapFiles } from './sitemap.js';
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+export function buildPublicationManifest({ fictionalDocuments, configDigest, synonyms, basePath, publicPath, readerFilters, taxonomy, dependencies, rendered, resolvedNavigation, cardUses, snippetUses, apiEmbedUses, focusedContracts, operations, publishedRelationships, redirects, apiSources, siteOrigin, siteIndexing, siteUpdated, diagramAssets, heroImages, faviconRoute, catalog }) {
+    const indexable = (doc) => siteIndexing && doc.frontmatter.seo?.noindex !== true;
+    const updatedFor = (doc) => doc.frontmatter.updated ?? siteUpdated;
+    const tabs = [...resolvedNavigation].flatMap(([key, nodes]) => {
+        const [channel, version, language] = key.split('|');
+        return nodes.filter(node => node.tab).map(node => navigationTabRecord(node, { channel, version, language }, basePath));
+    });
+    const tabFor = (doc) => {
+        const node = navigationTab(resolvedNavigation.get(`${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`) ?? [], doc.route);
+        return node ? { navigationTab: navigationTabRecord(node, doc.variant, basePath) } : {};
+    };
+    const sitemaps = siteOrigin && siteIndexing ? sitemapFiles(siteOrigin, rendered.filter(page => indexable(page.doc)).map(page => ({ route: page.doc.route, updated: updatedFor(page.doc) })).concat([{ route: publicPath('/llms.txt'), updated: undefined }]), {}, basePath) : new Map();
+    const manifest = {
+        schemaVersion: 1,
+        configDigest: configDigest,
+        ...(synonyms.length ? { searchSynonyms: synonyms } : {}),
+        basePath,
+        ...(sitemaps.size ? { sitemap: publicPath('/sitemap.xml') } : {}),
+        ...(readerFilters ? { readerFacets: readerFilters.facets } : {}),
+        ...(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.verified ? { verified: doc.frontmatter.verified } : {}), contentDigest: doc.contentDigest, breadcrumbs: navigationPath(resolvedNavigation.get(`${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`) ?? [], 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) })),
+        operations,
+        relationships: publishedRelationships,
+        redirects,
+        apiSources
+    };
+    const headers = {
+        [publicPath('/llms.min.txt')]: { 'Content-Type': 'text/plain; charset=utf-8' },
+        [publicPath('/llms.txt')]: { 'Content-Type': 'text/plain; charset=utf-8' },
+        ...Object.fromEntries(tabs.map(tab => [tab.indexUrl, { 'Content-Type': 'text/plain; charset=utf-8' }])),
+        ...Object.fromEntries(['/documents.json', '/build-info.json'].flatMap(route => [...new Set([route, publicPath(route)])].map(url => [url, { 'Content-Type': 'application/json' }]))),
+        [publicPath('/robots.txt')]: { 'Content-Type': 'text/plain; charset=utf-8' },
+        ...Object.fromEntries([...sitemaps.keys()].map(route => [route, { 'Content-Type': 'application/xml; charset=utf-8' }])),
+        ...Object.fromEntries(rendered.map(({ doc }) => [doc.route, { 'Content-Type': 'text/html; charset=utf-8', Link: `<${doc.markdownRoute}>; rel="alternate"; type="text/markdown"` }])),
+        ...Object.fromEntries(rendered.map(({ doc, markdown }, index) => [doc.markdownRoute, { 'Content-Type': 'text/markdown; charset=utf-8', 'Cache-Control': 'public, max-age=0, must-revalidate', ETag: `"${digest(markdown)}"`, Link: `<${siteOrigin ?? ''}${doc.route}>; rel="canonical", <${publicPath('/documents.json')}#/documents/${index}>; rel="describedby"; type="application/json"` }])),
+        ...Object.fromEntries(apiSources.map(item => [item.sourceUrl, { 'Content-Type': item.mediaType }])),
+        ...Object.fromEntries([...focusedContracts].map(([url, contract]) => [url, { 'Content-Type': 'application/json', 'Cache-Control': 'public, max-age=31536000, immutable', ETag: `"${contract.digest}"` }])),
+        ...Object.fromEntries(diagramAssets.map(asset => [asset.route, { 'Content-Type': 'image/svg+xml', 'Content-Security-Policy': 'sandbox', 'X-Content-Type-Options': 'nosniff' }])),
+        ...Object.fromEntries([...heroImages.keys()].filter(route => route.toLowerCase().endsWith('.svg')).map(route => [route, { 'Content-Type': 'image/svg+xml', 'Content-Security-Policy': 'sandbox', 'X-Content-Type-Options': 'nosniff' }])),
+        ...(faviconRoute.endsWith('.svg') ? { [faviconRoute]: { 'Content-Type': 'image/svg+xml', 'Content-Security-Policy': 'sandbox', 'X-Content-Type-Options': 'nosniff' } } : {})
+    };
+    if (catalog)
+        headers[publicPath('/.well-known/api-catalog')] = { 'Content-Type': 'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"' };
+    return { manifest, headers, sitemaps };
+}

package/dist/publication-plan.d.ts

@@ -0,0 +1,34 @@
+import { type Document, type Variant } from './content.js';
+import type { PublicationRoutingConfig } from './content-source.js';
+import { type MetadataProvider } from './metadata-provider.js';
+import { type ReaderSelection, type ReaderFiltersConfig } from './reader-filters.js';
+import { type CompilerSiteConfig, type CompilerPublicationsConfig } from './compiler-config.js';
+export type AuthoredPublicationConfig = PublicationRoutingConfig & {
+    site: CompilerSiteConfig;
+    publications: CompilerPublicationsConfig;
+    frontmatter?: unknown;
+};
+export type AuthoredPublicationPlan = {
+    contentDir: string;
+    docs: Map<string, Document>;
+    knownDocumentIds: Set<string>;
+    knownDocumentTypes: Map<string, string>;
+    authoredOperationIds: Set<string>;
+    routeOwners: Map<string, string>;
+};
+export declare function planAuthoredDocuments({ base, basePath, config, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }: {
+    base: string;
+    basePath: string;
+    config: AuthoredPublicationConfig;
+    variants: Variant[];
+    language: string;
+    readerFilters?: ReaderFiltersConfig;
+    contentFilter?: ReaderSelection;
+    metadataProvider?: {
+        provide: MetadataProvider;
+    };
+    metadataDependencies: Set<string>;
+    allowRouteCollisions?: boolean;
+    sourceOverrides?: ReadonlyMap<string, string>;
+    authoringFiles?: ReadonlySet<string>;
+}): Promise<AuthoredPublicationPlan>;

package/dist/publication-plan.js

@@ -0,0 +1,85 @@
+import { matchesContentFilter } from './content-filter.js';
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { markdownRoute, readDocument, routeFor } from './content.js';
+import { applyFormattingLocale, validateFrontmatter } from './frontmatter.js';
+import { mergeProvidedMetadata } from './metadata-provider.js';
+import { pageReaderFilters } from './reader-filters.js';
+import { configField } from './compiler-config.js';
+const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+async function files(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const nested = await Promise.all(entries.map(async (entry) => entry.isDirectory() ? files(path.join(dir, entry.name)) : /\.mdx?$/.test(entry.name) ? [path.join(dir, entry.name)] : []));
+    return nested.flat().sort();
+}
+export async function planAuthoredDocuments({ base, basePath, config, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }) {
+    const docs = new Map();
+    const knownDocumentIds = new Set();
+    const knownDocumentTypes = new Map();
+    const authoredOperationIds = new Set();
+    const routeOwners = new Map();
+    const contentDir = path.resolve(base, config.site.contentDir ?? 'content');
+    const authoredFiles = new Set(await files(contentDir));
+    // Authoring previews can supply absent pages without creating placeholders.
+    // Virtual sources remain inside the configured authored content directory.
+    for (const file of sourceOverrides?.keys() ?? []) {
+        const relative = path.relative(contentDir, file);
+        if (path.isAbsolute(file) && relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) && /\.mdx?$/.test(file))
+            authoredFiles.add(file);
+    }
+    for (const file of [...authoredFiles].sort()) {
+        const { frontmatter, sourceFrontmatter, body } = await readDocument(file, config.frontmatter, metadataProvider ? async (source) => {
+            const result = await metadataProvider.provide({ file, source, projectRoot: base });
+            const merged = mergeProvidedMetadata(source, result, file);
+            for (const dependency of merged.dependencies)
+                metadataDependencies.add(dependency);
+            return merged.page;
+        } : undefined, sourceOverrides?.get(file));
+        frontmatter.language ??= language;
+        applyFormattingLocale(frontmatter, config.frontmatter, sourceFrontmatter);
+        validateFrontmatter(frontmatter, config.frontmatter, file, sourceFrontmatter);
+        const pagePublications = frontmatter.publications;
+        if (pagePublications) {
+            if (sourceFrontmatter.channel !== undefined || sourceFrontmatter.version !== undefined)
+                throw new Error(`${file}: use publications instead of page-level channel or version`);
+            for (const publication of pagePublications) {
+                if (!config.publications.channels[publication.channel] || !config.publications.versions[publication.version])
+                    throw new Error(`${file}: unknown publication ${publication.channel}/${publication.version}`);
+                const enforced = configField(config.frontmatter, 'enforced');
+                if (configField(enforced, 'channel') && configField(enforced, 'channel') !== publication.channel || configField(enforced, 'version') && configField(enforced, 'version') !== publication.version)
+                    throw new Error(`${file}: publications conflicts with enforced channel or version`);
+            }
+        }
+        knownDocumentIds.add(frontmatter.id);
+        knownDocumentTypes.set(frontmatter.id, frontmatter.type);
+        if (frontmatter.type === 'api-reference')
+            for (const operation of frontmatter.operations ?? [])
+                authoredOperationIds.add(operation);
+        if (frontmatter.access?.policy !== 'public' && !authoringFiles?.has(file))
+            continue;
+        const marks = pageReaderFilters(frontmatter, readerFilters, file);
+        if (!matchesContentFilter(marks, contentFilter))
+            continue;
+        if (/\[\[TODO:[\s\S]*?\]\]/.test(body) || /\[\[TODO:[\s\S]*?\]\]/.test(JSON.stringify(frontmatter)) || frontmatter.summary?.startsWith('Draft guide for '))
+            throw new Error(`${file}: unresolved scaffold placeholders cannot be published`);
+        for (const variant of variants) {
+            if (pagePublications ? !pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : (frontmatter.channel && frontmatter.channel !== variant.channel || frontmatter.version && frontmatter.version !== variant.version))
+                continue;
+            if (frontmatter.language && frontmatter.language !== variant.language)
+                continue;
+            if (!pagePublications && (!frontmatter.channel || !frontmatter.version || !frontmatter.language))
+                throw new Error(`${file}: resolved frontmatter needs publication channel and version`);
+            const publishedFrontmatter = pagePublications ? { ...frontmatter, channel: variant.channel, version: variant.version } : frontmatter;
+            const key = keyFor(frontmatter.id, variant);
+            if (docs.has(key))
+                throw new Error(`Duplicate document identity ${key}`);
+            const route = routeFor(publishedFrontmatter, variant, config);
+            const collision = routeOwners.get(route.toLowerCase());
+            if (collision && !allowRouteCollisions)
+                throw new Error(`Route collision ${route}: ${collision} and ${key}`);
+            routeOwners.set(route.toLowerCase(), key);
+            docs.set(key, { file, frontmatter: publishedFrontmatter, body, tree: null, variant, route, markdownRoute: markdownRoute(route, basePath), readerFilters: marks });
+        }
+    }
+    return { contentDir, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners };
+}

package/dist/publication-render.d.ts

@@ -0,0 +1,71 @@
+import { type Freshness } from './freshness.js';
+import { type CardUse, validateRelationships } from './cards.js';
+import { type Cookbooks } from './cookbook-chooser.js';
+import { type Document, type FooterConfig, type HeaderConfig, type Variant } from './content.js';
+import { type OperationNavEntry, validateProjectNavigation } from './project-navigation.js';
+import { type Mode, type Palette } from './palettes.js';
+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, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }: {
+    freshness?: Freshness;
+    rendered: MaterializedPage[];
+    docs: Map<string, Document>;
+    relationships: ReturnType<typeof validateRelationships>;
+    knownOperations: Map<string, {
+        apiId: string;
+        reference: string;
+    }>;
+    cardUses: Map<Document, CardUse>;
+    publishedRelationships: Array<ReturnType<typeof validateRelationships>[number] & {
+        variant: Variant;
+    }>;
+    cookbooks: Cookbooks;
+    documentRoutes: Set<string>;
+    basePath: string;
+    siteOrigin?: string;
+    colorMode: Mode | 'system';
+    config: ResolvedCompilerConfig & {
+        site: CompilerSiteConfig;
+        publications: CompilerPublicationsConfig;
+    };
+    highlighter: CodeHighlighter;
+    editionLabel: (variant: Variant) => string;
+    customStyleFile?: string;
+    themePreset: string;
+    palette: Palette;
+    themeStyleFile?: string;
+    generatedPaletteCss?: string;
+    generatedBadgeCss?: string;
+    themeSwitcherData?: string;
+    generatedFontsCss?: string;
+    fontsPreload?: string;
+    shareFor: (doc: Document) => {
+        route: string;
+        generated: boolean;
+        file?: string;
+    } | undefined;
+    faviconRoute: string;
+    modeToggle: boolean;
+    header: HeaderConfig;
+    footer?: FooterConfig;
+    search: {
+        provider: 'lexical' | 'custom' | 'none';
+    };
+    readerFilters?: ReaderFiltersConfig;
+    variants: Variant[];
+    externalDocuments: Map<string, Array<{
+        label: string;
+        variant: Variant;
+        url: string;
+    }>>;
+    externalSiteLinks: Array<{
+        label: string;
+        url: string;
+        current: false;
+    }>;
+    navigationSpec: ReturnType<typeof validateProjectNavigation>;
+    navigationEntries: Map<string, OperationNavEntry[]>;
+    navigationTagOrder: Map<string, Map<string, string[]>>;
+}): Map<string, import("./content-source.js").NavigationNode[]>;

package/dist/publication-render.js

@@ -0,0 +1,92 @@
+import { resolveAuthoredChange, authoredChangeNotice } from './authored-change.js';
+import { resolveSubjectDeprecation, subjectDeprecationNotice } from './subject-deprecation.js';
+import { markdownSections } from './markdown-sections.js';
+import { contentDigest } from './freshness.js';
+import { configField } from './compiler-config.js';
+import { fictionalDocument, resolveLlmsDiscovery } from './llms-discovery.js';
+import { publicationRelationships, resolveCardTree } from './cards.js';
+import { resolveCookbookTree } from './cookbook-chooser.js';
+import { buildHtmlPage, heading, link, markdownRoute, paragraph, projectMetadata, renderMarkdown, root, text } from './content.js';
+import { navigationPath, navigationTab, navigationTabRecord, resolveProjectNavigation } from './project-navigation.js';
+import { outputUrl, publicTree, resolveOutputLinks } from './representation-tree.js';
+import { presetCatalog } from './palettes.js';
+const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+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, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
+    const resolvedNavigation = new Map();
+    const scopedRelationships = new Map();
+    const hasHome = rendered.some(page => page.doc.route === basePath || page.doc.route === '/');
+    for (const page of rendered) {
+        const navVariant = `${page.doc.variant.channel}|${page.doc.variant.version}|${page.doc.variant.language}`;
+        let edges = scopedRelationships.get(navVariant);
+        if (!edges) {
+            const local = new Map([...docs.values()].filter(doc => keyFor(doc.frontmatter.id, doc.variant) === keyFor(doc.frontmatter.id, page.doc.variant)).map(doc => [doc.frontmatter.id, doc]));
+            edges = publicationRelationships(relationships, local);
+            scopedRelationships.set(navVariant, edges);
+            publishedRelationships.push(...edges.map(edge => ({ ...edge, variant: page.doc.variant })));
+        }
+        const use = { targets: [], queries: [] };
+        page.doc.tree = resolveCardTree(page.doc.tree, page.doc, docs, edges, new Set(knownOperations.keys()), use, config);
+        page.doc.tree = resolveCookbookTree(page.doc.tree, page.doc, docs, cookbooks, use.targets);
+        cardUses.set(page.doc, use);
+        page.htmlTree = resolveOutputLinks(publicTree(page.doc.tree, 'html', documentRoutes, colorMode, basePath), page.doc.route, undefined, 'html', documentRoutes, basePath);
+        page.doc.subjectDeprecation = resolveSubjectDeprecation(page.doc, docs);
+        page.doc.change = resolveAuthoredChange(page.doc, docs);
+        const notices = (format) => root([...subjectDeprecationNotice(page.doc.subjectDeprecation, format).children, ...authoredChangeNotice(page.doc.change, format).children]);
+        const htmlNotice = resolveOutputLinks(notices('html'), page.doc.route, undefined, 'html', documentRoutes, basePath);
+        page.htmlTree.children.unshift(...htmlNotice.children);
+        const mdNotice = resolveOutputLinks(notices('markdown'), page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath);
+        const noticeMarkdown = mdNotice.children.length ? renderMarkdown(mdNotice) + '\n' : '';
+        const fictional = fictionalDocument(page.doc, resolveLlmsDiscovery(configField(config.outputs, 'llms')));
+        const mdTree = resolveOutputLinks(publicTree(page.doc.tree, 'markdown', documentRoutes, 'light', basePath), page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath);
+        if (fictional) {
+            for (const tree of [page.htmlTree, mdTree])
+                tree.children.unshift({ type: 'blockquote', children: [paragraph(text('Fictional API example. This page demonstrates documentation features; its operations do not describe a live service.'))] });
+        }
+        page.doc.contentDigest = contentDigest(page.doc, page.htmlTree, mdTree);
+        if (freshness)
+            page.doc.frontmatter.updated = freshness.resolve(page.doc, page.doc.contentDigest, typeof config.site.updated === 'string' ? config.site.updated : undefined);
+        const subjectLifecycleLabel = page.doc.frontmatter.subjectLifecycle === 'in-development' ? 'In development' : page.doc.frontmatter.subjectLifecycle === 'beta' ? 'Beta' : page.doc.frontmatter.subjectLifecycle === 'deprecated' ? 'Deprecated' : page.doc.frontmatter.subjectLifecycle === 'experimental' ? 'Experimental' : undefined;
+        const markdownLabel = (label, value) => renderMarkdown(root([paragraph({ type: 'strong', children: [text(`${label}: ${value}.`)] })])) + '\n';
+        let navigation = resolvedNavigation.get(navVariant);
+        if (!navigation) {
+            navigation = resolveProjectNavigation(navigationSpec, page.doc.variant, docs, navigationEntries.get(navVariant) ?? [], navigationTagOrder.get(navVariant) ?? new Map());
+            resolvedNavigation.set(navVariant, navigation);
+        }
+        const breadcrumbs = navigationPath(navigation, page.doc.route);
+        const tab = navigationTab(navigation, page.doc.route);
+        const tabRecord = tab ? navigationTabRecord(tab, page.doc.variant, basePath) : undefined;
+        const tabMarkdown = tabRecord ? renderMarkdown(root([paragraph(text('Navigation section: '), link(outputUrl(tabRecord.indexUrl, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), tabRecord.label), text(` (ID: ${tabRecord.id}). `), link(outputUrl(`${basePath}/llms.min.txt`, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), 'All sections and pages'))])) + '\n' : '';
+        const breadcrumbMarkdown = tabMarkdown + (breadcrumbs.length > 1 ? renderMarkdown(root([paragraph(text('Breadcrumbs: '), ...breadcrumbs.flatMap((crumb, index) => [
+                ...(index ? [text(' > ')] : []),
+                crumb.url && index < breadcrumbs.length - 1 ? link(outputUrl(markdownRoute(crumb.url, basePath), page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), crumb.label) : text(crumb.label)
+            ]))])) + '\n' : '');
+        page.markdown = projectMetadata(page.doc, config) + renderMarkdown(root([heading(1, page.doc.frontmatter.title)])) + '\n' + renderMarkdown(root([{ type: 'blockquote', children: [paragraph(text('Documentation index: '), link(outputUrl(`${basePath}/llms.min.txt`, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), 'llms.min.txt'), text(' · Document manifest: '), link(outputUrl(`${basePath}/documents.json`, page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath), 'documents.json'))] }])) + '\n' + breadcrumbMarkdown + (page.doc.frontmatter.date ? markdownLabel('Published', page.doc.frontmatter.date) : '') + (page.doc.frontmatter.updated && !(page.doc.frontmatter.type === 'changelog-entry' && page.doc.frontmatter.date) ? markdownLabel('Updated', page.doc.frontmatter.updated) : '') + (page.doc.frontmatter.verified ? markdownLabel('Verified', page.doc.frontmatter.verified) : '') + (page.doc.frontmatter.releaseVersion ? markdownLabel('Version', page.doc.frontmatter.releaseVersion) : '') + (subjectLifecycleLabel ? markdownLabel('Status', subjectLifecycleLabel) : '') + noticeMarkdown + renderMarkdown(mdTree);
+        const body = renderMarkdown(mdTree);
+        const sectionPrefix = page.markdown.slice(0, -body.length) + (fictional ? renderMarkdown(root([mdTree.children[0]])) + '\n' : '');
+        page.sections = markdownSections(page.doc.tree, page.doc.markdownRoute, page.markdown, sectionPrefix, tree => {
+            const resolved = resolveOutputLinks(publicTree(tree, 'markdown', documentRoutes, 'light', basePath), page.doc.route, siteOrigin, 'markdown', documentRoutes, basePath);
+            // Fragment-only links refer to the full parent, not the smaller resource.
+            const parentLinks = (node) => ({ ...node,
+                ...(typeof node.url === 'string' && node.url.startsWith('#') ? { url: `${siteOrigin ?? ''}${page.doc.markdownRoute}${node.url}` } : {}),
+                ...(node.children ? { children: node.children.map(parentLinks) } : {}) });
+            return renderMarkdown(parentLinks(resolved));
+        }, page.doc.frontmatter.standaloneSections);
+        const externalForPage = externalDocuments.get(page.doc.frontmatter.id) ?? [];
+        const shownLanguages = new Set([...variants.map(variant => variant.language), ...externalForPage.map(item => item.variant.language)]).size > 1;
+        const languageSuffix = (variant) => shownLanguages ? ` · ${variant.language}` : '';
+        const localAlternates = variants.flatMap(variant => {
+            const alternate = docs.get(keyFor(page.doc.frontmatter.id, variant));
+            const label = `${variant.channel} · ${variant.version}${languageSuffix(variant)}`;
+            if (alternate)
+                return [{ label, url: alternate.route, current: alternate === page.doc }];
+            const overview = [...docs.values()].filter(doc => doc.variant.channel === variant.channel && doc.variant.version === variant.version && doc.variant.language === variant.language && doc.frontmatter.access?.policy === 'public').sort((a, b) => a.route.length - b.route.length || a.route.localeCompare(b.route))[0];
+            return overview ? [{ label: `${label} · page unavailable; open overview`, url: overview.route, current: false }] : [];
+        });
+        const publicationAlternates = [...localAlternates, ...externalSiteLinks, ...externalForPage.map(item => ({
+                label: `${item.label}${item.label.toLowerCase() === item.variant.channel.toLowerCase() ? '' : ` · ${item.variant.channel}`} · ${item.variant.version}${languageSuffix(item.variant)}`,
+                url: item.url, current: false
+            }))];
+        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, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
+    }
+    return resolvedNavigation;
+}

package/dist/reader-filters.d.ts

@@ -0,0 +1,30 @@
+export type ReaderSelection = Record<string, string[]>;
+export type ReaderFacet = {
+    label: string;
+    options: Record<string, string>;
+};
+export type ReaderFilterControl = {
+    facet?: string;
+    display: 'select' | 'checks';
+    label?: string;
+    scope?: 'page';
+};
+export type ReaderFiltersConfig = {
+    facets: Record<string, ReaderFacet>;
+    typeDefaults: Record<string, ReaderSelection>;
+    controls: {
+        sidebar: boolean;
+        header?: ReaderFilterControl;
+    };
+    module?: string;
+};
+export declare function validateReaderSelection(value: unknown, config: ReaderFiltersConfig, where: string): ReaderSelection;
+export declare function validateReaderFilters(value: unknown): ReaderFiltersConfig | undefined;
+export declare function validateReaderFilterControl(value: unknown, config: ReaderFiltersConfig, where: string, allowPageScope?: boolean): ReaderFilterControl;
+export declare function pageReaderFilters(frontmatter: {
+    type: string;
+    audiences?: string[];
+    readerFilters?: unknown;
+}, config: ReaderFiltersConfig | undefined, file: string): ReaderSelection;
+export declare function readerFilterAttribute(selection: ReaderSelection): string;
+export declare function readerViewParam(selection: ReaderSelection): string;