@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/dist/components.d.ts

@@ -0,0 +1,2 @@
+export { componentApiVersion, defineComponent, content } from './component-content.js';
+export type { JsonValue, Attribute, Content, ComponentDefinition, ComponentOutput, AttributeValues } from './component-content.js';

package/dist/components.js

@@ -0,0 +1 @@
+export { componentApiVersion, defineComponent, content } from './component-content.js';

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+export type Source = {
+    file: string;
+    history: string[];
+};
+type Tree = {
+    source: Source;
+    value: unknown;
+};
+export declare class ConfigError extends Error {
+}
+export declare function loadConfig(file: string): Promise<{
+    value: Record<string, unknown>;
+    tree: Tree;
+    dependencies: string[];
+    digest: string;
+}>;
+export declare function explain(config: Awaited<ReturnType<typeof loadConfig>>, key: string): {
+    key: string;
+    value: unknown;
+    source: Source;
+    dependencies: string[];
+};
+export declare function explainSegments(config: Awaited<ReturnType<typeof loadConfig>>, segments: string[]): {
+    key: string;
+    value: unknown;
+    source: Source;
+    dependencies: string[];
+};
+export {};

package/dist/config.js

@@ -0,0 +1,149 @@
+import { validateExports } from './content-export-config.js';
+import { validateContentFilter } from './content-filter.js';
+import { validateReaderFilters } from './reader-filters.js';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseYaml } from './yaml-value.js';
+import { validateSearch } from './search-config.js';
+import { resolveTaxonomy } from './taxonomy.js';
+import { validateCookbooks } from './cookbook-chooser.js';
+const allowed = new Set(['exports', 'schemaVersion', 'site', 'navigation', 'redirects', 'apis', 'relationships', 'variables', 'snippets', 'callouts', 'badges', 'publications', 'outputs', 'templates', 'theme', 'frontmatter', 'metadata', 'audit', 'readerFilters', 'retrieval', 'chat', 'authoring', 'search', 'cookbooks', 'analytics', 'mcp', 'components']);
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const treeObject = (v) => object(v) && !('kind' in v && 'items' in v);
+export class ConfigError extends Error {
+}
+function valueOf(node) {
+    if (Array.isArray(node.value))
+        return node.value.map(x => valueOf(x));
+    if (treeObject(node.value))
+        return Object.fromEntries(Object.entries(node.value).map(([key, child]) => [key, valueOf(child)]));
+    return node.value;
+}
+function finalize(node) {
+    const directive = node.value;
+    if (object(directive) && directive.kind === 'concat')
+        return { source: node.source, value: directive.items.map(finalize) };
+    if (object(directive) && directive.kind === 'remove')
+        throw new ConfigError(`${node.source.file}: $remove has no inherited value`);
+    if (Array.isArray(node.value))
+        return { source: node.source, value: node.value.map(x => finalize(x)) };
+    if (treeObject(node.value))
+        return { source: node.source, value: Object.fromEntries(Object.entries(node.value).map(([key, child]) => [key, finalize(child)])) };
+    return node;
+}
+function merge(base, overlay) {
+    const directive = overlay.value;
+    if (object(directive) && directive.kind === 'concat') {
+        if (base && !Array.isArray(base.value))
+            throw new ConfigError(`${overlay.source.file}: $concat requires an array base`);
+        return { value: [...(base?.value ?? []), ...directive.items], source: { file: overlay.source.file, history: base ? [base.source.file] : [] } };
+    }
+    if (object(directive) && directive.kind === 'remove') {
+        if (!base)
+            throw new ConfigError(`${overlay.source.file}: $remove has no inherited value`);
+        const names = directive.items;
+        if (Array.isArray(base.value))
+            return { value: base.value.filter(item => !names.includes(String(valueOf(item)?.id))), source: { file: overlay.source.file, history: [base.source.file] } };
+        if (!treeObject(base.value))
+            throw new ConfigError(`${overlay.source.file}: $remove requires a map or keyed list`);
+        return { value: Object.fromEntries(Object.entries(base.value).filter(([key]) => !names.includes(key))), source: { file: overlay.source.file, history: [base.source.file] } };
+    }
+    if (base && treeObject(base.value) && treeObject(overlay.value)) {
+        const combined = { ...base.value };
+        for (const [key, child] of Object.entries(overlay.value))
+            combined[key] = merge(combined[key], child);
+        return { value: combined, source: { file: overlay.source.file, history: [base.source.file, ...base.source.history] } };
+    }
+    if (!base)
+        return overlay;
+    return { value: overlay.value, source: { file: overlay.source.file, history: [base.source.file, ...base.source.history] } };
+}
+export async function loadConfig(file) {
+    const dependencies = new Set();
+    const root = path.resolve(file);
+    async function read(current, stack, rootFile = false) {
+        current = path.resolve(current);
+        if (stack.includes(current))
+            throw new ConfigError(`Configuration cycle: ${[...stack, current].join(' -> ')}`);
+        dependencies.add(current);
+        const raw = await readFile(current, 'utf8');
+        let parsed;
+        try {
+            parsed = parseYaml(raw, current);
+        }
+        catch (error) {
+            throw new ConfigError(error.message);
+        }
+        if (rootFile && !object(parsed))
+            throw new ConfigError(`${current}: root must be a mapping`);
+        const next = [...stack, current];
+        async function resolve(value) {
+            const source = { file: current, history: [] };
+            if (Array.isArray(value))
+                return { source, value: await Promise.all(value.map(resolve)) };
+            if (!object(value))
+                return { source, value };
+            const directives = Object.keys(value).filter(key => key.startsWith('$'));
+            if (directives.length) {
+                if (directives.length !== 1 || Object.keys(value).length !== 1)
+                    throw new ConfigError(`${current}: exactly one directive is required`);
+                if (directives[0] === '$include' && typeof value.$include === 'string')
+                    return read(path.resolve(path.dirname(current), value.$include), next);
+                if (directives[0] === '$concat' && Array.isArray(value.$concat)) {
+                    const parts = await Promise.all(value.$concat.map(resolve));
+                    const items = parts.flatMap(part => Array.isArray(part.value) ? part.value : [part]);
+                    return { source, value: { kind: 'concat', items } };
+                }
+                if (directives[0] === '$remove' && Array.isArray(value.$remove) && value.$remove.every(x => typeof x === 'string'))
+                    return { source, value: { kind: 'remove', items: value.$remove } };
+                throw new ConfigError(`${current}: invalid ${directives[0]} directive`);
+            }
+            return { source, value: Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, child]) => [key, await resolve(child)]))) };
+        }
+        if (!object(parsed))
+            return resolve(parsed);
+        const presets = parsed.extends;
+        if (presets !== undefined && (!Array.isArray(presets) || !presets.every(x => typeof x === 'string')))
+            throw new ConfigError(`${current}: extends must be a list of paths`);
+        let result;
+        for (const preset of presets ?? [])
+            result = merge(result, await read(path.resolve(path.dirname(current), preset), next));
+        const local = { ...parsed };
+        delete local.extends;
+        return merge(result, await resolve(local));
+    }
+    const tree = finalize(await read(root, [], true));
+    const value = valueOf(tree);
+    if (!object(value) || value.schemaVersion !== 1)
+        throw new ConfigError(`${root}: schemaVersion must be 1`);
+    for (const key of Object.keys(value))
+        if (!allowed.has(key))
+            throw new ConfigError(`${root}: unknown setting ${key}`);
+    if (object(value.site) && value.site.contentFilter !== undefined)
+        validateContentFilter(value.site.contentFilter, validateReaderFilters(value.readerFilters));
+    validateExports(value.exports, value.readerFilters);
+    validateCookbooks(value.cookbooks, root);
+    validateSearch(value.search);
+    resolveTaxonomy(object(value.frontmatter) ? value.frontmatter.taxonomy : undefined);
+    if (object(value.publications) && ((object(value.publications.defaults) && Object.hasOwn(value.publications.defaults, 'locale')) || (Array.isArray(value.publications.enabled) && value.publications.enabled.some(item => object(item) && Object.hasOwn(item, 'locale')))))
+        throw new ConfigError(`${root}: publications.locale is now publications.language; page locale is reserved for formatting conventions`);
+    return { value, tree, dependencies: [...dependencies].sort(), digest: createHash('sha256').update(JSON.stringify(value)).digest('hex') };
+}
+export function explain(config, key) {
+    return explainSegments(config, key.split('.'));
+}
+export function explainSegments(config, segments) {
+    const node = segments.reduce((at, segment) => {
+        if (!at)
+            return undefined;
+        if (Array.isArray(at.value))
+            return at.value[Number(segment)];
+        if (treeObject(at.value))
+            return at.value[segment];
+        return undefined;
+    }, config.tree);
+    if (!node)
+        throw new ConfigError(`Unknown config path: ${segments.join('.')}`);
+    return { key: segments.join('.'), value: valueOf(node), source: node.source, dependencies: config.dependencies };
+}

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

@@ -0,0 +1,23 @@
+export declare const exportDigest: (bytes: string | Buffer) => string;
+export type ExportAsset = {
+    path: string;
+    mediaType: string;
+    bytes: number;
+    digest: string;
+};
+export declare function validateExportSvg(svg: string): void;
+export declare class ExportAssets {
+    readonly publicBase: string;
+    readonly artifacts: Map<string, string | Buffer<ArrayBufferLike>>;
+    readonly records: Map<string, ExportAsset>;
+    private registered;
+    private roots;
+    constructor(publicBase: string);
+    allow(roots: string[]): Promise<void>;
+    register(url: string, value: {
+        file?: string;
+        content?: string | Buffer;
+        extension?: string;
+    }, documentKey?: string): void;
+    resolve(url: string, sourceFile: string, documentKey?: string): Promise<ExportAsset | undefined>;
+}

package/dist/content-export-assets.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { parseFragment } from 'parse5';
+export const exportDigest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const media = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.avif': 'image/avif', '.svg': 'image/svg+xml', '.pdf': 'application/pdf', '.txt': 'text/plain', '.csv': 'text/csv', '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml' };
+const within = (root, file) => file === root || file.startsWith(root + path.sep);
+// External SVG files still must be passive and self-contained. Never fetch nested resources.
+export function validateExportSvg(svg) {
+    const fragment = parseFragment(svg);
+    const allowed = new Set('svg g defs marker path rect circle ellipse line polyline polygon text tspan title desc linearGradient radialGradient stop clipPath pattern symbol use style filter feGaussianBlur feOffset feBlend feColorMatrix feFlood feComposite feMerge feMergeNode mask'.split(' '));
+    const visit = (node) => {
+        if (node.nodeName === '#text' || node.nodeName === '#comment')
+            return;
+        if (!allowed.has(node.tagName))
+            throw new Error(`Unsupported passive SVG element ${node.tagName ?? node.nodeName}`);
+        for (const attr of node.attrs ?? []) {
+            if (attr.name === 'base' || attr.prefix && !['xmlns', 'xlink', 'xml'].includes(attr.prefix))
+                throw new Error('SVG base URLs and unsupported namespaces are not allowed');
+            if (attr.name === 'style' && /\\|@import|expression\s*\(|javascript:/i.test(attr.value))
+                throw new Error('SVG styles must be passive');
+            if (/^on/i.test(attr.name))
+                throw new Error('SVG event handlers are not allowed in exports');
+            if (attr.name === 'href' && !attr.value.startsWith('#'))
+                throw new Error('External SVG references are not supported in exports');
+            if (/url\(/i.test(attr.value.replace(/url\(\s*["']?#[^\s)"']+["']?\s*\)/g, '')))
+                throw new Error('External SVG styles are not supported in exports');
+        }
+        if (node.tagName === 'style') {
+            const css = (node.childNodes ?? []).map((child) => child.value ?? '').join('');
+            const withoutEmbeddedFonts = css.replace(/url\(\s*["']?data:(?:application\/(?:font-woff|x-font-ttf|x-font-opentype)|font\/(?:woff2?|ttf|otf));base64,[A-Za-z0-9+/=]+["']?\s*\)/g, '');
+            if (/\\|@import|expression\s*\(|javascript:|url\(/i.test(withoutEmbeddedFonts.replace(/url\(\s*["']?#[^\s)"']+["']?\s*\)/g, '')))
+                throw new Error('SVG styles must not load resources or execute code');
+        }
+        for (const child of node.childNodes ?? [])
+            visit(child);
+    };
+    const roots = fragment.childNodes.filter((node) => node.nodeName !== '#comment' && (node.nodeName !== '#text' || node.value.trim()));
+    if (roots.length !== 1 || roots[0].tagName !== 'svg')
+        throw new Error('Expected one passive SVG image');
+    visit(roots[0]);
+}
+export class ExportAssets {
+    publicBase;
+    artifacts = new Map();
+    records = new Map();
+    registered = new Map();
+    roots = [];
+    constructor(publicBase) {
+        this.publicBase = publicBase;
+    }
+    async allow(roots) { this.roots = await Promise.all(roots.map(root => realpath(root))); }
+    register(url, value, documentKey) {
+        const key = url.split(/[?#]/)[0];
+        const registrationKey = JSON.stringify([documentKey ?? null, key]);
+        const extension = value.extension ?? path.extname(value.file ?? key).toLowerCase();
+        const prior = this.registered.get(registrationKey);
+        if (prior && (prior.file !== value.file || prior.content !== value.content))
+            throw new Error(`Ambiguous export asset ${key}`);
+        this.registered.set(registrationKey, { ...value, extension });
+    }
+    async resolve(url, sourceFile, documentKey) {
+        const key = url.split(/[?#]/)[0];
+        // Authored assets belong to a document even when website routes overlap.
+        // Generated diagrams and contracts retain their shared registrations.
+        let resource = this.registered.get(JSON.stringify([documentKey ?? null, key]))
+            ?? this.registered.get(JSON.stringify([null, key]));
+        if (!resource) {
+            if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|\/)/i.test(url))
+                return undefined;
+            let decoded;
+            try {
+                decoded = decodeURIComponent(key);
+            }
+            catch {
+                throw new Error(`Invalid export asset URL ${url}`);
+            }
+            resource = { file: path.resolve(path.dirname(sourceFile), decoded), extension: path.extname(decoded).toLowerCase() };
+        }
+        const type = media[resource.extension];
+        if (!type)
+            throw new Error(`Unsupported export asset type ${resource.extension || '(none)'}: ${key}`);
+        let bytes;
+        if (resource.file) {
+            const file = await realpath(resource.file);
+            if (!this.roots.some(root => within(root, file)))
+                throw new Error(`Export asset escapes the configured asset roots: ${key}`);
+            if (file.split(path.sep).some(part => /^\.env(?:\.|$)|^\.git$|^(?:PROJECT|DEPLOYMENT)\.local\.md$|^AGENTS\.override\.md$/i.test(part)))
+                throw new Error('Private local files cannot be exported as assets');
+            bytes = await readFile(file);
+        }
+        else
+            bytes = Buffer.isBuffer(resource.content) ? resource.content : Buffer.from(resource.content);
+        if (resource.extension === '.svg')
+            validateExportSvg(bytes.toString('utf8'));
+        const digest = exportDigest(bytes);
+        const output = `assets/${digest}${resource.extension}`;
+        const record = { path: output, mediaType: type, bytes: bytes.length, digest };
+        this.artifacts.set(output, bytes);
+        this.records.set(output, record);
+        return record;
+    }
+}

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

@@ -0,0 +1,20 @@
+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 function runExportCommand(args: string[]): Promise<{
+    status: string;
+    output: string;
+    publication: import("./content-source.js").Variant;
+    formats: import("./content-export-config.js").ExportFormat[];
+    documents: number;
+    documentIds: string[];
+    assets: number;
+    digest: string;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId: string;
+        message: string;
+    }[];
+}>;

package/dist/content-export-command.js

@@ -0,0 +1,57 @@
+import { exportContent } from './content-export.js';
+export const exportHelp = `Usage: shoalrun export [config] --out DIRECTORY [--target NAME]
+       [--format markdown|html|both] [--document ID]...
+       [--channel C --version V --language L] [--public-base /help/] [--review]
+
+Export whole pages as resolved Markdown and passive HTML, with a manifest and assets.
+Navigation, facets, and a prior website build are not required.
+--review writes an API-review candidate; status needs-review exits 2 until pinned.
+`;
+export async function runExportCommand(args) {
+    const options = {};
+    const values = new Map();
+    let config;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--review') {
+            if (options.review)
+                throw new Error(exportHelp);
+            options.review = true;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            if (!['--out', '--target', '--format', '--document', '--channel', '--version', '--language', '--public-base'].includes(arg) || !args[index + 1] || args[index + 1].startsWith('--'))
+                throw new Error(exportHelp);
+            const value = args[++index];
+            if (arg === '--document') {
+                (options.documents ??= []).push(value);
+                continue;
+            }
+            if (values.has(arg))
+                throw new Error(exportHelp);
+            values.set(arg, value);
+        }
+        else {
+            if (config)
+                throw new Error(exportHelp);
+            config = arg;
+        }
+    }
+    const output = values.get('--out');
+    if (!output)
+        throw new Error(exportHelp);
+    const format = values.get('--format');
+    if (format && !['html', 'markdown', 'both'].includes(format))
+        throw new Error(exportHelp);
+    if (format)
+        options.formats = format === 'both' ? ['markdown', 'html'] : [format];
+    const coordinates = ['--channel', '--version', '--language'].map(key => values.get(key));
+    if (coordinates.some(Boolean)) {
+        if (!coordinates.every(Boolean))
+            throw new Error('Select all three export publication coordinates: --channel, --version, and --language');
+        options.publication = { channel: coordinates[0], version: coordinates[1], language: coordinates[2] };
+    }
+    options.target = values.get('--target');
+    options.publicBase = values.get('--public-base');
+    return exportContent(config ?? 'docs.config.yaml', output, options);
+}

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

@@ -0,0 +1,16 @@
+import { type ReaderSelection } from './reader-filters.js';
+import type { Variant } from './content.js';
+export type ExportFormat = 'markdown' | 'html';
+export type ExportTarget = {
+    formats: ExportFormat[];
+    documents?: string[];
+    publication?: Variant;
+    contentFilter?: ReaderSelection;
+    publicBase: string;
+    assetRoots: string[];
+    apiReview: Record<string, string>;
+    notices: string[];
+};
+export declare function exportPublicBase(value: unknown): string;
+export declare function validateExportTarget(value: unknown, readerFilters?: unknown): ExportTarget;
+export declare function validateExports(value: unknown, readerFilters?: unknown): void;

package/dist/content-export-config.js

@@ -0,0 +1,50 @@
+import { isConfigMapping } from './compiler-config.js';
+import { validateContentFilter } from './content-filter.js';
+import { validateReaderFilters } from './reader-filters.js';
+export function exportPublicBase(value) {
+    if (typeof value !== 'string' || !/^\/(?:[A-Za-z0-9_~.-]+\/)*$/.test(value) || value.split('/').some(part => part === '.' || part === '..')) {
+        throw new Error('Export publicBase must be a root-relative path with a trailing slash, such as /help/');
+    }
+    return value;
+}
+export function validateExportTarget(value, readerFilters) {
+    if (!isConfigMapping(value) || Object.keys(value).some(key => !['formats', 'documents', 'publication', 'contentFilter', 'publicBase', 'assetRoots', 'apiReview', 'notices'].includes(key)))
+        throw new Error('Export target accepts formats, documents, publication, contentFilter, publicBase, and assetRoots');
+    const formats = value.formats ?? ['markdown', 'html'];
+    if (!Array.isArray(formats) || !formats.length || formats.some(format => !['markdown', 'html'].includes(format)) || new Set(formats).size !== formats.length)
+        throw new Error('Export formats must be a nonempty unique list of markdown and/or html');
+    const strings = (raw, field) => {
+        if (raw === undefined)
+            return undefined;
+        if (!Array.isArray(raw) || !raw.length || raw.some(item => typeof item !== 'string' || !item.trim()) || new Set(raw).size !== raw.length)
+            throw new Error(`Export ${field} must be a nonempty unique list of strings`);
+        return raw;
+    };
+    let publication;
+    if (value.publication !== undefined) {
+        if (!isConfigMapping(value.publication) || Object.keys(value.publication).some(key => !['channel', 'version', 'language'].includes(key)) || ['channel', 'version', 'language'].some(key => typeof value.publication === 'object' && (typeof value.publication[key] !== 'string' || !value.publication[key].trim())))
+            throw new Error('Export publication needs channel, version, and language');
+        publication = value.publication;
+    }
+    if (value.apiReview !== undefined && (!isConfigMapping(value.apiReview) || Object.values(value.apiReview).some(digest => typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest))))
+        throw new Error('Export apiReview must map API IDs to lowercase SHA-256 digests');
+    return { formats: [...formats].sort(), ...(value.documents !== undefined ? { documents: strings(value.documents, 'documents') } : {}), ...(publication ? { publication } : {}),
+        ...(value.contentFilter !== undefined ? { contentFilter: validateContentFilter(value.contentFilter, validateReaderFilters(readerFilters)) } : {}),
+        publicBase: exportPublicBase(value.publicBase ?? '/'), assetRoots: strings(value.assetRoots, 'assetRoots') ?? [], apiReview: (value.apiReview ?? {}), notices: strings(value.notices, 'notices') ?? [] };
+}
+export function validateExports(value, readerFilters) {
+    if (value === undefined)
+        return;
+    if (!isConfigMapping(value) || !Object.keys(value).length)
+        throw new Error('exports must be a nonempty mapping of named targets');
+    for (const [name, target] of Object.entries(value)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name))
+            throw new Error(`Invalid export target name ${name}`);
+        try {
+            validateExportTarget(target, readerFilters);
+        }
+        catch (error) {
+            throw new Error(`exports.${name}: ${error.message}`);
+        }
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { ExportFormat } from './content-export-config.js';
+/** Lower interactions while representation-specific source blocks still exist. */
+export declare function portableTree(tree: any, format: ExportFormat, routes: Set<string>, basePath: string): any;
+export declare function passiveHtml(tree: any, prefix: string, checkAnchors?: boolean): {
+    html: string;
+    anchors: Array<{
+        id: string;
+        exportedId: string;
+        title?: string;
+    }>;
+};
+export declare function portableMarkdown(tree: any): string;

package/dist/content-export-render.js

@@ -0,0 +1,132 @@
+import { parseFragment, serialize } from 'parse5';
+import { publicTree } from './representation-tree.js';
+import { renderHtmlWithHeadings } from './html-renderer.js';
+import { heading, link, paragraph, root, text, renderMarkdown } from './content.js';
+import { walkthroughMarkdown } from './walkthrough.js';
+/** Lower interactions while representation-specific source blocks still exist. */
+export function portableTree(tree, format, routes, basePath) {
+    const walk = (node) => {
+        if (node.type === 'docRepresentation')
+            return node.representation === format ? node.children.flatMap(walk) : [];
+        if (node.type === 'docComponent')
+            return node.children.flatMap(walk);
+        if (['docReaderFilter', 'docReaderChoice'].includes(node.type))
+            return [];
+        if (node.type === 'docReaderSection')
+            return [paragraph({ type: 'strong', children: [text(`For ${node.description}.`)] }), ...node.children.flatMap(walk)];
+        if (node.type === 'docTabs')
+            return node.children.flatMap((tab) => [heading(3, tab.label), ...tab.children.flatMap(walk)]);
+        if (node.type === 'docWalkthrough')
+            return walkthroughMarkdown(node, walk, { heading, paragraph, text });
+        if (node.type === 'docCollapsible')
+            return [heading(3, node.title), ...node.children.flatMap(walk)];
+        if (['docTooltip', 'docInfoHint'].includes(node.type))
+            return [node.inline ? text(`${node.label} (${node.definition})`) : paragraph(text(`${node.label}: ${node.definition}`))];
+        if (node.type === 'docMath')
+            return [node.display ? { type: 'code', lang: 'latex', value: node.expression } : { type: 'inlineCode', value: node.expression }];
+        if (node.type === 'docDiagram')
+            return [paragraph({ type: 'image', url: node.url, alt: node.title }), paragraph(text(`${node.title}: ${node.summary}`)), ...(format === 'markdown' ? [{ type: 'code', lang: node.engine, value: node.source }] : [])];
+        if (node.type === 'docCookbookChooser')
+            return [paragraph(text(node.title)), ...node.options.flatMap((option) => [paragraph({ ...link(option.route, option.title), exportDocumentId: option.doc }), paragraph(text([option.when ?? option.summary, option.needs, option.outcome].filter(Boolean).join(' ')))])];
+        if (node.type === 'docTable')
+            return [{ ...node, filter: false, children: node.children.flatMap(walk) }];
+        if (node.type === 'docDefinitionList')
+            return [{ ...node, filter: false, items: node.items.map((item) => ({ ...item, term: item.term.flatMap(walk), definition: item.definition.flatMap(walk) })) }];
+        if (node.type === 'docSteps' || node.type === 'docTimeline')
+            return [{ ...node, items: node.items.map((item) => ({ ...item, children: item.children.flatMap(walk) })) }];
+        return [{ ...node, ...(node.children ? { children: node.children.flatMap(walk) } : {}) }];
+    };
+    const lowered = publicTree(root((tree.children ?? []).flatMap(walk)), format, routes, 'light', basePath);
+    const definitions = new Map();
+    const collectDefinitions = (node) => {
+        if (node.type === 'definition')
+            definitions.set(node.identifier, node);
+        for (const child of node.children ?? [])
+            collectDefinitions(child);
+    };
+    collectDefinitions(lowered);
+    const clean = (node) => {
+        if (node.data?.hName === 'svg' && node.data?.hProperties?.ariaHidden === 'true' && node.data?.hProperties?.['data-lucide'])
+            return text('');
+        if (node.type === 'linkReference' || node.type === 'imageReference') {
+            const definition = definitions.get(node.identifier);
+            if (!definition)
+                throw new Error(`Missing export link definition ${node.identifier}`);
+            node = { ...node, type: node.type === 'linkReference' ? 'link' : 'image', url: definition.url,
+                ...(definition.title ? { title: definition.title } : {}), ...(definition.exportDocumentId ? { exportDocumentId: definition.exportDocumentId } : {}) };
+        }
+        // Browser-only data and injected SVG icons are not part of the content contract.
+        const data = node.data ? { ...node.data } : undefined;
+        if (data) {
+            delete data.hChildren;
+            delete data.mathMarkup;
+        }
+        return { ...node, ...(data ? { data } : {}), ...(node.children ? { children: node.children.filter((child) => child.type !== 'definition').map(clean) } : {}) };
+    };
+    return clean(lowered);
+}
+const tags = new Set('a abbr article b blockquote br caption code col colgroup dd del details div dl dt em figcaption figure h1 h2 h3 h4 h5 h6 hr i img input kbd li ol p pre progress s section small span strong sub summary sup table tbody td th thead time tr ul'.split(' '));
+const attrs = new Set(['id', 'href', 'src', 'alt', 'title', 'colspan', 'rowspan', 'start', 'reversed', 'value', 'max', 'datetime', 'scope', 'align', 'type', 'checked', 'disabled', 'aria-label', 'aria-labelledby', 'aria-describedby', 'aria-hidden', 'role', 'tabindex', 'data-footnote-ref', 'data-footnote-backref', 'data-export-link']);
+export function passiveHtml(tree, prefix, checkAnchors = true) {
+    const rendered = renderHtmlWithHeadings(tree);
+    const fragment = parseFragment(rendered.html);
+    const anchors = [];
+    const ids = new Set();
+    const visit = (node) => {
+        if (node.nodeName === '#text')
+            return;
+        if (node.tagName) {
+            if (!tags.has(node.tagName))
+                throw new Error(`Unsupported passive HTML element <${node.tagName}>`);
+            const original = node.attrs ?? [];
+            for (const attr of original) {
+                if (/^on/i.test(attr.name))
+                    throw new Error('Event handlers are not allowed in exported HTML');
+                if (['href', 'src'].includes(attr.name)) {
+                    const url = new URL(attr.value, 'https://export.invalid/');
+                    if (!['https:', 'http:', ...(attr.name === 'href' ? ['mailto:', 'tel:'] : [])].includes(url.protocol) || url.username || url.password)
+                        throw new Error(`Unsafe exported URL: ${attr.value}`);
+                }
+            }
+            node.attrs = original.filter((attr) => attrs.has(attr.name));
+            const id = node.attrs.find((attr) => attr.name === 'id');
+            if (id) {
+                if (ids.has(id.value))
+                    throw new Error(`Duplicate exported anchor ${id.value}`);
+                ids.add(id.value);
+                const title = rendered.headings.find(heading => heading.id === id.value)?.title;
+                anchors.push({ id: id.value, exportedId: `${prefix}-${id.value}`, ...(title ? { title } : {}) });
+                id.value = `${prefix}-${id.value}`;
+            }
+            for (const attr of node.attrs)
+                if (['aria-labelledby', 'aria-describedby'].includes(attr.name))
+                    attr.value = attr.value.split(/\s+/).map((value) => `${prefix}-${value}`).join(' ');
+            if (node.tagName === 'details')
+                node.attrs.push({ name: 'open', value: '' });
+            if (node.tagName === 'input') {
+                if (original.find((attr) => attr.name === 'type')?.value !== 'checkbox')
+                    throw new Error('Only passive task-list checkboxes can be exported');
+                node.attrs.push({ name: 'disabled', value: '' });
+            }
+        }
+        for (const child of node.childNodes ?? [])
+            visit(child);
+    };
+    for (const child of fragment.childNodes)
+        visit(child);
+    const references = (node) => {
+        for (const attr of node.attrs ?? [])
+            if (attr.name === 'href' && attr.value.startsWith('#')) {
+                const fragmentId = decodeURIComponent(attr.value.slice(1));
+                if (ids.has(fragmentId))
+                    attr.value = `#${prefix}-${fragmentId}`;
+                else if (checkAnchors && !anchors.some(anchor => anchor.exportedId === fragmentId))
+                    throw new Error(`Missing local export anchor ${fragmentId}`);
+            }
+        for (const child of node.childNodes ?? [])
+            references(child);
+    };
+    references(fragment);
+    return { html: serialize(fragment) + '\n', anchors };
+}
+export function portableMarkdown(tree) { return renderMarkdown(tree); }

package/dist/content-export.d.ts

@@ -0,0 +1,30 @@
+import { type ExportFormat } from './content-export-config.js';
+import { type Variant } from './content.js';
+export type ContentExportOptions = {
+    target?: string;
+    formats?: ExportFormat[];
+    documents?: string[];
+    publication?: Variant;
+    publicBase?: string;
+    review?: boolean;
+};
+/** Export selected source content; never invoke the website shell/compiler. */
+export declare function exportContent(configFile: string, destination: string, options?: ContentExportOptions): Promise<{
+    status: string;
+    output: string;
+    publication: Variant;
+    formats: ExportFormat[];
+    documents: number;
+    documentIds: string[];
+    assets: number;
+    digest: string;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId: string;
+        message: string;
+    }[];
+}>;