@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.18

package/dist/publication-manifest.js

@@ -1,24 +1,32 @@
+import { documentKey, publicationKey, parsePublicationKey } from './publication-identity.js';
 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 keyFor = documentKey;
+export function buildPublicationManifest({ configPublications, 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 variant = parsePublicationKey(key);
+        return nodes.filter(node => node.tab).map(node => navigationTabRecord(node, variant, basePath));
     });
     const tabFor = (doc) => {
-        const node = navigationTab(resolvedNavigation.get(`${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`) ?? [], doc.route);
+        const node = navigationTab(resolvedNavigation.get(publicationKey(doc.variant)) ?? [], 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();
+    // Publish one compact catalog, limited to releases present in this edition.
+    const enabled = [...new Map(rendered.map(({ doc }) => [publicationKey(doc.variant), doc.variant])).values()];
+    const products = configPublications.products ? Object.fromEntries(Object.entries(configPublications.products).flatMap(([id, definition]) => {
+        const versions = [...new Set(enabled.filter(variant => variant.product === id).map(variant => variant.version))];
+        return versions.length ? [[id, { ...(definition.label ? { label: definition.label } : {}), ...(versions.includes(definition.defaultVersion) ? { defaultVersion: definition.defaultVersion } : {}), versions }]] : [];
+    })) : undefined;
     const manifest = {
         schemaVersion: 1,
         configDigest: configDigest,
+        ...(products ? { publications: { enabled, products } } : {}),
         ...(synonyms.length ? { searchSynonyms: synonyms } : {}),
         basePath,
         ...(sitemaps.size ? { sitemap: publicPath('/sitemap.xml') } : {}),
@@ -26,7 +34,7 @@ export function buildPublicationManifest({ fictionalDocuments, configDigest, syn
         ...(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) })),
+        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) })),
         operations,
         relationships: publishedRelationships,
         redirects,

package/dist/publication-plan.js

@@ -1,3 +1,4 @@
+import { documentKey, samePublication } from './publication-identity.js';
 import { hasScaffoldPlaceholders } from './scaffold-placeholders.js';
 import { validateFeatureClassification, matchesFeatures } from './deployment-profile.js';
 import { matchesContentFilter } from './content-filter.js';
@@ -7,8 +8,8 @@ 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}`;
+import { resolvePublication, configField } from './compiler-config.js';
+const keyFor = documentKey;
 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)] : []));
@@ -38,27 +39,38 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
             return merged.page;
         } : undefined, sourceOverrides?.get(file));
         frontmatter.language ??= language;
+        // A product's release default never comes from the legacy global version.
+        if (config.publications.products && frontmatter.product && !frontmatter.publications) {
+            if (!Object.hasOwn(config.publications.products, frontmatter.product))
+                throw new Error(`${file}: unknown publication product ${frontmatter.product}`);
+            const enforcedVersion = configField(configField(config.frontmatter, 'enforced'), 'version');
+            if (sourceFrontmatter.version === undefined && enforcedVersion === undefined)
+                frontmatter.version = resolvePublication(config.publications, { ...frontmatter, version: undefined }, language).version;
+            resolvePublication(config.publications, frontmatter, 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)
+            if (sourceFrontmatter.channel !== undefined || sourceFrontmatter.version !== undefined || (config.publications.products && sourceFrontmatter.product !== 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}`);
+                resolvePublication(config.publications, publication, language);
                 const enforced = configField(config.frontmatter, 'enforced');
-                if (configField(enforced, 'channel') && configField(enforced, 'channel') !== publication.channel || configField(enforced, 'version') && configField(enforced, 'version') !== publication.version)
+                if (configField(enforced, 'channel') && configField(enforced, 'channel') !== publication.channel || configField(enforced, 'version') && configField(enforced, 'version') !== publication.version || config.publications.products && configField(enforced, 'product') && configField(enforced, 'product') !== publication.product)
                     throw new Error(`${file}: publications conflicts with enforced channel or version`);
             }
         }
         knownDocumentIds.add(frontmatter.id);
+        const previousType = knownDocumentTypes.get(frontmatter.id);
+        if (previousType !== undefined && previousType !== frontmatter.type)
+            throw new Error(`${file}: stable document ID ${frontmatter.id} has inconsistent types across publications (${previousType} and ${frontmatter.type})`);
         knownDocumentTypes.set(frontmatter.id, frontmatter.type);
         if (frontmatter.type === 'api-reference')
             for (const operation of frontmatter.operations ?? [])
                 authoredOperationIds.add(operation);
         const classificationVariants = featureContext?.classificationPublications ?? variants;
-        const classificationEligible = frontmatter.access?.policy === 'public' && classificationVariants.some(variant => (pagePublications ? pagePublications.some(item => item.channel === variant.channel && item.version === variant.version) : frontmatter.channel === variant.channel && frontmatter.version === variant.version) && frontmatter.language === variant.language);
+        const classificationEligible = frontmatter.access?.policy === 'public' && classificationVariants.some(variant => (pagePublications ? pagePublications.some(item => samePublication({ ...item, language: frontmatter.language }, variant)) : samePublication({ channel: frontmatter.channel, version: frontmatter.version, language: frontmatter.language, ...(config.publications.products && frontmatter.product ? { product: frontmatter.product } : {}) }, variant)) && frontmatter.language === variant.language);
         if (classificationEligible)
             validateFeatureClassification(sourceFrontmatter, featureContext, `${file}: ${frontmatter.id}`);
         const included = matchesFeatures(frontmatter.requires, featureContext, `${file}: ${frontmatter.id}`);
@@ -80,13 +92,13 @@ export async function planAuthoredDocuments({ base, basePath, config, variants,
             throw new Error(`${file}: unresolved scaffold placeholders cannot be published`);
         let selectedPublication = false;
         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))
+            if (pagePublications ? !pagePublications.some(item => samePublication({ ...item, language: frontmatter.language }, variant)) : (frontmatter.channel && frontmatter.channel !== variant.channel || frontmatter.version && frontmatter.version !== variant.version || (config.publications.products && frontmatter.product !== variant.product)))
                 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 publishedFrontmatter = pagePublications ? { ...frontmatter, channel: variant.channel, version: variant.version, ...(variant.product ? { product: variant.product } : {}) } : frontmatter;
             const key = keyFor(frontmatter.id, variant);
             if (docs.has(key))
                 throw new Error(`Duplicate document identity ${key}`);

package/dist/publication-render.js

@@ -1,8 +1,9 @@
+import { documentKey, publicationKey, samePublication } from './publication-identity.js';
 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 { configField, isConfigMapping } from './compiler-config.js';
 import { fictionalDocument, resolveLlmsDiscovery } from './llms-discovery.js';
 import { publicationRelationships, resolveCardTree } from './cards.js';
 import { resolveCookbookTree } from './cookbook-chooser.js';
@@ -10,13 +11,17 @@ import { buildHtmlPage, heading, link, markdownRoute, paragraph, projectMetadata
 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}`;
+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 }) {
     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')))
+        throw new Error('site.publicationSelector must be a mapping with an optional boolean showLanguage');
+    const showLanguage = isConfigMapping(selector) && typeof selector.showLanguage === 'boolean' ? selector.showLanguage : new Set(rendered.map(item => item.doc.variant.language)).size > 1;
     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}`;
+        const navVariant = publicationKey(page.doc.variant);
         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]));
@@ -60,7 +65,7 @@ export function renderPublicationPages({ rendered, docs, relationships, knownOpe
                 ...(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);
+        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.availability?.since ? markdownLabel('Available since', page.doc.frontmatter.availability.since) : '') + (page.doc.frontmatter.availability?.through ? markdownLabel('Available through', page.doc.frontmatter.availability.through) : '') + (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 => {
@@ -71,22 +76,33 @@ export function renderPublicationPages({ rendered, docs, relationships, knownOpe
                 ...(node.children ? { children: node.children.map(parentLinks) } : {}) });
             return renderMarkdown(parentLinks(resolved));
         }, page.doc.frontmatter.standaloneSections);
-        const externalForPage = externalDocuments.get(page.doc.frontmatter.id) ?? [];
+        const externalForPage = (externalDocuments.get(page.doc.frontmatter.id) ?? []).filter(item => item.variant.product === page.doc.variant.product);
         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 localAlternates = variants.filter(variant => variant.product === page.doc.variant.product).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];
+            const overview = [...docs.values()].filter(doc => samePublication(doc.variant, variant) && 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, 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', publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
+        // Derive choices from the selected output, not the catalog: a customer
+        // edition must not advertise products or releases it did not publish.
+        const publicationChoices = config.publications.products ? [...new Map(rendered.map(item => [publicationKey(item.doc.variant), item.doc.variant])).values()]
+            .sort((left, right) => (left.product ?? '').localeCompare(right.product ?? '') || publicationKey(left).localeCompare(publicationKey(right)))
+            .flatMap(variant => {
+            const target = docs.get(keyFor(page.doc.frontmatter.id, variant)) ?? rendered.filter(item => samePublication(item.doc.variant, variant)).map(item => item.doc).sort((left, right) => left.route.length - right.route.length || left.route.localeCompare(right.route))[0];
+            if (!target)
+                return [];
+            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 });
     }
     return resolvedNavigation;
 }

package/dist/recipe-draft.js

@@ -1,3 +1,5 @@
+import { resolvePublication } from './compiler-config.js';
+import { samePublication } from './publication-identity.js';
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -17,8 +19,10 @@ function parseYaml(source, file) {
     return document.toJS();
 }
 function parseSpec(value) {
-    if (!object(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => !['schemaVersion', 'id', 'title', 'summary', 'slug', 'ingredients', 'inputs', 'outcome'].includes(key)))
+    if (!object(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => !['schemaVersion', 'id', 'title', 'summary', 'slug', 'ingredients', 'inputs', 'outcome', 'publication'].includes(key)))
         throw new Error('Recipe spec needs schemaVersion: 1 and only supported fields');
+    if (value.publication !== undefined && (!object(value.publication) || Object.keys(value.publication).some(key => !['product', 'channel', 'version', 'language'].includes(key)) || Object.values(value.publication).some(item => typeof item !== 'string' || !item)))
+        throw new Error('Recipe publication must declare product/channel/version/language strings');
     workflowValues(value.inputs, 'Recipe inputs');
     if (value.outcome !== undefined && (typeof value.outcome !== 'string' || !value.outcome.trim()))
         throw new Error('Recipe outcome must be nonempty text');
@@ -59,9 +63,8 @@ export async function renderRecipeDraft(configFile, specFile) {
     const config = (await loadConfig(configPath)).value;
     const spec = parseSpec(parseYaml(await readFile(specFile, 'utf8'), specFile));
     const defaults = config.publications?.defaults ?? {};
-    if (!defaults.channel || !defaults.version)
-        throw new Error('Recipe draft needs a default channel and version');
-    const language = defaults.language ?? defaultLanguage(config);
+    const product = spec.publication?.product ?? defaults.product;
+    const publication = resolvePublication(config.publications, { ...defaults, ...spec.publication, ...(product ? { product, version: spec.publication?.version } : {}) }, defaultLanguage(config));
     const seen = new Set();
     const operations = new Set();
     const sources = [];
@@ -95,7 +98,7 @@ export async function renderRecipeDraft(configFile, specFile) {
             for (const prerequisite of workflow.prerequisites)
                 prerequisites.add(prerequisite);
         }
-        if (header.channel !== defaults.channel || header.version !== defaults.version || header.language !== language)
+        if (!samePublication({ channel: String(header.channel), version: String(header.version), language: String(header.language), ...(config.publications.products && header.product ? { product: String(header.product) } : {}) }, publication))
             throw new Error(`Ingredient ${header.id} must match the recipe's default publication`);
         if (header.operations !== undefined) {
             if (!Array.isArray(header.operations) || header.operations.some(value => typeof value !== 'string'))
@@ -111,7 +114,7 @@ export async function renderRecipeDraft(configFile, specFile) {
     }
     const header = {
         id: spec.id, title: spec.title, summary: spec.summary, type: 'recipe', slug: spec.slug,
-        channel: defaults.channel, version: defaults.version, language,
+        ...publication,
         ...(operations.size ? { operations: [...operations] } : {}), access: { policy: 'draft' }
     };
     const sourceDigest = digest([JSON.stringify(spec), ...sources].join('\n'));

package/dist/scaffold.d.ts

@@ -4,6 +4,7 @@ export type ScaffoldInput = {
     summary: string;
     slug: string;
     operations?: string[];
+    product?: string;
     channel?: string;
     version?: string;
     language?: string;
@@ -19,8 +20,9 @@ export declare function scaffold(configFile: string, templateId: string, targetF
     id: string;
     file: string;
     publication: {
-        channel: any;
-        version: any;
+        product?: string;
+        channel: string;
+        version: string;
         language: string;
     };
     access: string;
@@ -31,8 +33,9 @@ export declare function scaffoldFromPath(configFile: string, templateId: string,
     id: string;
     file: string;
     publication: {
-        channel: any;
-        version: any;
+        product?: string;
+        channel: string;
+        version: string;
         language: string;
     };
     access: string;

package/dist/scaffold.js

@@ -1,3 +1,5 @@
+import { resolvePublication } from './compiler-config.js';
+import { samePublication } from './publication-identity.js';
 import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -100,14 +102,12 @@ export async function scaffold(configFile, templateId, targetFile, input) {
         if (!knownOperations.has(operation))
             throw new Error(`Unknown scaffold operation ${operation}`);
     const defaults = config.publications?.defaults;
-    const applicability = resolveFrontmatter(Object.fromEntries(Object.entries({ channel: input.channel, version: input.version, language: input.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
-    const channel = applicability.channel ?? defaults?.channel;
-    const version = applicability.version ?? defaults?.version;
-    const language = applicability.language ?? defaultLanguage(config);
-    if (!channel || !version || !language)
-        throw new Error('Scaffold needs channel, version, and language');
-    if (!config.publications?.enabled?.some((item) => item.channel === channel && item.version === version && (item.language ?? defaultLanguage(config)) === language))
-        throw new Error(`Scaffold publication ${channel}/${version}/${language} is not enabled`);
+    const applicability = resolveFrontmatter(Object.fromEntries(Object.entries({ product: input.product, channel: input.channel, version: input.version, language: input.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
+    const product = config.publications?.products ? applicability.product ?? defaults?.product : undefined;
+    const publication = resolvePublication(config.publications, { ...applicability, product, ...(product ? { product, version: config.frontmatter?.enforced?.version ?? input.version } : {}), channel: applicability.channel ?? defaults?.channel }, defaultLanguage(config));
+    const { channel, version, language } = publication;
+    if (!config.publications?.enabled?.some((item) => samePublication(resolvePublication(config.publications, item, defaultLanguage(config)), publication)))
+        throw new Error(`Scaffold publication ${product ? product + '/' : ''}${channel}/${version}/${language} is not enabled`);
     const root = path.dirname(path.resolve(configFile));
     const contentDir = await canonicalPath(path.resolve(root, config.site?.contentDir ?? 'content'));
     const target = await canonicalPath(targetFile);
@@ -118,13 +118,13 @@ export async function scaffold(configFile, templateId, targetFile, input) {
         ? path.resolve(path.dirname(explainSegments(loaded, ['templates', templateId, 'body']).source.file), template.body)
         : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../templates', template.body);
     const { header, body } = splitTemplate(await readFile(bodyFile, 'utf8'), bodyFile);
-    const frontmatter = { id: input.id, title: input.title, summary: input.summary, type: template.type, slug: input.slug, channel, version, language, ...(input.operations?.length ? { operations: input.operations } : {}), access: { policy: 'draft' } };
-    routeFor(frontmatter, { channel, version, language }, config);
+    const frontmatter = { id: input.id, title: input.title, summary: input.summary, type: template.type, slug: input.slug, ...publication, ...(!config.publications?.products && applicability.product ? { product: applicability.product } : {}), ...(input.operations?.length ? { operations: input.operations } : {}), access: { policy: 'draft' } };
+    routeFor(frontmatter, publication, config);
     const written = header ? fillTemplateHeader(header, frontmatter) : YAML.stringify(frontmatter);
     const content = `---\n${written.replace(/\s*$/, '\n')}---\n\n${body.trimStart().replace(/\s*$/, '\n')}`;
     await mkdir(path.dirname(target), { recursive: true });
     await writeFile(target, content, { flag: 'wx' });
-    return { status: 'ok', template: templateId, id: input.id, file: target, publication: { channel, version, language }, access: 'draft' };
+    return { status: 'ok', template: templateId, id: input.id, file: target, publication, access: 'draft' };
 }
 export async function scaffoldFromPath(configFile, templateId, targetFile, overrides = {}) {
     const loaded = await loadConfig(configFile);
@@ -137,14 +137,14 @@ export async function scaffoldFromPath(configFile, templateId, targetFile, overr
     if (parts.some(part => !part))
         throw new Error('Scaffold target needs a usable filename');
     const title = parts.at(-1).split('-').map(word => word[0].toUpperCase() + word.slice(1)).join(' ');
-    const selected = resolveFrontmatter(Object.fromEntries(Object.entries({ channel: overrides.channel, version: overrides.version, language: overrides.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
-    const channel = selected.channel ?? config.publications?.defaults?.channel;
-    const version = selected.version ?? config.publications?.defaults?.version;
-    const language = selected.language ?? defaultLanguage(config);
+    const selected = resolveFrontmatter(Object.fromEntries(Object.entries({ product: overrides.product, channel: overrides.channel, version: overrides.version, language: overrides.language }).filter(([, value]) => value !== undefined)), config.frontmatter);
+    const product = config.publications?.products ? selected.product ?? config.publications?.defaults?.product : undefined;
+    const { channel, version, language } = resolvePublication(config.publications, { ...selected, product, ...(product ? { product, version: config.frontmatter?.enforced?.version ?? overrides.version } : {}), channel: selected.channel ?? config.publications?.defaults?.channel }, defaultLanguage(config));
     const prefixGroups = [
         language === defaultLanguage(config) ? '' : language,
+        product ? config.publications.products[product].pathPrefix : '',
         config.publications?.channels?.[channel]?.pathPrefix ?? '',
-        config.publications?.versions?.[version]?.pathPrefix ?? ''
+        (product ? config.publications.products[product].versions : config.publications?.versions)?.[version]?.pathPrefix ?? ''
     ].map(value => value.split('/').filter(Boolean));
     const prefixCandidates = [];
     for (let start = 0; start < prefixGroups.length; start++) {

package/dist/search-query.d.ts

@@ -1,4 +1,5 @@
 export type SearchOptions = {
+    product?: string;
     channel?: string;
     version?: string;
     language?: string;
@@ -7,22 +8,14 @@ export type SearchOptions = {
 export declare function queryBuiltSite(directory: string, query: string, options?: SearchOptions): Promise<{
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     results: never[];
     matchMode?: undefined;
 } | {
     status: string;
     query: string;
-    publication: {
-        channel: string;
-        version: string;
-        language: string;
-    };
+    publication: import("./publication-identity.js").PublicationCoordinate;
     total: number;
     matchMode: string;
     results: {
@@ -46,6 +39,7 @@ export declare function queryBuiltSite(directory: string, query: string, options
                 channel: string;
                 version: string;
                 language: string;
+                product?: string | undefined;
                 section?: string | undefined;
                 id: string;
             };

package/dist/search-query.js

@@ -1,3 +1,4 @@
+import { parsePublicationKey } from './publication-identity.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { phraseMatches, queryUnits, validateSearchSynonyms } from './search-synonyms.js';
@@ -30,18 +31,18 @@ export async function queryBuiltSite(directory, query, options = {}) {
         throw new Error('Unsupported or invalid search-index.json');
     const synonyms = validateSearchSynonyms(index.synonyms);
     const matching = index.documents.filter(doc => {
-        const [channel, version, language] = doc.variant.split('|');
-        return (!options.channel || channel === options.channel) && (!options.version || version === options.version) && (!options.language || language === options.language);
+        const { product, channel, version, language } = parsePublicationKey(doc.variant);
+        return (!options.product || product === options.product) && (!options.channel || channel === options.channel) && (!options.version || version === options.version) && (!options.language || language === options.language);
     });
     const variants = [...new Set(matching.map(doc => doc.variant))].sort();
     if (!variants.length)
         throw new Error('No search documents match the selected publication');
     if (variants.length > 1)
-        throw new Error(`Search matches multiple publications (${variants.join(', ')}); pass --channel, --version, and --language`);
+        throw new Error(`Search matches multiple publications (${variants.join(', ')}); pass --product where applicable, --channel, --version, and --language`);
     const terms = queryUnits(query, synonyms);
     if (!terms.length) {
-        const [channel, version, language] = variants[0].split('|');
-        return { status: 'ok', query: query.trim(), publication: { channel, version, language }, total: 0, results: [] };
+        const publication = parsePublicationKey(variants[0]);
+        return { status: 'ok', query: query.trim(), publication, total: 0, results: [] };
     }
     const match = (value, unit) => phraseMatches(value, unit.term) || unit.alternatives.some(term => phraseMatches(value, term));
     // Page titles are short subject labels, often singular. Accept a plain final
@@ -78,10 +79,10 @@ export async function queryBuiltSite(directory, query, options = {}) {
         // 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))))
             score += 20;
-        const [channel, version, language] = doc.variant.split('|');
+        const { product, channel, version, language } = parsePublicationKey(doc.variant);
         const tokens = selected?.markdownTokens ?? doc.markdownTokens;
         const read = { tool: selected ? 'get_section' : 'get_page', arguments: {
-                id: doc.id, ...(selected ? { section: selected.id } : {}), channel, version, language,
+                id: doc.id, ...(selected ? { section: selected.id } : {}), ...(product === undefined ? {} : { product }), channel, version, language,
                 ...(tokens !== undefined ? { maxTokens: Math.min(100_000, Math.max(4096, tokens * 2 + 1024)) } : {}),
             } };
         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])) }];
@@ -115,6 +116,6 @@ export async function queryBuiltSite(directory, query, options = {}) {
         }
         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);
     });
-    const [channel, version, language] = variants[0].split('|');
-    return { status: 'ok', query: query.trim(), publication: { channel, version, language }, total: ranked.length, matchMode: stronger.length ? 'mixed' : complete.length ? 'all' : 'partial', results: ranked.slice(0, limit).map(({ matched, partialMatched, contentScore, prominentMatches, ...result }) => result) };
+    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/server.d.ts

@@ -1,10 +1,18 @@
 import { type Server, type ServerResponse } from 'node:http';
+export type PreviewStatus = {
+    profile?: string;
+    profileDigest?: string;
+    buildId?: string;
+    error?: string;
+};
 export type SiteExtras = {
     ask?: (request: Request) => Promise<Response>;
     search?: (request: Request) => Promise<Response>;
     widget?: string;
     publicSettings?: Record<string, unknown>;
     panel?: Record<string, string>;
+    preview?: PreviewStatus;
 };
+export declare function previewMarkup(basePath: string, preview?: PreviewStatus): string;
 export declare function createSiteServer(directory: string, liveClients?: Set<ServerResponse>, extras?: SiteExtras): Promise<Server>;
 export declare function serveSite(directory: string, host: string, port: number, liveClients?: Set<ServerResponse>, extras?: SiteExtras): Promise<Server>;

package/dist/server.js

@@ -6,6 +6,13 @@ import { readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { homeUrl, negotiatedDocument } from './negotiation.js';
 const types = { '.html': 'text/html; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.xml': 'application/xml; charset=utf-8', '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.txt': 'text/plain; charset=utf-8', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf' };
+const escapeHtml = (value) => value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character]));
+const scriptJson = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
+export function previewMarkup(basePath, preview) {
+    const identity = preview?.profile ? `Customer preview: ${preview.profile} (edition ${preview.profileDigest?.slice(0, 12) ?? 'unknown'}, build ${preview.buildId?.slice(0, 12) ?? 'unknown'}).` : '';
+    const failure = preview?.error ? `Build failed: ${preview.error}. Showing the last successful build.` : '';
+    return `${identity ? `<aside id="shoalrun-preview-edition" role="status">${escapeHtml(identity)}</aside>` : ''}${failure ? `<aside id="shoalrun-build-status" role="alert">${escapeHtml(failure)}</aside>` : ''}<script>const updates=new EventSource(${scriptJson(`${basePath}/__shoalrun/reload`)});updates.addEventListener("built",event=>{const update=JSON.parse(event.data);let pathname=location.pathname;try{pathname=decodeURIComponent(pathname)}catch{}const route=pathname.replace(/\\/+$/,"")||"/";if(update.routes&&!update.routes.includes(route)&&update.home){location.assign(update.home)}else{location.reload()}});updates.addEventListener("failed",event=>{let status=document.getElementById("shoalrun-build-status");if(!status){status=document.createElement("aside");status.id="shoalrun-build-status";status.setAttribute("role","alert");document.body.append(status)}status.textContent="Build failed: "+JSON.parse(event.data).message+". Showing the last successful build."})</script>`;
+}
 const bridgeLimit = 20_000;
 // Read a Node request into a Web `Request`, refusing bodies over the limit before a handler sees them.
 async function bridge(request, response, handler) {
@@ -91,6 +98,8 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
             if (liveClients && pathname === `${basePath}/__shoalrun/reload`) {
                 response.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
                 response.write(': connected\n\n');
+                if (extras.preview?.error)
+                    response.write(`event: failed\ndata: ${JSON.stringify({ message: extras.preview.error })}\n\n`);
                 liveClients.add(response);
                 response.on('close', () => liveClients.delete(response));
                 return;
@@ -149,7 +158,7 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
             const sendRepresentation = (body, resourceHeaders) => {
                 const match = request.headers['if-none-match'];
                 const etag = resourceHeaders.ETag;
-                const notModified = (request.method === 'GET' || request.method === 'HEAD') && etag && match?.split(',').some(value => value.trim() === '*' || value.trim().replace(/^W\//, '') === etag);
+                const notModified = !liveClients && (request.method === 'GET' || request.method === 'HEAD') && etag && match?.split(',').some(value => value.trim() === '*' || value.trim().replace(/^W\//, '') === etag);
                 response.writeHead(notModified ? 304 : 200, resourceHeaders);
                 response.end(notModified || request.method === 'HEAD' ? undefined : body);
             };
@@ -172,7 +181,7 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
             let body = await readFile(file);
             const documentRoute = pathname === '/' ? '/' : pathname.replace(/\/+$/, '');
             const document = manifest.documents.find(item => item.url === documentRoute);
-            const injected = `${liveClients ? `<script>const updates=new EventSource("${basePath}/__shoalrun/reload");updates.addEventListener("built",()=>location.reload());updates.addEventListener("failed",event=>{let status=document.getElementById("shoalrun-build-status");if(!status){status=document.createElement("aside");status.id="shoalrun-build-status";status.setAttribute("role","alert");document.body.append(status)}status.textContent="Build failed: "+JSON.parse(event.data).message})</script>` : ''}${extras.ask && extras.widget ? `<script src="${basePath}/__shoalrun/ask.js" defer></script>` : ''}`;
+            const injected = `${liveClients ? previewMarkup(basePath, extras.preview) : ''}${extras.ask && extras.widget ? `<script src="${basePath}/__shoalrun/ask.js" defer></script>` : ''}`;
             if (injected && file.endsWith('.html') && request.method !== 'HEAD')
                 body = Buffer.from(body.toString('utf8').replace('</body>', `${injected}</body>`));
             sendRepresentation(body, { ...(headers[pathname] ?? { 'Content-Type': types[path.extname(file)] ?? 'application/octet-stream' }), ...(file.toLowerCase().endsWith('.svg') ? { 'Content-Security-Policy': 'sandbox' } : {}), ...(document ? { Vary: 'Accept', Link: `<${document.markdownUrl}>; rel="alternate"; type="text/markdown"` } : {}) });
@@ -206,7 +215,9 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
             const document = manifest.documents.find(item => item.markdownUrl === pathname || (markdown && item.url === (pathname.replace(/\/+$/, '') || '/')));
             const twin = document && await siteFile(document.url === '/' ? '/index.html' : `${document.url}/index.html`).then(file => stat(file)).then(info => info.isFile()).catch(() => false) ? document.url : undefined;
             response.writeHead(404, { 'Content-Type': markdown ? 'text/markdown; charset=utf-8' : 'text/html; charset=utf-8', Vary: 'Accept', 'X-Robots-Tag': 'noindex', ...(twin ? { Link: `<${twin}>; rel="alternate"; type="text/html"` } : {}) });
-            const body = !markdown && errorHtml ? (twin ? addNotFoundTwin(errorHtml, twin) : errorHtml) : notFoundPage(basePath, home ?? `${basePath}/`, markdown, twin, search);
+            let body = !markdown && errorHtml ? (twin ? addNotFoundTwin(errorHtml, twin) : errorHtml) : notFoundPage(basePath, home ?? `${basePath}/`, markdown, twin, search);
+            if (!markdown && liveClients)
+                body = body.replace('</body>', `${previewMarkup(basePath, extras.preview)}</body>`);
             response.end(request.method === 'HEAD' ? undefined : body);
         }
     });

package/dist/subject-deprecation.js

@@ -1,3 +1,4 @@
+import { documentKey } from './publication-identity.js';
 import { link, paragraph, root, text } from './semantic-markdown.js';
 export function validateSubjectDeprecation(value, file) {
     if (value === undefined)
@@ -34,7 +35,7 @@ export function resolveSubjectDeprecation(doc, docs) {
         const id = value[key];
         if (!id)
             continue;
-        const target = docs.get(`${id}|${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`);
+        const target = docs.get(documentKey(id, doc.variant));
         if (id === doc.frontmatter.id || !target || target.frontmatter.access?.policy !== 'public')
             throw new Error(`${doc.file}: subjectDeprecation.${key} must name another public document in the same publication: ${id}`);
         result[key] = { id, title: target.frontmatter.title, url: target.route, markdownUrl: target.markdownRoute };

package/dist/vercel-function.js

@@ -90,7 +90,7 @@ export async function addAskFunction(input) {
     const runtime = {
         schemaVersion: 1,
         settings: { chat: settings.chat, retrieval: settings.retrieval, ...(settings.search ? { search: settings.search } : {}), ...(settings.readerFilters ? { readerFilters: settings.readerFilters } : {}) },
-        ...(publications?.channel && publications.version && publications.language ? { variant: { channel: publications.channel, version: publications.version, language: publications.language } } : {}),
+        ...(publications?.channel && publications.version && publications.language ? { variant: { ...(publications.product ? { product: publications.product } : {}), channel: publications.channel, version: publications.version, language: publications.language } } : {}),
         ...(origin ? { hosts: [new URL(origin).host] } : {})
     };
     await writeFile(path.join(func, 'runtime.json'), JSON.stringify(runtime, null, 2) + '\n');

package/example-configs/products/README.md

@@ -0,0 +1,37 @@
+# Independent product editions
+
+This runnable example publishes a small Payments and Reporting documentation site from six source pages. Payments has v2 and v3 releases; Reporting has an independent v1 release. The operating checklist is one source with explicit membership in all three publications.
+
+| Customer profile | Payments | Reporting | Feature grants |
+| --- | --- | --- | --- |
+| Customer A | v3 | v1 | Priority settlement and scheduled exports |
+| Customer B | v2 | v1 | Neither optional feature |
+
+From the repository root, build the CLI once with `npm --prefix framework run build`, then start either preview:
+
+```sh
+node framework/dist/cli.js dev framework/example-configs/products/docs.config.yaml /tmp/shoalrun-products-a --profile framework/example-configs/products/profiles/customer-a.yaml --port 8775
+```
+
+Open <http://127.0.0.1:8775/payments/v3/start> or <http://127.0.0.1:8775/reporting/v1/start>.
+
+```sh
+node framework/dist/cli.js dev framework/example-configs/products/docs.config.yaml /tmp/shoalrun-products-b --profile framework/example-configs/products/profiles/customer-b.yaml --port 8776
+```
+
+Open <http://127.0.0.1:8776/payments/v2/start> or <http://127.0.0.1:8776/reporting/v1/start>.
+
+To include both Payments releases in the same preview, select `profiles/all-releases.yaml` instead. The publication dropdown then offers Payments v2, Payments v3, and Reporting v1. Customer profiles A and B expose only their selected releases.
+
+Language labels are hidden automatically because this example publishes English only. Set `site.publicationSelector.showLanguage: false` to suppress language labels explicitly, or `true` to show them.
+
+Inspect these differences:
+
+- Customer A gets Payments v3 instructions and its priority settlement page. Customer B gets Payments v2 instructions.
+- Both editions use Reporting v1, but only Customer A includes the scheduled exports page and feature-specific sections.
+- Links from the shared operating checklist return to the current product and release.
+- Editing the selected profile, SKU manifest, or page source refreshes the preview. For example, change Customer A's Payments selection from v3 to v2 while leaving Reporting at v1.
+
+`requires` removes whole pages during compilation. `<ForFeature>` removes sections. Neither relies on browser reader filters. `profiles.requireClassification` checks every public source for an explicit `shared: true` or feature requirement.
+
+For a static edition, replace `dev` with `build` and omit `--port`; pass the same profile and output directory. The data and workflows in this example describe a fictional product suite.