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

package/dist/vercel.js

@@ -0,0 +1,103 @@
+import { addMcpFunction, removeStaleMcpFunctions } from './mcp-vercel.js';
+import { mcpDataPath, mcpRuntimePath } from './mcp-integrity.js';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { compile } from './compiler.js';
+import { homeUrl } from './negotiation.js';
+import { addAskFunction } from './vercel-function.js';
+function exact(route) {
+    return route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+async function removeStaleFunctions(directory, keep = new Set()) {
+    const visit = async (folder) => {
+        for (const entry of await readdir(folder, { withFileTypes: true }).catch(() => [])) {
+            if (!entry.isDirectory() || entry.name.endsWith('.func'))
+                continue;
+            const child = path.join(folder, entry.name);
+            if (entry.name === '__shoalrun') {
+                for (const name of ['ask.func', 'search.func']) {
+                    const generated = path.join(child, name);
+                    if (!keep.has(generated))
+                        await rm(generated, { recursive: true, force: true });
+                }
+            }
+            else
+                await visit(child);
+        }
+    };
+    await visit(directory);
+}
+export async function buildVercel(configFile, outputDirectory, provenance = {}, options = {}) {
+    const output = path.resolve(outputDirectory);
+    const staticDirectory = path.join(output, 'static');
+    const manifest = await compile(configFile, staticDirectory, provenance);
+    const basePath = manifest.basePath;
+    const functionsDirectory = path.join(output, 'functions');
+    const mcp = await addMcpFunction({ staticDirectory, functionsDirectory });
+    if (mcp.added) {
+        // Runtime data belongs to the function, never the public static filesystem.
+        await rm(path.join(staticDirectory, mcpRuntimePath), { force: true });
+        await rm(path.join(staticDirectory, mcpDataPath), { recursive: true, force: true });
+    }
+    const resourceHeaders = JSON.parse(await readFile(path.join(staticDirectory, 'resource-headers.json'), 'utf8'));
+    const routes = [
+        { src: '^/.*$', headers: { 'X-Content-Type-Options': 'nosniff' }, continue: true },
+        { src: '^/.*\\.svg$', headers: { 'Content-Security-Policy': 'sandbox' }, continue: true }
+    ];
+    if (mcp.added) {
+        routes.push({ src: '^/(?:mcp-runtime\\.json|__shoalrun/mcp-data(?:/.*)?)$', status: 404 });
+        routes.push({ src: `^${exact(mcp.path)}$`, dest: mcp.path });
+    }
+    const markdownRequest = { type: 'header', key: 'Accept', value: { re: '(?i)(?:^|,)\\s*text/markdown(?![^,]*;\\s*q=0(?:\\.0+)?(?:,|$))' } };
+    // The Node server serves Markdown only when its weight is at least HTML's (negotiation.ts). A header rule cannot
+    // compare two numbers, so this rule keeps HTML in the common case where HTML clearly wins: Markdown with a
+    // fractional weight beside text/html at full weight or, when text/html is absent, beside a full-weight wildcard.
+    const fullWeight = String.raw `\s*(?:,|$|;(?![^,]*\bq=)|;[^,]*\bq=1(?:\.0{0,3})?\s*(?:[,;]|$))`;
+    const markdownOutranked = { type: 'header', key: 'Accept', value: { re: String.raw `(?i)^(?=(?:.*,)?\s*text/markdown\s*;[^,]*\bq=0\.)(?:(?=(?:.*,)?\s*text/html${fullWeight})|(?!(?:.*,)?\s*text/html\s*(?:[,;]|$))(?=(?:.*,)?\s*(?:text|\*)/\*${fullWeight}))` } };
+    for (const document of manifest.documents) {
+        const src = document.url === '/' ? '^/$' : `^${exact(document.url)}/?$`;
+        const alternate = `<${document.markdownUrl}>; rel="alternate"; type="text/markdown"`;
+        routes.push({ src, dest: document.markdownUrl, has: [markdownRequest], missing: [markdownOutranked], headers: { 'Content-Type': 'text/markdown; charset=utf-8', Vary: 'Accept', 'Content-Location': document.markdownUrl, Link: `${alternate}, ${resourceHeaders[document.markdownUrl].Link}` } });
+        routes.push({ src, dest: document.url === '/' ? '/index.html' : `${document.url}/index.html`, headers: { 'Content-Type': 'text/html; charset=utf-8', Vary: 'Accept', Link: alternate } });
+    }
+    const home = manifest.documents.find(item => item.url === basePath)?.url ?? homeUrl(manifest.documents);
+    if (!manifest.documents.some(item => item.url === '/') && home)
+        routes.push({ src: '^/$', status: 302, headers: { Location: `${home}/` } });
+    if (basePath && !manifest.documents.some(item => item.url === basePath) && home)
+        routes.push({ src: `^${exact(basePath)}/?$`, status: 302, headers: { Location: `${home}/` } });
+    for (const redirect of manifest.redirects) {
+        routes.push({ src: `^${exact(redirect.from)}/?$`, status: redirect.status, headers: { Location: redirect.to } });
+        routes.push({ src: `^${exact(redirect.markdownFrom)}$`, status: redirect.status, headers: { Location: redirect.markdownTo } });
+    }
+    for (const document of manifest.documents) {
+        routes.push({ src: `^${exact(document.markdownUrl)}$`, headers: resourceHeaders[document.markdownUrl], continue: true });
+    }
+    for (const [url, headers] of Object.entries(resourceHeaders)) {
+        if (headers['Cache-Control'] && !manifest.documents.some(document => document.markdownUrl === url))
+            routes.push({ src: `^${exact(url)}$`, headers, continue: true });
+    }
+    for (const extension of ['html', 'md']) {
+        const route = `${basePath}/404.${extension}`;
+        routes.push({ src: `^${exact(route)}$`, headers: resourceHeaders[route], continue: true });
+    }
+    const overrides = Object.fromEntries(Object.entries(resourceHeaders).filter(([route, value]) => value['Content-Type'] && !manifest.documents.some(document => document.url === route)).map(([route, value]) => [route.slice(1), { contentType: value['Content-Type'] }]));
+    await mkdir(output, { recursive: true });
+    const recoveryHeaders = { 'X-Robots-Tag': 'noindex' };
+    const fallbacks = [
+        ...manifest.documents.map(document => ({
+            src: `^${exact(document.markdownUrl)}$`, dest: `${basePath}/404.md`, status: 404,
+            headers: { ...recoveryHeaders, 'Content-Type': 'text/markdown; charset=utf-8', Link: `<${document.url}>; rel="alternate"; type="text/html"` }
+        })),
+        { src: '^/.*\\.md$', dest: `${basePath}/404.md`, status: 404, headers: { ...recoveryHeaders, 'Content-Type': 'text/markdown; charset=utf-8' } },
+        { src: '^/.*$', dest: `${basePath}/404.md`, status: 404, has: [markdownRequest], missing: [markdownOutranked], headers: { ...recoveryHeaders, 'Content-Type': 'text/markdown; charset=utf-8', Vary: 'Accept' } },
+        { src: '^/.*$', dest: `${basePath}/404.html`, status: 404, headers: { ...recoveryHeaders, 'Content-Type': 'text/html; charset=utf-8', Vary: 'Accept' } }
+    ];
+    await writeFile(path.join(output, 'config.json'), JSON.stringify({ version: 3, routes: [...routes, { handle: 'filesystem' }, ...fallbacks], overrides }, null, 2) + '\n');
+    // The optional answer function. It goes in only when asked for, and a site that cannot support it still builds.
+    const chat = options.chat ? await addAskFunction({ configFile, staticDirectory, functionsDirectory, basePath }) : undefined;
+    const currentFunctions = path.join(functionsDirectory, basePath.slice(1), '__shoalrun');
+    const keep = chat?.added ? new Set(['ask.func', 'search.func'].map(name => path.join(currentFunctions, name))) : undefined;
+    await removeStaleFunctions(functionsDirectory, keep);
+    await removeStaleMcpFunctions(functionsDirectory, mcp.added ? mcp.directory : undefined);
+    return { documents: manifest.documents.length, output, ...(chat ? { chat } : {}), ...(mcp.added ? { mcp } : {}) };
+}

package/dist/walkthrough.d.ts

@@ -0,0 +1,25 @@
+export type WalkthroughStep = {
+    type: 'docWalkthroughStep';
+    title: string;
+    highlight: number[];
+    children: any[];
+};
+export type WalkthroughNode = {
+    type: 'docWalkthrough';
+    id: string;
+    title: string;
+    mode: 'separate' | 'unified';
+    layout: 'scroll' | 'spotlight';
+    code?: any;
+    sources: string[];
+    children: WalkthroughStep[];
+};
+export declare function parseLineRanges(value: string, lines: number, where: string): number[];
+export declare function walkthroughComponent(node: any, sourceFile: string, documentId: string, index: number, childrenOf: (nodes: any[]) => any[], projectRoot?: string): WalkthroughNode;
+export declare function walkthroughMarkdown(node: WalkthroughNode, walk: (node: any) => any[], helpers: {
+    heading: (depth: number, value: string) => any;
+    paragraph: (...children: any[]) => any;
+    text: (value: string) => any;
+}): any[];
+export declare function walkthroughHtml(node: WalkthroughNode, walk: (node: any) => any[], element: (name: string, properties: Record<string, unknown>, children: any[]) => any, text: (value: string) => any): any[];
+export declare function walkthroughCode(): (tree: any) => void;

package/dist/walkthrough.js

@@ -0,0 +1,336 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+const stepCode = (step) => step.children.at(-1)?.type === 'code' ? step.children.at(-1) : undefined;
+const stepBody = (step) => stepCode(step) ? step.children.slice(0, -1) : step.children;
+const lineCount = (value) => value.split(/\r\n|\r|\n/).length;
+// "1-3,5" becomes [1, 2, 3, 5].
+export function parseLineRanges(value, lines, where) {
+    const result = new Set();
+    for (const part of value.split(',').map(item => item.trim())) {
+        const match = /^(\d+)(?:-(\d+))?$/.exec(part);
+        if (!match)
+            throw new Error(`${where}: highlight must list lines or ranges, such as 1-3,5`);
+        const start = Number(match[1]);
+        const end = Number(match[2] ?? match[1]);
+        if (start < 1 || end < start)
+            throw new Error(`${where}: highlight range ${part} is reversed or starts before line 1`);
+        if (end > lines)
+            throw new Error(`${where}: highlight range ${part} is past the end of the ${lines}-line code`);
+        for (let line = start; line <= end; line++)
+            result.add(line);
+    }
+    return [...result].sort((a, b) => a - b);
+}
+const languages = {
+    ts: 'typescript', mts: 'typescript', cts: 'typescript', tsx: 'typescript', js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+    py: 'python', rb: 'ruby', go: 'go', rs: 'rust', java: 'java', cs: 'csharp', php: 'php', sh: 'bash', bash: 'bash', zsh: 'bash',
+    yaml: 'yaml', yml: 'yaml', json: 'json', html: 'html', css: 'css', sql: 'sql', xml: 'xml', md: 'markdown', mdx: 'mdx', http: 'http'
+};
+// Code can come from a project file instead of a fence, so a walkthrough shows the same code the project tests.
+// `region` takes the lines between `#region name` and `#endregion` comments; `lines` takes a fixed range.
+function sourceCode(attributes, sourceFile, where, projectRoot) {
+    const { file: source, lines, region, lang } = attributes;
+    if (source === undefined) {
+        if (lines !== undefined || region !== undefined || lang !== undefined)
+            throw new Error(`${where}: lines, region, and lang need a file attribute`);
+        return undefined;
+    }
+    if (!source || path.isAbsolute(source) || /^[a-z][a-z0-9+.-]*:/i.test(source))
+        throw new Error(`${where}: file must be a path relative to the page`);
+    if (lines !== undefined && region !== undefined)
+        throw new Error(`${where}: use lines or region, not both`);
+    const file = path.resolve(path.dirname(sourceFile), source);
+    let real;
+    try {
+        real = realpathSync(file);
+    }
+    catch {
+        throw new Error(`${where}: code file not found: ${file}`);
+    }
+    const boundary = sourceBoundary(sourceFile, projectRoot);
+    const relative = path.relative(boundary, real);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        throw new Error(`${where}: file ${source} is outside ${boundary}; code files must be in the page's Git repository or project directory`);
+    let text;
+    try {
+        text = readFileSync(real, 'utf8');
+    }
+    catch {
+        throw new Error(`${where}: code file not readable: ${file}`);
+    }
+    let all = text.replace(/\r\n?/g, '\n').replace(/\n$/, '').split('\n');
+    if (lines !== undefined) {
+        const match = /^(\d+)-(\d+)$/.exec(lines);
+        if (!match || Number(match[1]) < 1 || Number(match[2]) < Number(match[1]))
+            throw new Error(`${where}: lines must be one range, such as 12-30`);
+        if (Number(match[2]) > all.length)
+            throw new Error(`${where}: lines ${lines} is past the end of the ${all.length}-line file ${source}`);
+        all = all.slice(Number(match[1]) - 1, Number(match[2]));
+    }
+    if (region !== undefined) {
+        if (!region)
+            throw new Error(`${where}: region needs a name`);
+        const found = regions(all, source, where).get(region);
+        if (!found)
+            throw new Error(`${where}: no "#region ${region}" comment in ${source}`);
+        all = all.slice(found.start + 1, found.end).filter(line => !marker(line));
+        const indent = Math.min(...all.filter(line => line.trim()).map(line => /^\s*/.exec(line)[0].length));
+        if (Number.isFinite(indent))
+            all = all.map(line => line.slice(indent));
+    }
+    if (!all.some(line => line.trim()))
+        throw new Error(`${where}: the code taken from ${source} is empty`);
+    const language = lang ?? languages[path.extname(file).slice(1).toLowerCase()];
+    if (!language)
+        throw new Error(`${where}: set lang for ${source}; its extension doesn't name a language`);
+    return { code: { type: 'code', lang: language, meta: `filename="${path.basename(file)}"`, value: all.join('\n') }, file };
+}
+// Region comments such as `// #region name`, `# region name`, or `<!-- #endregion name -->` start their line,
+// after an optional comment opener, so a `#region` inside code or a URL is not a marker. The name is the first
+// word; text after it, such as `: what this does`, is a description. An end marker may repeat its region's name.
+const marker = (line) => {
+    const match = /^\s*(?:\/\/+|\/\*+|<!--|--|;+|')?\s*#\s?(end)?region\b\s*([^\s:]*)/.exec(line);
+    return match ? { end: !!match[1], name: match[2].replace(/(?:-->|\*\/)$/, '') || undefined } : undefined;
+};
+// Pair every region marker in the file, so a stray or mismatched marker fails the build instead of cutting a
+// region short.
+function regions(lines, source, where) {
+    const found = new Map();
+    const open = [];
+    lines.forEach((line, at) => {
+        const item = marker(line);
+        if (!item)
+            return;
+        const number = at + 1;
+        if (!item.end) {
+            if (!item.name)
+                throw new Error(`${where}: #region at line ${number} of ${source} needs a name`);
+            if (found.has(item.name) || open.some(entry => entry.name === item.name))
+                throw new Error(`${where}: region ${item.name} appears twice in ${source}; give each region its own name`);
+            open.push({ name: item.name, start: at });
+            return;
+        }
+        const current = open.pop();
+        if (!current)
+            throw new Error(`${where}: #endregion at line ${number} of ${source} has no matching #region`);
+        if (item.name && item.name !== current.name)
+            throw new Error(`${where}: #endregion ${item.name} at line ${number} of ${source} closes region ${current.name}`);
+        found.set(current.name, { start: current.start, end: at });
+    });
+    const unclosed = open.pop();
+    if (unclosed)
+        throw new Error(`${where}: region ${unclosed.name} at line ${unclosed.start + 1} of ${source} has no #endregion`);
+    return found;
+}
+// A page may read code from anywhere in its Git repository, so docs can show code that lives beside them, but
+// never from outside it: a docs change must not publish other files from the build machine. Outside a
+// repository, the project directory is the limit.
+function sourceBoundary(sourceFile, projectRoot) {
+    for (let directory = path.dirname(sourceFile);; directory = path.dirname(directory)) {
+        if (existsSync(path.join(directory, '.git')))
+            return realpathSync(directory);
+        if (path.dirname(directory) === directory)
+            return realpathSync(projectRoot ?? path.dirname(sourceFile));
+    }
+}
+const formatRanges = (lines) => {
+    const label = lines.length === 1 ? 'Line' : 'Lines';
+    const parts = [];
+    for (let index = 0; index < lines.length; index++) {
+        const start = lines[index];
+        while (lines[index + 1] === lines[index] + 1)
+            index++;
+        parts.push(start === lines[index] ? String(start) : `${start}–${lines[index]}`);
+    }
+    return `${label} ${parts.join(', ')}`;
+};
+export function walkthroughComponent(node, sourceFile, documentId, index, childrenOf, projectRoot) {
+    const literal = (element, allowed) => {
+        const attributes = element.attributes ?? [];
+        if (attributes.some((item) => item.type !== 'mdxJsxAttribute' || !allowed.includes(item.name) || typeof item.value !== 'string') || new Set(attributes.map((item) => item.name)).size !== attributes.length)
+            throw new Error(`${sourceFile}: <${element.name}> only accepts literal ${allowed.join(' and ')} attributes`);
+        return Object.fromEntries(attributes.map((item) => [item.name, item.value.trim()]));
+    };
+    if (node.type !== 'mdxJsxFlowElement')
+        throw new Error(`${sourceFile}: <Walkthrough> must be a block on its own lines`);
+    const settings = literal(node, ['title', 'layout', 'file', 'lines', 'region', 'lang']);
+    const { title } = settings;
+    if (!title)
+        throw new Error(`${sourceFile}: <Walkthrough> needs a nonempty title`);
+    const layout = settings.layout ?? 'scroll';
+    if (layout !== 'scroll' && layout !== 'spotlight')
+        throw new Error(`${sourceFile}: <Walkthrough> layout must be scroll or spotlight`);
+    const sources = [];
+    const children = node.children ?? [];
+    const fence = children[0]?.type === 'code' ? children[0] : undefined;
+    const shared = sourceCode(settings, sourceFile, `${sourceFile}: <Walkthrough>`, projectRoot);
+    if (shared && fence)
+        throw new Error(`${sourceFile}: <Walkthrough> takes its shared code from a file or a code fence, not both`);
+    if (shared)
+        sources.push(shared.file);
+    const code = shared?.code ?? fence;
+    const stepNodes = fence ? children.slice(1) : children;
+    if (stepNodes.some((child) => child.type !== 'mdxJsxFlowElement' || child.name !== 'Step'))
+        throw new Error(`${sourceFile}: <Walkthrough> accepts one optional code fence followed by <Step> children`);
+    if (stepNodes.length < 2)
+        throw new Error(`${sourceFile}: <Walkthrough> needs at least two steps`);
+    const steps = stepNodes.map((step, at) => {
+        const where = `${sourceFile}: <Step> ${at + 1}`;
+        const attributes = literal(step, ['title', 'highlight', 'file', 'lines', 'region', 'lang']);
+        if (!attributes.title)
+            throw new Error(`${where} needs a nonempty title`);
+        const body = childrenOf(step.children ?? []);
+        const included = sourceCode(attributes, sourceFile, where, projectRoot);
+        if (included && body.some(child => child.type === 'code'))
+            throw new Error(`${where} takes its code from a file or a code fence, not both`);
+        if (included) {
+            sources.push(included.file);
+            body.push(included.code);
+        }
+        const codes = body.filter(child => child.type === 'code');
+        if (code && codes.length)
+            throw new Error(`${where}: steps cannot add code when the walkthrough shares one code fence`);
+        if (codes.length > 1)
+            throw new Error(`${where} can contain one code fence`);
+        if (codes.length && body.at(-1) !== codes[0])
+            throw new Error(`${where}: put the code fence after the step's explanation`);
+        const shown = code ?? codes[0];
+        if (attributes.highlight !== undefined && !shown)
+            throw new Error(`${where}: highlight needs code to highlight`);
+        const highlight = attributes.highlight === undefined ? [] : parseLineRanges(attributes.highlight, lineCount(shown.value), where);
+        if (!body.some(child => child.type !== 'code'))
+            throw new Error(`${where} needs an explanation`);
+        return { type: 'docWalkthroughStep', title: attributes.title, highlight, children: body };
+    });
+    const id = `walk-${createHash('sha256').update(`${documentId}|${index}`).digest('hex').slice(0, 10)}`;
+    return { type: 'docWalkthrough', id, title, mode: code ? 'unified' : 'separate', layout, code, sources, children: steps };
+}
+// Markdown keeps every step as a section; unified steps repeat the lines they explain so an agent can quote them.
+export function walkthroughMarkdown(node, walk, helpers) {
+    const { heading, paragraph, text } = helpers;
+    const lines = node.code?.value.split(/\r\n|\r|\n/) ?? [];
+    return [
+        paragraph({ type: 'strong', children: [text(`Walkthrough: ${node.title}`)] }),
+        ...(node.code ? [node.code] : []),
+        ...node.children.flatMap((step, index) => [
+            heading(3, `Step ${index + 1}: ${step.title}`),
+            ...stepBody(step).flatMap(walk),
+            ...(node.code && step.highlight.length ? [
+                paragraph(text(`${formatRanges(step.highlight)}:`)),
+                { type: 'code', lang: node.code.lang, value: step.highlight.map(line => lines[line - 1]).join('\n') }
+            ] : []),
+            ...(stepCode(step) ? [stepCode(step)] : [])
+        ])
+    ];
+}
+export function walkthroughHtml(node, walk, element, text) {
+    const codeBox = (code, highlight) => element('div', { className: ['walkthrough-code'], ...(highlight.length ? { 'data-highlight': highlight.join(' ') } : {}) }, [code]);
+    const steps = node.children.map((step, index) => element('li', {
+        id: `${node.id}-step-${index + 1}`, className: ['walkthrough-step'],
+        ...(node.mode === 'unified' && step.highlight.length ? { 'data-highlight': step.highlight.join(' ') } : {})
+    }, [
+        element('h3', { className: ['walkthrough-step-title'] }, [element('span', { className: ['walkthrough-step-number'] }, [text(`Step ${index + 1}`)]), text(' '), text(step.title)]),
+        ...stepBody(step).flatMap(walk),
+        ...(node.mode === 'unified' && step.highlight.length ? [element('p', { className: ['walkthrough-lines'] }, [text(formatRanges(step.highlight))])] : []),
+        ...(stepCode(step) ? [codeBox(stepCode(step), step.highlight)] : [])
+    ]));
+    return [element('section', { className: ['walkthrough'], id: node.id, 'data-walkthrough': '', 'data-mode': node.mode, 'data-layout': node.layout, 'aria-label': node.title }, [
+            element('p', { className: ['walkthrough-title'] }, [text(node.title)]),
+            ...(node.code ? [codeBox(node.code, [])] : []),
+            element('ol', { className: ['walkthrough-steps'] }, steps)
+        ])];
+}
+const hasClass = (node, name) => [node.properties?.className].flat().includes(name);
+const textOf = (node) => node.type === 'text' ? node.value : (node.children ?? []).map(textOf).join('');
+function pieces(code) {
+    const result = [];
+    for (const child of code.children ?? []) {
+        const style = child.type === 'element' ? child.properties?.style : undefined;
+        // Finer pieces make movement read as code shifting rather than whole lines fading.
+        for (const part of textOf(child).match(/\r\n|\r|\n|[^\S\r\n]+|\w+|[^\w\s]/g) ?? [])
+            result.push({ text: part, style });
+    }
+    return result;
+}
+// Longest common subsequence of token text; returns pairs of matching indexes.
+function matches(before, after) {
+    if (before.length * after.length > 2_000_000)
+        return [];
+    const table = Array.from({ length: before.length + 1 }, () => new Uint32Array(after.length + 1));
+    for (let i = before.length - 1; i >= 0; i--)
+        for (let j = after.length - 1; j >= 0; j--) {
+            table[i][j] = before[i] === after[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    const pairs = [];
+    for (let i = 0, j = 0; i < before.length && j < after.length;) {
+        if (before[i] === after[j]) {
+            pairs.push([i, j]);
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return pairs;
+}
+export function walkthroughCode() {
+    return (tree) => {
+        const visit = (node) => {
+            if (node.type === 'element' && hasClass(node, 'walkthrough'))
+                return keyWalkthrough(node);
+            node.children?.forEach(visit);
+        };
+        visit(tree);
+    };
+}
+function keyWalkthrough(root) {
+    const boxes = [];
+    const collect = (node) => {
+        if (node.type === 'element' && hasClass(node, 'walkthrough-code'))
+            boxes.push(node);
+        else
+            node.children?.forEach(collect);
+    };
+    collect(root);
+    let next = 0;
+    let previous;
+    for (const box of boxes) {
+        const pre = (function find(node) { return node.tagName === 'pre' ? node : (node.children ?? []).map(find).find(Boolean); })(box);
+        const code = pre?.children?.find((child) => child.tagName === 'code');
+        if (!code)
+            continue;
+        const highlighted = new Set(String(box.properties?.dataHighlight ?? box.properties?.['data-highlight'] ?? '').split(' ').filter(Boolean).map(Number));
+        const all = pieces(code);
+        const visible = all.filter(piece => piece.text.trim());
+        const texts = visible.map(piece => piece.text);
+        const keys = new Array(texts.length);
+        if (previous)
+            for (const [from, to] of matches(previous.texts, texts))
+                keys[to] = previous.keys[from];
+        for (let index = 0; index < keys.length; index++)
+            keys[index] ??= `k${(next++).toString(36)}`;
+        previous = { texts, keys };
+        let visibleIndex = 0;
+        const lines = [[]];
+        for (const piece of all) {
+            if (/^(?:\r\n|\r|\n)$/.test(piece.text)) {
+                lines.push([]);
+                continue;
+            }
+            if (!piece.text.trim()) {
+                lines.at(-1).push({ type: 'text', value: piece.text });
+                continue;
+            }
+            lines.at(-1).push({ type: 'element', tagName: 'span', properties: { ...(piece.style ? { style: piece.style } : {}), dataK: keys[visibleIndex++] }, children: [{ type: 'text', value: piece.text }] });
+        }
+        code.children = lines.flatMap((line, index) => [
+            ...(index ? [{ type: 'text', value: '\n' }] : []),
+            { type: 'element', tagName: 'span', properties: { className: ['line', ...(highlighted.has(index + 1) ? ['is-highlighted'] : [])] }, children: line }
+        ]);
+        if (highlighted.size)
+            pre.properties = { ...pre.properties, dataFocus: '' };
+    }
+}

package/dist/yaml-value.d.ts

@@ -0,0 +1,2 @@
+/** YAML inputs must represent finite data; recursive OpenAPI schemas use $ref. */
+export declare function parseYaml(source: string, file: string): any;

package/dist/yaml-value.js

@@ -0,0 +1,36 @@
+import YAML from 'yaml';
+/** YAML inputs must represent finite data; recursive OpenAPI schemas use $ref. */
+export function parseYaml(source, file) {
+    const document = YAML.parseDocument(source, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new Error(`${file}: ${document.errors.map(error => error.message).join('; ')}`);
+    let value;
+    try {
+        value = document.toJS();
+    }
+    catch (error) {
+        throw new Error(`${file}: ${error.message}`);
+    }
+    const active = new WeakSet();
+    const finished = new WeakSet();
+    const pending = [{ value, at: '#' }];
+    while (pending.length) {
+        const item = pending.pop();
+        if (!item.value || typeof item.value !== 'object')
+            continue;
+        if (item.exit) {
+            active.delete(item.value);
+            finished.add(item.value);
+            continue;
+        }
+        if (active.has(item.value))
+            throw new Error(`${file}: Cyclic YAML alias at ${item.at}. Replace the cycle with finite values; recursive OpenAPI schemas should use $ref.`);
+        if (finished.has(item.value))
+            continue;
+        active.add(item.value);
+        pending.push({ ...item, exit: true });
+        for (const [key, child] of Object.entries(item.value))
+            pending.push({ value: child, at: `${item.at}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}` });
+    }
+    return value;
+}

package/example-configs/api-docs/README.md

@@ -0,0 +1,59 @@
+# Cedar Parcel API documentation starter
+
+This fictional parcel API uses the same OpenAPI source as the Shoalrun docs site's reference styling lab. It includes an overview, enrollment quickstart, generated references, search, system color mode, and linked reading paths.
+
+## Preview your site
+
+With the Shoalrun CLI installed, run these commands from this directory:
+
+```sh
+shoalrun config validate docs.config.yaml
+shoalrun dev docs.config.yaml site-dist --port 8772
+```
+
+Open `http://127.0.0.1:8772/`. Editing a page or config rebuilds the preview. The CLI retains the last successful build if a change fails.
+
+The development server builds the site before serving it. To inspect a fixed build instead, run `shoalrun build docs.config.yaml site-dist`, then `shoalrun serve site-dist --port 8772`.
+
+## Make it yours
+
+1. Change the title, header, footer, and `site.origin` in `docs.config.yaml`. Set the origin to the site's public URL before deployment.
+2. If you keep the Cedar example, customize its descriptions and examples together with the authored pages. Replace the fictional server URLs before sending requests. To use a different API, follow **Bring your own API** below; replacing the file alone is not enough.
+3. Update the authored pages in `content/`. Stable document IDs connect cards, navigation, and related reading. Keep their operation bindings consistent with `apis.cedar.operations`.
+4. Review the API content for public release. Run `shoalrun api review docs.config.yaml --output review`, inspect the candidate, and update `apis.cedar.publicReview.digest` with the reported digest when API content changes.
+5. Build again and inspect the overview, quickstart, and generated reference pages. Search for a field and try the color-mode toggle.
+
+## Bring your own API
+
+For a first import, start with `shoalrun init my-api-docs --starter minimal` and follow [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references). That guide supplies a complete small example: a local spec, operation registration, an authored reference, navigation, source review, and checks for both outputs. You can read the version bundled with your CLI using `shoalrun docs read guide.api-references`.
+
+To adapt this Cedar demo instead, update these connected parts before running the review:
+
+- Replace the source file and update its `source.path` if the filename changes. Remove the old `publicReview.digest`; it approves the Cedar source, not your replacement.
+- Replace `apis.cedar.operations` entries with operations from your spec. Each `sourceOperationId` must exist in that spec. Update the corresponding page's `operations` list and the registry's `reference` page ID together.
+- Update navigation operation IDs, authored API embeds, document links, related-reading relationships, header links, and footer links. Rewrite or remove the Cedar-specific guides and reference page as a connected set.
+- Update or remove `mappings`, `querySyntax`, and `discovery.endpoint` when they do not describe your API. Review `generateReferences` and whether publishing the complete source with `source.publish: true` is appropriate.
+
+Then run `shoalrun api review docs.config.yaml --output review`, inspect the candidate's HTML, Markdown, and contracts, and record the new digest. Rebuild and run `shoalrun api focused-audit site-dist`. A `Missing OpenAPI operationId createEnrollment` error means a Cedar operation binding still points into your replacement spec.
+
+## Explore the reference features
+
+The enrollment reference includes four request shapes, shared nested objects, required fields, nullable values, and four named examples. Parcel search includes direct field/operator filters and JSON, CSV, and spreadsheet responses. Other operations demonstrate a separate lookup server, binary manifest uploads, a deprecated route, and a delivery webhook with alternative proof shapes.
+
+The config maps OpenAPI lifecycle extensions to status badges and defines the direct-query syntax used by parcel search. Enrollment uses an application key; the parcel lookup has no authentication. The generated references describe the security rules for each operation.
+
+## Agent discovery
+
+Every page has a Markdown twin and a **Read as Markdown** link. `/llms.txt` indexes the site, and `/documents.json` provides the document inventory. API references link to focused contracts containing one operation. The complete OpenAPI source and API catalog are also published.
+
+`site.agentDiscovery` configures the early HTML instruction. `mode: focus` visually reveals it on keyboard focus; `visible` always shows it; `off` omits the block. Raw HTML agents and screen readers can encounter it in both `focus` and `visible` modes. The standard accessibility skip link and discovery files remain available in every mode.
+
+## Deploy
+
+Build Vercel routing and headers with:
+
+```sh
+shoalrun vercel build docs.config.yaml .vercel/output
+```
+
+Deploy the complete Build Output API directory using your Vercel project. A plain static folder upload does not apply the Markdown negotiation rules. See [Vercel hosting](https://www.shoalrun.com/publish/vercel/) for deployment instructions.