@dogsbay/render-html 0.0.0-stage → 0.2.0-beta.116

package/dist/render.js

@@ -0,0 +1,830 @@
+import { parseInline } from "@dogsbay/format-dogsbay-md/browser";
+import { attrs, esc, FOREIGN_END, FOREIGN_START, passthrough, slugify, unesc } from "./html.js";
+import { CALLOUTS, hasIcon, icon } from "./icons.js";
+import { badgeClass } from "./badge-variants.js";
+import { KBD_CLASS } from "./kbd-variants.js";
+import { TONE_CLASSES } from "./tone-classes.js";
+import { fileTreeHtml } from "./file-tree.js";
+import { stripMarkersForCopy } from "./code-markers.js";
+import { icons as ALERT_ICONS, chevronSvg as ALERT_CHEVRON } from "./alert-icons.js";
+import { parseLineRanges, plainHighlighter } from "./lines.js";
+import { scriptUrl } from "./url.js";
+export { FOREIGN_END, FOREIGN_START };
+export { scriptUrl };
+/** ctx.link, unless the target is a script link: then "#", and it is reported. */
+export function linkUrl(href, ctx) {
+    if (scriptUrl(href, "link")) {
+        ctx.unsafeUrls?.add(href.slice(0, 80));
+        return "#";
+    }
+    return ctx.link(href);
+}
+/** ctx.asset, unless the source is a script URL: then empty, and it is reported. */
+export function assetUrl(src, ctx) {
+    if (scriptUrl(src, "image")) {
+        ctx.unsafeUrls?.add(src.slice(0, 80));
+        return "";
+    }
+    return ctx.asset(src);
+}
+/**
+ * LaTeX → HTML with MathML for screen readers, at build time: no script on
+ * the page. As `@dogsbay/ui`'s MathKatex; a formula KaTeX cannot parse is
+ * shown in the error colour instead of failing the build.
+ */
+export function renderMath(latex, display, ctx) {
+    if (!ctx.math)
+        return undefined;
+    ctx.usedMath = true;
+    try {
+        const html = ctx.math(latex, display);
+        if (typeof html !== "string")
+            throw new TypeError("math renderer returned no string");
+        // The region must end where the formula ends, or classes after it would be skipped by the stylesheet build.
+        return `${FOREIGN_START}${html.replaceAll(FOREIGN_START, "").replaceAll(FOREIGN_END, "")}${FOREIGN_END}`;
+    }
+    catch {
+        return `<code class="text-destructive">${esc(latex)}</code>`;
+    }
+}
+/**
+ * Ids the layout and components generate. A heading that would take one gets an
+ * "h-" prefix, so it cannot shadow the search dialog, a nav group or a tab.
+ */
+const RESERVED_ID = /^(db-|tab-\d|tabpanel-\d|acc-\d|accpanel-\d|fn-|fnref-)/;
+export function uniqueId(ctx, base) {
+    if (RESERVED_ID.test(base))
+        base = `h-${base}`;
+    let id = base || "section";
+    let n = 1;
+    while (ctx.ids.has(id))
+        id = `${base}-${++n}`;
+    ctx.ids.add(id);
+    return id;
+}
+// ─── Inline ──────────────────────────────────────────────────────────
+export function renderInline(nodes, ctx) {
+    if (!nodes)
+        return "";
+    let out = "";
+    for (const n of nodes)
+        out += inline(n, ctx);
+    return out;
+}
+function decorate(html, n) {
+    if (n.strikethrough)
+        html = `<del>${html}</del>`;
+    if (n.italic)
+        html = `<em>${html}</em>`;
+    if (n.bold)
+        html = `<strong>${html}</strong>`;
+    return html;
+}
+function inline(n, ctx) {
+    switch (n.type) {
+        case "text":
+            return decorate(esc(n.text), n);
+        case "code":
+            return decorate(`<code>${esc(n.text)}</code>`, n);
+        case "link": {
+            const href = linkUrl(n.href, ctx);
+            const external = /^[a-z][a-z0-9+.-]*:|^\/\//i.test(href) && !href.startsWith("mailto:");
+            // An inline `:button`: Button.astro's classes at its small size, as the Astro pipeline renders it.
+            const variant = n.button ? buttonVariant(n.button.variant) : undefined;
+            const a = {
+                // Button.astro's small size, whose text-xs replaces the base text-sm (tailwind-merge in tv()).
+                ...passthrough(n.attrs, variant ? `${BUTTON_BASE.split(" ").filter((c) => c !== "text-sm").join(" ")} ${BUTTON_VARIANTS[variant] ?? BUTTON_VARIANTS.default} h-9 px-3 text-xs no-underline` : undefined),
+                href,
+                title: n.title,
+                "data-variant": variant,
+                "data-size": variant ? "sm" : undefined,
+            };
+            if (external)
+                a.rel = "noopener";
+            // A button carries no link icon (the icon rules skip [data-variant]); it is not marked.
+            if (!variant)
+                a["data-link-kind"] = external ? "external" : href.startsWith("#") ? undefined : "internal";
+            return `<a${attrs(a)}>${insideLink(true, ctx, () => renderInline(n.children, ctx))}</a>`;
+        }
+        case "image": {
+            const at = (n.attrs ?? {});
+            return `<img${attrs({
+                ...passthrough(at),
+                src: assetUrl(n.src, ctx),
+                alt: n.alt ?? "",
+                title: n.title,
+                width: n.width ?? at.width,
+                height: n.height ?? at.height,
+                loading: "lazy",
+                decoding: "async",
+                // As @dogsbay/plugin-image-zoom's walker: the link's own click wins over zooming. An author's
+                // own data-zoomable (to opt one image out with "false") is kept.
+                "data-zoomable": at["data-zoomable"] ?? (ctx.imageZoom && !(ctx.inLink && ctx.imageZoom === "outside-links") ? "true" : undefined),
+            })}>`;
+        }
+        case "highlight":
+            return `<mark class="rounded-sm bg-yellow-200/60 px-0.5 dark:bg-yellow-500/30">${renderInline(n.children, ctx)}</mark>`;
+        case "footnote-ref": {
+            const label = esc(n.label);
+            const refs = (ctx.fnRefs ??= new Map());
+            const count = (refs.get(n.label) ?? 0) + 1;
+            refs.set(n.label, count);
+            // The first reference is the backlink target; repeats get their own ids.
+            const id = count === 1 ? `fnref-${label}` : `fnref-${label}-${count}`;
+            return `<sup><a id="${id}" href="#fn-${label}" role="doc-noteref" class="text-primary hover:underline">[${label}]</a></sup>`;
+        }
+        case "kbd":
+            // Kbd.astro's keycap classes (synced from @dogsbay/ui).
+            return n.keys.map((k) => `<kbd class="${KBD_CLASS}">${esc(k)}</kbd>`).join("+");
+        case "badge": {
+            const variant = n.variant ?? "default";
+            return `<span${attrs({ ...passthrough(n.attrs, badgeClass(variant)), "data-variant": variant })}>${esc(n.text)}</span>`;
+        }
+        case "icon":
+            return namedIcon((n.library ? n.library + ":" : "") + n.name, "db-icon db-icon-inline", ctx);
+        case "math":
+            return renderMath(n.latex, false, ctx) ?? `<code class="db-math">${esc(n.latex)}</code>`;
+        case "html-inline":
+            return rewriteHtml(n.html, ctx);
+        case "break":
+            return "<br>";
+        default:
+            ctx.unknown.add(`inline:${n.type}`);
+            return "";
+    }
+}
+/** Plain text of inline nodes (for TOC entries, titles and search). */
+export function inlineText(nodes) {
+    if (!nodes)
+        return "";
+    let out = "";
+    for (const n of nodes) {
+        switch (n.type) {
+            case "text":
+            case "code":
+                out += n.text;
+                break;
+            case "link":
+            case "highlight":
+                out += inlineText(n.children);
+                break;
+            case "kbd":
+                out += n.keys.join("+");
+                break;
+            case "badge":
+                out += n.text;
+                break;
+            case "math":
+                out += n.latex;
+                break;
+            case "image":
+                out += n.alt ?? "";
+                break;
+            case "html-inline":
+                out += n.html.replace(/<[^>]*>/g, "");
+                break;
+        }
+    }
+    return out;
+}
+/** URL attributes the host does not rewrite, and unquoted values: only the script-link check. */
+const SCRIPT_ATTRS = /(\s)(href|src|xlink:href|action|formaction|poster|data)(\s*=\s*)("[^"]*"|'[^']*'|[^\s"'=<>`]+)/gi;
+function refuseScriptAttrs(tag, ctx) {
+    return tag.replace(SCRIPT_ATTRS, (m, sp, attr, eq, raw) => {
+        const quoted = raw.startsWith('"') || raw.startsWith("'");
+        const lower = attr.toLowerCase();
+        // Quoted href and src are checked (and rewritten) by rewriteHtml itself.
+        if (quoted && (lower === "href" || lower === "src"))
+            return m;
+        const v = unesc(quoted ? raw.slice(1, -1) : raw);
+        if (!scriptUrl(v, lower === "src" || lower === "poster" ? "image" : "link"))
+            return m;
+        ctx.unsafeUrls?.add(v.slice(0, 80));
+        return `${sp}${attr}${eq}"${lower === "href" ? "#" : ""}"`;
+    });
+}
+/**
+ * Rewrite href/src attributes of tags in raw HTML so root-relative links follow
+ * the site layout. Only attributes inside a start tag are touched (not text such
+ * as an escaped code example, nor data-href), and values are entity-decoded
+ * before resolving so `&amp;` is not escaped twice.
+ */
+export function rewriteHtml(raw, ctx) {
+    // Every raw-HTML sink comes through here, including HTML parsed out of a prop
+    // (a callout title, a card description) at render time.
+    const html = ctx.rawHtml ? ctx.rawHtml(raw) : raw;
+    return html.replace(/<[a-zA-Z][^<>]*>/g, (tag) => refuseScriptAttrs(tag, ctx).replace(/(\s)(href|src)(\s*=\s*)("([^"]*)"|'([^']*)')/gi, (m, sp, attr, eq, _q, dq, sq) => {
+        const v = unesc(dq ?? sq ?? "");
+        const isHref = attr.toLowerCase() === "href";
+        if (v && scriptUrl(v, isHref ? "link" : "image")) {
+            ctx.unsafeUrls?.add(v.slice(0, 80));
+            return `${sp}${attr}${eq}"${isHref ? "#" : ""}"`;
+        }
+        if (!v || v.startsWith("#") || /^[a-z][a-z0-9+.-]*:|^\/\//i.test(v))
+            return m;
+        const out = isHref ? ctx.link(v) : ctx.asset(v);
+        return `${sp}${attr}${eq}"${esc(out)}"`;
+    }));
+}
+// ─── Blocks ──────────────────────────────────────────────────────────
+export function renderBlocks(nodes, ctx) {
+    if (!nodes)
+        return "";
+    let out = "";
+    for (const n of nodes)
+        out += block(n, ctx);
+    return out;
+}
+const str = (v) => (v == null || v === "" ? undefined : String(v));
+/** A list item or step: the item's own inline run followed by its block children. */
+function itemBody(n, ctx) {
+    const lead = n.inline && n.inline.length ? `<p>${renderInline(n.inline, ctx)}</p>` : "";
+    return lead + renderBlocks(n.children, ctx);
+}
+/** Tight list items render their text without a wrapping <p>. */
+function listItem(n, ctx) {
+    const p = n.props ?? {};
+    const task = typeof p.checked === "boolean" ? `<input type="checkbox" disabled${p.checked ? " checked" : ""}> ` : "";
+    const lead = n.inline && n.inline.length ? renderInline(n.inline, ctx) : "";
+    const rest = renderBlocks(n.children, ctx);
+    const body = rest && lead ? `<p>${task}${lead}</p>${rest}` : task + lead + rest;
+    return `<li${attrs(passthrough(p))}>${body}</li>`;
+}
+function block(n, ctx) {
+    const p = (n.props ?? {});
+    switch (n.type) {
+        case "paragraph": {
+            // markdown-it treats a line that starts with a custom element (<db-popover>) as
+            // inline HTML and wraps it in <p>. A block child such as <div> would then make the
+            // browser close that <p> early and move the child out of the element, so a
+            // paragraph that is exactly one custom element, open tag to close tag, is emitted as-is.
+            const inl = n.inline ?? [];
+            const first = inl[0];
+            const last = inl[inl.length - 1];
+            const tag = first?.type === "html-inline" ? /^<([a-z][a-z0-9]*-[a-z0-9-]*)[\s>]/i.exec(first.html)?.[1]?.toLowerCase() : undefined;
+            if (tag && last?.type === "html-inline" && last.html.trim().toLowerCase() === `</${tag}>` && closesAtEnd(inl, tag)) {
+                return renderInline(inl, ctx) + "\n";
+            }
+            const only = inl.filter((i) => !(i.type === "text" && !i.text.trim()));
+            if (ctx.imageCaptions === "title" && only.length === 1 && only[0].type === "image" && only[0].title) {
+                // The figure form of the Astro pipeline's BlockImage (Image.astro, block), with its classes: the image's
+                // own class goes on the figure, as Image.astro takes `class` for the figure and keeps the img's fixed.
+                const img = only[0];
+                const { class: imgClass, ...at } = (img.attrs ?? {});
+                const framed = { ...img, attrs: { ...at, class: "rounded-lg border" } };
+                const figClass = ["my-4", imgClass].filter(Boolean).join(" ");
+                return `<figure${attrs(passthrough(p, figClass))}>${renderInline([framed], ctx)}<figcaption class="mt-2 text-center text-sm text-muted-foreground">${esc(img.title)}</figcaption></figure>\n`;
+            }
+            return `<p${attrs(passthrough(p))}>${renderInline(n.inline, ctx)}</p>\n`;
+        }
+        case "heading": {
+            const level = Math.min(6, Math.max(1, Number(p.level) || 2));
+            const text = inlineText(n.inline);
+            const id = uniqueId(ctx, str(p.id) ?? str(p.slug) ?? slugify(text));
+            if (level === 2 || level === 3)
+                ctx.headings.push({ depth: level, id, text });
+            // Astro serializer: a hover pilcrow link, hidden from assistive tech (the heading is the target).
+            const anchor = level > 1 ? `<a href="#${esc(id)}" class="ml-2 text-muted-foreground no-underline opacity-0 group-hover:opacity-100 focus:opacity-100" aria-hidden="true" tabindex="-1">&para;</a>` : "";
+            const { id: _i, ...rest } = passthrough(p, "group scroll-mt-20");
+            return `<h${level}${attrs({ id, ...rest })}>${renderInline(n.inline, ctx)}${anchor}</h${level}>\n`;
+        }
+        case "unordered-list":
+            return `<ul${attrs(passthrough(p))}>${(n.children ?? []).map((c) => listItem(c, ctx)).join("")}</ul>\n`;
+        case "ordered-list":
+            return `<ol${attrs({ ...passthrough(p), start: p.start != null && Number(p.start) !== 1 ? p.start : undefined })}>${(n.children ?? []).map((c) => listItem(c, ctx)).join("")}</ol>\n`;
+        case "list-item":
+            return listItem(n, ctx);
+        case "blockquote":
+            return `<blockquote${attrs(passthrough(p, "border-l-4 border-border pl-4 italic text-muted-foreground"))}>${renderBlocks(n.children, ctx)}</blockquote>\n`;
+        case "hr":
+            return `<hr class="my-8 border-border">\n`;
+        case "html":
+            return rewriteHtml(n.html ?? "", ctx) + "\n";
+        case "code":
+            return codeBlock(n, ctx);
+        case "table":
+            return table(n, ctx);
+        case "thead":
+            return `<thead class="[&_tr]:border-b">${renderBlocks(n.children, ctx)}</thead>`;
+        case "tbody":
+            return `<tbody class="[&_tr:last-child]:border-0">${renderBlocks(n.children, ctx)}</tbody>`;
+        case "tr":
+            return `<tr${attrs(passthrough(p, "border-b transition-colors hover:bg-muted/50"))}>${renderBlocks(n.children, ctx)}</tr>`;
+        case "th":
+        case "td": {
+            // Only the three values: the style is written as given.
+            const align = /^(left|center|right)$/i.test(str(p.align) ?? "") ? str(p.align).toLowerCase() : undefined;
+            const cls = n.type === "th" ? "px-2 py-2 text-left align-bottom font-semibold text-muted-foreground" : "p-2 align-top";
+            return `<${n.type}${attrs({ ...passthrough(p, cls), colspan: p.colspan, rowspan: p.rowspan, style: align ? `text-align:${align}` : p.style })}>${renderInline(n.inline, ctx)}${renderBlocks(n.children, ctx)}</${n.type}>`;
+        }
+        case "deflist":
+            return `<dl${attrs(passthrough(p, "my-4 space-y-2"))}>${renderBlocks(n.children, ctx)}</dl>\n`;
+        case "dt":
+            return `<dt class="font-semibold">${renderInline(n.inline, ctx)}</dt>`;
+        case "dd":
+            return `<dd class="ml-6 text-muted-foreground">${itemBody(n, ctx)}</dd>`;
+        case "footnote-list":
+            return `<section class="footnotes mt-12 border-t pt-6 text-sm text-muted-foreground" role="doc-endnotes"><ol>${renderBlocks(n.children, ctx)}</ol></section>\n`;
+        case "footnote-def": {
+            const label = esc(str(p.label) ?? "");
+            const body = n.inline?.length ? `<p>${renderInline(n.inline, ctx)} <a href="#fnref-${label}" class="text-primary no-underline" role="doc-backlink" aria-label="${esc(ctx.t("backToContent"))}">↩</a></p>` : "";
+            return `<li id="fn-${label}">${body}${renderBlocks(n.children, ctx)}</li>`;
+        }
+        case "callout":
+            return callout(n, ctx);
+        case "steps":
+            return steps(n, ctx);
+        case "step":
+            // Tight, like the Astro Step: the lead text is not wrapped in <p>.
+            return `<li>${renderInline(n.inline, ctx)}${renderBlocks(n.children, ctx)}</li>`;
+        case "tabs":
+            return tabs(n, ctx);
+        case "tab":
+            return renderBlocks(n.children, ctx);
+        case "accordion":
+            return accordion(n, ctx);
+        case "accordion-item":
+            return accordion({ type: "accordion", children: [n] }, ctx);
+        case "details":
+            return details(n, ctx);
+        case "figure":
+            return figure(n, ctx);
+        case "substeps": {
+            // SubSteps.astro: a lettered list; inside a step, steps.css styles it as the nested list.
+            const items = (n.children ?? []).map((c) => (c.type === "step" ? block(c, ctx) : `<li>${block(c, ctx)}</li>`)).join("");
+            return `<ol${attrs({ ...passthrough(p, "sub-steps-list"), role: "list" })}>${items}</ol>\n`;
+        }
+        case "annotation-list":
+            // format-astro's wrapBlock for annotation-list.
+            return `<div${attrs(passthrough(p, "my-2 rounded-md border-l-4 border-info/50 bg-info/5 p-4"))}>${renderBlocks(n.children, ctx)}</div>\n`;
+        case "avatar":
+            return avatar(p, ctx);
+        case "example":
+            return example(n, ctx);
+        case "cards":
+            return `<div${attrs(passthrough(p, "not-prose my-4 grid grid-cols-1 gap-4 sm:grid-cols-2"))}>${renderBlocks(n.children, ctx)}</div>\n`;
+        case "card":
+            return card(n, ctx);
+        case "link-card":
+            return linkCard(n, ctx);
+        case "grid": {
+            const cols = Math.min(6, Math.max(1, Number(p.cols) || 2));
+            return `<div${attrs({ ...passthrough(p, `not-prose my-4 grid grid-cols-1 gap-4 ${GRID_COLS[cols]}`) })}>${renderBlocks(n.children, ctx)}</div>\n`;
+        }
+        case "grid-item": {
+            const span = Number(p.span) || 0;
+            const rows = Number(p.rowSpan) || 0;
+            const style = [span > 1 && `grid-column:span ${span} / span ${span}`, rows > 1 && `grid-row:span ${rows} / span ${rows}`].filter(Boolean).join(";") || undefined;
+            // `label` draws a placeholder cell in the `tone` colours, as GridItem does in the Astro pipeline.
+            const label = str(p.label);
+            const inner = label !== undefined
+                ? `<div class="flex h-full min-h-16 items-center justify-center rounded-lg font-mono text-sm font-medium ${TONE_CLASSES[str(p.tone) ?? "primary-light"] ?? TONE_CLASSES["primary-light"]}">${esc(label)}</div>`
+                : renderBlocks(n.children, ctx);
+            const { label: _l, tone: _t, rowSpan: _r, ...rest } = p;
+            const pass = passthrough(rest);
+            // The span styles join an author's own `style` rather than replace it.
+            const merged = [style, str(pass.style)].filter(Boolean).join(";") || undefined;
+            return `<div${attrs({ ...pass, style: merged })}>${inner}</div>`;
+        }
+        case "files":
+            // Each list is a tree; anything else in the block (an intro, a note) renders as it is.
+            return (n.children ?? [])
+                .map((c) => (c.type === "unordered-list" || c.type === "ordered-list" ? fileTreeHtml(fileTreeItems(c, ctx), str(p.class) ?? "") + "\n" : renderBlocks([c], ctx)))
+                .join("");
+        case "container": {
+            // A `:::name` block no renderer knows: its content in a marked div (and a build warning).
+            const name = typeof n.meta?.name === "string" ? n.meta.name : "container";
+            ctx.unknown.add(`:::${name}`);
+            const title = typeof n.meta?.title === "string" ? `<p class="font-semibold">${esc(n.meta.title)}</p>` : "";
+            return `<div${attrs({ ...passthrough(p), "data-directive": name })}>${title}${renderBlocks(n.children, ctx)}</div>\n`;
+        }
+        case "link-button": {
+            const href = str(p.href);
+            const variant = buttonVariant(str(p.variant));
+            const label = insideLink(true, ctx, () => (n.children?.length === 1 && n.children[0].type === "paragraph" ? renderInline(n.children[0].inline, ctx) : renderBlocks(n.children, ctx)));
+            return `<p><a${attrs({ ...passthrough(p, `${BUTTON_BASE} ${BUTTON_VARIANTS[variant] ?? BUTTON_VARIANTS.default} h-10 px-4 py-2 no-underline`), "data-variant": variant, "data-size": "default", href: href ? linkUrl(href, ctx) : undefined })}>${label}</a></p>\n`;
+        }
+        case "youtube": {
+            // A card linking to the video, not an embed: the page must work offline, with no request to YouTube
+            // (the Astro pipeline embeds it on click). A local `poster` image is shown on it.
+            const id = str(p.id) ?? "";
+            const title = str(p.title) ?? "YouTube video";
+            // The video id is not the element's id (two cards for one video would share it).
+            const { id: _vid, ...ytRest } = p;
+            const poster = str(p.poster);
+            const play = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true" focusable="false"><path d="M8 5v14l11-7z"/></svg>';
+            return (`<a${attrs({ ...passthrough(ytRest, "not-prose group my-4 flex items-center gap-4 rounded-lg border bg-card p-3 text-card-foreground no-underline shadow-sm transition-colors hover:bg-accent/50"), href: `https://www.youtube.com/watch?v=${encodeURIComponent(id)}`, rel: "noopener", "data-component": "youtube" })}>` +
+                (poster ? `<img src="${esc(assetUrl(poster, ctx))}" alt="" class="h-16 w-28 shrink-0 rounded object-cover" loading="lazy">` : "") +
+                `<span class="flex size-10 shrink-0 items-center justify-center rounded-full bg-red-600 text-white">${play}</span>` +
+                `<span class="min-w-0"><span class="block font-semibold group-hover:underline">${esc(title)}</span><span class="block text-xs text-muted-foreground">YouTube</span></span></a>\n`);
+        }
+        case "diagram": {
+            // Importers that render diagrams themselves (the Astro pipeline's `diagram` node) carry the SVG; otherwise render or show the code.
+            const lang = str(p.lang) ?? "mermaid";
+            const code = str(p.code) ?? "";
+            const svg = str(p.svg) ?? ctx.diagram?.(lang, code);
+            return svg ? diagramFigure(lang, svg, str(p.title), p) : codeBlock({ type: "code", props: { ...p, language: lang }, html: code }, ctx);
+        }
+        case "math-block": {
+            const latex = str(p.latex) ?? "";
+            const html = renderMath(latex, true, ctx);
+            return html != null
+                ? `<div class="my-4 overflow-x-auto">${html}</div>\n`
+                : `<pre class="my-4 overflow-x-auto rounded-md border bg-muted p-4 text-sm"><code class="math-display">${esc(latex)}</code></pre>\n`;
+        }
+        case "math":
+            return `<pre class="my-4 overflow-x-auto rounded-md border bg-muted p-4 text-sm"><code class="math-display">${esc(n.html ?? inlineText(n.inline))}</code></pre>\n`;
+        case "related":
+            return `<nav class="related-resources" aria-label="${esc(ctx.t("related"))}">${renderInline(n.inline, ctx)}${renderBlocks(n.children, ctx)}</nav>\n`;
+        case "include": {
+            const target = str(p.path) ?? str(p.src) ?? str(p.file) ?? "";
+            const remote = /https?:\/\/\S+/.exec(target)?.[0];
+            if (remote) {
+                ctx.unknown.add("include of a remote file (not fetched)");
+                return `<p><a rel="noopener" href="${esc(remote)}">${esc(remote.split("/").pop() ?? remote)}</a></p>\n`;
+            }
+            ctx.unknown.add("include (unresolved)");
+            return `<!-- unresolved include: ${esc(target)} -->\n`;
+        }
+        default: {
+            ctx.unknown.add(n.type);
+            if (n.html && !n.children?.length)
+                return rewriteHtml(n.html, ctx);
+            const inner = (n.inline?.length ? `<p>${renderInline(n.inline, ctx)}</p>` : "") + renderBlocks(n.children, ctx);
+            return `<div${attrs(passthrough(p, `db-${slugify(n.type)}`))}>${inner}</div>\n`;
+        }
+    }
+}
+/** True when the element opened by the first node is closed by the last node and not before. */
+function closesAtEnd(inl, tag) {
+    let depth = 0;
+    for (let i = 0; i < inl.length; i++) {
+        const n = inl[i];
+        if (n.type !== "html-inline")
+            continue;
+        const h = n.html.trim().toLowerCase();
+        if (new RegExp(`^<${tag}[\\s>]`).test(h))
+            depth++;
+        else if (h === `</${tag}>`) {
+            depth--;
+            if (depth === 0 && i !== inl.length - 1)
+                return false;
+        }
+    }
+    return depth === 0;
+}
+const GRID_COLS = {
+    1: "sm:grid-cols-1",
+    2: "sm:grid-cols-2",
+    3: "sm:grid-cols-2 lg:grid-cols-3",
+    4: "sm:grid-cols-2 lg:grid-cols-4",
+    5: "sm:grid-cols-3 lg:grid-cols-5",
+    6: "sm:grid-cols-3 lg:grid-cols-6",
+};
+/** A button variant as Button.astro names it: the spec's `primary` is its filled `default`. */
+function buttonVariant(variant) {
+    return !variant || variant === "primary" ? "default" : variant;
+}
+const BUTTON_BASE = "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50";
+const BUTTON_VARIANTS = {
+    default: "bg-primary text-primary-foreground hover:bg-primary/90",
+    outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+    secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+    ghost: "hover:bg-accent hover:text-accent-foreground",
+    link: "text-primary underline-offset-4 hover:underline",
+    destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+};
+// ─── Code (CodeBlock.astro, with db-code-block for copy) ────────────
+const COPY_ICON = '<svg data-part="copy-icon" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>';
+const CHECK_ICON = '<svg data-part="check-icon" hidden xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M20 6 9 17l-5-5"/></svg>';
+/** A rendered diagram, as `@dogsbay/ui`'s Diagram.astro: dark mode inverts it and turns the hues back. */
+function diagramFigure(lang, svg, title, p) {
+    return (`<figure${attrs({ ...passthrough(p, "diagram not-prose my-4"), "data-lang": lang })}>` +
+        (title ? `<figcaption class="mb-2 text-sm text-muted-foreground">${esc(title)}</figcaption>` : "") +
+        `<div class="diagram-content overflow-x-auto [&>svg]:mx-auto [&>svg]:max-w-full dark:invert dark:[&>svg]:hue-rotate-180">${FOREIGN_START}${svg}${FOREIGN_END}</div></figure>\n`);
+}
+export function codeRequest(n) {
+    const p = (n.props ?? {});
+    const code = n.html ?? String(p.code ?? "");
+    const rawLang = str(p.language) ?? str(p.lang);
+    const lang = rawLang === "terminal" ? "bash" : rawLang;
+    // The fence's documented `mark`, `ins` and `del` are highlighted, added and removed lines.
+    const highlights = [...parseLineRanges(p.highlights ?? p.highlight ?? p.hl_lines), ...parseLineRanges(p.mark)];
+    const diffAdd = [...parseLineRanges(p.diffAdd), ...parseLineRanges(p.ins)];
+    const diffRemove = [...parseLineRanges(p.diffRemove), ...parseLineRanges(p.del)];
+    const lineNumbers = p.lineNumbers === true || p.lineNumbers === "true" || p.linenums != null;
+    return { code, lang, opts: { highlights, lineNumbers, diffAdd, diffRemove } };
+}
+/**
+ * Every block (language tag as written, and code) a tree's rendering may ask
+ * the highlighter for, so a highlighter that loads grammars per language
+ * (`Highlighter.load`) can load them before rendering: code nodes, and
+ * diagrams, which fall back to a code block when not rendered. The code is
+ * part of it: a markdown block needs the grammars its fences name. Looks
+ * through props as well as children, so a node a component nests elsewhere
+ * is found.
+ */
+export function highlightInputs(tree) {
+    const out = [];
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.forEach(walk);
+        if (!v || typeof v !== "object")
+            return;
+        const n = v;
+        if (n.type === "code") {
+            const { lang, code } = codeRequest(n);
+            out.push({ lang, code });
+        }
+        else if (n.type === "diagram") {
+            // The code block a diagram falls back to, built as the "diagram" case builds it.
+            const p = (n.props ?? {});
+            const { lang, code } = codeRequest({ type: "code", props: { ...p, language: str(p.lang) ?? "mermaid" }, html: str(p.code) ?? "" });
+            out.push({ lang, code });
+        }
+        if (n.children)
+            walk(n.children);
+        if (n.props)
+            for (const x of Object.values(n.props))
+                if (x && typeof x === "object")
+                    walk(x);
+    };
+    walk(tree);
+    return out;
+}
+function codeBlock(n, ctx) {
+    const p = (n.props ?? {});
+    const rawLang = str(p.language) ?? str(p.lang);
+    const { code, lang, opts } = codeRequest(n);
+    const svg = rawLang && ctx.diagram ? ctx.diagram(rawLang, code) : undefined;
+    if (svg)
+        return diagramFigure(rawLang, svg, str(p.title) ?? str(p.filename), p);
+    const title = str(p.title) ?? str(p.filename);
+    const { highlights, lineNumbers, diffAdd, diffRemove } = opts;
+    const hl = ctx.highlighter ?? plainHighlighter;
+    const pre = hl.code(code, lang, opts);
+    // A block with annotations takes CodeRich's styles, as the Astro pipeline routes it to CodeRich.
+    const diffs = diffAdd.length > 0 || diffRemove.length > 0;
+    const rich = lineNumbers || highlights.length > 0 || diffs || code.includes("[!code");
+    const plain = !lang || hl.resolve(lang) === "text";
+    const copyLabel = esc(ctx.t("copyCode"));
+    const copyBtn = (extra = "") => `<button type="button" data-part="copy" aria-label="${copyLabel}" class="inline-flex h-7 w-7 items-center justify-center rounded-md text-code-fg/50 transition-colors hover:bg-code-fg/10 hover:text-code-fg/80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring${extra}">${COPY_ICON}${CHECK_ICON}</button>`;
+    let header = "";
+    let floating = "";
+    const mode = ctx.codeBlockTitle ?? true;
+    if (mode === "auto" ? !!title : mode && (title || !plain)) {
+        const left = title ? `<span class="min-w-0 font-medium text-code-fg" data-part="title">${esc(title)}</span>` : `<span class="select-none" data-part="label">${esc(lang ?? "")}</span>`;
+        const langRight = title && !plain ? `<span class="select-none" data-part="language">${esc(lang ?? "")}</span>` : "";
+        header = `<div data-part="header" class="flex items-center justify-between border-b border-code-fg/10 bg-code-fg/5 px-4 py-2 text-xs text-code-fg/70">${left}<span class="flex shrink-0 items-center gap-2">${langRight}${copyBtn()}</span></div>`;
+    }
+    else {
+        floating = copyBtn(" absolute right-2 top-2 z-10 opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100");
+    }
+    return (`<db-code-block${attrs({
+        ...passthrough(p, "not-prose group relative my-4 overflow-hidden rounded-lg border bg-code-bg text-sm"),
+        // CodeRich's name for an annotated block, CodeBlock's otherwise, as the Astro pipeline renders them.
+        "data-component": rich ? "code-rich" : "code-block",
+        "data-lang": lang,
+        "data-line-numbers": lineNumbers || undefined,
+        // With a gutter or [!code …] markers the text on the page is not the code: copy the source, markers removed.
+        "data-copy-text": str(p.copyText) ?? (lineNumbers || diffs || code.includes("[!code") ? stripMarkersForCopy(code.replace(/\n$/, "")) : undefined),
+    })}>` +
+        header +
+        floating +
+        `<div data-part="code" class="${rich ? "code-rich-body " : ""}relative overflow-x-auto [&_pre]:!m-0 [&_pre]:!rounded-none [&_pre]:!border-0 [&_pre]:px-4 [&_pre]:py-3">${pre}</div></db-code-block>\n`);
+}
+function table(n, ctx) {
+    const p = (n.props ?? {});
+    const caption = str(p.caption);
+    const cap = caption ? `<caption class="mb-2 text-left text-sm font-medium text-foreground">${renderInline(parseInline(caption), ctx)}</caption>` : "";
+    // Focusable so keyboard users can scroll a wide table (axe scrollable-region-focusable).
+    return `<div class="relative w-full overflow-x-auto" tabindex="0"><table${attrs(passthrough(p, "my-4 w-full caption-top text-sm"))}>${cap}${renderBlocks(n.children, ctx)}</table></div>\n`;
+}
+// ─── Callouts (Alert.astro / CollapsibleAlert.astro) ────────────────
+/** Authored type → Alert variant (format-astro serialize.ts). */
+const VARIANT_ALIAS = { important: "info", caution: "danger", error: "failure", hint: "tip", attention: "warning" };
+const ALERT_BASE = "relative w-full rounded-lg border p-4 [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:size-4 [&>svg~div]:pl-7";
+const ALERT_VARIANT = {
+    note: "border-note/50 bg-note/5 text-foreground [&>svg]:text-note",
+    abstract: "border-abstract/50 bg-abstract/5 text-foreground [&>svg]:text-abstract",
+    info: "border-info/50 bg-info/5 text-foreground [&>svg]:text-info",
+    tip: "border-tip/50 bg-tip/5 text-foreground [&>svg]:text-tip",
+    success: "border-success/50 bg-success/5 text-foreground [&>svg]:text-success",
+    question: "border-question/50 bg-question/5 text-foreground [&>svg]:text-question",
+    warning: "border-warning/50 bg-warning/5 text-foreground [&>svg]:text-warning",
+    failure: "border-failure/50 bg-failure/5 text-foreground [&>svg]:text-failure",
+    danger: "border-danger/50 bg-danger/5 text-foreground [&>svg]:text-danger",
+    bug: "border-bug/50 bg-bug/5 text-foreground [&>svg]:text-bug",
+    example: "border-example/50 bg-example/5 text-foreground [&>svg]:text-example",
+    quote: "border-quote/50 bg-quote/5 text-foreground [&>svg]:text-quote",
+};
+const COLLAPSIBLE = Object.fromEntries(Object.keys(ALERT_VARIANT).map((v) => [v, { border: `border-${v}/50`, summary: `bg-${v}/10`, icon: `text-${v}`, body: `bg-${v}/3` }]));
+function calloutLabel(type, ctx) {
+    return ctx.t(`callout.${type}`) || CALLOUTS[type]?.label || type.charAt(0).toUpperCase() + type.slice(1);
+}
+function callout(n, ctx) {
+    const p = (n.props ?? {});
+    const type = (str(p.type) ?? "note").toLowerCase();
+    const variant = ALERT_VARIANT[VARIANT_ALIAS[type] ?? type] ? VARIANT_ALIAS[type] ?? type : "note";
+    const title = str(p.title);
+    const titleHtml = title ? renderInline(parseInline(title), ctx) : esc(calloutLabel(type, ctx));
+    const body = renderBlocks(n.children, ctx);
+    if (p.collapsible === true || p.collapsible === "true" || p.collapsed != null) {
+        const open = p.collapsed === false || p.collapsed === "false" || p.open != null;
+        return collapsibleAlert(variant, titleHtml, body, open, p);
+    }
+    return (`<div${attrs({ ...passthrough(p, `${ALERT_BASE} ${ALERT_VARIANT[variant]} my-4`), "data-variant": variant, "data-type": type, role: "note" })}>` +
+        (ALERT_ICONS[variant] ?? "").replace("<svg ", '<svg aria-hidden="true" focusable="false" ') +
+        `<div data-part="title" class="mb-1 text-sm font-semibold leading-none tracking-tight">${titleHtml}</div>` +
+        `<div class="text-sm [&_p]:leading-relaxed">${body}</div></div>\n`);
+}
+function collapsibleAlert(variant, titleHtml, body, open, p) {
+    const c = COLLAPSIBLE[variant] ?? COLLAPSIBLE.note;
+    const icon = (ALERT_ICONS[variant] ?? "").replace("<svg ", '<svg aria-hidden="true" focusable="false" ');
+    return (`<details${attrs({ ...passthrough(p, `group/collapsible relative my-4 w-full overflow-hidden rounded-lg border [&>summary]:list-none [&>summary::-webkit-details-marker]:hidden ${c.border}`), "data-variant": variant, open })}>` +
+        `<summary class="flex cursor-pointer select-none items-center gap-2 px-4 py-3 text-sm font-semibold ${c.summary}"><span class="shrink-0 [&>svg]:size-4 ${c.icon}">${icon}</span><span class="flex-1 text-foreground" data-part="title">${titleHtml}</span><span class="shrink-0 text-muted-foreground transition-transform duration-200 group-open/collapsible:rotate-180">${ALERT_CHEVRON.replace("<svg ", '<svg aria-hidden="true" focusable="false" ')}</span></summary>` +
+        `<div class="px-4 py-3 text-sm [&_p]:leading-relaxed ${c.body}">${body}</div></details>\n`);
+}
+// ─── Steps (Steps.astro; CSS in steps.css) ───────────────────────────
+// ─── Avatar (Avatar.astro) and example (MarkdownExample.astro) ──────
+const AVATAR = "relative inline-flex h-10 w-10 shrink-0 items-center justify-center overflow-hidden rounded-full bg-muted";
+const AVATAR_FALLBACK = "flex h-full w-full items-center justify-center rounded-full bg-muted text-sm font-semibold text-muted-foreground";
+function avatar(p, ctx) {
+    const src = str(p.src);
+    const alt = str(p.alt) ?? "";
+    const initials = str(p.fallback) || alt.split(" ").map((w) => w[0] ?? "").join("").slice(0, 2).toUpperCase();
+    const { src: _s, alt: _a, fallback: _f, ...rest } = p;
+    // As Avatar.astro: the initials stand in when the image fails to load.
+    const inner = src
+        ? `<img class="aspect-square h-full w-full object-cover" src="${esc(assetUrl(src, ctx))}" alt="${esc(alt)}" width="40" height="40" onerror="this.hidden=true;this.nextElementSibling.hidden=false"><span class="${AVATAR_FALLBACK}" aria-hidden="true" hidden>${esc(initials)}</span>`
+        : `<span class="${AVATAR_FALLBACK}" aria-hidden="true">${esc(initials)}</span>`;
+    return `<span${attrs(passthrough(rest, AVATAR))}>${inner}</span>`;
+}
+const CHEVRON = '<svg class="h-3 w-3 transition-transform group-open:rotate-90" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"></polyline></svg>';
+/**
+ * A live example: the rendered content, then its source in a collapsed panel. The Astro component's optional
+ * plain-Markdown panel (`fallback=true`) needs a second Markdown renderer and is left out; it is reported.
+ */
+function example(n, ctx) {
+    const p = (n.props ?? {});
+    const title = str(p.title);
+    if (p.fallback === true || p.fallback === "true")
+        ctx.unknown.add("example fallback panel (not rendered)");
+    return (`<figure class="my-6 overflow-hidden rounded-lg border border-border bg-card">` +
+        (title ? `<figcaption class="border-b border-border bg-muted/30 px-4 py-2 text-sm font-medium">${esc(title)}</figcaption>` : "") +
+        `<div class="border-b border-border"><div class="border-b border-border bg-muted/10 px-4 py-1 text-[11px] uppercase tracking-wide text-muted-foreground">Rendered</div>` +
+        `<div${attrs({ class: "markdown-preview p-6 [&>:first-child]:mt-0 [&>:last-child]:mb-0" })}>${renderBlocks(n.children, ctx)}</div></div>` +
+        `<details class="group"><summary class="flex cursor-pointer list-none select-none items-center gap-2 px-4 py-2 text-xs text-muted-foreground hover:text-foreground">${CHEVRON}<span class="uppercase tracking-wide">Source</span></summary>` +
+        `<pre class="m-0 overflow-auto border-t border-border bg-muted/20 p-4 text-xs"><code>${esc(String(p.source ?? ""))}</code></pre></details></figure>\n`);
+}
+function steps(n, ctx) {
+    const p = (n.props ?? {});
+    const items = (n.children ?? []).map((c) => (c.type === "step" ? block(c, ctx) : `<li>${block(c, ctx)}</li>`)).join("");
+    return `<ol${attrs({ ...passthrough(p, "steps-list"), role: "list" })}>${items}</ol>\n`;
+}
+// ─── Tabs (Tabs*.astro + db-tabs) ───────────────────────────────────
+const TAB_TRIGGER = "inline-flex items-center justify-center whitespace-nowrap rounded-sm px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 aria-selected:bg-background aria-selected:text-foreground aria-selected:shadow-sm";
+const TAB_CONTENT = "px-4 py-3 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 [&>:first-child]:mt-0 [&>:last-child]:mb-0";
+function tabs(n, ctx) {
+    const p = (n.props ?? {});
+    const kids = (n.children ?? []).filter((c) => c.type === "tab");
+    if (!kids.length)
+        return renderBlocks(n.children, ctx);
+    const group = ++ctx.seq;
+    const used = new Set();
+    // The label itself: synced groups match by value, and a slug would merge C, C++ and C#.
+    const values = kids.map((k, i) => {
+        let v = (str(k.props?.label) ?? `Tab ${i + 1}`).trim();
+        while (used.has(v))
+            v += ` (${i + 1})`;
+        used.add(v);
+        return v;
+    });
+    const syncKey = str(p.syncKey) ?? str(p["sync-key"]) ?? str(p.group);
+    let list = "";
+    let panels = "";
+    kids.forEach((k, i) => {
+        const tid = `tab-${group}-${i + 1}`;
+        const pid = `tabpanel-${group}-${i + 1}`;
+        const sel = i === 0;
+        list += `<button data-part="trigger" data-value="${esc(values[i])}" role="tab" type="button" id="${tid}" aria-controls="${pid}" aria-selected="${sel}" tabindex="${sel ? 0 : -1}"${sel ? ' data-state="active"' : ""} class="${TAB_TRIGGER}">${esc(str(k.props?.label) ?? `Tab ${i + 1}`)}</button>`;
+        panels += `<div data-part="content" data-value="${esc(values[i])}" role="tabpanel" id="${pid}" aria-labelledby="${tid}" tabindex="0"${sel ? ' data-state="active"' : " hidden"} class="${TAB_CONTENT}">${renderBlocks(k.children, ctx)}</div>`;
+    });
+    return `<db-tabs${attrs({ ...passthrough(p, "my-4 w-full overflow-hidden rounded-lg border border-border"), "default-value": values[0], "sync-key": syncKey })}><div data-part="list" role="tablist" aria-orientation="horizontal" class="flex items-center border-b border-border bg-muted p-1 text-muted-foreground">${list}</div>${panels}</db-tabs>\n`;
+}
+// ─── Accordion (Accordion*.astro + db-accordion) ────────────────────
+function accordion(n, ctx) {
+    const p = (n.props ?? {});
+    const group = ++ctx.seq;
+    const items = (n.children ?? []).filter((c) => c.type === "accordion-item");
+    const chevron = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="shrink-0 transition-transform duration-200" aria-hidden="true" focusable="false"><path d="m6 9 6 6 6-6"/></svg>';
+    const html = items
+        .map((it, i) => {
+        const label = str(it.props?.label) ?? str(it.props?.title) ?? `Item ${i + 1}`;
+        const value = str(it.props?.value) ?? `${slugify(label)}-${i + 1}`;
+        const tid = `acc-${group}-${i + 1}`;
+        const cid = `accpanel-${group}-${i + 1}`;
+        return (`<div data-part="item" data-value="${esc(value)}" class="border-b">` +
+            `<button data-part="trigger" type="button" id="${tid}" aria-controls="${cid}" aria-expanded="false" class="flex w-full items-center justify-between border-0 bg-transparent py-4 text-left font-medium text-foreground transition-all hover:underline disabled:pointer-events-none disabled:opacity-50 [&[aria-expanded=true]>svg]:rotate-180">` +
+            `<span>${renderInline(parseInline(label), ctx)}</span>${chevron}</button>` +
+            `<div data-part="content" id="${cid}" role="region" aria-labelledby="${tid}" hidden class="overflow-hidden pb-4 text-sm transition-all">${renderBlocks(it.children, ctx)}</div></div>`);
+    })
+        .join("");
+    // As Accordion.astro: one open item at a time unless `type="multiple"`; `defaultValue` opens items.
+    const dv = p.defaultValue;
+    const defaultValue = Array.isArray(dv) ? dv.map(String).join(",") : str(dv);
+    const { defaultValue: _d, ...rest } = p;
+    return `<db-accordion${attrs({ ...passthrough(rest, "my-4 w-full"), type: str(p.type) ?? "single", "default-value": defaultValue })}>${html}</db-accordion>\n`;
+}
+// `:::details` renders as a CollapsibleAlert, as in the Astro serializer.
+function details(n, ctx) {
+    const p = (n.props ?? {});
+    const title = str(p.title) ?? str(p.summary) ?? ctx.t("details");
+    // `variant` as documented, then `type`, as the Astro pipeline reads it.
+    const type = (str(p.variant) ?? str(p.type) ?? "").toLowerCase();
+    const variant = ALERT_VARIANT[VARIANT_ALIAS[type] ?? type] ? VARIANT_ALIAS[type] ?? type : "note";
+    return collapsibleAlert(variant, renderInline(parseInline(title), ctx), renderBlocks(n.children, ctx), p.open != null && p.open !== false, p);
+}
+function figure(n, ctx) {
+    const p = (n.props ?? {});
+    const caption = str(p.caption);
+    const kids = n.children ?? [];
+    const body = kids.length === 1 && kids[0].type === "paragraph" && kids[0].inline?.every((i) => i.type === "image" || (i.type === "text" && !i.text.trim()))
+        ? renderInline(kids[0].inline, ctx)
+        : renderBlocks(kids, ctx);
+    return `<figure${attrs(passthrough(p, "my-4"))}>${body}${caption ? `<figcaption class="mt-2 text-center text-sm text-muted-foreground">${renderInline(parseInline(caption), ctx)}</figcaption>` : ""}</figure>\n`;
+}
+// ─── Cards (Card.astro, LinkCard.astro) ─────────────────────────────
+/** Render `fn` as the content of a link (or not), so images inside links are not made zoomable. */
+function insideLink(yes, ctx, fn) {
+    if (!yes)
+        return fn();
+    const was = ctx.inLink;
+    ctx.inLink = true;
+    try {
+        return fn();
+    }
+    finally {
+        ctx.inLink = was;
+    }
+}
+/**
+ * An icon by name. With a resolver (the Node CLI): Icon.astro's markup around the SVG or emoji @dogsbay/icons
+ * gives, so pages match the Astro pipeline's. Without one: the built-in Lucide set. An icon neither knows is
+ * recorded for a build warning and leaves a marked, empty span.
+ */
+function namedIcon(name, cls, ctx) {
+    const resolved = ctx.icons?.(name);
+    if (resolved)
+        return `<span class="inline-flex shrink-0 ${cls}" aria-hidden="true" data-icon="${esc(name)}">${resolved.startsWith("<") ? resolved : esc(resolved)}</span>`;
+    const builtin = name.replace(/^lucide:/, "");
+    if (hasIcon(builtin))
+        return icon(builtin, cls);
+    (ctx.missingIcons ??= new Set()).add(name);
+    return `<span class="db-icon-missing" data-icon="${esc(name)}"></span>`;
+}
+/** The `:::files` list as file-tree entries: a folder has entries or a name ending in "/". */
+function fileTreeItems(list, ctx) {
+    return (list?.children ?? [])
+        .filter((li) => li.type === "list-item")
+        .map((li) => {
+        const inline = li.inline ?? (li.children ?? []).find((c) => c.type === "paragraph")?.inline ?? [];
+        const sub = (li.children ?? []).find((c) => c.type === "unordered-list" || c.type === "ordered-list");
+        // The name is the entry's text and code spans, as the Astro pipeline reads it (link text does not count).
+        const name = inline.map((n) => (n.type === "text" || n.type === "code" ? n.text : "")).join("");
+        return { label: renderInline(inline, ctx), folder: !!sub || /\/\s*$/.test(name), children: fileTreeItems(sub, ctx) };
+    });
+}
+function card(n, ctx) {
+    const p = (n.props ?? {});
+    const title = str(p.title);
+    const href = str(p.href);
+    const desc = str(p.description);
+    const ic = str(p.icon);
+    // An image path is shown as an image, as the Astro pipeline's cardIconHtml does.
+    const iconHtml = !ic ? "" : /\.(svg|png|jpe?g|webp|avif)$/i.test(ic) ? `<img src="${esc(assetUrl(ic, ctx))}" alt="" class="size-5 mb-2" loading="lazy">` : namedIcon(ic, "mb-2 size-5 text-muted-foreground", ctx);
+    const inner = insideLink(!!href, ctx, () => iconHtml +
+        (title ? `<h3 class="m-0 border-0 p-0 text-base font-semibold">${renderInline(parseInline(title), ctx)}</h3>` : "") +
+        (desc ? `<p class="m-0 mt-1 text-sm text-muted-foreground [text-decoration:none]">${renderInline(parseInline(desc), ctx)}</p>` : "") +
+        // Body blocks in the same description wrapper as the Astro pipeline's card (a <div>: they carry their own <p>).
+        (n.children?.length ? `<div class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${renderBlocks(n.children, ctx)}</div>` : ""));
+    const cls = `rounded-lg border bg-card p-4 text-card-foreground shadow-sm${href ? " transition-colors hover:border-foreground/20" : ""}`;
+    return href
+        ? `<div${attrs(passthrough(p, cls))}><div class="p-0"><a href="${esc(linkUrl(href, ctx))}" class="block text-foreground [text-decoration:none]">${inner}</a></div></div>`
+        : `<div${attrs(passthrough(p, cls))}><div class="p-0">${inner}</div></div>`;
+}
+function linkCard(n, ctx) {
+    // A body of more than one paragraph stays as children (the parser folds a single paragraph into
+    // the description). The Astro pipeline renders that as a linked card (standaloneCardToAstro); so
+    // does this, where the body used to be dropped.
+    if (n.children?.length)
+        return card(n, ctx);
+    const p = (n.props ?? {});
+    const title = str(p.title) ?? "";
+    const href = str(p.href) ?? "#";
+    const desc = str(p.description);
+    const chevron = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5" aria-hidden="true" focusable="false"><path d="m9 18 6-6-6-6"/></svg>';
+    const ic = str(p.icon);
+    const iconHtml = ic ? namedIcon(ic, "size-4 shrink-0 text-muted-foreground", ctx) : "";
+    return `<a${attrs({ ...passthrough(p, "group not-prose my-4 flex flex-col gap-1 rounded-lg border bg-card p-4 text-card-foreground no-underline shadow-sm transition-colors hover:bg-accent/50"), href: linkUrl(href, ctx) })}><div class="flex items-center justify-between"><span class="flex min-w-0 items-center gap-2">${iconHtml}<span class="text-sm font-semibold group-hover:underline">${insideLink(true, ctx, () => renderInline(parseInline(title), ctx))}</span></span>${chevron}</div>${desc ? `<p class="m-0 text-sm text-muted-foreground">${insideLink(true, ctx, () => renderInline(parseInline(desc), ctx))}</p>` : ""}</a>`;
+}