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

package/dist/palettes.js

@@ -0,0 +1,160 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+// Palette tokens are written without the --color- prefix. Every palette defines all of them for both modes.
+export const paletteTokens = [
+    'text', 'page', 'surface', 'link', 'link-hover', 'focus', 'ink', 'accent', 'accent-contrast',
+    'header-muted', 'header-border', 'border', 'border-soft', 'border-nested',
+    'field-surface', 'field-border', 'field-accent',
+    'presence-bg', 'presence-text', 'optional-bg', 'optional-text',
+    'muted', 'nav-heading', 'section-heading', 'nav-text', 'nav-hover', 'nav-active', 'nav-active-text',
+    'deprecated-bg', 'deprecated-text', 'beta-bg', 'beta-text', 'development-bg', 'development-text', 'experimental-bg', 'experimental-text',
+    'emphasis', 'summary', 'code-bg', 'code-text', 'code-muted', 'code-border', 'code-block',
+    'callout-line', 'callout-bg',
+    ...['note', 'tip', 'important', 'warning', 'caution'].flatMap(tone => [`callout-${tone}-line`, `callout-${tone}-bg`, `callout-${tone}-text`]),
+    'strong-surface', 'strong-text'
+];
+// One catalog feeds config validation, the theme previewer, and its Markdown fallback.
+export const presetCatalog = [
+    { name: 'shoal', palette: 'kelp', shape: 'Flat page with a ruled sidebar and square-cornered controls.' },
+    { name: 'reef', palette: 'coral', shape: 'Rounded panels on a tinted page, with pill navigation and controls.' },
+    { name: 'ledger', palette: 'ink', masthead: 'inked', shape: 'Technical manual with an inked masthead, monospace headings, and numbered sections.' },
+    { name: 'vice', palette: 'vice', masthead: 'inked', shape: 'Night masthead with a sunset stripe, bold italic type, and neon rules.' }
+];
+export const paletteCatalog = [
+    { name: 'kelp', colors: 'Sea green on white.' },
+    { name: 'coral', colors: 'Coral accent over cool blue-gray neutrals.' },
+    { name: 'ink', colors: 'Black ink on warm paper with a vermilion accent.' },
+    { name: 'harbor', colors: 'Navy ink, blue links, and a yellow callout rule.' },
+    { name: 'amethyst', colors: 'Violet accents over lavender neutrals.' },
+    { name: 'vice', colors: 'Flamingo pink and aqua by day, neon on night purple after dark.' }
+];
+export const paletteNames = paletteCatalog.map(palette => palette.name);
+const paletteDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../styles/themes/palettes');
+const hex = /^#(?:[\da-f]{3}|[\da-f]{6})$/i;
+// WCAG 2.2 pairs: 1.4.3 needs 4.5:1 for text; 1.4.11 needs 3:1 for focus rings, field boundaries, and filled controls.
+export const contrastPairs = [
+    ...['page', 'surface', 'field-surface'].flatMap(bg => ['text', 'muted', 'link', 'ink', 'emphasis', 'section-heading', 'nav-text', 'nav-heading', 'summary', 'header-muted'].map(fg => [fg, bg, 4.5])),
+    ['link-hover', 'page', 4.5], ['link-hover', 'surface', 4.5], ['nav-text', 'nav-hover', 4.5], ['ink', 'nav-hover', 4.5],
+    ['muted', 'code-bg', 4.5],
+    ['text', 'callout-bg', 4.5], ['link', 'callout-bg', 4.5], ['text', 'code-bg', 4.5],
+    ['nav-active-text', 'nav-active', 4.5], ['presence-text', 'presence-bg', 4.5], ['optional-text', 'optional-bg', 4.5],
+    ['deprecated-text', 'deprecated-bg', 4.5], ['beta-text', 'beta-bg', 4.5], ['development-text', 'development-bg', 4.5], ['experimental-text', 'experimental-bg', 4.5],
+    // Typed callouts: body text and links on the tinted background, and the label and icon in the tone's text color.
+    ...['note', 'tip', 'important', 'warning', 'caution'].flatMap(tone => ['text', 'link', `callout-${tone}-text`].map(fg => [fg, `callout-${tone}-bg`, 4.5])),
+    ['code-text', 'code-block', 4.5], ['code-muted', 'code-block', 4.5], ['accent-contrast', 'accent', 4.5], ['strong-text', 'strong-surface', 4.5],
+    ['focus', 'page', 3], ['focus', 'surface', 3], ['field-border', 'page', 3], ['field-border', 'surface', 3], ['field-border', 'field-surface', 3],
+    ['accent', 'page', 3], ['accent', 'surface', 3]
+];
+const channel = (value) => { const c = value / 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+// Accepts #rgb, #rgba, #rrggbb, and #rrggbbaa. A translucent color is blended over `under` before measuring.
+function rgb(color, under = '#ffffff') {
+    const digits = color.slice(1);
+    const full = digits.length <= 4 ? [...digits].map(c => c + c).join('') : digits;
+    const [r, g, b, a = 255] = [0, 2, 4, 6].map(i => i < full.length ? parseInt(full.slice(i, i + 2), 16) : undefined).filter((value) => value !== undefined);
+    if (a === 255)
+        return [r, g, b];
+    const base = rgb(under);
+    return [r, g, b].map((value, index) => value * (a / 255) + base[index] * (1 - a / 255));
+}
+function luminance(channels) {
+    const [r, g, b] = channels.map(channel);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export function contrast(foreground, background, backdrop = '#ffffff') {
+    const solidBackground = rgb(background, backdrop);
+    const solidHex = `#${solidBackground.map(value => Math.round(value).toString(16).padStart(2, '0')).join('')}`;
+    const [high, low] = [luminance(rgb(foreground, solidHex)), luminance(solidBackground)].sort((x, y) => y - x);
+    return (high + 0.05) / (low + 0.05);
+}
+function tokenMap(value, where, complete) {
+    if (value === undefined && !complete)
+        return {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${where} must be a mapping of color tokens`);
+    const map = {};
+    for (const [key, color] of Object.entries(value)) {
+        if (!paletteTokens.includes(key))
+            throw new Error(`${where}.${key} is not a palette token. Use one of: ${paletteTokens.join(', ')}`);
+        if (typeof color !== 'string' || !hex.test(color))
+            throw new Error(`${where}.${key} must be a hex color such as "#1b5fd1"`);
+        map[key] = color.toLowerCase();
+    }
+    if (complete) {
+        const missing = paletteTokens.filter(token => !map[token]);
+        if (missing.length)
+            throw new Error(`${where} is missing ${missing.join(', ')}`);
+    }
+    return map;
+}
+async function builtIn(name) {
+    const file = path.join(paletteDirectory, `${name}.yaml`);
+    const parsed = YAML.parse(await readFile(file, 'utf8'));
+    return { name, light: tokenMap(parsed?.light, `${name}.light`, true), dark: tokenMap(parsed?.dark, `${name}.dark`, true), files: [file] };
+}
+// A palette setting is a built-in name, or { extends, light, dark } with partial overrides.
+export async function resolvePalette(value, fallback) {
+    if (value === undefined || typeof value === 'string') {
+        const name = value ?? fallback;
+        if (!paletteNames.includes(name))
+            throw new Error(`theme.palette must be one of ${paletteNames.join(', ')}, or a mapping with extends, light, and dark`);
+        return builtIn(name);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('theme.palette must be a palette name or a mapping');
+    const { extends: base = fallback, light, dark, ...extra } = value;
+    if (Object.keys(extra).length)
+        throw new Error(`theme.palette does not accept ${Object.keys(extra).join(', ')}`);
+    if (typeof base !== 'string' || !paletteNames.includes(base))
+        throw new Error(`theme.palette.extends must be one of ${paletteNames.join(', ')}`);
+    const parent = await builtIn(base);
+    return {
+        name: 'custom',
+        light: { ...parent.light, ...tokenMap(light, 'theme.palette.light', false) },
+        dark: { ...parent.dark, ...tokenMap(dark, 'theme.palette.dark', false) },
+        files: parent.files
+    };
+}
+export function contrastProblems(palette, modes) {
+    return modes.flatMap(mode => contrastPairs.flatMap(([fg, bg, minimum]) => {
+        const ratio = contrast(palette[mode][fg], palette[mode][bg]);
+        return ratio + 1e-9 < minimum ? [`${mode}: ${fg} ${palette[mode][fg]} on ${bg} ${palette[mode][bg]} is ${ratio.toFixed(2)}:1; needs ${minimum}:1`] : [];
+    }));
+}
+// Custom callout tones sit on the page, so check body text, links, and the tone's label against its background.
+export function calloutToneProblems(tones, palette, modes) {
+    return [...tones].flatMap(([name, tone]) => modes.flatMap(mode => {
+        const colors = mode === 'dark' ? tone.dark : tone;
+        if (!colors)
+            return [`callouts.tones.${name} needs dark colors because the site shows dark mode. Add callouts.tones.${name}.dark with line, background, and text.`];
+        const page = palette[mode].page;
+        return [['text', palette[mode].text], ['link', palette[mode].link], ['label text', colors.text]].flatMap(([role, foreground]) => {
+            const ratio = contrast(foreground, colors.background, page);
+            return ratio + 1e-9 < 4.5 ? [`callouts.tones.${name} ${mode}: ${role} ${foreground} on background ${colors.background} is ${ratio.toFixed(2)}:1; needs 4.5:1`] : [];
+        });
+    }));
+}
+// Custom callout tones carry their dark colors inline; these rules switch to them wherever dark mode applies.
+const darkCallouts = '.content blockquote.callout[data-callout-dark]{--callout-line:var(--callout-dark-line)!important;--callout-bg:var(--callout-dark-bg)!important;--callout-text:var(--callout-dark-text)!important}';
+// Dark surfaces get a faint edge so panels, code, and cards stay distinct from the page.
+const edge = { light: '0 0 #0000', dark: '0 0 0 1px #ffffff0f,inset 0 1px 0 #ffffff0d' };
+const declarations = (tokens, mode) => `color-scheme:${mode};${paletteTokens.map(token => `--color-${token}:${tokens[token]}`).join(';')};--shadow-edge:${edge[mode]}`;
+// Code blocks are dark in both modes, so syntax colors come from the palette's dark set. A color that falls
+// below 4.5:1 on either mode's code background falls back to plain code text rather than failing the build.
+const syntaxSources = { keyword: 'accent', string: 'callout-tip-text', 'string-expression': 'callout-tip-text', constant: 'callout-warning-text', function: 'callout-note-text', parameter: 'callout-important-text', link: 'link' };
+export function syntaxColors(palette) {
+    return Object.fromEntries(Object.entries(syntaxSources).map(([role, token]) => {
+        const color = palette.dark[token];
+        const readable = ['light', 'dark'].every(mode => contrast(color, palette[mode]['code-block']) + 1e-9 >= 4.5);
+        return [role, readable ? color : 'var(--color-code-text)'];
+    }));
+}
+const syntaxCss = (palette) => `:root{${Object.entries(syntaxColors(palette)).map(([role, color]) => `--code-token-${role}:${color}`).join(';')}}`;
+// light and dark lock the site to one mode. system follows the reader's OS until they choose with the toggle.
+export function paletteCss(palette, mode) {
+    const blocks = mode === 'system'
+        ? [`:root{${declarations(palette.light, 'light')}}`, `@media (prefers-color-scheme:dark){:root:not([data-mode=light]){${declarations(palette.dark, 'dark')}}:root:not([data-mode=light]) ${darkCallouts}}`, `:root[data-mode=dark]{${declarations(palette.dark, 'dark')}}`, `:root[data-mode=dark] ${darkCallouts}`]
+        : [`:root{${declarations(palette[mode], mode)}}`, ...(mode === 'dark' ? [darkCallouts] : [])];
+    return `/* Generated from the ${palette.name} palette. */\n${blocks.join('\n')}\n${syntaxCss(palette)}\n.content pre,.examples pre,.code-block{background:var(--color-code-block)}\n`;
+}

package/dist/procedure-components.d.ts

@@ -0,0 +1,2 @@
+export declare function procedureComponent(node: any, sourceFile: string, transformChildren: (children: any[]) => any[]): any;
+export declare function procedureTree(node: any, representation: 'html' | 'markdown', walk: (node: any) => any[], element: (name: string, properties: Record<string, unknown>, children: any[]) => any, text: (value: string) => any, paragraph: (...children: any[]) => any): any[];

package/dist/procedure-components.js

@@ -0,0 +1,94 @@
+import { stepIcon, validateLucideIcon } from './icons.js';
+export function procedureComponent(node, sourceFile, transformChildren) {
+    const timeline = node.name === 'Timeline';
+    const container = timeline ? 'Timeline' : 'Steps';
+    const itemName = timeline ? 'Milestone' : 'Step';
+    const containerAttributes = node.attributes ?? [];
+    const allowedContainer = timeline ? ['current'] : ['variant', 'toc', 'headingLevel'];
+    if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || containerAttributes.some((attribute) => attribute.type !== 'mdxJsxAttribute' || !allowedContainer.includes(attribute.name) || typeof attribute.value !== 'string') || new Set(containerAttributes.map((attribute) => attribute.name)).size !== containerAttributes.length)
+        throw new Error(`${sourceFile}: <${container}> needs direct <${itemName}> children and supported literal attributes`);
+    const containerValue = (name) => containerAttributes.find((attribute) => attribute.name === name)?.value?.trim();
+    const variant = timeline ? undefined : containerValue('variant') ?? 'rail';
+    const toc = timeline ? undefined : containerValue('toc') ?? 'ignore';
+    const headingLevel = timeline ? undefined : Number(containerValue('headingLevel') ?? '2');
+    if (!timeline && !['rail', 'cards', 'plain'].includes(variant))
+        throw new Error(`${sourceFile}: <Steps> variant must be rail, cards, or plain`);
+    if (!timeline && !['include', 'ignore'].includes(toc))
+        throw new Error(`${sourceFile}: <Steps> toc must be include or ignore`);
+    if (!timeline && !['2', '3', '4', '5', '6'].includes(containerValue('headingLevel') ?? '2'))
+        throw new Error(`${sourceFile}: <Steps> headingLevel must be 2, 3, 4, 5, or 6`);
+    if (timeline && !containerValue('current'))
+        throw new Error(`${sourceFile}: <Timeline> needs a nonempty current milestone id`);
+    const directChildren = node.children.flatMap((child) => child.type === 'paragraph' ? child.children : [child]).filter((child) => child.type !== 'text' || child.value.trim());
+    const items = directChildren.map((item) => {
+        const attributes = item.attributes ?? [];
+        const allowed = timeline ? ['id', 'title', 'date'] : ['title', 'icon'];
+        if (!['mdxJsxFlowElement', 'mdxJsxTextElement'].includes(item.type) || item.name !== itemName || attributes.some((attribute) => attribute.type !== 'mdxJsxAttribute' || !allowed.includes(attribute.name) || typeof attribute.value !== 'string') || new Set(attributes.map((attribute) => attribute.name)).size !== attributes.length)
+            throw new Error(`${sourceFile}: <${container}> only accepts <${itemName}> with ${allowed.join(', ')} attributes`);
+        const value = (name) => attributes.find((attribute) => attribute.name === name)?.value?.trim();
+        const title = value('title');
+        if (!title)
+            throw new Error(`${sourceFile}: <${itemName}> needs a nonempty title`);
+        const id = timeline ? value('id') : undefined;
+        if (timeline && (!id || !/^[a-z][a-z0-9-]*$/.test(id)))
+            throw new Error(`${sourceFile}: <Milestone> id must use lowercase letters, numbers, and hyphens, starting with a letter`);
+        const date = timeline ? value('date') : undefined;
+        const icon = timeline ? undefined : value('icon');
+        if (icon)
+            validateLucideIcon(icon, sourceFile, 'Step icon');
+        if (date && (!/^\d{4}-\d{2}-\d{2}$/.test(date) || Number.isNaN(Date.parse(`${date}T00:00:00Z`)) || new Date(`${date}T00:00:00Z`).toISOString().slice(0, 10) !== date))
+            throw new Error(`${sourceFile}: <Milestone> date must be a real YYYY-MM-DD date`);
+        const transformed = transformChildren(item.children ?? []);
+        if (!transformed.length || transformed.every((child) => child.type === 'text' && !child.value.trim()))
+            throw new Error(`${sourceFile}: <${itemName}> needs body content`);
+        const children = item.type === 'mdxJsxTextElement' ? [{ type: 'paragraph', children: transformed }] : transformed;
+        return { title, ...(id ? { id } : {}), ...(date ? { date } : {}), ...(icon ? { icon } : {}), children };
+    });
+    if (timeline) {
+        const ids = items.map(item => item.id);
+        if (new Set(ids).size !== ids.length)
+            throw new Error(`${sourceFile}: <Timeline> milestone ids must be unique`);
+        const currentIndex = ids.indexOf(containerValue('current'));
+        if (currentIndex < 0)
+            throw new Error(`${sourceFile}: <Timeline> current must match a milestone id`);
+        return { type: 'docTimeline', currentIndex, items };
+    }
+    return { type: 'docSteps', variant, toc, headingLevel, items };
+}
+export function procedureTree(node, representation, walk, element, text, paragraph) {
+    const timeline = node.type === 'docTimeline';
+    if (representation === 'markdown') {
+        const summary = timeline ? [paragraph(text(`${node.currentIndex} of ${node.items.length} milestones complete. Current: ${node.items[node.currentIndex].title}.`))] : [];
+        return [...summary, { type: 'list', ordered: true, spread: true, children: node.items.map((item, index) => ({
+                    type: 'listItem', spread: true, children: [
+                        ...(timeline ? [paragraph({ type: 'strong', children: [text(`${index < node.currentIndex ? 'Complete' : index === node.currentIndex ? 'Current' : 'Upcoming'}: ${item.title}${item.date ? ` (${item.date})` : ''}`)] })] : [{ type: 'heading', depth: node.headingLevel, children: [text(item.title)] }]),
+                        ...item.children.flatMap(walk)
+                    ]
+                })) }];
+    }
+    if (timeline) {
+        const current = node.items[node.currentIndex];
+        const summary = `${node.currentIndex} of ${node.items.length} milestones complete · Current: ${current.title}`;
+        const items = node.items.map((item, index) => {
+            const status = index < node.currentIndex ? 'complete' : index === node.currentIndex ? 'current' : 'upcoming';
+            return element('li', { className: [`doc-milestone-${status}`], ...(status === 'current' ? { 'aria-current': 'step' } : {}) }, [
+                element('div', { className: ['doc-milestone-head'] }, [
+                    { type: 'strong', children: [text(item.title)] },
+                    element('span', { className: ['doc-milestone-status'] }, [text(status === 'complete' ? 'Complete' : status === 'current' ? 'Current' : 'Upcoming')]),
+                    ...(item.date ? [element('time', { dateTime: item.date }, [text(item.date)])] : [])
+                ]),
+                element('div', { className: ['doc-milestone-body'] }, item.children.flatMap(walk))
+            ]);
+        });
+        return [element('section', { className: ['doc-timeline'], 'aria-label': 'Progress timeline' }, [
+                element('div', { className: ['doc-timeline-summary'] }, [text(summary)]),
+                element('progress', { className: ['doc-timeline-progress'], value: node.currentIndex, max: node.items.length, 'aria-label': 'Milestones complete' }, []),
+                element('ol', { className: ['doc-timeline-list'], role: 'list' }, items)
+            ])];
+    }
+    const items = node.items.map((item) => element('li', {}, [
+        element(`h${node.headingLevel}`, { className: ['doc-step-head', ...(node.toc === 'ignore' ? ['doc-step-heading-toc-ignore'] : [])] }, [...(item.icon ? [stepIcon(item.icon)] : []), text(item.title)]),
+        element('div', { className: ['doc-step-body'] }, item.children.flatMap(walk))
+    ]));
+    return [element('ol', { className: ['doc-steps', `doc-steps-${node.variant}`], ...(node.variant !== 'plain' ? { role: 'list' } : {}) }, items)];
+}

package/dist/project-navigation.d.ts

@@ -0,0 +1,41 @@
+import type { Document, NavigationNode, Variant } from './content-source.js';
+export type OperationNavEntry = {
+    id: string;
+    apiId: string;
+    documentId: string;
+    title: string;
+    tag: string;
+    search: string;
+};
+type NavSpec = {
+    id: string;
+    label?: string;
+    tab?: boolean;
+    landing?: string;
+    doc?: string;
+    operation?: string;
+    generated?: 'tags' | 'remaining';
+    api?: string;
+    tag?: string;
+    search?: string;
+    items?: NavSpec[];
+};
+export declare function validateProjectNavigation(layout: any, docs: Map<string, Document>, operations: Map<string, {
+    apiId: string;
+    reference: string;
+}>, apiIds: Set<string>): NavSpec[];
+export declare function resolveProjectNavigation(layout: NavSpec[], variant: Variant, docs: Map<string, Document>, entries: OperationNavEntry[], tagOrder: Map<string, string[]>): NavigationNode[];
+export declare function navigationTab(nodes: NavigationNode[], route: string): NavigationNode | undefined;
+export declare function navigationTabRecord(node: NavigationNode, variant: Variant, basePath: string): {
+    id: string;
+    label: string;
+    variant: Variant;
+    url: string;
+    markdownUrl: string;
+    indexUrl: string;
+};
+export declare function navigationPath(nodes: NavigationNode[], route: string): Array<{
+    label: string;
+    url?: string;
+}>;
+export {};

package/dist/project-navigation.js

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto';
+import { markdownRoute } from './content-source.js';
+const variantKey = (variant) => `${variant.channel}|${variant.version}|${variant.language}`;
+const docKey = (id, variant) => `${id}|${variantKey(variant)}`;
+const tagId = (placeholder, tag) => `${placeholder}-tag-${createHash('sha256').update(tag).digest('hex').slice(0, 8)}`;
+export function validateProjectNavigation(layout, docs, operations, apiIds) {
+    if (!Array.isArray(layout))
+        throw new Error('navigation must be a list');
+    const ids = new Set();
+    const tagGenerators = new Set();
+    const availableDocIds = new Set([...docs.values()].map(doc => doc.frontmatter.id));
+    const walk = (nodes, inheritedApi, inheritedTag, depth = 0) => {
+        for (const node of nodes) {
+            if (!node || typeof node !== 'object' || Array.isArray(node) || typeof node.id !== 'string' || !node.id)
+                throw new Error('Navigation nodes need stable IDs');
+            if (ids.has(node.id))
+                throw new Error(`Duplicate navigation ID ${node.id}`);
+            ids.add(node.id);
+            for (const key of Object.keys(node))
+                if (!['id', 'label', 'tab', 'landing', 'doc', 'operation', 'generated', 'api', 'tag', 'search', 'items'].includes(key))
+                    throw new Error(`Unknown navigation field ${key}: ${node.id}`);
+            if (node.tab !== undefined && node.tab !== true)
+                throw new Error(`Navigation tab must be true when set: ${node.id}`);
+            if (node.tab) {
+                if (depth || !Array.isArray(node.items) || !/^[a-z][a-z0-9-]*$/.test(node.id))
+                    throw new Error(`Navigation tabs need a top-level group and a lowercase hyphenated ID: ${node.id}`);
+                if (typeof node.landing !== 'string' || !availableDocIds.has(node.landing))
+                    throw new Error(`Navigation tab needs a valid landing document ID: ${node.id}`);
+            }
+            else if (node.landing !== undefined)
+                throw new Error(`Navigation landing requires tab: true: ${node.id}`);
+            if (node.label !== undefined && typeof node.label !== 'string')
+                throw new Error(`Navigation label must be text: ${node.id}`);
+            if (node.search !== undefined && typeof node.search !== 'string')
+                throw new Error(`Navigation search terms must be text: ${node.id}`);
+            if (node.doc && node.items)
+                throw new Error(`Navigation node cannot be both a page and a group: ${node.id}`);
+            const kinds = [node.doc !== undefined, node.operation !== undefined, node.generated !== undefined, node.items !== undefined].filter(Boolean).length;
+            if (kinds !== 1)
+                throw new Error(`Navigation node needs exactly one of doc, operation, generated, or items: ${node.id}`);
+            if (node.api !== undefined && (typeof node.api !== 'string' || !apiIds.has(node.api)))
+                throw new Error(`Unknown navigation API ${node.api}: ${node.id}`);
+            const api = node.api ?? inheritedApi;
+            if (node.doc !== undefined) {
+                if (typeof node.doc !== 'string' || !availableDocIds.has(node.doc))
+                    throw new Error(`Navigation targets missing document ${node.doc}`);
+                if (node.tag || node.api)
+                    throw new Error(`Page navigation node cannot set api or tag: ${node.id}`);
+            }
+            else if (node.operation !== undefined) {
+                const known = operations.get(node.operation);
+                if (!known)
+                    throw new Error(`Unknown stable operation ID ${node.operation}: ${node.id}`);
+                if (api && api !== known.apiId)
+                    throw new Error(`Navigation operation ${node.operation} belongs to API ${known.apiId}`);
+                if (node.tag)
+                    throw new Error(`Operation navigation node cannot set tag: ${node.id}`);
+            }
+            else if (node.generated !== undefined) {
+                if (!['tags', 'remaining'].includes(node.generated))
+                    throw new Error(`Unknown navigation generator ${node.generated}: ${node.id}`);
+                if (!api)
+                    throw new Error(`Generated navigation needs an API: ${node.id}`);
+                if (node.label || node.search || node.tag)
+                    throw new Error(`Generated navigation only accepts id, api, and generated: ${node.id}`);
+                if (node.generated === 'remaining' && !inheritedTag)
+                    throw new Error(`generated: remaining needs a tag group: ${node.id}`);
+                if (node.generated === 'tags') {
+                    if (inheritedTag)
+                        throw new Error(`generated: tags cannot be inside a tag group: ${node.id}`);
+                    if (tagGenerators.has(api))
+                        throw new Error(`Duplicate generated: tags for API ${api}`);
+                    tagGenerators.add(api);
+                }
+            }
+            else {
+                if (typeof node.label !== 'string' || !node.label || !Array.isArray(node.items) || !node.items.length)
+                    throw new Error(`Navigation group needs label and nonempty items: ${node.id}`);
+                if (node.search)
+                    throw new Error(`Navigation group cannot set search: ${node.id}`);
+                if (node.tag !== undefined && (typeof node.tag !== 'string' || !node.tag || !api))
+                    throw new Error(`Navigation tag group needs an API and tag: ${node.id}`);
+                walk(node.items, api, node.tag ?? inheritedTag, depth + 1);
+            }
+        }
+    };
+    walk(layout);
+    return layout;
+}
+export function resolveProjectNavigation(layout, variant, docs, entries, tagOrder) {
+    const byId = new Map(entries.map(entry => [entry.id, entry]));
+    if (byId.size !== entries.length)
+        throw new Error(`Duplicate operation reference in ${variantKey(variant)}`);
+    const byDocument = new Map(entries.map(entry => [entry.documentId, entry]));
+    const reserved = new Set();
+    const reserve = (nodes) => {
+        for (const node of nodes) {
+            const entry = node.operation ? byId.get(node.operation) : node.doc ? byDocument.get(node.doc) : undefined;
+            if (entry) {
+                if (reserved.has(entry.id))
+                    throw new Error(`Operation placed more than once in navigation: ${entry.id}`);
+                reserved.add(entry.id);
+            }
+            if (node.items)
+                reserve(node.items);
+        }
+    };
+    reserve(layout);
+    const placed = new Set();
+    const leaf = (entry, id, label, search) => {
+        if (placed.has(entry.id))
+            throw new Error(`Operation placed more than once in navigation: ${entry.id}`);
+        placed.add(entry.id);
+        const doc = docs.get(docKey(entry.documentId, variant));
+        if (!doc)
+            throw new Error(`Missing reference document variant for ${entry.id}`);
+        return { id, label: label ?? entry.title, route: doc.route, search: [entry.search, search].filter(Boolean).join(' '), subjectLifecycle: doc.frontmatter.subjectLifecycle, method: doc.endpoint?.method, webhook: doc.endpoint?.webhook, readerFilters: doc.readerFilters };
+    };
+    const render = (nodes, inheritedApi, inheritedTag) => nodes.flatMap(node => {
+        const api = node.api ?? inheritedApi;
+        if (node.doc) {
+            const doc = docs.get(docKey(node.doc, variant));
+            if (!doc)
+                return [];
+            const entry = byDocument.get(node.doc);
+            return entry ? [leaf(entry, node.id, node.label ?? doc.frontmatter.title, node.search)] : [{ id: node.id, label: node.label ?? doc.frontmatter.title, route: doc.route, search: node.search, subjectLifecycle: doc.frontmatter.subjectLifecycle, readerFilters: doc.readerFilters }];
+        }
+        if (node.operation) {
+            const entry = byId.get(node.operation);
+            return entry ? [leaf(entry, node.id, node.label, node.search)] : [];
+        }
+        if (node.generated) {
+            const candidates = entries.filter(entry => entry.apiId === api && !reserved.has(entry.id) && !placed.has(entry.id));
+            if (node.generated === 'remaining')
+                return candidates.filter(entry => entry.tag === inheritedTag).map(entry => leaf(entry, `${node.id}-${entry.id}`));
+            const tags = [...new Set([...(tagOrder.get(api) ?? []), ...candidates.map(entry => entry.tag)])];
+            return tags.flatMap(tag => {
+                const items = candidates.filter(entry => entry.tag === tag).map(entry => leaf(entry, `${node.id}-${entry.id}`));
+                return items.length ? [{ id: tagId(node.id, tag), label: tag, items }] : [];
+            });
+        }
+        const items = render(node.items ?? [], api, node.tag ?? inheritedTag);
+        if (!items.length)
+            return [];
+        if (node.tab) {
+            const landing = docs.get(docKey(node.landing, variant));
+            if (!landing)
+                throw new Error(`Navigation tab landing ${node.landing} is unavailable in ${variantKey(variant)}: ${node.id}`);
+            if (!navigationPath(items, landing.route).length)
+                throw new Error(`Navigation tab landing must belong to its items: ${node.id}`);
+            return [{ id: node.id, label: node.label, tab: true, route: landing.route, items }];
+        }
+        return [{ id: node.id, label: node.label, items }];
+    });
+    const resolved = render(layout);
+    // A direct link must select one tab, independent of browser state or tree order.
+    const owners = new Map();
+    const assign = (nodes, owner) => {
+        for (const node of nodes) {
+            if (node.items)
+                assign(node.items, owner);
+            else if (node.route) {
+                const previous = owners.get(node.route);
+                if (previous !== undefined && previous !== owner)
+                    throw new Error(`Page belongs to multiple navigation sections: ${node.route}`);
+                owners.set(node.route, owner);
+            }
+        }
+    };
+    for (const node of resolved)
+        assign(node.tab ? node.items : [node], node.tab ? node.id : '');
+    return resolved;
+}
+export function navigationTab(nodes, route) {
+    return nodes.find(node => node.tab && navigationPath(node.items ?? [], route).length > 0);
+}
+export function navigationTabRecord(node, variant, basePath) {
+    const suffix = createHash('sha256').update(variantKey(variant)).digest('hex').slice(0, 12);
+    return { id: node.id, label: node.label, variant, url: node.route, markdownUrl: markdownRoute(node.route, basePath), indexUrl: `${basePath}/.well-known/shoalrun/navigation/${node.id}-${suffix}.txt` };
+}
+export function navigationPath(nodes, route) {
+    for (const node of nodes) {
+        if (!node.tab && node.route === route)
+            return [{ label: node.label, url: node.route }];
+        const child = navigationPath(node.items ?? [], route);
+        if (child.length)
+            return [{ label: node.label, ...(node.route ? { url: node.route } : {}) }, ...child];
+    }
+    return [];
+}

package/dist/provider-http.d.ts

@@ -0,0 +1,10 @@
+export type Transport = {
+    fetch?: typeof fetch;
+    retries?: number;
+    retryDelayMs?: number;
+    signal?: AbortSignal;
+};
+export declare function providerError(value: unknown, secrets?: Array<string | undefined>): string;
+export declare function throwIfCancelled(signal?: AbortSignal): void;
+export declare function retryPause(milliseconds: number, signal?: AbortSignal): Promise<void>;
+export declare function postJson(label: string, url: string, headers: Record<string, string>, body: unknown, transport: Transport): Promise<unknown>;

package/dist/provider-http.js

@@ -0,0 +1,60 @@
+// Shared by the embedding and chat providers: one place for timeouts, retries, and keeping the key out of errors.
+export function providerError(value, secrets = []) {
+    let message = String(value instanceof Error ? value.message : value);
+    for (const secret of secrets.filter((item) => Boolean(item))) {
+        message = message.split(secret).join('[redacted]');
+        message = message.split(encodeURIComponent(secret)).join('[redacted]');
+    }
+    return message.replace(/Bearer\s+[^\s,;"']+/gi, 'Bearer [redacted]').slice(0, 200);
+}
+export function throwIfCancelled(signal) { signal?.throwIfAborted(); }
+export async function retryPause(milliseconds, signal) {
+    throwIfCancelled(signal);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(); }, milliseconds);
+        const abort = () => { clearTimeout(timer); reject(signal?.reason); };
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+async function failureDetail(response) {
+    try {
+        const body = await response.json();
+        const error = typeof body.error === 'string' ? body.error : body.error?.message;
+        return String(body.detail ?? body.message ?? error ?? '').slice(0, 200);
+    }
+    catch {
+        return '';
+    }
+}
+// POST JSON with a timeout, retrying rate limits, server errors, and network failures. Neither the key nor the request body
+// appears in an error message.
+export async function postJson(label, url, headers, body, transport) {
+    const send = transport.fetch ?? fetch;
+    const retries = transport.retries ?? 3;
+    const secret = headers.authorization?.replace(/^Bearer\s+/i, '');
+    for (let attempt = 0;; attempt++) {
+        throwIfCancelled(transport.signal);
+        const delay = () => retryPause((transport.retryDelayMs ?? 1000) * 2 ** attempt, transport.signal);
+        let response;
+        try {
+            response = await send(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(body), signal: AbortSignal.any([AbortSignal.timeout(60_000), ...(transport.signal ? [transport.signal] : [])]) });
+        }
+        catch (error) {
+            throwIfCancelled(transport.signal);
+            if (attempt < retries) {
+                await delay();
+                continue;
+            }
+            throw new Error(`${label} request failed: ${providerError(error, [secret])}`);
+        }
+        throwIfCancelled(transport.signal);
+        if (response.ok)
+            return response.json();
+        if ((response.status === 429 || response.status >= 500) && attempt < retries) {
+            await delay();
+            continue;
+        }
+        const detail = await failureDetail(response);
+        throw new Error(`${label} returned ${response.status}${detail ? `: ${providerError(detail, [secret])}` : ''}`);
+    }
+}