@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/compiler.js

@@ -7,7 +7,7 @@ import { resolveTaxonomy } from './taxonomy.js';
 import { resolveMcp } from './mcp-config.js';
 import { fictionalDocument, resolveLlmsDiscovery } from './llms-discovery.js';
 import { resolveAnalytics } from './analytics.js';
-import { navigationCounts } from './compiler-config.js';
+import { navigationCounts, navigationHeading } from './compiler-config.js';
 import { validateAuthoringGuidance } from './authoring-guidance.js';
 import { loadFreshness } from './freshness.js';
 import { resolveAgentDiscovery } from './agent-discovery.js';
@@ -226,6 +226,7 @@ export async function compile(configFile, destination, provenance = {}, options
     // `demo` ships it hidden until a page is opened with ?theme-switcher.
     const themeSwitcherSetting = configField(htmlOptions, 'themeSwitcher') ?? false;
     navigationCounts(config.outputs);
+    navigationHeading(config.outputs);
     if (typeof themeSwitcherSetting !== 'boolean' && themeSwitcherSetting !== 'demo')
         throw new Error('outputs.html.themeSwitcher must be true, false, or demo');
     const themeSwitcher = themeSwitcherSetting !== false;

package/dist/component-names.js

@@ -1 +1 @@
-export const builtinComponentNames = new Set('FrontmatterReference 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 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

@@ -15,6 +15,7 @@ import { validateReaderFilterControl, validateReaderSelection } from './reader-f
 import { walkthroughComponent } from './walkthrough.js';
 import { procedureComponent } from './procedure-components.js';
 import { parsePlainMarkdown, paragraph, link, text } from './semantic-markdown.js';
+import { lowerSectionMarkers, sectionIdentities } from './section-identity.js';
 function isMdxRoot(tree) {
     return !!tree && typeof tree === 'object'
         && tree.type === 'root'
@@ -58,6 +59,7 @@ 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()) {
     if (!isMdxRoot(tree))
         throw new Error(`${current.file}: parsed content must be a root with children`);
+    tree = lowerSectionMarkers(tree, current.file);
     let pluginDepth = 0;
     let tabsIndex = 0;
     let walkthroughIndex = 0;
@@ -98,6 +100,8 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
         if (node.type === 'heading' && stack.length)
             throw new Error(`${sourceFile}: snippet headings need an anchor adapter; put headings in the page`);
         if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+            if (node.name === 'Anchor')
+                throw new Error(`${sourceFile}: <Anchor> must be the single trailing marker of an authored root level-two heading`);
             if (node.name && componentPlugins.has(node.name)) {
                 const start = node.position?.start;
                 const location = `${sourceFile}${start ? `:${start.line}:${start.column}` : ''}: <${node.name}>`;
@@ -693,5 +697,7 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
         }
         return node;
     }
-    return walk(tree, {}, [], current.file);
+    const transformed = walk(tree, {}, [], current.file);
+    sectionIdentities(transformed, current.file);
+    return transformed;
 }

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

@@ -0,0 +1,108 @@
+/** Browser-safe delivery contracts. These types do not import the compiler. */
+export type ContentPublication = {
+    channel: string;
+    version: string;
+    language: string;
+};
+export type ContentFormat = 'html' | 'markdown';
+export type ContentRef = {
+    kind: 'page';
+    documentId: string;
+} | {
+    kind: 'section';
+    documentId: string;
+    sectionId: string;
+} | {
+    kind: 'snippet';
+    id: string;
+};
+export type ContentFile = {
+    path: string;
+    bytes: number;
+    digest: string;
+};
+export type ContentAsset = ContentFile & {
+    mediaType: string;
+};
+export type ContentAnchor = {
+    id: string;
+    exportedId: string;
+    title?: string;
+};
+export type ContentLink = {
+    key: string;
+    kind: 'resource' | 'canonical' | 'external' | 'asset';
+    href: string;
+    ref?: ContentRef;
+    fragment?: string;
+    query?: string;
+    asset?: string;
+};
+export type ContentRepresentation = ContentAsset & {
+    anchors: ContentAnchor[];
+    links: ContentLink[];
+};
+export type ContentResource = {
+    ref: ContentRef;
+    publication: ContentPublication;
+    title: string;
+    summary: string;
+    type: string;
+    canonicalUrl?: string;
+    source?: {
+        documentId?: string;
+        snippetId?: string;
+        valuesDigest?: string;
+    };
+    representations: Partial<Record<ContentFormat, ContentRepresentation>>;
+    assets: string[];
+    externalDependencies: Array<{
+        url: string;
+        kind: 'image';
+    }>;
+};
+export type ContentManifest = {
+    schemaVersion: 1;
+    kind: 'shoalrun-content-export';
+    digest: string;
+    publicBase: string;
+    publication: ContentPublication;
+    review: {
+        status: 'ok' | 'required';
+        apis: Array<{
+            apiId: string;
+            digest: string;
+        }>;
+    };
+    resources: ContentResource[];
+    assets: ContentAsset[];
+    files: ContentFile[];
+    diagnostics: Array<{
+        code: string;
+        documentId?: string;
+        message: string;
+    }>;
+};
+export type ContentResult = {
+    resource: Readonly<ContentResource>;
+    representation: Readonly<ContentRepresentation>;
+    format: ContentFormat;
+    content: string;
+    revision: string;
+};
+export interface ContentSnapshot {
+    readonly revision: string;
+    readonly publication: Readonly<ContentPublication>;
+    list(): readonly Readonly<ContentResource>[];
+    get(ref: ContentRef, options: {
+        format: ContentFormat;
+        signal?: AbortSignal;
+    }): Promise<ContentResult>;
+    dispose(): void;
+}
+export type ContentErrorCode = 'invalid_manifest' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'network_error' | 'invalid_content' | 'disposed';
+export declare class ContentDeliveryError extends Error {
+    readonly code: ContentErrorCode;
+    constructor(code: ContentErrorCode, message: string);
+}
+export declare function contentRefKey(ref: ContentRef): string;

package/dist/content-delivery-contract.js

@@ -0,0 +1,15 @@
+export class ContentDeliveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ContentDeliveryError';
+    }
+}
+export function contentRefKey(ref) {
+    switch (ref.kind) {
+        case 'page': return JSON.stringify(['page', ref.documentId]);
+        case 'section': return JSON.stringify(['section', ref.documentId, ref.sectionId]);
+        case 'snippet': return JSON.stringify(['snippet', ref.id]);
+    }
+}

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

@@ -0,0 +1,3 @@
+export declare function freeze<T>(value: T): T;
+export declare function sha256(bytes: Uint8Array): Promise<string>;
+export declare function readBounded(response: Response, limit: number, signal: AbortSignal): Promise<Uint8Array>;

package/dist/content-delivery-transport.js

@@ -0,0 +1,47 @@
+import { ContentDeliveryError } from './content-delivery-contract.js';
+export function freeze(value) { if (value && typeof value === 'object') {
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        freeze(child);
+} return value; }
+export async function sha256(bytes) { return [...new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes))].map(byte => byte.toString(16).padStart(2, '0')).join(''); }
+export async function readBounded(response, limit, signal) {
+    const declared = response.headers.get('content-length');
+    if (declared && (!/^\d+$/.test(declared) || Number(declared) > limit)) {
+        await response.body?.cancel().catch(() => { });
+        throw new ContentDeliveryError('invalid_content', 'Response exceeds the content size limit.');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return new Uint8Array();
+    const abort = () => { void reader.cancel(signal.reason).catch(() => { }); };
+    signal.addEventListener('abort', abort, { once: true });
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const next = await reader.read();
+            signal.throwIfAborted();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > limit) {
+                await reader.cancel();
+                throw new ContentDeliveryError('invalid_content', 'Response exceeds the content size limit.');
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return bytes;
+}

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

@@ -0,0 +1,7 @@
+import type { ContentManifest, ContentRef } from './content-delivery-contract.js';
+export declare const safeContentPath: (value: any) => value is string;
+export declare const validContentPublication: (value: any) => boolean;
+export declare function validContentRef(value: any): value is ContentRef;
+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

@@ -0,0 +1,122 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const keys = (value, allowed) => object(value) && Object.keys(value).every(key => allowed.includes(key));
+const nonempty = (value) => typeof value === 'string' && value.length > 0 && value.length <= 2048;
+const digestPattern = /^[a-f0-9]{64}$/;
+const pathPattern = /^(?:NOTICES\.txt|(?:content|assets)\/[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*)$/;
+export const safeContentPath = (value) => typeof value === 'string' && pathPattern.test(value) && value.split('/').every(part => part !== '.' && part !== '..');
+const invalid = (message) => { throw new ContentDeliveryError('invalid_manifest', message); };
+export const validContentPublication = (value) => object(value) && Object.keys(value).length === 3 && ['channel', 'version', 'language'].every(key => nonempty(value[key]));
+const samePublication = (left, right) => ['channel', 'version', 'language'].every(key => left[key] === right[key]);
+export function validContentRef(value) {
+    if (!object(value))
+        return false;
+    if (value.kind === 'page')
+        return Object.keys(value).length === 2 && nonempty(value.documentId);
+    if (value.kind === 'section')
+        return Object.keys(value).length === 3 && nonempty(value.documentId) && typeof value.sectionId === 'string' && /^[a-z0-9][a-z0-9-]{0,511}$/.test(value.sectionId);
+    return value.kind === 'snippet' && Object.keys(value).length === 2 && nonempty(value.id);
+}
+function safeExternal(value, image = false) {
+    try {
+        const url = new URL(value);
+        return typeof value === 'string' && !url.username && !url.password && (image ? ['http:', 'https:'] : ['http:', 'https:', 'mailto:', 'tel:']).includes(url.protocol);
+    }
+    catch {
+        return false;
+    }
+}
+export function validateContentManifest(value, maxResources = 10_000, maxResourceBytes = 8_000_000) {
+    if (!keys(value, ['schemaVersion', 'kind', 'digest', 'publicBase', 'publication', 'review', 'resources', 'assets', 'files', 'diagnostics']) || value.schemaVersion !== 1 || value.kind !== 'shoalrun-content-export' || !digestPattern.test(value.digest ?? ''))
+        invalid('Unsupported content manifest.');
+    if (typeof value.publicBase !== 'string' || !/^\/(?:[A-Za-z0-9_~.-]+\/)*$/.test(value.publicBase) || value.publicBase.split('/').some((part) => part === '.' || part === '..'))
+        invalid('Invalid content mount.');
+    if (!validContentPublication(value.publication))
+        invalid('Invalid publication.');
+    if (!keys(value.review, ['status', 'apis']) || value.review.status !== 'ok' || !Array.isArray(value.review.apis) || value.review.apis.some((api) => !keys(api, ['apiId', 'digest']) || !nonempty(api.apiId) || !digestPattern.test(api.digest ?? '')))
+        invalid('Content must have approved API review metadata.');
+    if (!Array.isArray(value.resources) || !value.resources.length || value.resources.length > maxResources || !Array.isArray(value.files) || !Array.isArray(value.assets) || !Array.isArray(value.diagnostics))
+        invalid('Invalid manifest inventory.');
+    const files = new Map();
+    const checkFile = (file) => object(file) && safeContentPath(file.path) && Number.isSafeInteger(file.bytes) && file.bytes >= 0 && file.bytes <= maxResourceBytes && digestPattern.test(file.digest ?? '');
+    for (const file of value.files) {
+        if (!keys(file, ['path', 'bytes', 'digest']) || !checkFile(file) || files.has(file.path))
+            invalid('Invalid or duplicate file.');
+        files.set(file.path, file);
+    }
+    const listed = (file) => checkFile(file) && files.has(file.path) && files.get(file.path).bytes === file.bytes && files.get(file.path).digest === file.digest;
+    const assets = new Set();
+    for (const asset of value.assets) {
+        if (!keys(asset, ['path', 'bytes', 'digest', 'mediaType']) || !listed(asset) || !asset.path.startsWith('assets/') || !nonempty(asset.mediaType) || assets.has(asset.path))
+            invalid('Invalid or duplicate asset.');
+        assets.add(asset.path);
+    }
+    validateContentResources(value.resources, value.publication, assets, listed, value.publicBase);
+    if (value.diagnostics.some((item) => !keys(item, ['code', 'documentId', 'message']) || typeof item.code !== 'string' || item.documentId !== undefined && typeof item.documentId !== 'string' || typeof item.message !== 'string'))
+        invalid('Invalid diagnostics.');
+}
+/** Shared metadata validation; transport supplies its file/asset inventory policy. */
+export function validateContentResources(resources, expectedPublication, assets, checkRepresentation, publicBase = '/') {
+    const refs = new Set();
+    const links = [];
+    for (const resource of resources) {
+        if (!keys(resource, ['ref', 'publication', 'title', 'summary', 'type', 'canonicalUrl', 'source', 'representations', 'assets', 'externalDependencies']) || !validContentRef(resource.ref) || !validContentPublication(resource.publication) || !samePublication(resource.publication, expectedPublication) || typeof resource.title !== 'string' || typeof resource.summary !== 'string' || typeof resource.type !== 'string')
+            invalid('Invalid resource metadata.');
+        const key = contentRefKey(resource.ref);
+        if (refs.has(key))
+            invalid('Duplicate content reference.');
+        refs.add(key);
+        if (resource.canonicalUrl !== undefined && !safeExternal(resource.canonicalUrl, true))
+            invalid('Invalid canonical URL.');
+        if (resource.source !== undefined && (!object(resource.source) || !Object.keys(resource.source).length || Object.keys(resource.source).some(key => !['documentId', 'snippetId', 'valuesDigest'].includes(key)) || Object.values(resource.source).some(value => !nonempty(value))))
+            invalid('Invalid resource source.');
+        if (resource.source?.valuesDigest !== undefined && !digestPattern.test(resource.source.valuesDigest))
+            invalid('Invalid snippet values digest.');
+        if (!Array.isArray(resource.assets) || new Set(resource.assets).size !== resource.assets.length || resource.assets.some((asset) => !assets.has(asset)))
+            invalid('Unknown resource asset.');
+        if (!Array.isArray(resource.externalDependencies) || resource.externalDependencies.some((dependency) => !keys(dependency, ['url', 'kind']) || dependency.kind !== 'image' || !safeExternal(dependency.url, true)))
+            invalid('Invalid external dependency.');
+        if (!object(resource.representations) || !Object.keys(resource.representations).length || Object.keys(resource.representations).some(format => !['html', 'markdown'].includes(format)))
+            invalid('Invalid representations.');
+        for (const [format, rep] of Object.entries(resource.representations)) {
+            if (!keys(rep, ['path', 'bytes', 'digest', 'mediaType', 'anchors', 'links']) || !checkRepresentation(rep) || !rep.path.startsWith('content/') || rep.mediaType !== (format === 'html' ? 'text/html' : 'text/markdown') || !Array.isArray(rep.anchors) || !Array.isArray(rep.links))
+                invalid('Invalid representation file.');
+            const ids = new Set();
+            const exportedIds = new Set();
+            const linkKeys = new Set();
+            for (const anchor of rep.anchors) {
+                if (!keys(anchor, ['id', 'exportedId', 'title']) || !nonempty(anchor.id) || !nonempty(anchor.exportedId) || ids.has(anchor.id) || exportedIds.has(anchor.exportedId) || anchor.title !== undefined && typeof anchor.title !== 'string')
+                    invalid('Invalid representation anchor.');
+                ids.add(anchor.id);
+                exportedIds.add(anchor.exportedId);
+            }
+            for (const link of rep.links) {
+                if (!keys(link, ['key', 'kind', 'href', 'ref', 'fragment', 'query', 'asset']) || !nonempty(link.key) || linkKeys.has(link.key) || typeof link.href !== 'string' || !['resource', 'canonical', 'external', 'asset'].includes(link.kind))
+                    invalid('Invalid representation link.');
+                linkKeys.add(link.key);
+                if (link.kind === 'resource' && !validContentRef(link.ref) || link.kind === 'asset' && !assets.has(link.asset) || ['canonical', 'external'].includes(link.kind) && !safeExternal(link.href))
+                    invalid('Invalid link destination.');
+                if (link.fragment !== undefined && typeof link.fragment !== 'string' || link.query !== undefined && typeof link.query !== 'string')
+                    invalid('Invalid link suffix.');
+                if (['resource', 'asset'].includes(link.kind)) {
+                    const linkPath = link.href.split(/[?#]/, 1)[0];
+                    if (!link.href.startsWith('#') && !link.href.startsWith(publicBase) || /\\|%2e|%2f|%5c/i.test(linkPath))
+                        invalid('Link leaves content mount.');
+                    let url;
+                    try {
+                        url = new URL(link.href, 'https://content.invalid' + publicBase);
+                    }
+                    catch {
+                        return invalid('Invalid internal link URL.');
+                    }
+                    if (url.origin !== 'https://content.invalid' || !url.pathname.startsWith(publicBase))
+                        invalid('Link leaves content mount.');
+                }
+                links.push(link);
+            }
+        }
+    }
+    for (const link of links)
+        if (link.kind === 'resource' && !refs.has(contentRefKey(link.ref)))
+            invalid('Link references absent content.');
+}

package/dist/content-delivery.d.ts

@@ -0,0 +1,21 @@
+import type { ContentSnapshot } from './content-delivery-contract.js';
+export * from './content-delivery-contract.js';
+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';
+export type ContentDeliveryLimits = {
+    manifestBytes?: number;
+    resourceBytes?: number;
+    resources?: number;
+};
+export type ManifestContentSourceOptions = {
+    manifestUrl: string | URL;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+    limits?: ContentDeliveryLimits;
+};
+/** Opens one immutable manifest revision. The caller owns trust in the build/host. */
+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

@@ -0,0 +1,119 @@
+import { ContentDeliveryError, contentRefKey } from './content-delivery-contract.js';
+export * from './content-delivery-contract.js';
+export * from './content-rest-contract.js';
+import { validateContentManifest, validContentRef } from './content-delivery-validation.js';
+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. */
+export async function openManifestContentSource(options) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    let manifestUrl;
+    try {
+        manifestUrl = new URL(options.manifestUrl, typeof location === 'undefined' ? undefined : location.href);
+    }
+    catch {
+        throw new ContentDeliveryError('invalid_manifest', 'Manifest URL must be a valid HTTP(S) URL.');
+    }
+    if (!['http:', 'https:'].includes(manifestUrl.protocol) || manifestUrl.username || manifestUrl.password || manifestUrl.hash || manifestUrl.search)
+        invalid('Manifest URL must be an HTTP(S) URL without credentials, query, or fragment.');
+    if (typeof location !== 'undefined' && manifestUrl.origin !== location.origin)
+        invalid('Browser content must be served from the application origin.');
+    const manifestBytes = options.limits?.manifestBytes ?? 5_000_000;
+    const resourceBytes = options.limits?.resourceBytes ?? 8_000_000;
+    const resources = options.limits?.resources ?? 10_000;
+    for (const limit of [manifestBytes, resourceBytes, resources])
+        if (!Number.isSafeInteger(limit) || limit <= 0)
+            invalid('Limits must be positive safe integers.');
+    const lifetime = new AbortController();
+    let disposed = false;
+    const openSignal = options.signal ? AbortSignal.any([options.signal, lifetime.signal]) : lifetime.signal;
+    async function request(url, mediaType, limit, signal, revision = false) {
+        signal.throwIfAborted();
+        let response;
+        try {
+            response = await fetcher(url.href, { signal, redirect: 'error', credentials: 'same-origin', cache: 'no-store', headers: { Accept: mediaType } });
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            throw new ContentDeliveryError('network_error', 'Cannot fetch content.');
+        }
+        const rejectResponse = async (code, message) => { await response.body?.cancel().catch(() => { }); throw new ContentDeliveryError(code, message); };
+        if (response.status === 404)
+            return rejectResponse(revision ? 'stale_revision' : 'not_found', 'Content is unavailable.');
+        if (!response.ok)
+            return rejectResponse('network_error', `Content request failed (${response.status}).`);
+        if (response.redirected || response.url && response.url !== url.href)
+            return rejectResponse('invalid_content', 'Redirected content is not accepted.');
+        if (response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase() !== mediaType)
+            return rejectResponse('invalid_content', 'Unexpected content type.');
+        try {
+            return await readBounded(response, limit, signal);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (error instanceof ContentDeliveryError)
+                throw error;
+            throw new ContentDeliveryError('network_error', 'Content response was interrupted.');
+        }
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await request(manifestUrl, 'application/json', manifestBytes, openSignal)));
+    }
+    catch (error) {
+        if (error instanceof ContentDeliveryError || openSignal.aborted)
+            throw error;
+        invalid('Manifest is not valid UTF-8 JSON.');
+    }
+    validateContentManifest(manifest, resources, resourceBytes);
+    const { digest, ...body } = manifest;
+    if (await sha256(new TextEncoder().encode(JSON.stringify(body))) !== digest)
+        invalid('Manifest digest does not match its contents.');
+    openSignal.throwIfAborted();
+    const mount = new URL(manifest.publicBase, manifestUrl.origin);
+    if (!manifestUrl.pathname.startsWith(mount.pathname))
+        invalid('Manifest is outside its declared content mount.');
+    freeze(manifest);
+    const byRef = new Map(manifest.resources.map(resource => [contentRefKey(resource.ref), resource]));
+    const active = () => { if (disposed)
+        throw new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'); };
+    return Object.freeze({
+        revision: manifest.digest, publication: manifest.publication,
+        list() { active(); return manifest.resources; },
+        async get(ref, getOptions) {
+            active();
+            if (!validContentRef(ref))
+                throw new ContentDeliveryError('not_found', 'Invalid content reference.');
+            const resource = byRef.get(contentRefKey(ref));
+            if (!resource)
+                throw new ContentDeliveryError('not_found', 'No matching content in this publication.');
+            const format = getOptions?.format;
+            if (!['html', 'markdown'].includes(format))
+                throw new ContentDeliveryError('unsupported_format', 'The requested representation is unavailable.');
+            const representation = resource.representations[format];
+            if (!representation)
+                throw new ContentDeliveryError('unsupported_format', 'The requested representation is unavailable.');
+            const signal = getOptions.signal ? AbortSignal.any([lifetime.signal, getOptions.signal]) : lifetime.signal;
+            const bytes = await request(new URL(representation.path, mount), representation.mediaType, resourceBytes, signal, true);
+            if (bytes.byteLength !== representation.bytes || await sha256(bytes) !== representation.digest)
+                throw new ContentDeliveryError('stale_revision', 'Representation differs from the opened revision.');
+            signal.throwIfAborted();
+            active();
+            let content;
+            try {
+                content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new ContentDeliveryError('invalid_content', 'Content is not valid UTF-8.');
+            }
+            return Object.freeze({ resource, representation, format, content, revision: manifest.digest });
+        },
+        dispose() { if (!disposed) {
+            disposed = true;
+            lifetime.abort(new ContentDeliveryError('disposed', 'Content snapshot has been disposed.'));
+        } },
+    });
+}
+export { openRestContentSource } from './content-rest-client.js';

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

@@ -0,0 +1,11 @@
+/** Expanded snippets may share nodes; give every authored occurrence its own identity. */
+export declare function isolateExportTree(value: any): any;
+/** Stable internal provenance survives cloning, slicing, and portable lowering. */
+export declare function markExportSource(tree: any): void;
+/** Map semantic heading provenance to the actual IDs assigned by the renderer. */
+export declare function exportHeadingInventory(tree: any, reservedIds?: Iterable<string>): {
+    headings: Map<string, string>;
+    ids: Set<string>;
+};
+/** HTML keeps source IDs; Markdown keeps clean headings and maps source to local IDs. */
+export declare function preserveExportHeadingIds(tree: any, source: ReturnType<typeof exportHeadingInventory>, format: 'html' | 'markdown'): Map<string, string>;

package/dist/content-export-anchors.js

@@ -0,0 +1,79 @@
+import { parseFragment } from 'parse5';
+import { renderHtmlWithHeadings } from './html-renderer.js';
+/** Expanded snippets may share nodes; give every authored occurrence its own identity. */
+export function isolateExportTree(value) {
+    if (Array.isArray(value))
+        return value.map(isolateExportTree);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, isolateExportTree(item)]));
+    return value;
+}
+/** Stable internal provenance survives cloning, slicing, and portable lowering. */
+export function markExportSource(tree) {
+    let index = 0;
+    const walk = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            node.forEach(walk);
+            return;
+        }
+        if (typeof node.type === 'string')
+            node.data = { ...node.data, exportSourceKey: `source-${index++}` };
+        for (const [key, value] of Object.entries(node))
+            if (!['data', 'position'].includes(key))
+                walk(value);
+    };
+    walk(tree);
+}
+/** Map semantic heading provenance to the actual IDs assigned by the renderer. */
+export function exportHeadingInventory(tree, reservedIds = []) {
+    const copy = structuredClone(tree);
+    const mark = (node) => {
+        if (node.data?.exportSourceKey)
+            node.data.hProperties = { ...node.data.hProperties, 'data-export-source-key': node.data.exportSourceKey };
+        for (const child of node.children ?? [])
+            mark(child);
+    };
+    mark(copy);
+    const parsed = parseFragment(renderHtmlWithHeadings(copy, undefined, reservedIds).html);
+    const headings = new Map();
+    const ids = new Set();
+    const visit = (node) => {
+        const id = node.attrs?.find((attr) => attr.name === 'id')?.value;
+        if (id) {
+            ids.add(id);
+            const key = node.attrs?.find((attr) => attr.name === 'data-export-source-key')?.value;
+            if (/^h[2-6]$/.test(node.tagName ?? '') && key)
+                headings.set(key, id);
+        }
+        for (const child of node.childNodes ?? [])
+            visit(child);
+    };
+    visit(parsed);
+    return { headings, ids };
+}
+/** HTML keeps source IDs; Markdown keeps clean headings and maps source to local IDs. */
+export function preserveExportHeadingIds(tree, source, format) {
+    const local = exportHeadingInventory(tree);
+    const aliases = new Map();
+    const walk = (node) => {
+        const key = node.data?.exportSourceKey;
+        if (key && (node.type === 'heading' || /^h[2-6]$/.test(node.data?.hName ?? '')) && local.headings.has(key)) {
+            const original = source.headings.get(key);
+            if (!original)
+                throw new Error('Cannot determine full-source identity for an exported heading');
+            aliases.set(original, format === 'html' ? original : local.headings.get(key));
+            if (format === 'html')
+                node.data.hProperties = { ...node.data.hProperties, id: original };
+        }
+        for (const child of node.children ?? [])
+            walk(child);
+    };
+    walk(tree);
+    // Non-heading anchors (explicit aliases, footnotes, component IDs) retain IDs.
+    for (const id of local.ids)
+        if (!Array.from(local.headings.values()).includes(id) && source.ids.has(id))
+            aliases.set(id, id);
+    return aliases;
+}

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

@@ -1,11 +1,13 @@
-export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both] [--document ID]...\n       [--channel C --version V --language L] [--public-base /help/] [--review]\n\nExport whole pages as resolved Markdown and passive HTML, with a manifest and assets.\nNavigation, facets, and a prior website build are not required.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n";
+export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both] [--document ID]...\n       [--channel C --version V --language L] [--public-base /help/] [--review]\n       [--previous-manifest FILE] [--fail-on-removed]\n\nExport selected pages, sections, and named snippets as Markdown and passive HTML.\nConfigure typed resources in an export target; --document selects whole pages.\nNavigation, facets, and a prior website build are not required.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n--previous-manifest compares public references with an earlier reviewed export.\n--fail-on-removed requires that baseline and refuses to replace output if references disappear.\n";
 export declare function runExportCommand(args: string[]): Promise<{
     status: string;
     output: string;
     publication: import("./content-source.js").Variant;
     formats: import("./content-export-config.js").ExportFormat[];
+    resources: number;
     documents: number;
     documentIds: string[];
+    comparison: import("./content-export-comparison.js").ContentExportComparison;
     assets: number;
     digest: string;
     apiReview: {
@@ -14,7 +16,7 @@ export declare function runExportCommand(args: string[]): Promise<{
     }[];
     diagnostics: {
         code: string;
-        documentId: string;
+        documentId?: string;
         message: string;
     }[];
 }>;