@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/markdown.js

@@ -0,0 +1,612 @@
+/**
+ * A small, dependency-free, deterministic Markdown renderer (CommonMark-ish).
+ *
+ * Blocks: ATX headings (#..######, optional closing #s), setext headings,
+ * paragraphs (hard break = two trailing spaces or a trailing backslash),
+ * fenced code (``` and ~~~, info word becomes class="language-x" when it is
+ * [A-Za-z0-9_+-]+), indented code, blockquotes (recursive, lazy continuation),
+ * bullet lists (- * +) and ordered lists (1. / 1), `start` kept when not 1),
+ * nesting by indentation, tight vs loose lists, thematic breaks (--- *** ___).
+ *
+ * Inlines: backslash escapes, code spans, **strong** / __strong__, *em* /
+ * _em_ (intraword `_` is literal), ~~del~~, [text](url "title"),
+ * ![alt](url "title"), <autolinks>. Emphasis that does not close stays literal.
+ *
+ * Not supported: reference links, HTML entities (`&` is always escaped, so
+ * `&amp;` shows literally), tables, footnotes, task lists.
+ *
+ * Safety: raw HTML is never passed through; every `<` in the source is
+ * escaped. Link and image URLs must be http, https, mailto, relative,
+ * `#fragment` or `/absolute`; anything else (javascript:, data:, ...) is
+ * rendered as plain text without an <a> / <img>.
+ */
+const MAX_DEPTH = 32;
+const EXCERPT_MAX = 200;
+// ---------------------------------------------------------------- escaping
+export function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => (c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;'));
+}
+/** Scheme check on a URL stripped of whitespace/control characters. */
+function isSafeUrl(url) {
+    const stripped = url.replace(/[\u0000-\u0020\u007f-\u009f\u00ad\u200b-\u200f\u2028\u2029\ufeff]/g, '');
+    const m = /^([^:/?#]*):/.exec(stripped);
+    return m === null || /^(https?|mailto)$/i.test(m[1] ?? '');
+}
+function encodeUrl(url) {
+    return escapeHtml(url.replace(/[\u0000-\u001f\u007f]/g, '').replace(/ /g, '%20'));
+}
+const unescapeMd = (s) => s.replace(/\\([!-/:-@[-`{-~])/g, '$1');
+const isPunct = (c) => c !== undefined && /[\p{P}\p{S}]/u.test(c);
+const isSpace = (c) => c === undefined || /\s/.test(c);
+/** Index of the `]` matching an already-opened `[` (scan starts at `from`), or -1. */
+function findCloseBracket(s, from) {
+    let depth = 1;
+    for (let j = from; j < s.length; j++) {
+        const c = s[j];
+        if (c === '\\')
+            j++;
+        else if (c === '`') {
+            const run = /^`+/.exec(s.slice(j))?.[0] ?? '`';
+            const end = s.indexOf(run, j + run.length);
+            j = end === -1 ? j + run.length - 1 : end + run.length - 1;
+        }
+        else if (c === '[')
+            depth++;
+        else if (c === ']' && --depth === 0)
+            return j;
+    }
+    return -1;
+}
+/** Parse `(dest "title")` starting at the `(` at s[k]. */
+function parseDestination(s, k) {
+    const ws = (i) => {
+        while (i < s.length && /[ \t\n]/.test(s[i]))
+            i++;
+        return i;
+    };
+    let i = ws(k + 1);
+    let href;
+    if (s[i] === '<') {
+        let j = i + 1;
+        while (j < s.length && s[j] !== '>' && s[j] !== '<' && s[j] !== '\n')
+            j++;
+        if (s[j] !== '>')
+            return null;
+        href = unescapeMd(s.slice(i + 1, j));
+        i = j + 1;
+    }
+    else {
+        const start = i;
+        let depth = 0;
+        while (i < s.length) {
+            const c = s[i];
+            if (c === '\\' && i + 1 < s.length) {
+                i += 2;
+                continue;
+            }
+            if (/[\s\u0000-\u001f]/.test(c))
+                break;
+            if (c === '(')
+                depth++;
+            else if (c === ')') {
+                if (depth === 0)
+                    break;
+                depth--;
+            }
+            i++;
+        }
+        if (depth !== 0)
+            return null;
+        href = unescapeMd(s.slice(start, i));
+    }
+    const afterDest = i;
+    i = ws(i);
+    if (s[i] === ')')
+        return { href, title: null, end: i + 1 };
+    const open = s[i];
+    const close = open === '"' ? '"' : open === "'" ? "'" : open === '(' ? ')' : null;
+    if (close === null || i === afterDest)
+        return null;
+    let j = i + 1;
+    while (j < s.length && s[j] !== close)
+        j += s[j] === '\\' ? 2 : 1;
+    if (j >= s.length)
+        return null;
+    const title = unescapeMd(s.slice(i + 1, j));
+    j = ws(j + 1);
+    return s[j] === ')' ? { href, title, end: j + 1 } : null;
+}
+function parseInline(s, depth) {
+    const items = [];
+    let buf = '';
+    const flush = () => {
+        if (buf !== '')
+            items.push({ t: 'text', v: buf });
+        buf = '';
+    };
+    let i = 0;
+    while (i < s.length) {
+        const c = s[i];
+        const next = s[i + 1];
+        if (c === '\\') {
+            if (next === '\n') {
+                flush();
+                items.push({ t: 'br' });
+                i += 2;
+            }
+            else if (next !== undefined && /[!-/:-@[-`{-~]/.test(next)) {
+                buf += next;
+                i += 2;
+            }
+            else {
+                buf += c;
+                i++;
+            }
+        }
+        else if (c === '\n') {
+            const spaces = /( *)$/.exec(buf)?.[1]?.length ?? 0;
+            buf = buf.slice(0, buf.length - spaces);
+            if (spaces >= 2) {
+                flush();
+                items.push({ t: 'br' });
+            }
+            else {
+                buf += '\n';
+            }
+            i++;
+        }
+        else if (c === '`') {
+            const run = /^`+/.exec(s.slice(i))?.[0] ?? '`';
+            let end = -1;
+            for (let j = s.indexOf('`', i + run.length); j !== -1;) {
+                const r = /^`+/.exec(s.slice(j))?.[0] ?? '`';
+                if (r.length === run.length) {
+                    end = j;
+                    break;
+                }
+                j = s.indexOf('`', j + r.length);
+            }
+            if (end === -1) {
+                buf += run;
+                i += run.length;
+            }
+            else {
+                let code = s.slice(i + run.length, end).replace(/\n/g, ' ');
+                if (code.length > 2 && code.startsWith(' ') && code.endsWith(' ') && code.trim() !== '')
+                    code = code.slice(1, -1);
+                flush();
+                items.push({ t: 'code', v: code });
+                i = end + run.length;
+            }
+        }
+        else if (c === '*' || c === '_' || c === '~') {
+            let n = 1;
+            while (s[i + n] === c)
+                n++;
+            if (c === '~' && n !== 2) {
+                buf += c.repeat(n);
+                i += n;
+                continue;
+            }
+            const before = s[i - 1];
+            const after = s[i + n];
+            const left = !isSpace(after) && (!isPunct(after) || isSpace(before) || isPunct(before));
+            const right = !isSpace(before) && (!isPunct(before) || isSpace(after) || isPunct(after));
+            const open = c === '_' ? left && (!right || isPunct(before)) : left;
+            const close = c === '_' ? right && (!left || isPunct(after)) : right;
+            flush();
+            items.push({ t: 'delim', ch: c, n, orig: n, open, close });
+            i += n;
+        }
+        else if (c === '[' || (c === '!' && next === '[')) {
+            const isImg = c === '!';
+            const labelStart = i + (isImg ? 2 : 1);
+            const closeIdx = depth < MAX_DEPTH ? findCloseBracket(s, labelStart) : -1;
+            const dest = closeIdx !== -1 && s[closeIdx + 1] === '(' ? parseDestination(s, closeIdx + 1) : null;
+            if (closeIdx === -1 || dest === null) {
+                buf += isImg ? '![' : '[';
+                i = labelStart;
+                continue;
+            }
+            const children = parseInline(s.slice(labelStart, closeIdx), depth + 1);
+            flush();
+            if (isImg) {
+                const alt = nodesToText(children);
+                items.push(isSafeUrl(dest.href) ? { t: 'img', src: dest.href, alt, title: dest.title } : { t: 'text', v: alt });
+            }
+            else if (isSafeUrl(dest.href)) {
+                items.push({ t: 'link', href: dest.href, title: dest.title, c: children });
+            }
+            else {
+                items.push(...children);
+            }
+            i = dest.end;
+        }
+        else if (c === '<') {
+            const auto = /^<([A-Za-z][A-Za-z0-9+.-]{1,31}:[^\s<>]*)>/.exec(s.slice(i));
+            const mail = /^<([A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+)>/.exec(s.slice(i));
+            if (auto && isSafeUrl(auto[1])) {
+                flush();
+                items.push({ t: 'link', href: auto[1], title: null, c: [{ t: 'text', v: auto[1] }] });
+                i += auto[0].length;
+            }
+            else if (mail) {
+                flush();
+                items.push({ t: 'link', href: `mailto:${mail[1]}`, title: null, c: [{ t: 'text', v: mail[1] }] });
+                i += mail[0].length;
+            }
+            else {
+                buf += c;
+                i++;
+            }
+        }
+        else {
+            buf += c;
+            i++;
+        }
+    }
+    flush();
+    return resolveEmphasis(items);
+}
+const delimToText = (it) => (it.t === 'delim' ? { t: 'text', v: it.ch.repeat(it.n) } : it);
+/** CommonMark-style delimiter matching, simplified. */
+function resolveEmphasis(items) {
+    for (let ci = 0; ci < items.length; ci++) {
+        const closer = items[ci];
+        if (closer?.t !== 'delim' || !closer.close)
+            continue;
+        while (closer.n > 0) {
+            let oi = -1;
+            for (let k = ci - 1; k >= 0; k--) {
+                const o = items[k];
+                if (o?.t !== 'delim' || o.ch !== closer.ch || !o.open || o.n === 0)
+                    continue;
+                const rule3 = (o.close || closer.open) && (o.orig + closer.orig) % 3 === 0 && !(o.orig % 3 === 0 && closer.orig % 3 === 0);
+                if (rule3)
+                    continue;
+                oi = k;
+                break;
+            }
+            if (oi === -1)
+                break;
+            const opener = items[oi];
+            const use = closer.ch === '~' ? 2 : opener.n >= 2 && closer.n >= 2 ? 2 : 1;
+            const tag = closer.ch === '~' ? 'del' : use === 2 ? 'strong' : 'em';
+            const inner = items.slice(oi + 1, ci).map(delimToText);
+            opener.n -= use;
+            closer.n -= use;
+            items.splice(oi + 1, ci - oi - 1, { t: 'wrap', tag, c: inner });
+            ci = oi + 2;
+            if (opener.n === 0) {
+                items.splice(oi, 1);
+                ci--;
+            }
+            if (closer.n === 0) {
+                items.splice(ci, 1);
+                ci--;
+                break;
+            }
+        }
+    }
+    return items.map(delimToText);
+}
+function nodesToText(nodes) {
+    return nodes
+        .map((n) => {
+        switch (n.t) {
+            case 'text':
+            case 'code':
+                return n.v;
+            case 'br':
+                return ' ';
+            case 'img':
+                return n.alt;
+            default:
+                return nodesToText(n.c);
+        }
+    })
+        .join('');
+}
+function nodesToHtml(nodes) {
+    return nodes
+        .map((n) => {
+        switch (n.t) {
+            case 'text':
+                return escapeHtml(n.v);
+            case 'code':
+                return `<code>${escapeHtml(n.v)}</code>`;
+            case 'br':
+                return '<br>\n';
+            case 'wrap':
+                return `<${n.tag}>${nodesToHtml(n.c)}</${n.tag}>`;
+            case 'link':
+                return `<a href="${encodeUrl(n.href)}"${n.title === null ? '' : ` title="${escapeHtml(n.title)}"`}>${nodesToHtml(n.c)}</a>`;
+            case 'img':
+                return `<img src="${encodeUrl(n.src)}" alt="${escapeHtml(n.alt)}"${n.title === null ? '' : ` title="${escapeHtml(n.title)}"`}>`;
+        }
+    })
+        .join('');
+}
+const FENCE_RE = /^( {0,3})(`{3,}|~{3,})(.*)$/;
+const ATX_RE = /^ {0,3}(#{1,6})(?:[ \t]+(.*)|[ \t]*)$/;
+const HR_RE = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/;
+const LIST_RE = /^( {0,3})([-*+]|\d{1,9}[.)])( +|$)(.*)$/;
+const QUOTE_RE = /^ {0,3}>/;
+const isBlank = (l) => l.trim() === '';
+const indentOf = (l) => /^ */.exec(l)?.[0].length ?? 0;
+const isHr = (l) => HR_RE.test(l);
+const listKey = (m) => m[2].slice(-1);
+/** Can this line interrupt a paragraph? */
+function interruptsParagraph(l) {
+    const fence = FENCE_RE.exec(l);
+    if (fence && !(fence[2]?.startsWith('`') && (fence[3] ?? '').includes('`')))
+        return true;
+    if (ATX_RE.test(l) || isHr(l) || QUOTE_RE.test(l))
+        return true;
+    const m = LIST_RE.exec(l);
+    return m !== null && (m[4] ?? '') !== '' && (/^[-*+]/.test(m[2]) || parseInt(m[2], 10) === 1);
+}
+function makeParagraph(lines, st) {
+    const text = lines.map((l) => l.trimStart()).join('\n').trimEnd();
+    const nodes = parseInline(text, 0);
+    if (st.excerpt === null) {
+        const plain = nodesToText(nodes).replace(/\s+/g, ' ').trim();
+        if (plain !== '')
+            st.excerpt = plain;
+    }
+    const inner = nodesToHtml(nodes);
+    return { html: `<p>${inner}</p>`, para: inner, blankBefore: false };
+}
+function parseBlocks(lines, st, depth) {
+    if (depth > MAX_DEPTH) {
+        const text = lines.filter((l) => !isBlank(l));
+        return text.length ? [makeParagraph(text, st)] : [];
+    }
+    const out = [];
+    let blank = false;
+    const push = (b) => {
+        out.push({ ...b, blankBefore: blank && out.length > 0 });
+        blank = false;
+    };
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (isBlank(line)) {
+            blank = true;
+            i++;
+            continue;
+        }
+        // fenced code
+        const fence = FENCE_RE.exec(line);
+        if (fence && !(fence[2]?.startsWith('`') && (fence[3] ?? '').includes('`'))) {
+            const indent = fence[1]?.length ?? 0;
+            const marker = fence[2];
+            const closeRe = new RegExp(`^ {0,3}${marker[0] === '`' ? '`' : '~'}{${marker.length},}[ \\t]*$`);
+            const info = (fence[3] ?? '').trim().split(/\s+/)[0] ?? '';
+            const body = [];
+            i++;
+            while (i < lines.length && !closeRe.test(lines[i])) {
+                const l = lines[i];
+                body.push(l.slice(Math.min(indent, indentOf(l))));
+                i++;
+            }
+            i++; // closing fence (or past the end for an unterminated one)
+            push(codeBlock(body, info));
+            continue;
+        }
+        // ATX heading
+        const atx = ATX_RE.exec(line);
+        if (atx) {
+            const level = atx[1].length;
+            const content = (atx[2] ?? '').replace(/(^|[ \t]+)#+[ \t]*$/, '').trim();
+            push(heading(level, content));
+            i++;
+            continue;
+        }
+        if (isHr(line)) {
+            push({ html: '<hr>', blankBefore: false });
+            i++;
+            continue;
+        }
+        // blockquote
+        if (QUOTE_RE.test(line)) {
+            const inner = [];
+            while (i < lines.length) {
+                const l = lines[i];
+                if (QUOTE_RE.test(l)) {
+                    inner.push(l.replace(/^ {0,3}> ?/, ''));
+                }
+                else if (!isBlank(l) && inner.length > 0 && !isBlank(inner[inner.length - 1]) && !interruptsParagraph(l)) {
+                    inner.push(l); // lazy continuation
+                }
+                else
+                    break;
+                i++;
+            }
+            const blocks = parseBlocks(inner, st, depth + 1);
+            push({ html: `<blockquote>\n${blocks.map((b) => b.html + '\n').join('')}</blockquote>`, blankBefore: false });
+            continue;
+        }
+        // list
+        const lm = LIST_RE.exec(line);
+        if (lm) {
+            const res = parseList(lines, i, st, depth);
+            push(res.block);
+            i = res.next;
+            continue;
+        }
+        // indented code
+        if (indentOf(line) >= 4) {
+            const body = [];
+            while (i < lines.length && (isBlank(lines[i]) || indentOf(lines[i]) >= 4)) {
+                body.push(lines[i].slice(4));
+                i++;
+            }
+            while (body.length && isBlank(body[body.length - 1]))
+                body.pop();
+            push(codeBlock(body, ''));
+            continue;
+        }
+        // paragraph / setext heading
+        const para = [line];
+        i++;
+        let setext = 0;
+        while (i < lines.length) {
+            const l = lines[i];
+            if (isBlank(l))
+                break;
+            if (/^ {0,3}=+[ \t]*$/.test(l))
+                setext = 1;
+            else if (/^ {0,3}-+[ \t]*$/.test(l))
+                setext = 2;
+            if (setext) {
+                i++;
+                break;
+            }
+            if (interruptsParagraph(l))
+                break;
+            para.push(l);
+            i++;
+        }
+        if (setext) {
+            const text = para.map((l) => l.trim()).join('\n');
+            push(heading(setext, text, para));
+        }
+        else {
+            push(makeParagraph(para, st));
+        }
+    }
+    return out;
+    function heading(level, content, src) {
+        if (src) {
+            const p = makeParagraph(src, st); // records the excerpt like a paragraph
+            return { html: `<h${level}>${p.para}</h${level}>`, blankBefore: false };
+        }
+        return { html: `<h${level}>${nodesToHtml(parseInline(content, 0))}</h${level}>`, blankBefore: false };
+    }
+}
+function codeBlock(body, info) {
+    const cls = /^[A-Za-z0-9_+-]+$/.test(info) ? ` class="language-${info}"` : '';
+    const text = body.length ? escapeHtml(body.join('\n')) + '\n' : '';
+    return { html: `<pre><code${cls}>${text}</code></pre>`, blankBefore: false };
+}
+function parseList(lines, start, st, depth) {
+    const first = LIST_RE.exec(lines[start]);
+    const key = listKey(first);
+    const ordered = /\d/.test(first[2]);
+    const startNum = ordered ? parseInt(first[2], 10) : 1;
+    const items = [];
+    let loose = false;
+    let i = start;
+    const siblingAt = (idx) => {
+        const l = lines[idx];
+        if (l === undefined || isHr(l))
+            return null;
+        const m = LIST_RE.exec(l);
+        return m && listKey(m) === key ? m : null;
+    };
+    while (i < lines.length) {
+        const m = siblingAt(i);
+        if (!m)
+            break;
+        const base = m[1].length;
+        const markerLen = m[2].length;
+        const spaces = m[3].length;
+        let rest = m[4];
+        let contentIndent;
+        if (rest === '')
+            contentIndent = base + markerLen + 1;
+        else if (spaces > 4) {
+            contentIndent = base + markerLen + 1;
+            rest = ' '.repeat(spaces - 1) + rest;
+        }
+        else
+            contentIndent = base + markerLen + spaces;
+        const body = [rest];
+        i++;
+        while (i < lines.length) {
+            const l = lines[i];
+            if (isBlank(l)) {
+                let j = i;
+                while (j < lines.length && isBlank(lines[j]))
+                    j++;
+                if (j < lines.length && indentOf(lines[j]) >= contentIndent) {
+                    for (; i < j; i++)
+                        body.push('');
+                    continue;
+                }
+                break;
+            }
+            if (indentOf(l) >= contentIndent) {
+                body.push(l.slice(contentIndent));
+            }
+            else if (siblingAt(i) || LIST_RE.test(l) || isHr(l) || interruptsParagraph(l) || isBlank(body[body.length - 1])) {
+                break;
+            }
+            else {
+                body.push(l.trimStart()); // lazy continuation
+            }
+            i++;
+        }
+        items.push(body);
+        let j = i;
+        while (j < lines.length && isBlank(lines[j]))
+            j++;
+        if (j > i && siblingAt(j)) {
+            loose = true;
+            i = j;
+        }
+        else if (j === i)
+            continue;
+        else
+            break;
+    }
+    const rendered = items.map((body) => parseBlocks(body, st, depth + 1));
+    if (rendered.some((blocks) => blocks.some((b, k) => k > 0 && b.blankBefore)))
+        loose = true;
+    const lis = rendered.map((blocks) => {
+        if (blocks.length === 0)
+            return '<li></li>';
+        let inner = '';
+        blocks.forEach((b, k) => {
+            if (!loose && b.para !== undefined)
+                inner += (k > 0 ? '\n' : '') + b.para;
+            else
+                inner += '\n' + b.html;
+        });
+        const last = blocks[blocks.length - 1];
+        if (loose || last.para === undefined)
+            inner += '\n';
+        return `<li>${inner}</li>`;
+    });
+    const tag = ordered ? 'ol' : 'ul';
+    const attr = ordered && startNum !== 1 ? ` start="${startNum}"` : '';
+    return { block: { html: `<${tag}${attr}>\n${lis.join('\n')}\n</${tag}>`, blankBefore: false }, next: i };
+}
+// ------------------------------------------------------------------ excerpt
+function truncate(text) {
+    if (text.length <= EXCERPT_MAX)
+        return text;
+    let cut = text.slice(0, EXCERPT_MAX - 1);
+    if (text[EXCERPT_MAX - 1] !== ' ') {
+        const sp = cut.lastIndexOf(' ');
+        if (sp > 0)
+            cut = cut.slice(0, sp);
+    }
+    cut = cut.trimEnd();
+    if (/[\ud800-\udbff]$/.test(cut))
+        cut = cut.slice(0, -1);
+    return cut + '…';
+}
+export function renderMarkdown(src) {
+    const normalized = src
+        .replace(/\r\n?/g, '\n')
+        .replace(/\u0000/g, '�')
+        .split('\n')
+        .map((l) => l.replace(/^[ \t]+/, (ws) => ws.replace(/\t/g, '    ')));
+    const st = { excerpt: null };
+    const blocks = parseBlocks(normalized, st, 0);
+    const html = blocks.map((b) => b.html + '\n').join('');
+    return { html, excerpt: truncate(st.excerpt ?? '') };
+}
+//# sourceMappingURL=markdown.js.map

package/lib/src/media.d.ts

@@ -0,0 +1,82 @@
+import { type SourceSpan } from './errors.js';
+/** Helpers that produce a value (escaped like any substituted value). */
+export declare const VALUE_HELPERS: readonly ['url', 'width', 'height', 'type', 'size', 'integrity', 'datauri', 'srcset'];
+/** Helpers that write a tag (trusted markup: inserted as-is; every attribute value is escaped). */
+export declare const TAG_HELPERS: readonly ['img', 'video', 'audio', 'source', 'script', 'stylesheet', 'preload', 'modulepreload', 'pre', 'svg'];
+export declare const FILE_HELPERS: readonly string[];
+/** The largest file `datauri` inlines. */
+export declare const DATAURI_MAX = 32768;
+/** The lowercase extension of a path's last segment ('' if none). */
+export declare function extensionOf(path: string): string;
+/** The media type of a path, by extension (`application/octet-stream` when unknown). */
+export declare function mediaType(path: string): string;
+export declare function isImagePath(path: string): boolean;
+/** The URL of a tree path: each segment percent-encoded like `encodeURIComponent`. */
+export declare function fileUrl(path: string): string;
+/** `sha384-<base64>`, the subresource integrity of `bytes`. */
+export declare function integrityOf(bytes: Uint8Array): string;
+export interface ImageSize {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * The width and height of an image file, from its header (PNG, JPEG, GIF, WebP, AVIF): bounded reads,
+ * no decoding. undefined for an SVG (its size is in its markup, often relative). E_DATA when the
+ * bytes are no supported image, or the header is truncated or malformed.
+ */
+export declare function imageSize(bytes: Uint8Array, path: string): ImageSize | undefined;
+/** A file of the tree a helper writes markup for. */
+export interface TreeFile {
+    /** Its normalized absolute tree path. */
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+/** An attribute written in the template: `alt="…"` (value) or `controls` (bare). */
+export interface HelperAttr {
+    readonly name: string;
+    readonly value?: string;
+}
+/** What a helper produced: markup (inserted as-is) or a value (escaped like any `${…}`). */
+export type HelperOutput = {
+    readonly markup: string;
+} | {
+    readonly value: string;
+};
+/** The files of the stage's tree at a RENDER, as `${file …}` sees them. */
+export interface TemplateTree {
+    get(path: string): Uint8Array | undefined;
+    isDirectory(path: string): boolean;
+    /** Where a FINGERPRINT earlier in the stage moved `path` (its content-hashed name), if it did. */
+    renamed?(path: string): string | undefined;
+}
+export interface HelperOptions {
+    /** RENDER --inline-svg: the svg helper may paste SVG markup into the page. */
+    readonly inlineSvg: boolean;
+}
+/** The file `${file "<raw>"}` names: an absolute path in the tree (E_PATH, E_TYPE, E_NOT_FOUND otherwise). */
+export declare function resolveFile(raw: string, tree: TemplateTree, span: SourceSpan): TreeFile;
+/**
+ * What `${file "<raw>" | helper attrs…}` writes (`helper` undefined: the file's URL). A value is
+ * escaped by the caller like any substituted value; markup is inserted as it is.
+ */
+export declare function renderFile(raw: string, helper: string | undefined, attrs: readonly HelperAttr[], tree: TemplateTree, opts: HelperOptions, span: SourceSpan): HelperOutput;
+/** What `helper` writes for file `f` (`undefined`: no helper, the file's URL). */
+export declare function renderFileHelper(helper: string | undefined, f: TreeFile, attrs: readonly HelperAttr[], opts: HelperOptions, span: SourceSpan): HelperOutput;
+/** The image plugin's `<name>.json` (docs/PLUGINS.md, "The metadata file"), version 1: what the helpers read. */
+export interface ImageMetadata {
+    /** The metadata file's tree path (for messages). */
+    readonly path: string;
+    readonly src: string;
+    readonly type: string;
+    readonly width: number;
+    readonly height: number;
+    readonly srcset: string;
+    readonly sources: ReadonlyArray<{
+        readonly type: string;
+        readonly srcset: string;
+    }>;
+}
+/** The metadata version this sitefile reads. */
+export declare const IMAGE_METADATA_VERSION = 1;
+/** `/dir/name.ext` -> `/dir/name.json` ('' for a path without an extension). */
+export declare function metadataPathOf(path: string): string;