@shoalrun/cli 1.0.0 → 1.1.0

package/agent-docs/start.md

@@ -36,7 +36,7 @@ Install an exact version of the beta and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init .
 ```
 

package/agent-docs/start.sections/start-your-own-project.md

@@ -38,7 +38,7 @@ Install an exact version of the beta and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init .
 ```
 

package/assets/search-lexical.js

@@ -57,10 +57,21 @@ export async function search(query, context) {
     const matched = terms.filter(term => match(title, term) || match(summary, term) || match(text, term) || headings.some(heading => match(heading, term)));
     if (!matched.length) continue;
     let score = 0;
-    for (const term of terms) score += weight(title, term, title.startsWith(term.term) ? 12 : 8) || weight(summary, term, 4) || (headings.some(heading => match(heading, term)) ? 3 : 0) || weight(text, term, 1);
+    let contentScore = 0;
+    for (const term of terms) {
+      const termScore = weight(title, term, title.startsWith(term.term) ? 12 : 8) || weight(summary, term, 4) || (headings.some(heading => match(heading, term)) ? 3 : 0) || weight(text, term, 1);
+      score += termScore;
+      if (!fallbackStopWords.has(term.term)) contentScore += termScore;
+    }
     const section = filtered || terms.every(term => match(title, term)) ? undefined : doc.headings.find((heading, index) => terms.every(term => match(headings[index], term)));
-    hits.push({ score, matched: matched.length, partialMatched: matched.filter(term => !fallbackStopWords.has(term.term)).length, result: { url: section ? `${doc.url}#${section.id}` : doc.url, title: doc.title, summary: doc.summary, section: section?.title } });
+    hits.push({ score, contentScore, matched: matched.length, partialMatched: matched.filter(term => !fallbackStopWords.has(term.term)).length, result: { url: section ? `${doc.url}#${section.id}` : doc.url, title: doc.title, summary: doc.summary, section: section?.title } });
   }
-  const complete = hits.filter(hit => hit.matched === terms.length);
-  return (complete.length ? complete : hits.filter(hit => hit.partialMatched > 0)).sort((a, b) => (complete.length ? b.matched - a.matched : b.partialMatched - a.partialMatched) || b.score - a.score || a.result.title.localeCompare(b.result.title)).slice(0, context.limit).map(hit => hit.result);
+  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);
+  return (complete.length ? complete : hits.filter(hit => hit.partialMatched > 0)).sort((a, b) => (complete.length ? b.contentScore - a.contentScore : b.partialMatched - a.partialMatched) || b.score - a.score || a.result.title.localeCompare(b.result.title)).slice(0, context.limit).map(hit => hit.result);
 }

package/dist/code-reference-model.d.ts

@@ -17,14 +17,14 @@ export declare const codeReferenceSchema: z.ZodObject<{
             constructor: "constructor";
             module: "module";
             type: "type";
-            constant: "constant";
-            enum: "enum";
-            method: "method";
-            property: "property";
             namespace: "namespace";
             class: "class";
             interface: "interface";
+            enum: "enum";
+            method: "method";
+            property: "property";
             attribute: "attribute";
+            constant: "constant";
         }>;
         parent: z.ZodOptional<z.ZodString>;
         visibility: z.ZodDefault<z.ZodEnum<{

package/dist/compiler.d.ts

@@ -39,6 +39,14 @@ export declare function compile(configFile: string, destination?: string, proven
             }>;
         }>;
     }[];
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     profileSelection: {
         schemaVersion: number;
         profileDigest: string;

package/dist/compiler.js

@@ -1,3 +1,4 @@
+import { sectionSelectionReport, writeSectionSelectionReport } from './section-selection.js';
 import { buildPdfSiteArtifacts } from './pdf-site.js';
 import { resolvePdfButton, validatePdfButtonStyle } from './pdf-button.js';
 import { documentKey, publicationKey, samePublication } from './publication-identity.js';
@@ -306,7 +307,7 @@ async function compileProject(configFile, destination, provenance, options, ownH
     const varying = (field) => new Set(variants.map(variant => variant[field])).size > 1;
     const editionLabel = (variant) => editionBadge === 'never' ? '' : ['product', 'channel', 'version', 'language']
         .filter(field => variant[field] !== undefined && (editionBadge === 'always' || varying(field))).map(field => variant[field]).join(' · ');
-    const { docs, knownDocumentIds, knownDocumentTypes, routeOwners, contentDir, snippets, apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation } = await prepareContentWorkspace({
+    const { sectionSelection, docs, knownDocumentIds, knownDocumentTypes, routeOwners, contentDir, snippets, apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation } = await prepareContentWorkspace({
         base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies,
         sourceOverrides: options.sourceOverrides, authoringFiles: options.authoringFiles
     });
@@ -481,12 +482,15 @@ async function compileProject(configFile, destination, provenance, options, ownH
     const { artifacts, buildId } = await assembleArtifacts({
         extraArtifacts: sitePdfs.artifacts,
         base, basePath, publicPath, canonical, siteOrigin, manifest, provenanceRecord, rendered, sitemaps,
-        privateDependencies: new Set([...(loaded.deployment?.file ? [loaded.deployment.file] : []), ...(loaded.deployment?.assetFiles ?? [])]),
+        privateDependencies: new Set([
+            ...[...snippets.values()].filter(snippet => !snippetUses.some(use => use.file === snippet.file)).map(snippet => snippet.file),
+            ...(sectionSelection.hasConditions || contentFilter ? componentPlugins.dependencies : []), ...(loaded.deployment?.file ? [loaded.deployment.file] : []), ...(loaded.deployment?.assetFiles ?? [])
+        ]),
         diagramAssets, heroImages, focusedContracts, styleFiles, themeStyleFile, generatedPaletteCss,
         generatedBadgeCss, search, synonyms, config: artifactConfig, builtInSearchProvider, customReaderModule, analyticsModule, mcpAnalyticsModule,
         previewFiles, assetDirectory, themeSwitcher, themeDirectory, palette, colorMode, generatedFontsCss,
         fontFiles, projectFontAssets, fonts, shareImages, shareFor, themePreset, shareFontFiles, shareCache, faviconFile,
-        faviconRoute, customStyleFile, scriptFiles, componentAssets: loaded.deployment?.context.grants ? componentPlugins.assets.filter(asset => usedComponentAssets.has(asset.route)) : componentPlugins.assets, redirects, apiPublications, api, catalog, headers,
+        faviconRoute, customStyleFile, scriptFiles, componentAssets: loaded.deployment?.context.grants || sectionSelection.hasConditions || contentFilter ? componentPlugins.assets.filter(asset => usedComponentAssets.has(asset.route)) : componentPlugins.assets, redirects, apiPublications, api, catalog, headers,
         documentRoutes, readerFilters, apiSources
     });
     if (destination) {
@@ -500,9 +504,11 @@ async function compileProject(configFile, destination, provenance, options, ownH
             if (loaded.deployment?.context.grants && !options.authoringFiles)
                 await writeFile(path.join(localGuide, 'profile-selection.json'), JSON.stringify({ ...profileSelection(loaded.deployment), buildId, configDigest: loaded.digest }, null, 2) + '\n');
         });
+        if (!options.authoringFiles)
+            await writeSectionSelectionReport(base, sectionSelection, { target: { kind: 'site', output: target }, buildId, configDigest: loaded.digest, filterOrigin: 'site.contentFilter' });
         // Authoring captures resolve revision dates without changing captured inputs.
         if (!options.authoringFiles)
             await freshness?.commit();
     }
-    return { ...manifest, buildId, apiPublicationReview, profileSelection: profileSelection(loaded.deployment), ...(options.authoringFiles ? { authoringSources: rendered.map(({ doc }) => ({ id: doc.frontmatter.id, file: doc.file, url: doc.route, markdownUrl: doc.markdownRoute })) } : {}) };
+    return { ...manifest, buildId, apiPublicationReview, contentSelection: sectionSelectionReport(sectionSelection), profileSelection: profileSelection(loaded.deployment), ...(options.authoringFiles ? { authoringSources: rendered.map(({ doc }) => ({ id: doc.frontmatter.id, file: doc.file, url: doc.route, markdownUrl: doc.markdownRoute })) } : {}) };
 }

package/dist/component-names.js

@@ -1 +1 @@
-export const builtinComponentNames = new Set('Anchor FrontmatterReference ForFeature ForPublication ReaderSection ReaderChoice ReaderFilter Only Badge Kbd Tooltip InfoHint Progress Math ActionLink Button DefinitionList Term Definition Steps Timeline Milestone FileTree Tree Folder File Table CollapsibleGroup Collapsible Section Hero ThemePreview Diagram Image Tabs Walkthrough Step Tab Fields Field CookbookChooser DocCard DocCards DocCollection RelatedReading ApiExample ApiSchema Snippet Var DocLink Callout'.split(' '));
+export const builtinComponentNames = new Set('Anchor FrontmatterReference ForFeature ForFacet ForPublication ReaderSection ReaderChoice ReaderFilter Only Badge Kbd Tooltip InfoHint Progress Math ActionLink Button DefinitionList Term Definition Steps Timeline Milestone FileTree Tree Folder File Table CollapsibleGroup Collapsible Section Hero ThemePreview Diagram Image Tabs Walkthrough Step Tab Fields Field CookbookChooser DocCard DocCards DocCollection RelatedReading ApiExample ApiSchema Snippet Var DocLink Callout'.split(' '));

package/dist/component-transform.js

@@ -1,5 +1,5 @@
 import { documentKey } from './publication-identity.js';
-import { pruneFeatureTree } from './deployment-profile.js';
+import { createSectionSelection, evaluatePublicationGuard, pruneSelectedTree, warnReaderSection } from './section-selection.js';
 import { lowerComponent } from './component-plugins.js';
 import { cardComponent } from './cards.js';
 import { cookbookChooserComponent } from './cookbook-chooser.js';
@@ -61,8 +61,10 @@ function literalAttributes(attributes) {
 export function transformMdx(tree, current, registry, snippets = new Map(), projectValues = {}, uses = [], calloutTypes = resolveCalloutTypes(undefined, current.file), projectRoot, readerConfig, frontmatterConfig = {}, publicationConfig, badgeVariants = resolveBadgeVariants(undefined, current.file), componentPlugins = new Map(), publicationRegistry) {
     if (!isMdxRoot(tree))
         throw new Error(`${current.file}: parsed content must be a root with children`);
-    tree = lowerSectionMarkers(pruneFeatureTree(tree, current.featureContext, current.file), current.file);
-    snippets = new Map([...snippets].map(([id, definition]) => [id, { ...definition, tree: pruneFeatureTree(definition.tree, current.featureContext, definition.file) }]));
+    current.sectionSelection ??= createSectionSelection(readerConfig, undefined, publicationConfig);
+    const originalSnippets = snippets;
+    tree = lowerSectionMarkers(pruneSelectedTree(tree, current), current.file);
+    snippets = new Map([...snippets].map(([id, definition]) => [id, { ...definition, tree: pruneSelectedTree(definition.tree, current, definition.file, false) }]));
     let pluginDepth = 0;
     let tabsIndex = 0;
     let walkthroughIndex = 0;
@@ -133,27 +135,14 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                     throw new Error(`${sourceFile}: <FrontmatterReference> must be an empty block`);
                 return childrenOf(parsePlainMarkdown(frontmatterReference(frontmatterConfig, true)), scope, stack, sourceFile);
             }
-            if (node.name === 'ForFeature') {
-                const selected = pruneFeatureTree({ type: 'root', children: [node] }, current.featureContext, sourceFile);
+            if (node.name === 'ForFeature' || node.name === 'ForFacet') {
+                const selected = pruneSelectedTree({ type: 'root', children: [node] }, current, sourceFile);
                 return childrenOf(selected.children, scope, stack, sourceFile);
             }
             if (node.name === 'ForPublication') {
-                const attributes = node.attributes ?? [];
-                const allowed = ['product', 'channel', 'version', 'language'];
-                if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || !attributes.length || !literalAttributes(attributes) || attributes.some((item) => !allowed.includes(item.name) || !item.value.trim()) || new Set(attributes.map((item) => item.name)).size !== attributes.length) {
-                    throw new Error(`${sourceFile}: <ForPublication> needs block content and distinct literal channel, version, or language attributes`);
-                }
-                const product = attributes.find(item => item.name === 'product')?.value ?? current.variant.product;
-                for (const item of attributes) {
-                    const catalog = item.name === 'product' ? publicationConfig?.products
-                        : item.name === 'channel' ? publicationConfig?.channels
-                            : item.name === 'version' ? (product ? publicationConfig?.products?.[product]?.versions : publicationConfig?.versions) : undefined;
-                    if (publicationConfig && item.name !== 'language' && (!catalog || !Object.hasOwn(catalog, item.value)))
-                        throw new Error(`${sourceFile}: <ForPublication> names unknown ${item.name} ${item.value}`);
-                }
-                if (attributes.some((item) => current.variant[item.name] !== item.value))
+                if (!evaluatePublicationGuard(node, current, sourceFile, publicationConfig))
                     return [];
-                return childrenOf(node.children, scope, stack, sourceFile);
+                return childrenOf(node.children ?? [], scope, stack, sourceFile);
             }
             if (node.name === 'ReaderSection' || node.name === 'ReaderChoice' || node.name === 'ReaderFilter') {
                 if (!readerConfig || node.type !== 'mdxJsxFlowElement')
@@ -179,6 +168,8 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                 const selection = validateReaderSelection(choices, readerConfig, `${sourceFile}: <${node.name}>`);
                 if (!Object.keys(selection).length)
                     throw new Error(`${sourceFile}: <${node.name}> needs at least one filter choice`);
+                if (node.name === 'ReaderSection')
+                    warnReaderSection(current, sourceFile, node.position?.start?.line ?? 1, selection);
                 const description = Object.entries(selection).map(([facet, values]) => `${readerConfig.facets[facet].label}: ${values.map(value => readerConfig.facets[facet].options[value]).join(' or ')}`).join('; ');
                 const children = node.name === 'ReaderSection' ? childrenOf(node.children ?? [], scope, stack, sourceFile) : [];
                 const containsSection = (item) => item.type === 'docReaderSection' || (item.children ?? []).some(containsSection);
@@ -628,8 +619,9 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                 if (!invocation || typeof invocation !== 'object' || Array.isArray(invocation))
                     throw new Error(`${sourceFile}: snippet values must be a literal mapping`);
                 const values = resolveSnippetValues(id, definition, projectValues, { ...(current.frontmatter.variables ?? {}), ...scope }, invocation);
-                uses.push({ id, file: definition.file, documentId: current.frontmatter.id });
-                return childrenOf(definition.tree.children, values, [...stack, id], definition.file);
+                uses.push({ id, file: definition.file, documentId: current.frontmatter.id, documentKey: documentKey(current.frontmatter.id, current.variant) });
+                const selectedTree = pruneSelectedTree(originalSnippets.get(id).tree, current, definition.file);
+                return childrenOf(selectedTree.children, values, [...stack, id], definition.file);
             }
             if (node.name === 'Var') {
                 if (!stack.length || node.type !== 'mdxJsxTextElement' || node.children?.length)

package/dist/conditional-tree.d.ts

@@ -0,0 +1,2 @@
+/** Validate every guard, including excluded descendants, without expanding dependencies. */
+export declare function pruneConditionalTree(tree: any, evaluate: (node: any, ancestorIncluded: boolean) => boolean | undefined): any;

package/dist/conditional-tree.js

@@ -0,0 +1,14 @@
+/** Validate every guard, including excluded descendants, without expanding dependencies. */
+export function pruneConditionalTree(tree, evaluate) {
+    const walk = (node, ancestorIncluded = true) => {
+        if (!node || typeof node !== 'object')
+            return [node];
+        const match = evaluate(node, ancestorIncluded);
+        if (match !== undefined) {
+            const children = (node.children ?? []).flatMap((child) => walk(child, ancestorIncluded && match));
+            return ancestorIncluded && match ? children : [];
+        }
+        return [{ ...node, ...(node.children ? { children: node.children.flatMap((child) => walk(child, ancestorIncluded)) } : {}) }];
+    };
+    return walk(tree)[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[];