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

package/dist/remote-import.js

@@ -0,0 +1,292 @@
+import { createHash } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { request } from 'node:https';
+import { BlockList, isIP } from 'node:net';
+import path from 'node:path';
+import YAML from 'yaml';
+import { ApiReader } from './api.js';
+const maxFileBytes = 4 * 1024 * 1024;
+const maxTotalBytes = 16 * 1024 * 1024;
+const maxFiles = 128;
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const blocked = new BlockList();
+for (const [address, prefix] of [
+    ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+    ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
+    ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24],
+    ['203.0.113.0', 24], ['192.88.99.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4]
+])
+    blocked.addSubnet(address, prefix, 'ipv4');
+for (const [address, prefix] of [
+    ['::', 128], ['::1', 128], ['64:ff9b::', 96],
+    ['2001::', 32], ['2001:db8::', 32], ['2002::', 16], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8]
+])
+    blocked.addSubnet(address, prefix, 'ipv6');
+function checkedUrl(value, origin) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`OpenAPI source needs an absolute HTTPS URL: ${value}`);
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.port || url.search || url.hash || isIP(url.hostname.replace(/^\[|\]$/g, ''))) {
+        throw new Error(`OpenAPI source needs a public HTTPS URL without credentials, port, query, or fragment: ${value}`);
+    }
+    if (origin && url.origin !== origin)
+        throw new Error(`Remote $ref leaves the OpenAPI source origin: ${value}`);
+    return url;
+}
+async function publicAddress(hostname) {
+    const addresses = await lookup(hostname, { all: true, verbatim: true });
+    if (!addresses.length || addresses.some(({ address, family }) => !isPublicImportAddress(address, family))) {
+        throw new Error(`OpenAPI source host does not resolve only to public addresses: ${hostname}`);
+    }
+    return addresses[0];
+}
+export function isPublicImportAddress(address, family) {
+    return !blocked.check(address, family === 4 ? 'ipv4' : 'ipv6');
+}
+async function downloadPublic(url) {
+    const address = await publicAddress(url.hostname);
+    return new Promise((resolve, reject) => {
+        const req = request(url, {
+            method: 'GET', timeout: 10_000, headers: { accept: 'application/yaml, application/json, text/yaml, text/plain', 'accept-encoding': 'identity' },
+            lookup: ((_host, options, callback) => {
+                if (options.all)
+                    callback(null, [address]);
+                else
+                    callback(null, address.address, address.family);
+            })
+        }, response => {
+            if (response.statusCode !== 200) {
+                response.resume();
+                reject(new Error(`OpenAPI download returned HTTP ${response.statusCode} for ${url}`));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            response.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > maxFileBytes) {
+                    req.destroy(new Error(`OpenAPI source exceeds ${maxFileBytes} bytes: ${url}`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on('end', () => resolve(Buffer.concat(chunks)));
+            response.on('error', reject);
+        });
+        const deadline = setTimeout(() => req.destroy(new Error(`OpenAPI download exceeded 30 seconds: ${url}`)), 30_000);
+        req.once('close', () => clearTimeout(deadline));
+        req.on('timeout', () => req.destroy(new Error(`OpenAPI download timed out: ${url}`)));
+        req.on('error', reject);
+        req.end();
+    });
+}
+function parse(source, url) {
+    const document = YAML.parseDocument(source.toString('utf8'), { uniqueKeys: true });
+    if (document.errors.length)
+        throw new Error(`${url}: ${document.errors.map(error => error.message).join('; ')}`);
+    return document.toJS();
+}
+function localPath(url, entry) {
+    return url === entry ? 'openapi.yaml' : `refs/${hash(url)}.yaml`;
+}
+async function snapshot(entry, directory, download) {
+    const entryUrl = checkedUrl(entry);
+    const queue = [entryUrl.href];
+    const queued = new Set(queue);
+    const files = [];
+    let totalBytes = 0;
+    for (let index = 0; index < queue.length; index++) {
+        const currentUrl = queue[index];
+        const bytes = await download(new URL(currentUrl));
+        totalBytes += bytes.length;
+        if (bytes.length > maxFileBytes || totalBytes > maxTotalBytes)
+            throw new Error('Remote OpenAPI source exceeds the import size limit');
+        const value = parse(bytes, currentUrl);
+        if (index === 0 && (!value || typeof value !== 'object' || Array.isArray(value) || !/^3\.(0|1)\./.test(String(value.openapi)))) {
+            throw new Error(`${currentUrl}: OpenAPI 3.0.x or 3.1.x document required`);
+        }
+        const currentPath = localPath(currentUrl, entry);
+        function rewriteReference(reference) {
+            if (reference.startsWith('#'))
+                return reference;
+            let target;
+            try {
+                target = new URL(reference, currentUrl);
+            }
+            catch {
+                throw new Error(`Invalid remote reference ${reference} in ${currentUrl}`);
+            }
+            let fragment;
+            try {
+                fragment = decodeURIComponent(target.hash);
+            }
+            catch {
+                throw new Error(`Invalid remote reference fragment ${reference}`);
+            }
+            target.hash = '';
+            checkedUrl(target.href, entryUrl.origin);
+            if (fragment && !fragment.startsWith('#/'))
+                throw new Error(`Unsupported remote reference fragment ${reference}`);
+            if (!queued.has(target.href)) {
+                if (queue.length >= maxFiles)
+                    throw new Error(`Remote OpenAPI source exceeds ${maxFiles} files`);
+                queue.push(target.href);
+                queued.add(target.href);
+            }
+            if (target.href === currentUrl)
+                return fragment || '#';
+            const relative = path.posix.relative(path.posix.dirname(currentPath), localPath(target.href, entry));
+            return `${relative.startsWith('.') ? relative : `./${relative}`}${fragment}`;
+        }
+        async function rewrite(node, kind = 'object', map = false) {
+            if (!node || typeof node !== 'object')
+                return;
+            if (Array.isArray(node)) {
+                for (const child of node)
+                    await rewrite(child, kind);
+                return;
+            }
+            if (map) {
+                for (const child of Object.values(node))
+                    await rewrite(child, kind);
+                return;
+            }
+            if (typeof node.$ref === 'string')
+                node.$ref = rewriteReference(node.$ref);
+            if (node.discriminator?.mapping && typeof node.discriminator.mapping === 'object') {
+                for (const [name, target] of Object.entries(node.discriminator.mapping)) {
+                    if (typeof target !== 'string')
+                        throw new Error(`Invalid discriminator mapping ${name} in ${currentUrl}`);
+                    if (target.startsWith('.') || target.startsWith('/') || target.includes('/') || /\.(?:ya?ml|json)(?:#|$)/i.test(target))
+                        node.discriminator.mapping[name] = rewriteReference(target);
+                }
+            }
+            for (const [key, child] of Object.entries(node)) {
+                if (key === '$ref' || key.startsWith('x-') || ['example', 'default', 'enum', 'const', 'security'].includes(key) ||
+                    (kind === 'example' && key === 'value') || (kind === 'schema' && key === 'examples'))
+                    continue;
+                const childKind = kind === 'schema' || key === 'schema' || key === 'schemas' ? 'schema' : key === 'examples' ? 'example' : kind;
+                const isMap = kind === 'schema'
+                    ? ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas'].includes(key)
+                    : ['paths', 'webhooks', 'schemas', 'responses', 'parameters', 'requestBodies', 'headers', 'links', 'callbacks', 'pathItems', 'securitySchemes', 'examples', 'content', 'encoding', 'variables', 'flows', 'scopes'].includes(key);
+                await rewrite(child, childKind, isMap);
+            }
+        }
+        await rewrite(value);
+        const output = path.join(directory, currentPath);
+        const digest = hash(bytes);
+        const snapshotText = `# Imported from ${currentUrl}\n# Source SHA-256: ${digest}\n${YAML.stringify(value)}`;
+        await mkdir(path.dirname(output), { recursive: true });
+        await writeFile(output, snapshotText);
+        files.push({ url: currentUrl, path: currentPath, digest, snapshotDigest: hash(snapshotText) });
+    }
+    const lock = { version: 1, entry, files: files.sort((a, b) => a.url.localeCompare(b.url)) };
+    await writeFile(path.join(directory, 'source-lock.json'), JSON.stringify(lock, null, 2) + '\n');
+    await new ApiReader().collectReferences(path.join(directory, 'openapi.yaml'));
+    return lock;
+}
+function changes(previous, next) {
+    const oldFiles = new Map(previous?.files.map(file => [file.url, file]) ?? []);
+    const newFiles = new Map(next.files.map(file => [file.url, file]));
+    return [...new Set([...oldFiles.keys(), ...newFiles.keys()])].sort().flatMap(url => {
+        const before = oldFiles.get(url);
+        const after = newFiles.get(url);
+        return before?.digest === after?.digest && before?.snapshotDigest === after?.snapshotDigest ? [] : [{
+                url, before: before?.digest ?? null, after: after?.digest ?? null,
+                snapshotBefore: before?.snapshotDigest ?? null, snapshotAfter: after?.snapshotDigest ?? null
+            }];
+    });
+}
+export async function importRemoteOpenApi(url, directory, options = {}) {
+    const entry = checkedUrl(url).href;
+    const output = path.resolve(directory);
+    try {
+        await lstat(output);
+        throw new Error(`Import output already exists: ${output}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await mkdir(path.dirname(output), { recursive: true });
+    const candidate = await mkdtemp(path.join(path.dirname(output), '.shoalrun-import-'));
+    try {
+        const lock = await snapshot(entry, candidate, options.download ?? downloadPublic);
+        await rename(candidate, output);
+        return { status: 'imported', directory: output, entry: lock.entry, files: lock.files, changes: changes(undefined, lock) };
+    }
+    catch (error) {
+        await rm(candidate, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function refreshRemoteOpenApi(directory, options = {}) {
+    const output = path.resolve(directory);
+    if (!(await lstat(output)).isDirectory())
+        throw new Error(`Snapshot must be a directory: ${output}`);
+    const previous = JSON.parse(await readFile(path.join(output, 'source-lock.json'), 'utf8'));
+    if (previous.version !== 1 || !Array.isArray(previous.files) || previous.files.some(file => typeof file.path !== 'string' || typeof file.snapshotDigest !== 'string' ||
+        (file.path !== 'openapi.yaml' && !/^refs\/[0-9a-f]{64}\.yaml$/.test(file.path))))
+        throw new Error(`Invalid source-lock.json in ${output}`);
+    for (const file of previous.files) {
+        if (!(await lstat(path.join(output, file.path))).isFile())
+            throw new Error(`Snapshot file is not a regular file: ${file.path}`);
+        const actual = hash(await readFile(path.join(output, file.path)));
+        if (actual !== file.snapshotDigest)
+            throw new Error(`Local OpenAPI snapshot changed since import: ${file.path}`);
+    }
+    const entry = checkedUrl(previous.entry).href;
+    const candidate = await mkdtemp(path.join(path.dirname(output), '.shoalrun-import-'));
+    try {
+        const lock = await snapshot(entry, candidate, options.download ?? downloadPublic);
+        const changed = changes(previous, lock);
+        if (!changed.length) {
+            await rm(candidate, { recursive: true, force: true });
+            return { status: 'unchanged', directory: output, entry, files: lock.files, changes: changed };
+        }
+        const nextOutput = path.resolve(options.output ?? `${output}-refresh-${hash(JSON.stringify(lock)).slice(0, 12)}`);
+        const relative = path.relative(output, nextOutput);
+        if (nextOutput === output || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))) {
+            throw new Error(`Refresh output must be outside the current snapshot: ${nextOutput}`);
+        }
+        let existingOutput = false;
+        try {
+            existingOutput = (await lstat(nextOutput)).isDirectory();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (existingOutput) {
+            const existing = JSON.parse(await readFile(path.join(nextOutput, 'source-lock.json'), 'utf8'));
+            if (JSON.stringify(existing) !== JSON.stringify(lock))
+                throw new Error(`Refresh output already exists with different content: ${nextOutput}`);
+            for (const file of existing.files)
+                if (!(await lstat(path.join(nextOutput, file.path))).isFile() || hash(await readFile(path.join(nextOutput, file.path))) !== file.snapshotDigest) {
+                    throw new Error(`Refresh output already exists with changed content: ${nextOutput}`);
+                }
+            await rm(candidate, { recursive: true, force: true });
+            return { status: 'updated', directory: nextOutput, previousDirectory: output, entry, files: lock.files, changes: changed };
+        }
+        try {
+            await lstat(nextOutput);
+            throw new Error(`Refresh output already exists: ${nextOutput}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await mkdir(path.dirname(nextOutput), { recursive: true });
+        await rename(candidate, nextOutput);
+        return { status: 'updated', directory: nextOutput, previousDirectory: output, entry, files: lock.files, changes: changed };
+    }
+    catch (error) {
+        await rm(candidate, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/representation-tree.d.ts

@@ -0,0 +1,3 @@
+export declare function publicTree(tree: any, representation: 'html' | 'markdown', documentRoutes: Set<string>, mode?: 'light' | 'dark' | 'system', basePath?: string): any;
+export declare function outputUrl(value: string, pageRoute: string, origin: string | undefined, representation: 'html' | 'markdown', documentRoutes: Set<string>, basePath?: string): string;
+export declare function resolveOutputLinks(tree: any, pageRoute: string, origin: string | undefined, representation: 'html' | 'markdown', documentRoutes: Set<string>, basePath?: string): any;

package/dist/representation-tree.js

@@ -0,0 +1,320 @@
+import { createHash } from 'node:crypto';
+import katex from 'katex';
+import { badgeIcon, treeIcon } from './icons.js';
+import { heading, link, list, markdownRoute, paragraph, text } from './content.js';
+import { walkthroughHtml, walkthroughMarkdown } from './walkthrough.js';
+import { procedureTree } from './procedure-components.js';
+import { readerViewParam } from './reader-filters.js';
+import { paletteCatalog, presetCatalog } from './palettes.js';
+import { diagramSvg } from './diagram-svg.js';
+export function publicTree(tree, representation, documentRoutes, mode = 'light', basePath = '') {
+    let diagramIndex = 0;
+    const element = (name, properties, children) => ({ type: 'paragraph', data: { hName: name, hProperties: properties }, children });
+    const walk = (node) => {
+        if (node.type === 'docComponent') {
+            const children = node.children.flatMap(walk);
+            if (representation === 'markdown')
+                return children;
+            return [element('section', { 'data-shoalrun-component': node.name, 'data-component-data': JSON.stringify(node.componentData), 'data-component-module': `${basePath}${node.browser.moduleUrl}`, 'data-component-styles': JSON.stringify(node.browser.styleUrls.map((url) => `${basePath}${url}`)) }, [
+                    element('div', { 'data-component-controls': '', hidden: true }, []),
+                    element('div', { 'data-component-content': '' }, children)
+                ])];
+        }
+        if (node.type === 'docRepresentation')
+            return node.representation === representation ? node.children.flatMap(walk) : [];
+        if (node.type === 'docCookbookChooser') {
+            const prompt = node.mode === 'single' ? 'Choose one recipe.' : 'Choose one or more recipes.';
+            const details = (option) => [option.when ? `Use when: ${option.when}` : option.summary, option.needs ? `You need: ${option.needs}` : '', option.outcome ? `You will have: ${option.outcome}` : ''].filter(Boolean);
+            if (representation === 'markdown')
+                return [
+                    paragraph(text(`${node.title}. ${prompt}`)),
+                    list(node.options.map((option) => [paragraph(link(option.markdownRoute, `${option.label} — ${option.title}`)), ...details(option).map((value) => paragraph(text(value)))]))
+                ];
+            return [element('section', { className: ['cookbook-chooser'], 'data-cookbook-chooser': JSON.stringify({ options: node.options, id: node.id, mode: node.mode, title: node.title }) }, [
+                    element('div', { className: ['cookbook-chooser-controls'], hidden: true }, [
+                        element('fieldset', {}, [element('legend', {}, [text(node.title)]), ...node.options.map((option) => element('label', { className: ['cookbook-option'] }, [
+                                element('input', { type: node.mode === 'single' ? 'radio' : 'checkbox', value: option.id }, []),
+                                element('span', {}, [element('strong', {}, [text(option.label)]), ...details(option).map((value) => element('span', { className: ['cookbook-option-detail'] }, [text(value)]))])
+                            ]))]),
+                        element('p', { className: ['cookbook-chooser-status'], role: 'status', 'aria-live': 'polite' }, [text(prompt)]),
+                        element('div', { className: ['cookbook-path-actions'], hidden: true }, [
+                            element('a', { className: ['cookbook-share'], href: '#' }, [text('Link to this path')]),
+                            element('button', { type: 'button', className: ['cookbook-download'] }, [text('Download Markdown')]),
+                            element('button', { type: 'button', className: ['cookbook-print'] }, [text('Print this path')])
+                        ]),
+                        element('div', { className: ['cookbook-chooser-result'] }, [])
+                    ]),
+                    element('div', { className: ['cookbook-chooser-approved'] }, [
+                        element('p', {}, [text('Recipes in this cookbook:')]),
+                        element('ul', {}, node.options.map((option) => element('li', {}, [element('a', { href: option.route }, [text(`${option.label} — ${option.title}`)])])))
+                    ])
+                ])];
+        }
+        if (node.type === 'docReaderSection') {
+            const children = node.children.flatMap(walk);
+            return representation === 'markdown' ? [paragraph({ type: 'strong', children: [text(`For ${node.description}.`)] }), ...children]
+                : [element('section', { className: ['reader-section'], 'data-reader-filters': JSON.stringify(node.selection) }, children)];
+        }
+        if (node.type === 'docReaderChoice') {
+            if (representation === 'markdown') {
+                const choice = link(`${node.route}?${node.scope === 'page' ? 'pageView' : 'view'}=${encodeURIComponent(readerViewParam(node.selection))}`, node.label);
+                choice.data = { htmlDestination: true };
+                return [paragraph(choice)];
+            }
+            return [element('button', { type: 'button', className: ['reader-choice'], 'data-reader-choice': JSON.stringify(node.selection), 'data-reader-scope': node.scope }, [text(node.label)])];
+        }
+        if (node.type === 'docReaderFilter') {
+            return representation === 'markdown' ? [] : [element('div', { className: ['reader-filter-slot'], 'data-reader-filter': JSON.stringify(node.control) }, [])];
+        }
+        if (node.type === 'docTable') {
+            const table = node.children.flatMap(walk);
+            if (representation === 'markdown')
+                return table;
+            const filter = node.filter ? element('div', { className: ['doc-table-filter'], hidden: true }, [
+                element('label', {}, [text('Filter rows'), element('input', { type: 'search', placeholder: 'Search table rows' }, [])]),
+                element('span', { className: ['doc-table-count'], role: 'status', 'aria-live': 'polite' }, [])
+            ]) : null;
+            return [element('div', { className: ['doc-table'], ...(node.filter ? { 'data-table-filter': '' } : {}) }, [
+                    ...(filter ? [filter] : []),
+                    element('div', { className: ['doc-table-scroll', ...(node.sticky ? ['doc-table-sticky'] : [])], ...(node.sticky ? { tabIndex: 0 } : {}) }, table)
+                ])];
+        }
+        if (node.type === 'docBadge') {
+            if (representation === 'markdown')
+                return [text(node.label)];
+            return [element('span', { className: ['doc-badge', `doc-badge-${node.variant}`] }, [...(node.icon ? [badgeIcon(node.icon)] : []), text(node.label)])];
+        }
+        if (node.type === 'docKbd')
+            return representation === 'markdown' ? [text(node.label)] : [element('kbd', { className: ['doc-kbd'] }, [text(node.label)])];
+        if (node.type === 'docInfoHint') {
+            if (representation === 'markdown')
+                return [paragraph(text(`${node.label}: ${node.definition}`))];
+            return [element('details', { className: ['doc-info-hint'] }, [element('summary', {}, [text(node.label)]), element('p', {}, [text(node.definition)])])];
+        }
+        if (node.type === 'docTooltip') {
+            if (representation === 'markdown')
+                return [node.inline ? text(`${node.label} (${node.definition})`) : paragraph(text(`${node.label}: ${node.definition}`))];
+            const tooltip = element('span', { className: ['doc-tooltip'], 'data-tooltip': '' }, [
+                element('span', { className: ['doc-tooltip-trigger'] }, [text(node.label)]),
+                element('span', { className: ['doc-tooltip-separator'] }, [text(': ')]),
+                element('span', { className: ['doc-tooltip-popup'] }, [text(node.definition)])
+            ]);
+            return [node.inline ? tooltip : paragraph(tooltip)];
+        }
+        if (node.type === 'docProgress') {
+            const summary = `${node.label}: ${node.value} of ${node.max} complete`;
+            if (representation === 'markdown')
+                return [paragraph(text(`${summary}.`))];
+            return [element('div', { className: ['doc-progress'] }, [element('p', { className: ['doc-progress-label'] }, [text(summary)]), element('progress', { value: node.value, max: node.max, 'aria-label': node.label }, [text(`${node.value} of ${node.max}`)])])];
+        }
+        if (node.type === 'docMath') {
+            if (representation === 'markdown') {
+                const math = node.display ? { type: 'code', lang: 'latex', value: node.expression } : { type: 'inlineCode', value: node.expression };
+                return [node.block && !node.display ? paragraph(math) : math];
+            }
+            const marker = `SHOALRUNMATH${createHash('sha256').update(`${node.display}|${node.expression}`).digest('hex').slice(0, 24)}`;
+            const markup = katex.renderToString(node.expression, { output: 'mathml', displayMode: node.display, throwOnError: true, strict: 'error', trust: false, maxExpand: 1000 });
+            const math = element(node.display ? 'div' : 'span', { className: [node.display ? 'doc-math-display' : 'doc-math-inline'] }, [{ type: 'text', value: marker, data: { mathMarkup: markup } }]);
+            return [node.block && !node.display ? paragraph(math) : math];
+        }
+        if (node.type === 'docActionLink') {
+            const children = node.children.flatMap(walk);
+            const url = representation === 'markdown' && documentRoutes.has(node.url) ? markdownRoute(node.url, basePath) : node.url;
+            return [{ type: 'link', url, children, ...(representation === 'html' ? { data: { hProperties: { className: ['doc-action-link', `doc-action-${node.variant}`] } } } : {}) }];
+        }
+        if (node.type === 'docDefinitionList') {
+            if (representation === 'markdown') {
+                const inline = new Set(['text', 'strong', 'emphasis', 'inlineCode', 'link', 'delete', 'image', 'break']);
+                const blocks = (children) => {
+                    const result = [];
+                    let pending = [];
+                    const flush = () => { if (pending.length)
+                        result.push(paragraph(...pending)); pending = []; };
+                    for (const child of children) {
+                        if (inline.has(child.type))
+                            pending.push(child);
+                        else {
+                            flush();
+                            result.push(child);
+                        }
+                    }
+                    flush();
+                    return result;
+                };
+                return [{ type: 'list', ordered: false, spread: true, children: node.items.map((item) => ({ type: 'listItem', spread: true, children: [
+                                paragraph({ type: 'strong', children: item.term.flatMap(walk).flatMap((term) => term.type === 'paragraph' ? term.children : [term]) }),
+                                ...blocks(item.definition.flatMap(walk))
+                            ] })) }];
+            }
+            const list = element('dl', { className: ['doc-definition-list'] }, node.items.flatMap((item) => [
+                element('dt', {}, item.term.flatMap(walk).flatMap((term) => term.type === 'paragraph' ? term.children : [term])),
+                element('dd', {}, item.definition.flatMap(walk))
+            ]));
+            if (!node.filter)
+                return [list];
+            const controls = element('div', { className: ['doc-definition-filter'], hidden: true }, [
+                element('label', {}, [text('Filter terms and definitions'), element('input', { type: 'search', placeholder: 'Search glossary' }, [])]),
+                element('span', { className: ['doc-definition-count'], role: 'status', 'aria-live': 'polite' }, [])
+            ]);
+            return [element('div', { className: ['doc-definition-list-wrap'], 'data-definition-filter': '' }, [controls, list])];
+        }
+        if (node.type === 'docFileTree') {
+            const item = (entry) => {
+                const url = entry.url && representation === 'markdown' && documentRoutes.has(entry.url) ? markdownRoute(entry.url, basePath) : entry.url;
+                const label = url ? link(url, entry.name) : text(entry.name);
+                const children = entry.children.map(item);
+                if (representation === 'markdown')
+                    return { type: 'listItem', spread: !!children.length, children: [paragraph(label), ...(children.length ? [{ type: 'list', ordered: false, children }] : [])] };
+                const icons = entry.kind === 'folder' && (!entry.icon || entry.icon === 'folder')
+                    ? [element('span', { className: ['tree-folder-closed'] }, [treeIcon('folder')]), element('span', { className: ['tree-folder-open'] }, [treeIcon('folder-open')])]
+                    : [treeIcon(entry.icon || 'file')];
+                const caption = element('span', { className: ['file-tree-label'] }, [
+                    ...icons,
+                    ...(url ? [{ type: 'link', url, children: [text(entry.name)] }] : [text(entry.name)])
+                ]);
+                return element('li', { className: [entry.kind === 'folder' ? 'file-tree-folder' : 'file-tree-file'] }, entry.kind === 'folder' ? [element('details', { className: ['file-tree-branch'], ...(!entry.collapsed ? { open: true } : {}) }, [element('summary', {}, [caption]), ...(children.length ? [element('ul', {}, children)] : [])])] : [caption]);
+            };
+            const items = node.items.map(item);
+            return representation === 'markdown' ? [{ type: 'list', ordered: false, children: items }] : [element('div', { className: ['doc-file-tree'], 'data-file-tree': '' }, [...(node.controls ? [element('div', { className: ['file-tree-controls'], hidden: true }, [element('button', { type: 'button', 'data-tree-expand': '' }, [text('Expand all')]), element('button', { type: 'button', 'data-tree-collapse': '' }, [text('Collapse all')])])] : []), element('ul', {}, items)])];
+        }
+        if (node.type === 'docSteps' || node.type === 'docTimeline')
+            return procedureTree(node, representation, walk, element, text, paragraph);
+        if (representation === 'markdown' && node.data?.htmlOnly)
+            return [];
+        if (representation === 'html' && (node.data?.exampleOnly || node.data?.markdownOnly))
+            return [];
+        if (node.type === 'docDiagram') {
+            if (representation === 'markdown')
+                return [
+                    paragraph({ type: 'strong', children: [text(node.title)] }),
+                    paragraph(text(node.summary)),
+                    paragraph(link(node.url, `View ${node.title} diagram`)),
+                    { type: 'code', lang: node.engine, value: node.source }
+                ];
+            if (node.diagramSvg) {
+                const visual = element('div', { className: ['doc-diagram-visual'] }, []);
+                Object.assign(visual.data, { hChildren: [diagramSvg(node.diagramSvg, node.title, `diagram-instance-${++diagramIndex}`)] });
+                return [element('figure', { className: ['doc-diagram'], 'data-renderer': 'pele', ...(node.width ? { style: `max-width:${node.width}px` } : {}) }, [
+                        visual,
+                        element('figcaption', {}, [{ type: 'strong', children: [text(node.title)] }, text(` — ${node.summary}`)])
+                    ])];
+            }
+            return [element('figure', { className: ['doc-diagram'], 'data-color-mode': mode, ...(node.width ? { style: `max-width:${node.width}px` } : {}) }, [
+                    { type: 'image', url: node.url, alt: node.title, data: { hProperties: { className: ['diagram-light'] } } },
+                    { type: 'image', url: node.darkUrl, alt: node.title, data: { hProperties: { className: ['diagram-dark'] } } },
+                    element('figcaption', {}, [{ type: 'strong', children: [text(node.title)] }, text(` — ${node.summary}`)])
+                ])];
+        }
+        // Images are phrasing nodes; keep standalone images inside a block so
+        // Markdown serialization retains the separators between surrounding blocks.
+        if (node.type === 'docImage') {
+            const image = { type: 'image', url: node.url, alt: node.alt, ...(representation === 'html' ? { data: { hProperties: { className: ['doc-image', ...(node.align ? [`doc-image-align-${node.align}`] : [])], ...(node.width ? { style: `width:100%;max-width:${node.width}px` } : {}) } } } : {}) };
+            if (representation === 'markdown')
+                return [paragraph(image), ...(node.caption ? [paragraph(text(node.caption))] : []), ...(node.expand ? [paragraph(link(node.url, 'View original image'))] : [])];
+            if (!node.expand && !node.caption)
+                return [paragraph(image)];
+            const visual = node.expand ? { type: 'link', url: node.url, data: { hProperties: { 'data-image-expand': '', 'aria-label': `Enlarge image: ${node.alt || 'Image'}` } }, children: [image] } : image;
+            return [element('figure', { className: ['doc-image-figure', ...(node.align ? [`doc-image-align-${node.align}`] : [])], ...(node.width ? { style: `max-width:${node.width}px` } : {}) }, [paragraph(visual), ...(node.caption ? [element('figcaption', {}, [text(node.caption)])] : [])])];
+        }
+        if (node.type === 'themePreview') {
+            const cell = (value, asCode) => ({ type: 'tableCell', children: [asCode ? { type: 'inlineCode', value } : text(value)] });
+            const row = (values, codeColumns) => ({ type: 'tableRow', children: values.map((value, column) => cell(value, codeColumns.includes(column))) });
+            const table = (head, rows, codeColumns) => ({ type: 'table', align: head.map(() => null), children: [row(head, []), ...rows.map(values => row(values, codeColumns))] });
+            const fallback = [
+                paragraph(text('Every preset works with every palette, in light or dark mode.')),
+                table(['Preset', 'Shape', 'Default palette'], presetCatalog.map(preset => [preset.name, preset.shape, preset.palette]), [0, 2]),
+                table(['Palette', 'Colors'], paletteCatalog.map(palette => [palette.name, palette.colors]), [0]),
+                { type: 'code', lang: 'yaml', meta: 'title="docs.config.yaml"', value: 'theme:\n  preset: vice\n  palette: harbor\n  mode: system' }
+            ];
+            if (representation === 'markdown')
+                return fallback;
+            return [element('div', { className: ['theme-preview'], 'data-theme-preview': JSON.stringify({ presets: presetCatalog.map(({ name, palette, masthead }) => ({ name, palette, masthead })), palettes: paletteCatalog.map(palette => palette.name) }) }, [fallback[0], element('details', { className: ['theme-preview-catalog'] }, [element('summary', {}, [text('Browse themes and palettes')]), ...fallback.slice(1)])])];
+        }
+        if (node.type === 'docHero') {
+            const links = node.links.map((item) => item.children ? { ...item, children: item.children.flatMap(walk) } : item);
+            if (representation === 'markdown')
+                return [
+                    ...(node.customTitle ? [paragraph({ type: 'strong', children: [text(node.title)] })] : []),
+                    paragraph(text(node.tagline)),
+                    ...(links.length ? [{ type: 'list', ordered: false, spread: false, children: links.map((item) => ({ type: 'listItem', spread: false, children: [paragraph(...walk(item))] })) }] : []),
+                    ...(node.image && node.image.alt ? [paragraph({ type: 'image', url: node.image.url, alt: node.image.alt })] : []),
+                    ...(node.code ? [node.code] : [])
+                ];
+            // With an image or code block the hero becomes two columns: text, then the visual.
+            const visual = node.image
+                ? [element('div', { className: ['hero-visual'] }, [{ type: 'image', url: node.image.url, alt: node.image.alt, data: { hProperties: { loading: 'eager', decoding: 'async' } } }])]
+                : node.code ? [element('div', { className: ['hero-visual', 'hero-visual-code'] }, [node.code])] : [];
+            const copy = [
+                element('h1', { className: ['hero-title'] }, [text(node.title)]),
+                element('p', { className: ['hero-tagline'] }, [text(node.tagline)]),
+                ...(links.length ? [element('div', { className: ['hero-actions'] }, links.map((item, index) => ({ ...item, data: { hProperties: { className: ['hero-action', index ? 'hero-secondary' : 'hero-primary'] } } })))] : [])
+            ];
+            return [element('section', { className: ['hero', ...(visual.length ? ['has-visual'] : [])], 'data-hero': '', ...(node.align === 'start' || visual.length ? { 'data-align': 'start' } : {}) }, visual.length ? [element('div', { className: ['hero-copy'] }, copy), ...visual] : copy)];
+        }
+        if (node.type === 'docSection') {
+            const children = node.children.flatMap(walk);
+            if (representation === 'markdown')
+                return children;
+            return [element('section', { className: ['splash-section'], ...(node.variant ? { 'data-variant': node.variant } : {}), ...(node.sectionId ? { id: node.sectionId } : {}) }, [element('div', { className: ['splash-inner'] }, children)])];
+        }
+        if (node.type === 'docCollapsibleGroup') {
+            const children = node.children.flatMap(walk);
+            return representation === 'markdown' ? children : [element('div', { className: ['doc-collapsible-group'] }, children)];
+        }
+        if (node.type === 'docCollapsible') {
+            const children = node.children.flatMap(walk);
+            if (representation === 'markdown')
+                return [heading(3, node.title), ...children];
+            return [element('details', { className: ['doc-collapsible'], ...(node.open ? { open: true } : {}) }, [element('summary', {}, [text(node.title)]), element('div', { className: ['collapsible-body'] }, children)])];
+        }
+        if (node.type === 'docWalkthrough')
+            return representation === 'markdown' ? walkthroughMarkdown(node, walk, { heading, paragraph, text }) : walkthroughHtml(node, walk, element, text);
+        if (node.type === 'docTabs') {
+            if (representation === 'markdown')
+                return node.children.flatMap((tab) => [heading(3, tab.label), ...tab.children.flatMap(walk)]);
+            const links = node.children.map((tab, index) => ({ ...link(`#${node.id}-panel-${index + 1}`, tab.label), data: { hProperties: { 'data-tab-value': tab.value } } }));
+            const panels = node.children.map((tab, index) => element('section', { id: `${node.id}-panel-${index + 1}`, className: ['doc-tabpanel'] }, [
+                { ...heading(3, tab.label), data: { hProperties: { className: ['tab-fallback-heading'] } } },
+                ...tab.children.flatMap(walk)
+            ]));
+            return [element('div', { className: ['doc-tabs'], 'data-tabs': '', ...(node.sync ? { 'data-tab-sync': node.sync } : {}), ...(node.equalHeight ? { 'data-equal-height': '' } : {}) }, [element('div', { className: ['doc-tablist'], 'aria-label': node.label }, links), ...panels])];
+        }
+        if (node.type === 'link' && documentRoutes.has(node.url) && representation === 'markdown')
+            return [{ ...node, url: markdownRoute(node.url, basePath), children: node.children.flatMap(walk) }];
+        if (node.children)
+            return [{ ...node, children: node.children.flatMap(walk) }];
+        return [node];
+    };
+    return walk(tree)[0];
+}
+// Resolve authored links against the published page route, then use the public
+// origin when one is configured. Keep fragment-only links local to the page.
+export function outputUrl(value, pageRoute, origin, representation, documentRoutes, basePath = '') {
+    if (!value || value.startsWith('#') || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(value))
+        return value;
+    const target = new URL(value, `https://shoalrun.invalid${basePath && pageRoute === basePath ? `${pageRoute}/` : pageRoute}`);
+    if (basePath && value.startsWith('/') && target.pathname !== basePath && !target.pathname.startsWith(`${basePath}/`))
+        target.pathname = `${basePath}${target.pathname}`;
+    if (representation === 'markdown' && documentRoutes.has(target.pathname))
+        target.pathname = markdownRoute(target.pathname, basePath);
+    return `${origin ?? ''}${target.pathname}${target.search}${target.hash}`;
+}
+export function resolveOutputLinks(tree, pageRoute, origin, representation, documentRoutes, basePath = '') {
+    const walk = (node) => {
+        const resolved = { ...node };
+        if (['link', 'image', 'definition'].includes(node.type) && typeof node.url === 'string')
+            resolved.url = outputUrl(node.url, pageRoute, node.type === 'image' && representation === 'html' ? undefined : origin, node.data?.htmlDestination ? 'html' : representation, documentRoutes, basePath);
+        if (node.data?.hProperties) {
+            const properties = { ...node.data.hProperties };
+            for (const key of ['href', 'src'])
+                if (typeof properties[key] === 'string')
+                    properties[key] = outputUrl(properties[key], pageRoute, key === 'src' && representation === 'html' ? undefined : origin, node.data?.htmlDestination ? 'html' : representation, documentRoutes, basePath);
+            resolved.data = { ...node.data, hProperties: properties };
+        }
+        if (node.children)
+            resolved.children = node.children.map(walk);
+        return resolved;
+    };
+    return walk(tree);
+}
+// Search runs in the reader's browser. The framework owns the header box; a provider module owns retrieval.