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

package/dist/server.js

@@ -0,0 +1,223 @@
+import { loadMcpRuntime, createMcpHttpHandler } from './mcp-http.js';
+import { bridgeMcp } from './mcp-node.js';
+import { notFoundPage, addNotFoundTwin } from './not-found.js';
+import { createServer } from 'node:http';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { homeUrl, negotiatedDocument } from './negotiation.js';
+const types = { '.html': 'text/html; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.xml': 'application/xml; charset=utf-8', '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.txt': 'text/plain; charset=utf-8', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf' };
+const bridgeLimit = 20_000;
+// Read a Node request into a Web `Request`, refusing bodies over the limit before a handler sees them.
+async function bridge(request, response, handler) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > bridgeLimit) {
+            response.writeHead(413, { 'Content-Type': 'application/json' });
+            response.end('{"error":"The request is too large."}');
+            return;
+        }
+        chunks.push(chunk);
+    }
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers))
+        if (value !== undefined)
+            headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+    const method = request.method ?? 'GET';
+    const result = await handler(new Request(`http://${request.headers.host ?? 'localhost'}${request.url ?? '/'}`, { method, headers, ...(method === 'GET' || method === 'HEAD' ? {} : { body: Buffer.concat(chunks) }) }));
+    // Headers.entries() joins repeated Set-Cookie values into one, which a browser reads as a single cookie. They are copied one by one.
+    for (const [name, value] of result.headers)
+        if (name !== 'set-cookie')
+            response.setHeader(name, value);
+    const cookies = result.headers.getSetCookie();
+    if (cookies.length)
+        response.setHeader('set-cookie', cookies);
+    response.writeHead(result.status);
+    response.end(Buffer.from(await result.arrayBuffer()));
+}
+export async function createSiteServer(directory, liveClients, extras = {}) {
+    const root = path.resolve(directory);
+    const realRoot = await realpath(root);
+    const loadState = async () => {
+        const headers = JSON.parse(await readFile(path.join(root, 'resource-headers.json'), 'utf8'));
+        const manifest = JSON.parse(await readFile(path.join(root, 'documents.json'), 'utf8'));
+        const redirects = JSON.parse(await readFile(path.join(root, 'redirects.json'), 'utf8').catch(() => '[]'));
+        const search = await siteFile(`${manifest.basePath ?? ''}/search-index.json`).then(file => stat(file)).then(info => info.isFile()).catch(() => false);
+        const errorHtml = await siteFile(`${manifest.basePath ?? ''}/404.html`).then(file => readFile(file, 'utf8')).catch(() => undefined);
+        return { headers, manifest, redirects, search, errorHtml, home: manifest.documents.find(item => item.url === manifest.basePath)?.url ?? homeUrl(manifest.documents), routes: new Set(manifest.documents.map(item => item.url)) };
+    };
+    const initialState = await loadState();
+    let mcp = await loadMcpRuntime(root);
+    let mcpHandler = mcp ? createMcpHttpHandler(mcp) : undefined;
+    let mcpBuild = mcp?.runtime.buildId;
+    async function siteFile(route) {
+        const file = path.resolve(root, `.${route}`);
+        if (file !== root && !file.startsWith(`${root}${path.sep}`))
+            throw new Error('Invalid path');
+        const realFile = await realpath(file);
+        if (realFile !== realRoot && !realFile.startsWith(`${realRoot}${path.sep}`))
+            throw new Error('Invalid path');
+        return file;
+    }
+    return createServer(async (request, response) => {
+        response.setHeader('X-Content-Type-Options', 'nosniff');
+        response.setHeader('Cache-Control', 'no-cache');
+        let pathname = '';
+        let recoveryState = initialState;
+        try {
+            pathname = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname);
+            if (pathname.includes('\0') || pathname.split('/').includes('..'))
+                throw new Error('Invalid path');
+            const { headers, manifest, redirects, search, errorHtml, home, routes } = liveClients ? await loadState() : initialState;
+            recoveryState = { headers, manifest, redirects, search, errorHtml, home, routes };
+            const basePath = manifest.basePath ?? '';
+            if (liveClients && manifest.buildId !== mcpBuild) {
+                const next = await loadMcpRuntime(root);
+                mcp = next;
+                mcpHandler = next ? createMcpHttpHandler(next) : undefined;
+                mcpBuild = manifest.buildId;
+            }
+            const internalPath = pathname.toLowerCase().replace(/\/+$/, '');
+            if (internalPath === '/mcp-runtime.json' || internalPath === '/__shoalrun/mcp-data' || internalPath.startsWith('/__shoalrun/mcp-data/')) {
+                response.writeHead(404);
+                response.end();
+                return;
+            }
+            if (mcp && mcpHandler && pathname === mcp.runtime.path) {
+                await bridgeMcp(request, response, mcpHandler);
+                return;
+            }
+            if (liveClients && pathname === `${basePath}/__shoalrun/reload`) {
+                response.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+                response.write(': connected\n\n');
+                liveClients.add(response);
+                response.on('close', () => liveClients.delete(response));
+                return;
+            }
+            if (extras.ask && pathname === `${basePath}/__shoalrun/ask`) {
+                try {
+                    await bridge(request, response, extras.ask);
+                }
+                catch {
+                    if (!response.headersSent) {
+                        response.writeHead(400, { 'Content-Type': 'application/json' });
+                        response.end('{"error":"The request could not be read."}');
+                    }
+                }
+                return;
+            }
+            if (extras.search && pathname === `${basePath}/__shoalrun/search`) {
+                try {
+                    await bridge(request, response, extras.search);
+                }
+                catch {
+                    if (!response.headersSent) {
+                        response.writeHead(400, { 'Content-Type': 'application/json' });
+                        response.end('{"error":"The request could not be read."}');
+                    }
+                }
+                return;
+            }
+            // The public settings a hosted chat publishes. Serving them makes the panel run as the public chat instead of the local preview.
+            if (extras.ask && extras.publicSettings && pathname === `${basePath}/__shoalrun/chat.json`) {
+                response.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+                response.end(request.method === 'HEAD' ? undefined : JSON.stringify(extras.publicSettings));
+                return;
+            }
+            if (extras.ask && extras.widget && pathname === `${basePath}/__shoalrun/ask.js`) {
+                response.writeHead(200, { 'Content-Type': 'text/javascript; charset=utf-8', 'Cache-Control': 'no-store' });
+                // A local preview has no chat.json, so the panel wording from chat.panel is handed to the script directly.
+                response.end(request.method === 'HEAD' ? undefined : `${extras.panel ? `window.__shoalrunPanel=${JSON.stringify(extras.panel)};\n` : ''}${extras.widget}`);
+                return;
+            }
+            if ((pathname === '/' && !routes.has('/')) || (basePath && (pathname === basePath || pathname === `${basePath}/`) && !routes.has(basePath)))
+                if (home) {
+                    response.writeHead(302, { Location: `${home}/` });
+                    response.end();
+                    return;
+                }
+            const redirectPath = pathname.replace(/(.)\/+$/, '$1');
+            const redirect = redirects.find(item => item.from === redirectPath);
+            const markdownRedirect = redirects.find(item => item.markdownTo && item.markdownFrom === pathname);
+            const location = redirect?.to ?? markdownRedirect?.markdownTo;
+            if (location) {
+                response.writeHead((redirect ?? markdownRedirect).status, { Location: location });
+                response.end();
+                return;
+            }
+            const sendRepresentation = (body, resourceHeaders) => {
+                const match = request.headers['if-none-match'];
+                const etag = resourceHeaders.ETag;
+                const notModified = (request.method === 'GET' || request.method === 'HEAD') && etag && match?.split(',').some(value => value.trim() === '*' || value.trim().replace(/^W\//, '') === etag);
+                response.writeHead(notModified ? 304 : 200, resourceHeaders);
+                response.end(notModified || request.method === 'HEAD' ? undefined : body);
+            };
+            const negotiated = negotiatedDocument(pathname, request.headers.accept, manifest.documents);
+            if (negotiated) {
+                const body = await readFile(await siteFile(negotiated.markdownUrl));
+                sendRepresentation(body, { ...headers[negotiated.markdownUrl], Vary: 'Accept', 'Content-Location': negotiated.markdownUrl, Link: [`<${negotiated.markdownUrl}>; rel="alternate"; type="text/markdown"`, headers[negotiated.markdownUrl]?.Link].filter(Boolean).join(', ') });
+                return;
+            }
+            let file = await siteFile(pathname);
+            const info = await stat(file);
+            if (info.isDirectory()) {
+                if (!pathname.endsWith('/')) {
+                    response.writeHead(301, { Location: `${pathname}/${new URL(request.url ?? '/', 'http://localhost').search}`, ...(routes.has(pathname) ? { Vary: 'Accept' } : {}) });
+                    response.end();
+                    return;
+                }
+                file = await siteFile(path.posix.join(pathname, 'index.html'));
+            }
+            let body = await readFile(file);
+            const documentRoute = pathname === '/' ? '/' : pathname.replace(/\/+$/, '');
+            const document = manifest.documents.find(item => item.url === documentRoute);
+            const injected = `${liveClients ? `<script>const updates=new EventSource("${basePath}/__shoalrun/reload");updates.addEventListener("built",()=>location.reload());updates.addEventListener("failed",event=>{let status=document.getElementById("shoalrun-build-status");if(!status){status=document.createElement("aside");status.id="shoalrun-build-status";status.setAttribute("role","alert");document.body.append(status)}status.textContent="Build failed: "+JSON.parse(event.data).message})</script>` : ''}${extras.ask && extras.widget ? `<script src="${basePath}/__shoalrun/ask.js" defer></script>` : ''}`;
+            if (injected && file.endsWith('.html') && request.method !== 'HEAD')
+                body = Buffer.from(body.toString('utf8').replace('</body>', `${injected}</body>`));
+            sendRepresentation(body, { ...(headers[pathname] ?? { 'Content-Type': types[path.extname(file)] ?? 'application/octet-stream' }), ...(file.toLowerCase().endsWith('.svg') ? { 'Content-Security-Policy': 'sandbox' } : {}), ...(document ? { Vary: 'Accept', Link: `<${document.markdownUrl}>; rel="alternate"; type="text/markdown"` } : {}) });
+        }
+        catch (error) {
+            const missing = ['ENOENT', 'ENOTDIR'].includes(error.code ?? '') || error instanceof URIError || (error instanceof Error && error.message === 'Invalid path');
+            if (!missing) {
+                response.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+                response.end(request.method === 'HEAD' ? undefined : 'Internal server error\n');
+                return;
+            }
+            const { manifest, search, errorHtml, home } = recoveryState;
+            const basePath = manifest.basePath ?? '';
+            if (liveClients && manifest.buildId !== mcpBuild) {
+                const next = await loadMcpRuntime(root);
+                mcp = next;
+                mcpHandler = next ? createMcpHttpHandler(next) : undefined;
+                mcpBuild = manifest.buildId;
+            }
+            const internalPath = pathname.toLowerCase().replace(/\/+$/, '');
+            if (internalPath === '/mcp-runtime.json' || internalPath === '/__shoalrun/mcp-data' || internalPath.startsWith('/__shoalrun/mcp-data/')) {
+                response.writeHead(404);
+                response.end();
+                return;
+            }
+            if (mcp && mcpHandler && pathname === mcp.runtime.path) {
+                await bridgeMcp(request, response, mcpHandler);
+                return;
+            }
+            const markdown = pathname.endsWith('.md') || !!negotiatedDocument('/', request.headers.accept, [{ url: '/', markdownUrl: '/index.md' }]);
+            const document = manifest.documents.find(item => item.markdownUrl === pathname || (markdown && item.url === (pathname.replace(/\/+$/, '') || '/')));
+            const twin = document && await siteFile(document.url === '/' ? '/index.html' : `${document.url}/index.html`).then(file => stat(file)).then(info => info.isFile()).catch(() => false) ? document.url : undefined;
+            response.writeHead(404, { 'Content-Type': markdown ? 'text/markdown; charset=utf-8' : 'text/html; charset=utf-8', Vary: 'Accept', 'X-Robots-Tag': 'noindex', ...(twin ? { Link: `<${twin}>; rel="alternate"; type="text/html"` } : {}) });
+            const body = !markdown && errorHtml ? (twin ? addNotFoundTwin(errorHtml, twin) : errorHtml) : notFoundPage(basePath, home ?? `${basePath}/`, markdown, twin, search);
+            response.end(request.method === 'HEAD' ? undefined : body);
+        }
+    });
+}
+export async function serveSite(directory, host, port, liveClients, extras) {
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error('Server port must be an integer from 0 to 65535');
+    const server = await createSiteServer(directory, liveClients, extras);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => { server.off('error', reject); resolve(); });
+    });
+    return server;
+}

package/dist/share-images.d.ts

@@ -0,0 +1,24 @@
+import type { Palette } from './palettes.js';
+export type ShareSettings = {
+    enabled: boolean;
+    template?: string;
+    fonts: string[];
+};
+export type ShareCard = {
+    title: string;
+    summary: string;
+    site: string;
+    type: string;
+    url: string;
+};
+export declare const shareWidth = 1200;
+export declare const shareHeight = 630;
+export declare function resolveShareImages(value: unknown, declaringFile: string): ShareSettings;
+export declare const shareRoute: (route: string) => string;
+export declare function wrapText(text: string, widths: Record<string, number>, size: number, maxWidth: number, maxLines: number): string[];
+export declare function defaultShareSvg(card: ShareCard, preset: string, palette: Palette): Promise<string>;
+export declare function fillShareTemplate(template: string, card: ShareCard, file: string): string;
+export declare const bundledShareFonts: () => string[];
+export declare function renderPng(svg: string, fontFiles: string[], cacheDirectory: string, width?: number): Promise<Buffer>;
+export declare function faviconSvg(preset: string, palette: Palette): string;
+export declare function touchIconSvg(icon: string, palette: Palette): string;

package/dist/share-images.js

@@ -0,0 +1,187 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+// Share images: a 1200×630 PNG per page for link previews, drawn from an SVG template with resvg at build time.
+// resvg reads TrueType and OpenType only, so styles/fonts/share holds static TTF cuts of the bundled fonts
+// plus their glyph widths, which the default template uses to wrap titles.
+const shareFontDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../styles/fonts/share');
+export const shareWidth = 1200;
+export const shareHeight = 630;
+const presetFonts = {
+    shoal: { title: 'inter-700.ttf', body: 'inter-400.ttf' },
+    reef: { title: 'figtree-700.ttf', body: 'figtree-400.ttf' },
+    ledger: { title: 'jetbrains-mono-700.ttf', body: 'source-serif-4-400.ttf' },
+    vice: { title: 'jost-italic-800.ttf', body: 'figtree-400.ttf' }
+};
+const fontFormats = new Set(['.ttf', '.otf']);
+// outputs.html.shareImages: omitted or true draws the default card, false turns images off, and a mapping names a template.
+export function resolveShareImages(value, declaringFile) {
+    if (value === undefined || value === true)
+        return { enabled: true, fonts: [] };
+    if (value === false)
+        return { enabled: false, fonts: [] };
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !['template', 'fonts'].includes(key)))
+        throw new Error('outputs.html.shareImages must be true, false, or a mapping with template and fonts');
+    const settings = value;
+    const local = (file) => path.resolve(path.dirname(declaringFile), file);
+    if (settings.template !== undefined && (typeof settings.template !== 'string' || path.extname(settings.template).toLowerCase() !== '.svg'))
+        throw new Error('outputs.html.shareImages.template must be a local .svg file');
+    const fonts = settings.fonts ?? [];
+    if (!Array.isArray(fonts) || fonts.some(file => typeof file !== 'string' || !fontFormats.has(path.extname(file).toLowerCase())))
+        throw new Error('outputs.html.shareImages.fonts must list local .ttf or .otf files');
+    const resolved = { enabled: true, template: settings.template === undefined ? undefined : local(settings.template), fonts: fonts.map(local) };
+    for (const file of [...(resolved.template ? [resolved.template] : []), ...resolved.fonts])
+        if (!existsSync(file))
+            throw new Error(`outputs.html.shareImages: file not found: ${file}`);
+    return resolved;
+}
+// Each page's image lives beside its route, so /styling/themes becomes /assets/share/styling/themes.png.
+export const shareRoute = (route) => `/assets/share${route === '/' ? '/index' : route}.png`;
+const escape = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+let metricsCache;
+async function metrics() {
+    metricsCache ??= JSON.parse(await readFile(path.join(shareFontDirectory, 'metrics.json'), 'utf8'));
+    return metricsCache;
+}
+// Greedy word wrap using the font's advance widths; the last line gets an ellipsis when text is cut.
+export function wrapText(text, widths, size, maxWidth, maxLines) {
+    const measure = (value) => [...value].reduce((total, char) => total + (widths[char] ?? .56) * size, 0);
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        const next = line ? `${line} ${word}` : word;
+        if (measure(next) <= maxWidth || !line) {
+            line = next;
+            continue;
+        }
+        lines.push(line);
+        line = word;
+    }
+    if (line)
+        lines.push(line);
+    if (lines.length <= maxLines)
+        return lines;
+    const kept = lines.slice(0, maxLines);
+    let last = kept[maxLines - 1];
+    while (last && measure(`${last}…`) > maxWidth)
+        last = last.replace(/\s*\S+$/, '');
+    kept[maxLines - 1] = `${last}…`;
+    return kept;
+}
+// Lines split at word boundaries by character count, for project templates whose fonts the build cannot measure.
+function wrapByCharacters(text, perLine, maxLines) {
+    const widths = new Proxy({}, { get: () => 1 });
+    return wrapText(text, widths, 1, perLine, maxLines);
+}
+function brandMark(preset, x, y, size, palette) {
+    const accent = palette.dark.accent;
+    if (preset === 'ledger')
+        return `<rect x="${x}" y="${y}" width="${size}" height="${size}" fill="${accent}"/>`;
+    if (preset === 'vice')
+        return `<defs><linearGradient id="sun" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#ffd166"/><stop offset=".45" stop-color="#ff8a3d"/><stop offset="1" stop-color="#ff4fa3"/></linearGradient></defs><circle cx="${x + size / 2}" cy="${y + size / 2}" r="${size / 2}" fill="url(#sun)"/>`;
+    if (preset === 'reef')
+        return `<rect x="${x}" y="${y}" width="${size}" height="${size}" rx="${size * .3}" fill="${accent}" transform="rotate(12 ${x + size / 2} ${y + size / 2})"/>`;
+    const s = size / 64;
+    return `<g transform="translate(${x} ${y}) scale(${s})" fill="${accent}"><path d="M4 40c2-7 6-11 10-11 5 0 8 5 8 12v3H4z"/><path d="M26 37c2-10 6-16 10-16 5 0 9 7 9 17v6H26z"/><path d="M47 40c2-7 5-10 9-10 5 0 8 5 8 11v3H47z"/><path d="M5 51c8-4 15-4 23 0s15 4 23 0 10-4 13-3" fill="none" stroke="${accent}" stroke-width="4" stroke-linecap="round"/><path d="M5 59c8-4 15-4 23 0s15 4 23 0 10-4 13-3" fill="none" stroke="${accent}" stroke-width="4" stroke-linecap="round"/></g>`;
+}
+export async function defaultShareSvg(card, preset, palette) {
+    const fonts = presetFonts[preset] ?? presetFonts.shoal;
+    const all = await metrics();
+    const titleFont = all[fonts.title];
+    const bodyFont = all[fonts.body];
+    const pad = 80;
+    const width = shareWidth - pad * 2;
+    const background = palette.light['strong-surface'];
+    const ink = palette.light['strong-text'];
+    const accent = palette.dark.accent;
+    const muted = palette.dark.muted;
+    let size = 68;
+    let title = wrapText(card.title, titleFont.widths, size, width, 3);
+    if (title.length > 2) {
+        size = 56;
+        title = wrapText(card.title, titleFont.widths, size, width, 3);
+    }
+    const summary = card.summary ? wrapText(card.summary, bodyFont.widths, 30, width, 2) : [];
+    const text = (family) => `font-family="${escape(family.family)}" font-weight="${family.weight}" font-style="${family.style}"`;
+    const titleTop = 200;
+    const titleLead = size * 1.12;
+    const summaryTop = titleTop + (title.length - 1) * titleLead + 64;
+    const decoration = {
+        shoal: `<rect x="0" y="0" width="12" height="${shareHeight}" fill="${accent}"/>`,
+        reef: `<circle cx="${shareWidth - 60}" cy="${shareHeight + 40}" r="360" fill="${accent}" opacity=".22"/>`,
+        ledger: `<rect x="0" y="${shareHeight - 14}" width="${shareWidth}" height="14" fill="${accent}"/>`,
+        vice: `<defs><linearGradient id="stripe" x1="0" x2="1"><stop offset="0" stop-color="#ff4fa3"/><stop offset=".5" stop-color="#ff8a3d"/><stop offset="1" stop-color="#3ee6dc"/></linearGradient><radialGradient id="glow" cx=".85" cy="1.2" r=".8"><stop offset="0" stop-color="#ff4fa3" stop-opacity=".45"/><stop offset="1" stop-color="#ff4fa3" stop-opacity="0"/></radialGradient></defs><rect width="${shareWidth}" height="${shareHeight}" fill="url(#glow)"/><rect x="0" y="${shareHeight - 12}" width="${shareWidth}" height="12" fill="url(#stripe)"/>`
+    }[preset] ?? '';
+    const footerY = shareHeight - pad + 10;
+    // The URL sits at the right of the footer; drop it rather than let it collide with a long site name.
+    const measure = (value, widths, px) => [...value].reduce((total, char) => total + (widths[char] ?? .56) * px, 0);
+    const site = wrapText(card.site, titleFont.widths, 26, width - 50, 1)[0] ?? '';
+    const url = card.url && 50 + measure(site, titleFont.widths, 26) + 48 + measure(card.url, bodyFont.widths, 22) <= width ? card.url : '';
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${shareWidth}" height="${shareHeight}" viewBox="0 0 ${shareWidth} ${shareHeight}">`,
+        `<rect width="${shareWidth}" height="${shareHeight}" fill="${background}"/>`,
+        decoration,
+        `<text x="${pad}" y="${titleTop - 78}" ${text(bodyFont)} font-size="22" letter-spacing="4" fill="${accent}">${escape(card.type.toUpperCase())}</text>`,
+        ...title.map((line, index) => `<text x="${pad}" y="${titleTop + index * titleLead}" ${text(titleFont)} font-size="${size}" letter-spacing="${preset === 'ledger' ? -1 : -2}" fill="${ink}">${escape(line)}</text>`),
+        ...summary.map((line, index) => `<text x="${pad}" y="${summaryTop + index * 42}" ${text(bodyFont)} font-size="30" fill="${muted}">${escape(line)}</text>`),
+        brandMark(preset, pad, footerY - 30, 34, palette),
+        `<text x="${pad + 50}" y="${footerY}" ${text(titleFont)} font-size="26" fill="${ink}">${escape(site)}</text>`,
+        ...(url ? [`<text x="${shareWidth - pad}" y="${footerY}" text-anchor="end" ${text(bodyFont)} font-size="22" fill="${muted}">${escape(url)}</text>`] : []),
+        '</svg>'
+    ].join('');
+}
+// Project templates use {{placeholders}}; unknown names fail so a typo cannot ship an image with raw braces.
+export function fillShareTemplate(template, card, file) {
+    const title = wrapByCharacters(card.title, 30, 3);
+    const summary = wrapByCharacters(card.summary, 60, 2);
+    const values = {
+        title: card.title, summary: card.summary, site: card.site, type: card.type, url: card.url,
+        'title.1': title[0] ?? '', 'title.2': title[1] ?? '', 'title.3': title[2] ?? '',
+        'summary.1': summary[0] ?? '', 'summary.2': summary[1] ?? ''
+    };
+    return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, name) => {
+        if (!Object.hasOwn(values, name))
+            throw new Error(`${file}: unknown share image placeholder {{${name}}}; use ${Object.keys(values).join(', ')}`);
+        return escape(values[name]);
+    });
+}
+export const bundledShareFonts = () => Object.values(presetFonts).flatMap(font => [font.title, font.body]).filter((file, index, all) => all.indexOf(file) === index).map(file => path.join(shareFontDirectory, file));
+// Rendered PNGs are cached by content, so unchanged pages skip resvg on later builds.
+// The key covers the SVG, the font bytes, the output width, and the resvg version, so any change redraws.
+// Digests are memoized per file version, so a font edited during `shoalrun dev` is hashed again.
+const fontDigests = new Map();
+const fontDigest = async (file) => {
+    const { mtimeMs, size } = await stat(file);
+    const version = `${file}|${mtimeMs}|${size}`;
+    if (!fontDigests.has(version))
+        fontDigests.set(version, readFile(file).then(bytes => createHash('sha256').update(bytes).digest('hex')));
+    return fontDigests.get(version);
+};
+const resvgVersion = String(createRequire(import.meta.url)('@resvg/resvg-js/package.json').version);
+export async function renderPng(svg, fontFiles, cacheDirectory, width = shareWidth) {
+    const { Resvg } = await import('@resvg/resvg-js');
+    const key = createHash('sha256').update(JSON.stringify([svg, await Promise.all(fontFiles.map(fontDigest)), width, resvgVersion])).digest('hex').slice(0, 24);
+    const cached = path.join(cacheDirectory, `${key}.png`);
+    if (existsSync(cached))
+        return readFile(cached);
+    const png = new Resvg(svg, { fitTo: { mode: 'width', value: width }, font: { fontFiles, loadSystemFonts: false, defaultFontFamily: 'Inter' } }).render().asPng();
+    await mkdir(cacheDirectory, { recursive: true });
+    await writeFile(cached, png);
+    return png;
+}
+// The favicon repeats the preset's brand mark in the palette accent; a 180px touch icon puts it on the inked surface.
+export function faviconSvg(preset, palette) {
+    const light = { ...palette, dark: { ...palette.dark, accent: palette.light.accent } };
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">${brandMark(preset, preset === 'shoal' ? 0 : 6, preset === 'shoal' ? 0 : 6, preset === 'shoal' ? 64 : 52, light)}</svg>`;
+}
+export function touchIconSvg(icon, palette) {
+    // Nest the icon's own <svg> so its viewBox still applies; only its position and size change.
+    const body = icon.replace(/^(?:\s|<\?xml[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)+/i, '');
+    if (!/^<svg\b/.test(body))
+        throw new Error('site.favicon must be an SVG document with an <svg> root element');
+    const nested = body.replace(/^<svg\b([^>]*)>/, (_, attributes) => `<svg${attributes.replace(/\s(?:x|y|width|height)=(?:"[^"]*"|'[^']*')/g, '')} x="40" y="40" width="100" height="100">`);
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180" width="180" height="180"><rect width="180" height="180" fill="${palette.light['strong-surface']}"/>${nested}</svg>`;
+}

package/dist/site-path.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeBasePath(value: unknown): string;
+export declare function sitePath(basePath: string, route: string): string;

package/dist/site-path.js

@@ -0,0 +1,15 @@
+// The mount point for every public URL in a built site. Internal build manifests
+// remain at the output root so local tools can find them without a config file.
+export function normalizeBasePath(value) {
+    if (value === undefined || value === '')
+        return '';
+    if (typeof value !== 'string' || !/^\/(?:[A-Za-z0-9._~-]+)(?:\/[A-Za-z0-9._~-]+)*\/?$/.test(value) || value.split('/').some(part => part === '.' || part === '..')) {
+        throw new Error('site.basePath must be a path such as /docs without queries, escapes, or dot segments');
+    }
+    return value.replace(/\/$/, '');
+}
+export function sitePath(basePath, route) {
+    if (!route.startsWith('/') || route.startsWith('//'))
+        throw new Error(`Invalid public route ${route}`);
+    return `${basePath}${route}`;
+}

package/dist/sitemap.d.ts

@@ -0,0 +1,8 @@
+export type SitemapPage = {
+    route: string;
+    updated?: string;
+};
+export declare function sitemapFiles(origin: string, pages: SitemapPage[], limits?: {
+    urls?: number;
+    bytes?: number;
+}, basePath?: string): Map<string, string>;

package/dist/sitemap.js

@@ -0,0 +1,58 @@
+// Sitemaps use the same published routes as HTML, with no build-time dates pretending to be content updates.
+const namespace = 'http://www.sitemaps.org/schemas/sitemap/0.9';
+const maxUrls = 50_000;
+const maxBytes = 50 * 1024 * 1024;
+const escapeXml = (value) => value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[character]);
+const header = '<?xml version="1.0" encoding="UTF-8"?>\n';
+const entry = (url, updated) => `  <url><loc>${escapeXml(url)}</loc>${updated ? `<lastmod>${escapeXml(updated)}</lastmod>` : ''}</url>`;
+const urlset = (entries) => `${header}<urlset xmlns="${namespace}">\n${entries.map(page => entry(page.url, page.updated)).join('\n')}\n</urlset>\n`;
+export function sitemapFiles(origin, pages, limits = {}, basePath = '') {
+    const base = new URL(origin);
+    if (base.protocol !== 'https:' || base.username || base.password || base.pathname !== '/' || base.search || base.hash)
+        throw new Error('site.origin must be an HTTPS origin without a path, query, or fragment');
+    const urls = pages.map(({ route, updated }) => {
+        if (!route.startsWith('/') || route.startsWith('//') || /[?#\\]/.test(route))
+            throw new Error(`Invalid sitemap route ${route}`);
+        return { url: new URL(route, base).href, updated };
+    }).sort((a, b) => a.url.localeCompare(b.url));
+    if (new Set(urls.map(page => page.url)).size !== urls.length)
+        throw new Error('The sitemap has duplicate canonical URLs');
+    const files = new Map();
+    const chunks = [];
+    let current = [];
+    let size = Buffer.byteLength(urlset([]));
+    for (const page of urls) {
+        const added = Buffer.byteLength(entry(page.url, page.updated)) + (current.length ? 1 : 0);
+        if (current.length + 1 > (limits.urls ?? maxUrls) || size + added > (limits.bytes ?? maxBytes)) {
+            if (!current.length)
+                throw new Error(`Sitemap URL is too large: ${page.url}`);
+            chunks.push(current);
+            current = [page];
+            size = Buffer.byteLength(urlset(current));
+        }
+        else {
+            current.push(page);
+            size += added;
+        }
+    }
+    if (current.length)
+        chunks.push(current);
+    if (!chunks.length)
+        return files;
+    if (chunks.length === 1) {
+        files.set(`${basePath}/sitemap.xml`, urlset(chunks[0]));
+        return files;
+    }
+    if (chunks.length > maxUrls)
+        throw new Error('The sitemap needs more than 50,000 child files; split this site by origin');
+    const children = chunks.map((chunk, index) => {
+        const route = `${basePath}/sitemap-${index + 1}.xml`;
+        files.set(route, urlset(chunk));
+        return `${base.origin}${route}`;
+    });
+    const index = `${header}<sitemapindex xmlns="${namespace}">\n${children.map(url => `  <sitemap><loc>${escapeXml(url)}</loc></sitemap>`).join('\n')}\n</sitemapindex>\n`;
+    if (Buffer.byteLength(index) > maxBytes)
+        throw new Error('The sitemap index exceeds 50 MB; split this site by origin');
+    files.set(`${basePath}/sitemap.xml`, index);
+    return files;
+}

package/dist/snippets.d.ts

@@ -0,0 +1,19 @@
+export type SnippetVariable = {
+    type: 'string' | 'number' | 'boolean';
+    required?: boolean;
+    default?: string | number | boolean;
+    enum?: Array<string | number | boolean>;
+};
+export type SnippetDefinition = {
+    file: string;
+    tree: any;
+    variables: Record<string, SnippetVariable>;
+};
+export type SnippetUse = {
+    id: string;
+    file: string;
+    documentId: string;
+};
+export declare function validateSnippetConfig(id: string, definition: any): Record<string, SnippetVariable>;
+export declare function snippetAttribute(attribute: any, label: string): unknown;
+export declare function resolveSnippetValues(id: string, definition: SnippetDefinition, projectValues: unknown, pageValues: unknown, invocation: Record<string, unknown>): Record<string, string | number | boolean>;

package/dist/snippets.js

@@ -0,0 +1,84 @@
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const safeName = (name) => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(name) && !['__proto__', 'prototype', 'constructor'].includes(name);
+const safeId = (id) => /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(id) && id.split('.').every(safeName);
+export function validateSnippetConfig(id, definition) {
+    if (!safeId(id))
+        throw new Error(`Invalid snippet ID ${id}`);
+    if (!object(definition))
+        throw new Error(`Snippet ${id} must be a mapping`);
+    for (const key of Object.keys(definition))
+        if (!['file', 'variables'].includes(key))
+            throw new Error(`Unknown snippet setting ${id}.${key}`);
+    if (typeof definition.file !== 'string' || !/\.mdx?$/.test(definition.file))
+        throw new Error(`Snippet ${id} needs a .md or .mdx file`);
+    const variables = definition.variables ?? {};
+    if (!object(variables))
+        throw new Error(`Snippet ${id}.variables must be a mapping`);
+    for (const [name, variable] of Object.entries(variables)) {
+        if (!safeName(name) || !object(variable))
+            throw new Error(`Invalid snippet variable ${id}.${name}`);
+        for (const key of Object.keys(variable))
+            if (!['type', 'required', 'default', 'enum'].includes(key))
+                throw new Error(`Unknown snippet variable setting ${id}.${name}.${key}`);
+        if (!['string', 'number', 'boolean'].includes(variable.type))
+            throw new Error(`Snippet ${id}.${name} needs a scalar type`);
+        if (variable.required !== undefined && typeof variable.required !== 'boolean')
+            throw new Error(`Snippet ${id}.${name}.required must be boolean`);
+        if (variable.default !== undefined && typeof variable.default !== variable.type)
+            throw new Error(`Snippet ${id}.${name}.default must be ${variable.type}`);
+        if (variable.enum !== undefined && (!Array.isArray(variable.enum) || !variable.enum.length || variable.enum.some((item) => typeof item !== variable.type)))
+            throw new Error(`Snippet ${id}.${name}.enum must contain ${variable.type} values`);
+        if (variable.default !== undefined && variable.enum && !variable.enum.includes(variable.default))
+            throw new Error(`Snippet ${id}.${name}.default is not in its enum`);
+    }
+    return variables;
+}
+function literal(node) {
+    if (node?.type === 'Literal' && ['string', 'number', 'boolean'].includes(typeof node.value))
+        return node.value;
+    if (node?.type === 'ObjectExpression') {
+        const result = {};
+        for (const property of node.properties ?? []) {
+            if (property.type !== 'Property' || property.computed || property.method || property.shorthand || property.kind !== 'init')
+                throw new Error('Snippet values must be literal properties');
+            const name = property.key.type === 'Identifier' ? property.key.name : property.key.type === 'Literal' ? property.key.value : null;
+            if (typeof name !== 'string' || !safeName(name) || Object.prototype.hasOwnProperty.call(result, name))
+                throw new Error(`Invalid snippet value name ${name}`);
+            result[name] = literal(property.value);
+        }
+        return result;
+    }
+    throw new Error('Snippet values must be literal strings, numbers, or booleans');
+}
+export function snippetAttribute(attribute, label) {
+    if (typeof attribute.value === 'string')
+        return attribute.value;
+    const program = attribute.value?.data?.estree;
+    if (program?.body?.length === 1 && program.body[0].type === 'ExpressionStatement')
+        return literal(program.body[0].expression);
+    throw new Error(`${label}: snippet attributes must be literal values`);
+}
+export function resolveSnippetValues(id, definition, projectValues, pageValues, invocation) {
+    if (projectValues !== undefined && !object(projectValues))
+        throw new Error('Project variables must be a mapping');
+    if (pageValues !== undefined && !object(pageValues))
+        throw new Error('Page variables must be a mapping');
+    const values = {};
+    for (const [name, variable] of Object.entries(definition.variables)) {
+        const value = invocation[name] ?? pageValues?.[name] ?? projectValues?.[name] ?? variable.default;
+        if (value === undefined) {
+            if (variable.required)
+                throw new Error(`Snippet ${id} requires variable ${name}`);
+            continue;
+        }
+        if (typeof value !== variable.type)
+            throw new Error(`Snippet ${id}.${name} must be ${variable.type}`);
+        if (variable.enum && !variable.enum.includes(value))
+            throw new Error(`Snippet ${id}.${name} is not in its enum`);
+        values[name] = value;
+    }
+    for (const name of Object.keys(invocation))
+        if (!(name in definition.variables))
+            throw new Error(`Unknown snippet variable ${id}.${name}`);
+    return values;
+}