@shoalrun/cli 0.1.0-beta.1 → 1.1.0

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

@@ -1,11 +1,16 @@
 /** Browser-safe delivery contracts. These types do not import the compiler. */
+/** Exact documentation publication selected by a content source. */
 export type ContentPublication = {
     channel: string;
     version: string;
     language: string;
     product?: string;
 };
+/** Portable representations a content client can request. */
 export type ContentFormat = 'html' | 'markdown';
+/** Stable identity of a page, a section within a page, or a named snippet instance.
+ * A reference is scoped to the publication and revision of the opened snapshot.
+ */
 export type ContentRef = {
     kind: 'page';
     documentId: string;
@@ -17,19 +22,23 @@ export type ContentRef = {
     kind: 'snippet';
     id: string;
 };
+/** Export-relative file path, byte length, and SHA-256 digest. */
 export type ContentFile = {
     path: string;
     bytes: number;
     digest: string;
 };
+/** A content-addressed file with its declared media type. */
 export type ContentAsset = ContentFile & {
     mediaType: string;
 };
+/** Mapping from a canonical document fragment to its exported HTML ID. */
 export type ContentAnchor = {
     id: string;
     exportedId: string;
     title?: string;
 };
+/** Classified link and optional resource identity for application routing. */
 export type ContentLink = {
     key: string;
     kind: 'resource' | 'canonical' | 'external' | 'asset';
@@ -39,15 +48,22 @@ export type ContentLink = {
     query?: string;
     asset?: string;
 };
+/** One portable format, including its file metadata, anchors, and typed links. */
 export type ContentRepresentation = ContentAsset & {
     anchors: ContentAnchor[];
     links: ContentLink[];
 };
+/** Inventory entry describing one exported document, section, or snippet instance. */
 export type ContentResource = {
+    /** Stable identity used by ContentSnapshot.get. */
     ref: ContentRef;
+    /** Exact product, channel, version, and documentation language. */
     publication: ContentPublication;
+    /** Human-readable resource title. */
     title: string;
+    /** Short explanation of the resource's purpose. */
     summary: string;
+    /** Authored document type, or section/snippet for a selected resource. */
     type: string;
     canonicalUrl?: string;
     source?: {
@@ -55,6 +71,7 @@ export type ContentResource = {
         snippetId?: string;
         valuesDigest?: string;
     };
+    /** Available portable formats and their files, anchors, and typed links. */
     representations: Partial<Record<ContentFormat, ContentRepresentation>>;
     assets: string[];
     externalDependencies: Array<{
@@ -62,6 +79,7 @@ export type ContentResource = {
         kind: 'image';
     }>;
 };
+/** One validated, content-addressed export inventory. */
 export type ContentManifest = {
     schemaVersion: 1 | 2;
     kind: 'shoalrun-content-export';
@@ -84,26 +102,47 @@ export type ContentManifest = {
         message: string;
     }>;
 };
+/** A fetched representation together with the metadata needed to render or route it. */
 export type ContentResult = {
+    /** Inventory entry that was selected by the requested reference. */
     resource: Readonly<ContentResource>;
+    /** File, media type, anchors, and typed links for the selected format. */
     representation: Readonly<ContentRepresentation>;
+    /** Representation actually returned by the source. */
     format: ContentFormat;
+    /** Validated UTF-8 HTML or Markdown text. */
     content: string;
+    /** Revision shared by this response and its opened content snapshot. */
     revision: string;
 };
+/** A client pinned to one immutable inventory revision and publication. */
 export interface ContentSnapshot {
+    /** Content digest identifying this inventory revision. */
     readonly revision: string;
+    /** Publication shared by every resource available from this snapshot. */
     readonly publication: Readonly<ContentPublication>;
+    /** List the resources in the opened inventory without fetching their bodies.
+     * @returns Read-only resource entries for this publication and revision.
+     */
     list(): readonly Readonly<ContentResource>[];
+    /** Fetch one available representation of a stable content reference.
+     * @param ref Page, section, or named snippet instance in this snapshot.
+     * @param options Required format and an optional signal for this read.
+     * @returns Validated representation text with its routing and revision metadata.
+     */
     get(ref: ContentRef, options: {
         format: ContentFormat;
         signal?: AbortSignal;
     }): Promise<ContentResult>;
+    /** Cancel pending requests and prevent subsequent reads or inventory access. */
     dispose(): void;
 }
+/** Stable error categories raised by content-source validation and reads. */
 export type ContentErrorCode = 'invalid_manifest' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'network_error' | 'invalid_content' | 'disposed';
+/** Delivery failure with a machine-readable code and a human-readable message. */
 export declare class ContentDeliveryError extends Error {
     readonly code: ContentErrorCode;
     constructor(code: ContentErrorCode, message: string);
 }
+/** Serialize a reference to a deterministic key without including publication scope. */
 export declare function contentRefKey(ref: ContentRef): string;

package/dist/content-delivery-contract.js

@@ -1,3 +1,4 @@
+/** Delivery failure with a machine-readable code and a human-readable message. */
 export class ContentDeliveryError extends Error {
     code;
     constructor(code, message) {
@@ -6,6 +7,7 @@ export class ContentDeliveryError extends Error {
         this.name = 'ContentDeliveryError';
     }
 }
+/** Serialize a reference to a deterministic key without including publication scope. */
 export function contentRefKey(ref) {
     switch (ref.kind) {
         case 'page': return JSON.stringify(['page', ref.documentId]);

package/dist/content-delivery-validation.d.ts

@@ -2,6 +2,12 @@ import type { ContentManifest, ContentRef, ContentPublication } from './content-
 export declare const safeContentPath: (value: any) => value is string;
 export declare const validContentPublication: (value: any) => value is ContentPublication;
 export declare function validContentRef(value: any): value is ContentRef;
+/** Validate a parsed manifest's shape, identities, paths, and resource bounds.
+ * This assertion narrows the value but doesn't verify fetched file bytes or trust in a host.
+ * @param value Parsed JSON manifest to validate.
+ * @param maxResources Maximum allowed resource count; defaults to 10,000.
+ * @param maxResourceBytes Maximum declared representation bytes; defaults to 8,000,000.
+ */
 export declare function validateContentManifest(value: any, maxResources?: number, maxResourceBytes?: number): asserts value is ContentManifest;
 /** Shared metadata validation; transport supplies its file/asset inventory policy. */
 export declare function validateContentResources(resources: any[], expectedPublication: unknown, assets: Set<string>, checkRepresentation: (value: any) => boolean, publicBase?: string): void;

package/dist/content-delivery-validation.js

@@ -26,6 +26,12 @@ function safeExternal(value, image = false) {
         return false;
     }
 }
+/** Validate a parsed manifest's shape, identities, paths, and resource bounds.
+ * This assertion narrows the value but doesn't verify fetched file bytes or trust in a host.
+ * @param value Parsed JSON manifest to validate.
+ * @param maxResources Maximum allowed resource count; defaults to 10,000.
+ * @param maxResourceBytes Maximum declared representation bytes; defaults to 8,000,000.
+ */
 export function validateContentManifest(value, maxResources = 10_000, maxResourceBytes = 8_000_000) {
     if (!keys(value, ['schemaVersion', 'kind', 'digest', 'publicBase', 'publication', 'review', 'resources', 'assets', 'files', 'diagnostics']) || ![1, 2].includes(value.schemaVersion) || value.kind !== 'shoalrun-content-export' || !digestPattern.test(value.digest ?? ''))
         invalid('Unsupported content manifest.');

package/dist/content-delivery.d.ts

@@ -4,18 +4,36 @@ export * from './content-rest-contract.js';
 export { validateContentManifest } from './content-delivery-validation.js';
 export { mountContent } from './content-mount.js';
 export type { ContentMount } from './content-mount.js';
+/** Positive safe-integer bounds applied when opening and reading content. */
 export type ContentDeliveryLimits = {
+    /** Maximum manifest or REST inventory bytes. Defaults to 5,000,000. */
     manifestBytes?: number;
+    /** Maximum bytes for an individual representation. Defaults to 8,000,000. */
     resourceBytes?: number;
+    /** Maximum resource count in the inventory. Defaults to 10,000. */
     resources?: number;
 };
+/** Configuration for opening a static content-export manifest. */
 export type ManifestContentSourceOptions = {
+    /** Manifest URL; a browser resolves relative URLs against its current location. */
     manifestUrl: string | URL;
+    /** Fetch implementation. Defaults to globalThis.fetch. */
     fetch?: typeof globalThis.fetch;
+    /** Cancel the opening request. Use get's signal to cancel an individual read. */
     signal?: AbortSignal;
+    /** Inventory and representation bounds. */
     limits?: ContentDeliveryLimits;
 };
-/** Opens one immutable manifest revision. The caller owns trust in the build/host. */
+/** Open and validate one immutable static manifest revision.
+ * The caller owns trust in the compiler output and host. Browser URLs must use
+ * the application's origin. Requests reject redirects and unexpected content types.
+ * @param options Manifest URL, request implementation, cancellation, and limits.
+ * @returns A revision-pinned snapshot for listing and reading exported resources.
+ * @example
+ * const snapshot = await openManifestContentSource({ manifestUrl: '/help/manifest.json' });
+ * const page = await snapshot.get({ kind: 'page', documentId: 'guide.start' }, { format: 'markdown' });
+ * snapshot.dispose();
+ */
 export declare function openManifestContentSource(options: ManifestContentSourceOptions): Promise<ContentSnapshot>;
 export { openRestContentSource } from './content-rest-client.js';
 export type { RestContentSourceOptions } from './content-rest-client.js';

package/dist/content-delivery.js

@@ -6,7 +6,16 @@ export { validateContentManifest } from './content-delivery-validation.js';
 import { freeze, sha256, readBounded } from './content-delivery-transport.js';
 const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
 export { mountContent } from './content-mount.js';
-/** Opens one immutable manifest revision. The caller owns trust in the build/host. */
+/** Open and validate one immutable static manifest revision.
+ * The caller owns trust in the compiler output and host. Browser URLs must use
+ * the application's origin. Requests reject redirects and unexpected content types.
+ * @param options Manifest URL, request implementation, cancellation, and limits.
+ * @returns A revision-pinned snapshot for listing and reading exported resources.
+ * @example
+ * const snapshot = await openManifestContentSource({ manifestUrl: '/help/manifest.json' });
+ * const page = await snapshot.get({ kind: 'page', documentId: 'guide.start' }, { format: 'markdown' });
+ * snapshot.dispose();
+ */
 export async function openManifestContentSource(options) {
     const fetcher = options.fetch ?? globalThis.fetch;
     let manifestUrl;

package/dist/content-export-command.d.ts

@@ -4,7 +4,12 @@ export declare function runExportCommand(args: string[]): Promise<{
     preparedPdf: import("./content-export.js").PdfExportPreparation;
     status: string;
     output: string;
-    publication: import("./content-source.js").Variant;
+    publication: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
     formats: import("./content-export-config.js").ExportFormat[];
     profileSelection: {
         schemaVersion: number;
@@ -18,6 +23,14 @@ export declare function runExportCommand(args: string[]): Promise<{
             requires?: import("./deployment-profile.js").FeatureRequirements;
         }[];
     } | undefined;
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     resources: number;
     documents: number;
     documentIds: string[];
@@ -42,7 +55,12 @@ export declare function runExportCommand(args: string[]): Promise<{
     pdf: string;
     status: string;
     output: string;
-    publication: import("./content-source.js").Variant;
+    publication: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
     formats: import("./content-export-config.js").ExportFormat[];
     profileSelection: {
         schemaVersion: number;
@@ -56,6 +74,14 @@ export declare function runExportCommand(args: string[]): Promise<{
             requires?: import("./deployment-profile.js").FeatureRequirements;
         }[];
     } | undefined;
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     resources: number;
     documents: number;
     documentIds: string[];
@@ -78,7 +104,12 @@ export declare function runExportCommand(args: string[]): Promise<{
 } | {
     status: string;
     output: string;
-    publication: import("./content-source.js").Variant;
+    publication: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
     formats: import("./content-export-config.js").ExportFormat[];
     profileSelection: {
         schemaVersion: number;
@@ -92,6 +123,14 @@ export declare function runExportCommand(args: string[]): Promise<{
             requires?: import("./deployment-profile.js").FeatureRequirements;
         }[];
     } | undefined;
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     resources: number;
     documents: number;
     documentIds: string[];

package/dist/content-export.d.ts

@@ -66,7 +66,12 @@ export declare function exportContent(configFile: string, destination: string, o
     preparedPdf: PdfExportPreparation;
     status: string;
     output: string;
-    publication: Variant;
+    publication: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
     formats: ExportFormat[];
     profileSelection: {
         schemaVersion: number;
@@ -80,6 +85,14 @@ export declare function exportContent(configFile: string, destination: string, o
             requires?: import("./deployment-profile.js").FeatureRequirements;
         }[];
     } | undefined;
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     resources: number;
     documents: number;
     documentIds: string[];
@@ -104,7 +117,12 @@ export declare function exportContent(configFile: string, destination: string, o
     pdf: string;
     status: string;
     output: string;
-    publication: Variant;
+    publication: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
     formats: ExportFormat[];
     profileSelection: {
         schemaVersion: number;
@@ -118,6 +136,14 @@ export declare function exportContent(configFile: string, destination: string, o
             requires?: import("./deployment-profile.js").FeatureRequirements;
         }[];
     } | undefined;
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     resources: number;
     documents: number;
     documentIds: string[];
@@ -140,7 +166,12 @@ export declare function exportContent(configFile: string, destination: string, o
 } | {
     status: string;
     output: string;
-    publication: Variant;
+    publication: {
+        product?: string;
+        channel: string;
+        version: string;
+        language: string;
+    };
     formats: ExportFormat[];
     profileSelection: {
         schemaVersion: number;
@@ -154,6 +185,14 @@ export declare function exportContent(configFile: string, destination: string, o
             requires?: import("./deployment-profile.js").FeatureRequirements;
         }[];
     } | undefined;
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     resources: number;
     documents: number;
     documentIds: string[];

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,8 @@ 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;
     subjectDeprecation?: ResolvedSubjectDeprecation;

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,25 +6,28 @@ 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 & {
         snippets?: unknown;
         variables?: unknown;
         apis?: unknown;
+        codeReferences?: unknown;
     };
     loaded: Awaited<ReturnType<typeof loadConfig>>;
     variants: Variant[];
     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>;