@shoalrun/cli 1.0.0 → 1.1.0

package/dist/content-export.js

@@ -1,5 +1,6 @@
+import { createSectionSelection, pruneSelectedTree, sectionSelectionReport, writeSectionSelectionReport } from './section-selection.js';
 import { documentKey, publicationKey, samePublication } from './publication-identity.js';
-import { pruneFeatureTree, profileSelection } from './deployment-profile.js';
+import { profileSelection } from './deployment-profile.js';
 import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -121,7 +122,8 @@ export async function exportContent(configFile, destination, options = {}) {
     const providerSetting = configField(config.metadata, 'provider');
     const metadataProvider = await loadMetadataProvider(providerSetting, providerSetting ? explainSegments(loaded, ['metadata', 'provider', 'module']).source.file : configFile);
     const metadataDependencies = new Set();
-    const workspace = await prepareContentWorkspace({ base, basePath, config, loaded, variants: [publication], language, readerFilters, metadataProvider, metadataDependencies, allowRouteCollisions: true });
+    const sectionSelection = createSectionSelection(readerFilters, selection, publications);
+    const workspace = await prepareContentWorkspace({ base, basePath, config, loaded, variants: [publication], language, readerFilters, metadataProvider, metadataDependencies, sectionSelection, allowRouteCollisions: true });
     const { docs: eligible, apiPlan, snippets, sourceForOperation } = workspace;
     const ids = new Set(target.resources ? target.resources.filter(item => item.kind !== 'snippet').map(item => item.documentId) : target.documents);
     for (const id of ids) {
@@ -180,7 +182,7 @@ export async function exportContent(configFile, destination, options = {}) {
                 throw new Error(`Unknown export snippet ${selection.snippetId}`);
             // This is an explicit isolated context. It has no containing page, operations,
             // relationships, page variables, or inherited publication/access metadata.
-            const snippetDocument = { featureContext: loaded.deployment?.context, file: definition.file, body: '', tree: root([]), variant: publication,
+            const snippetDocument = { sectionSelection, featureContext: loaded.deployment?.context, file: definition.file, body: '', tree: root([]), variant: publication,
                 route: `/__content_snippets/${encodeURIComponent(selection.id)}`, markdownRoute: '',
                 frontmatter: { id: selection.id, title: selection.title, summary: selection.summary, type: 'snippet', slug: '/', access: { policy: 'public' } } };
             const checkSnippet = (id, seen = new Set()) => {
@@ -190,7 +192,7 @@ export async function exportContent(configFile, destination, options = {}) {
                 const source = snippets.get(id);
                 if (!source)
                     throw new Error(`Unknown snippet ${id}`);
-                visitTree(pruneFeatureTree(source.tree, loaded.deployment?.context, source.file), node => {
+                visitTree(pruneSelectedTree(source.tree, snippetDocument, source.file, false), node => {
                     if (['RelatedReading', 'DocCard', 'DocCards', 'DocCollection', 'CookbookChooser', 'ApiExample', 'ApiSchema', 'FrontmatterReference', 'Anchor'].includes(node.name))
                         throw new Error(`Snippet instance ${selection.id}: <${node.name}> needs page context`);
                     if (node.name === 'Snippet') {
@@ -316,6 +318,11 @@ export async function exportContent(configFile, destination, options = {}) {
         const key = `${sourceKeyFor(destination)}:${format}`;
         if (canonicalAnchors.has(key))
             return canonicalAnchors.get(key);
+        // An export-selected tree cannot prove anchors in a differently selected website.
+        // Refuse the fragment rather than silently publish a broken canonical link.
+        const normalizeSelection = (value) => JSON.stringify(Object.entries(value ?? {}).sort(([a], [b]) => compare(a, b)).map(([facet, choices]) => [facet, [...choices].sort(compare)]));
+        if (sectionSelection.hasConditions && normalizeSelection(selection) !== normalizeSelection(siteSelection))
+            throw new Error(`Cannot verify canonical anchor in ${destination.frontmatter.id} across different site and export contentFilter selections; include the target resource or use its page URL without a fragment`);
         const source = sourceInventories.get(key);
         if (!source || destination.endpoint)
             throw new Error(`Cannot validate canonical fragments in ${destination.frontmatter.id}; select the target resource explicitly`);
@@ -553,7 +560,7 @@ export async function exportContent(configFile, destination, options = {}) {
         };
         const input = { documents: printDocuments, title: selected.length === 1 ? selected[0].title : site.title, publication, assets: assets.artifacts, publicBase: target.publicBase, config: pdfConfig, configFile, assetRoots: [...roots, ...pdfInputs.map(file => path.dirname(file))] };
         const preparedPdf = { input, manifest, inputs };
-        const common = { status: unreviewed.length ? 'needs-review' : 'ok', output: path.resolve(destination || base), publication, formats: target.formats, profileSelection: profileSelection(loaded.deployment), resources: records.length, documents: records.length, documentIds: selected.map(item => item.doc.frontmatter.id), comparison: { status: 'no-baseline', added: [], removed: [], diagnostics: [] }, assets: assets.records.size, apiReview: manifest.review.apis, diagnostics };
+        const common = { status: unreviewed.length ? 'needs-review' : 'ok', output: path.resolve(destination || base), publication, formats: target.formats, profileSelection: profileSelection(loaded.deployment), contentSelection: sectionSelectionReport(sectionSelection), resources: records.length, documents: records.length, documentIds: selected.map(item => item.doc.frontmatter.id), comparison: { status: 'no-baseline', added: [], removed: [], diagnostics: [] }, assets: assets.records.size, apiReview: manifest.review.apis, diagnostics };
         if (options.preparePdfOnly)
             return { ...common, digest: exportDigest(JSON.stringify(manifest)), preparedPdf };
         checkOutputDirectory(destination, base, workspace.contentDir, inputs);
@@ -573,6 +580,7 @@ export async function exportContent(configFile, destination, options = {}) {
         const digest = exportDigest(JSON.stringify(payload));
         pdfArtifacts.set('manifest.json', JSON.stringify({ ...payload, digest }, null, 2) + '\n');
         await commitArtifacts(path.resolve(destination), pdfArtifacts, undefined, 'pdf');
+        await writeSectionSelectionReport(base, sectionSelection, { target: { kind: 'pdf', name: options.target ?? null, output: path.resolve(destination) }, buildId: digest, configDigest: loaded.digest, filterOrigin: target.contentFilter ? 'export.contentFilter' : 'site.contentFilter' });
         return { ...common, digest, pdf: filename };
     }
     const manifest = { schemaVersion: publication.product === undefined ? 1 : 2, kind: 'shoalrun-content-export', publicBase: target.publicBase, publication,
@@ -599,7 +607,8 @@ export async function exportContent(configFile, destination, options = {}) {
             throw new Error('Review candidate cannot overwrite an approved export; choose a separate review destination');
     }
     await commitArtifacts(path.resolve(destination), artifacts, undefined, 'export');
+    await writeSectionSelectionReport(base, sectionSelection, { target: { kind: 'export', name: options.target ?? null, output: path.resolve(destination) }, buildId: bundleDigest, configDigest: loaded.digest, filterOrigin: target.contentFilter ? 'export.contentFilter' : 'unfiltered' });
     return { status: unreviewed.length ? 'needs-review' : 'ok', output: path.resolve(destination), publication, formats: target.formats,
-        profileSelection: profileSelection(loaded.deployment), resources: records.length, documents: records.filter(item => item.ref.kind === 'page').length, documentIds: records.flatMap(item => item.ref.kind === 'page' ? [item.ref.documentId] : []), comparison, assets: assets.records.size, digest: bundleDigest,
+        profileSelection: profileSelection(loaded.deployment), contentSelection: sectionSelectionReport(sectionSelection), resources: records.length, documents: records.filter(item => item.ref.kind === 'page').length, documentIds: records.flatMap(item => item.ref.kind === 'page' ? [item.ref.documentId] : []), comparison, assets: assets.records.size, digest: bundleDigest,
         apiReview: reviews.map(row => ({ apiId: row.apiId, digest: row.digest })), diagnostics };
 }

package/dist/content-filter.d.ts

@@ -2,3 +2,5 @@ import { type ReaderFiltersConfig, type ReaderSelection } from './reader-filters
 /** Build-time page selection; every selected facet must match at least one choice. */
 export declare function validateContentFilter(value: unknown, facets?: ReaderFiltersConfig): ReaderSelection | undefined;
 export declare function matchesContentFilter(marks: ReaderSelection | undefined, selection: ReaderSelection | undefined): boolean;
+/** Section requirements narrow a selected page; unselected facets pass. */
+export declare function matchesSectionContentFilter(requirements: ReaderSelection, selection: ReaderSelection | undefined): boolean;

package/dist/content-filter.js

@@ -14,3 +14,7 @@ export function validateContentFilter(value, facets) {
 export function matchesContentFilter(marks, selection) {
     return !selection || Object.entries(selection).every(([facet, choices]) => choices.some(choice => marks?.[facet]?.includes(choice)));
 }
+/** Section requirements narrow a selected page; unselected facets pass. */
+export function matchesSectionContentFilter(requirements, selection) {
+    return Object.entries(requirements).every(([facet, choices]) => !selection?.[facet] || choices.some(choice => selection[facet].includes(choice)));
+}

package/dist/content-mount.d.ts

@@ -1,10 +1,21 @@
 import type { ContentAnchor, ContentLink, ContentResult } from './content-delivery-contract.js';
+/** Handles and rewritten routing metadata for one mounted HTML instance. */
 export type ContentMount = {
+    /** Anchors after instance-specific ID rewriting. */
     anchors: readonly ContentAnchor[];
+    /** Typed links, including rewritten local fragments for this instance. */
     links: readonly ContentLink[];
+    /** Remove nodes that still belong to this mount. */
     unmount(): void;
 };
-/** Mount trusted compiler output, not arbitrary HTML. This is not a sanitizer. */
+/** Mount trusted compiler HTML with instance-specific anchor and accessibility IDs.
+ * This is not a sanitizer. The result must come from trusted compiler output.
+ * The mount replaces the container's children and rewrites local routing metadata.
+ * @param container DOM element receiving the content.
+ * @param result A validated HTML representation; Markdown results aren't accepted.
+ * @param options Optional unique instance ID and cancellation signal.
+ * @returns Rewritten anchors, typed links, and an unmount handle.
+ */
 export declare function mountContent(container: Element, result: ContentResult, options?: {
     instanceId?: string;
     signal?: AbortSignal;

package/dist/content-mount.js

@@ -1,5 +1,12 @@
 import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
-/** Mount trusted compiler output, not arbitrary HTML. This is not a sanitizer. */
+/** Mount trusted compiler HTML with instance-specific anchor and accessibility IDs.
+ * This is not a sanitizer. The result must come from trusted compiler output.
+ * The mount replaces the container's children and rewrites local routing metadata.
+ * @param container DOM element receiving the content.
+ * @param result A validated HTML representation; Markdown results aren't accepted.
+ * @param options Optional unique instance ID and cancellation signal.
+ * @returns Rewritten anchors, typed links, and an unmount handle.
+ */
 export function mountContent(container, result, options = {}) {
     options.signal?.throwIfAborted();
     if (result.format !== 'html')

package/dist/content-rest-client.d.ts

@@ -1,12 +1,22 @@
 import type { ContentSnapshot, ContentPublication } from './content-delivery-contract.js';
 import type { ContentDeliveryLimits } from './content-delivery.js';
+/** Options for a REST inventory and its revision-pinned resource reads. */
 export type RestContentSourceOptions = {
+    /** REST mount URL, such as /content/v1. Browser requests must use the application's origin. */
     baseUrl: string | URL;
+    /** Exact publication to request; include product for a product-scoped source. */
     publication: ContentPublication;
+    /** Expected inventory revision. Omit it to open the current revision. */
     revision?: string;
+    /** Fetch implementation. Defaults to globalThis.fetch. */
     fetch?: typeof globalThis.fetch;
+    /** Cancel the inventory-opening request. */
     signal?: AbortSignal;
+    /** Inventory and representation bounds. */
     limits?: ContentDeliveryLimits;
 };
-/** Preloads a REST inventory and pins all subsequent reads to that revision. */
+/** Open a REST inventory and pin subsequent resource reads to its revision.
+ * @param options REST mount, exact publication, optional revision, and request settings.
+ * @returns A snapshot with the same list/get/dispose interface as the manifest source.
+ */
 export declare function openRestContentSource(options: RestContentSourceOptions): Promise<ContentSnapshot>;

package/dist/content-rest-client.js

@@ -7,7 +7,10 @@ const digestPattern = /^[a-f0-9]{64}$/;
 const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const exactKeys = (value, keys) => record(value) && Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
 const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
-/** Preloads a REST inventory and pins all subsequent reads to that revision. */
+/** Open a REST inventory and pin subsequent resource reads to its revision.
+ * @param options REST mount, exact publication, optional revision, and request settings.
+ * @returns A snapshot with the same list/get/dispose interface as the manifest source.
+ */
 export async function openRestContentSource(options) {
     let baseUrl;
     try {

package/dist/content-rest-contract.d.ts

@@ -1,16 +1,19 @@
 import type { ContentPublication, ContentRef, ContentResource } from './content-delivery-contract.js';
 /** Public identity only: independent of publication, revision, and export filenames. */
 export declare function contentResourceKey(ref: ContentRef): string;
+/** One resource inventory entry with its REST lookup key. */
 export type ContentRestEntry = {
     key: string;
     resource: ContentResource;
 };
+/** Revision-scoped inventory envelope returned by the content REST service. */
 export type ContentRestList = {
     schemaVersion: 1 | 2;
     revision: string;
     publication: ContentPublication;
     resources: ContentRestEntry[];
 };
+/** Revision-scoped metadata envelope for a single content resource. */
 export type ContentRestResource = {
     schemaVersion: 1 | 2;
     revision: string;
@@ -18,7 +21,9 @@ export type ContentRestResource = {
     key: string;
     resource: ContentResource;
 };
+/** Error categories used by the content REST protocol. */
 export type ContentRestErrorCode = 'invalid_request' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'method_not_allowed' | 'internal_error';
+/** JSON error envelope returned by the content REST service. */
 export type ContentRestError = {
     error: {
         code: ContentRestErrorCode;

package/dist/content-source.d.ts

@@ -57,6 +57,7 @@ export type Frontmatter = {
     [key: string]: unknown;
 };
 export type Document = {
+    sectionSelection?: import('./section-selection.js').SectionSelection;
     codeReference?: import('./code-reference-model.js').CodeReference;
     featureContext?: import('./deployment-profile.js').FeatureContext;
     change?: ResolvedChange;

package/dist/content-workspace.d.ts

@@ -1,3 +1,4 @@
+import { type SectionSelection } from './section-selection.js';
 import { type Document, type Variant } from './content.js';
 import { type AuthoredPublicationConfig } from './publication-plan.js';
 import { type loadConfig } from './config.js';
@@ -5,7 +6,7 @@ import { type SnippetDefinition } from './snippets.js';
 import type { ReaderFiltersConfig, ReaderSelection } from './reader-filters.js';
 import type { loadMetadataProvider } from './metadata-provider.js';
 /** Shared source resolution. No website navigation, styles, hosting or provider setup. */
-export declare function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }: {
+export declare function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions, sectionSelection: suppliedSectionSelection }: {
     base: string;
     basePath: string;
     config: AuthoredPublicationConfig & {
@@ -19,12 +20,14 @@ export declare function prepareContentWorkspace({ base, basePath, config, loaded
     language: string;
     readerFilters?: ReaderFiltersConfig;
     contentFilter?: ReaderSelection;
+    sectionSelection?: SectionSelection;
     metadataProvider?: Awaited<ReturnType<typeof loadMetadataProvider>>;
     metadataDependencies: Set<string>;
     sourceOverrides?: ReadonlyMap<string, string>;
     authoringFiles?: ReadonlySet<string>;
     allowRouteCollisions?: boolean;
 }): Promise<{
+    sectionSelection: SectionSelection;
     docs: Map<string, Document>;
     knownDocumentIds: Set<string>;
     knownDocumentTypes: Map<string, string>;

package/dist/content-workspace.js

@@ -1,3 +1,4 @@
+import { createSectionSelection } from './section-selection.js';
 import { documentKey } from './publication-identity.js';
 import { matchesFeatures } from './deployment-profile.js';
 import path from 'node:path';
@@ -10,7 +11,8 @@ import { explainSegments } from './config.js';
 import { validateSnippetConfig } from './snippets.js';
 const keyFor = documentKey;
 /** Shared source resolution. No website navigation, styles, hosting or provider setup. */
-export async function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions }) {
+export async function prepareContentWorkspace({ base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions, sectionSelection: suppliedSectionSelection }) {
+    const sectionSelection = suppliedSectionSelection ?? createSectionSelection(readerFilters, contentFilter, config.publications);
     const { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir } = await planAuthoredDocuments({
         base, basePath, config, variants, language, readerFilters, contentFilter, featureContext: loaded.deployment?.context, metadataProvider, metadataDependencies, sourceOverrides, authoringFiles, allowRouteCollisions
     });
@@ -34,6 +36,7 @@ export async function prepareContentWorkspace({ base, basePath, config, loaded,
     });
     const { api, sourceForVariant, knownOperations } = apiPlan;
     for (const [key, doc] of docs) {
+        doc.sectionSelection = sectionSelection;
         doc.featureContext = loaded.deployment?.context;
         for (const operationId of doc.frontmatter.operations ?? []) {
             const known = knownOperations.get(operationId);
@@ -84,6 +87,6 @@ export async function prepareContentWorkspace({ base, basePath, config, loaded,
             throw new Error(`no OpenAPI source for ${variant.channel}/${variant.version} (${operationId})`);
         return { ...binding, sourceOperationId: operation.sourceOperationId };
     };
-    return { docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir, snippets,
+    return { sectionSelection, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, contentDir, snippets,
         apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation };
 }

package/dist/deployment-profile.d.ts

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

package/dist/deployment-profile.js

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

package/dist/palettes.d.ts

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

package/dist/publication-manifest.js

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

package/dist/representation-tree.js

@@ -20,8 +20,14 @@ export function publicTree(tree, representation, documentRoutes, mode = 'light',
                     element('div', { 'data-component-content': '' }, children)
                 ])];
         }
-        if (node.type === 'docRepresentation')
-            return node.representation === representation ? node.children.flatMap(walk) : [];
+        if (node.type === 'docRepresentation') {
+            if (node.representation !== representation)
+                return [];
+            const children = node.children.flatMap(walk);
+            // Mark HTML-only content so agent-parity checks can distinguish intentional
+            // format-specific prose from accidental content loss in the Markdown twin.
+            return representation === 'html' ? [element('div', { 'data-markdown-ignore': '' }, children)] : children;
+        }
         if (node.type === 'docCookbookChooser') {
             const prompt = node.mode === 'single' ? 'Choose one recipe.' : 'Choose one or more recipes.';
             const details = (option) => [option.when ? `Use when: ${option.when}` : option.summary, option.needs ? `You need: ${option.needs}` : '', option.outcome ? `You will have: ${option.outcome}` : ''].filter(Boolean);

package/dist/search-query.js

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

package/dist/section-selection.d.ts

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

package/dist/section-selection.js

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

package/dist/snippets.d.ts

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

package/example-configs/facet-sections/README.md

@@ -0,0 +1,37 @@
+# Additional information in a selected build
+
+This example uses one shared page, with an internal operations section. It needs
+no customer profile or feature manifest. From this directory, with Shoalrun installed:
+
+```sh
+shoalrun build docs.config.yaml dist/complete
+shoalrun build customer.config.yaml dist/customer
+shoalrun serve dist/complete --port 8771
+```
+
+Open <http://127.0.0.1:8771/>. In another terminal, serve the customer output:
+
+```sh
+shoalrun serve dist/customer --port 8772
+```
+
+Open <http://127.0.0.1:8772/>. Both sites show **Review a bill** and **Get help**.
+Only the complete build has **Check the retry queue**. Check `index.md` and
+`search-index.json` in each output: the customer files must contain neither that
+heading nor its instructions. The unfiltered build includes all valid blocks.
+
+**Unmarked sections stay included. Unmarked pages are excluded when a selected
+facet has no matching page mark.** This page explicitly belongs to both audiences.
+`<ForFacet audience="internal partner">` would accept either choice if both were
+configured; multiple facet attributes must all match. A facet the build doesn't
+filter passes automatically. Selection removes sections rather than swapping
+variants. Use positive literal matches only.
+
+`<ReaderSection>` is different: it hides content in browser views while publishing
+it in output files. Never use it to omit internal instructions from a customer
+build. Build-time omission doesn't authenticate the complete site's deployment.
+
+After each successful build, `.shoalrun/content-selection.json` records its target
+and section decisions. Follow its `receipt` path for the artifact-specific copy;
+these reports belong outside served output. Portable exports need their own
+`contentFilter`; PDF exports inherit the site's filter unless overridden.