@dogsbay/format-astro 0.2.0-beta.12 → 0.2.0-beta.121

package/dist/serialize.js

@@ -1,25 +1,9 @@
-/**
- * Tone palette for `:::grid-item{label="..." tone="..."}` cells.
- * Each tone is a `bg + text` Tailwind class pair. Used to make grid demos
- * declarative — authors specify a tone instead of writing the styling.
- */
-const TONE_CLASSES = {
-    // Primary scale (intensity)
-    "primary": "bg-primary text-primary-foreground",
-    "primary-strong": "bg-primary/80 text-primary-foreground",
-    "primary-medium": "bg-primary/60 text-primary-foreground",
-    "primary-half": "bg-primary/50 text-primary-foreground",
-    "primary-light": "bg-primary/20 text-primary",
-    "primary-soft": "bg-primary/10 text-primary",
-    // Neutral
-    "muted": "bg-muted text-muted-foreground",
-    // Named colors (for layout demos with distinct cells)
-    "blue": "bg-blue-500/15 text-blue-700 dark:text-blue-300",
-    "amber": "bg-amber-500/15 text-amber-700 dark:text-amber-300",
-    "green": "bg-green-500/15 text-green-700 dark:text-green-300",
-    "purple": "bg-purple-500/15 text-purple-700 dark:text-purple-300",
-    "red": "bg-red-500/15 text-red-700 dark:text-red-300",
-};
+import { walkInline, applyTextFlags, renderLeaf, indent, isSafeHref, apiPageLayout, apiSymbolLevels, } from "@dogsbay/serialize-core";
+import { parseInline } from "@dogsbay/format-dogsbay-md";
+import { decorateDiff, hasDiffMarks } from "./diff-decoration.js";
+import { TONE_CLASSES } from "./tone-classes.js";
+import { apiBlockHtml, apiPropertiesHtml } from "./api-markdown.js";
+export { TONE_CLASSES };
 const COMPONENT_IMPORTS = {
     "markdown-example": [
         'import MarkdownExample from "@ui/markdown-example/MarkdownExample.astro";',
@@ -55,6 +39,9 @@ const COMPONENT_IMPORTS = {
     ],
     diagram: ['import Diagram from "@ui/diagram/Diagram.astro";'],
     youtube: ['import YouTube from "@ui/youtube/YouTube.astro";'],
+    badge: ['import Badge from "@ui/badge/Badge.astro";'],
+    kbd: ['import Kbd from "@ui/kbd/Kbd.astro";'],
+    files: ['import FileTree from "@ui/files/FileTree.astro";'],
     "math-block": ['import MathKatex from "@ui/math/MathKatex.astro";'],
     image: ['import BlockImage from "@ui/image/Image.astro";'],
     "api-class": ['import ApiSymbol from "@ui/api-symbol/ApiSymbol.astro";'],
@@ -96,6 +83,9 @@ const COMPONENT_IMPORTS = {
     "link-card": [
         'import LinkCard from "@ui/link-card/LinkCard.astro";',
     ],
+    "link-button": [
+        'import Button from "@ui/button/Button.astro";',
+    ],
     avatar: [
         'import Avatar from "@ui/avatar/Avatar.astro";',
     ],
@@ -109,12 +99,50 @@ export function escapeExpr(s) {
     // JSON.stringify handles all special characters (quotes, backslashes, newlines, etc.)
     // and produces a valid JS string literal. This avoids template literal edge cases
     // where backtick + brace combinations create false expression boundaries.
-    return JSON.stringify(s);
+    //
+    // `<` becomes \u003c: Astro parses the template as HTML before the expression is
+    // JavaScript, so a `<script>` inside a string (a code block showing one, say) would
+    // be taken for a real script tag and its text compiled as JavaScript. Vite's
+    // dependency scan then fails to parse it and a production build breaks.
+    return JSON.stringify(s).replace(/</g, "\\u003c");
 }
 /** Escape for use in an HTML attribute value (double-quoted). */
 export function escapeAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
+export function componentAttr(name, value) {
+    return /[&"<>]/.test(value)
+        ? ` ${name}={${escapeExpr(value)}}`
+        : ` ${name}="${value}"`;
+}
+/**
+ * Render extra attributes from an inline element's `attrs` field
+ * (links and images today; spans in a future phase) as ` key="val"`
+ * pairs prefixed with a leading space, suitable for splicing into an
+ * open tag immediately after the element's first-class attrs (href,
+ * src, etc.). `id`, `class`, and `style` are first-class; any other
+ * key passes through verbatim.
+ */
+/** `{…}` attributes on a COMPONENT (Badge, Button): `componentAttr`, which Astro does not entity-decode. */
+function renderInlineComponentAttrs(attrs) {
+    if (!attrs)
+        return "";
+    return Object.entries(attrs)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => componentAttr(key, String(value)))
+        .join("");
+}
+function renderInlineElementAttrs(attrs) {
+    if (!attrs)
+        return "";
+    const parts = [];
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === undefined)
+            continue;
+        parts.push(` ${key}="${escapeAttr(String(value))}"`);
+    }
+    return parts.join("");
+}
 /** Escape text for use directly in an Astro template (not inside an expression). */
 export function escapeTemplate(s) {
     let result = "";
@@ -149,6 +177,13 @@ export function treeToAstro(nodes, options) {
         mode: options?.mode ?? "template",
         imageOptimization: options?.imageOptimization ?? false,
         codeBlockTitle: options?.codeBlockTitle ?? true,
+        imageCaptions: options?.imageCaptions ?? false,
+        combinedPrefix: options?.combinedPrefix ?? "",
+        // Mixed prose+endpoint pages render endpoints as embedded blocks;
+        // pages that are nothing but endpoints/headings keep the
+        // full-viewport operation layout (the OpenAPI page shape).
+        embeddedEndpoints: apiPageLayout(nodes).embeddedEndpoints,
+        apiSymbolLevels: apiSymbolLevels(nodes),
     };
     // Pre-scan for inline `icon` nodes anywhere in the tree.
     // `inlineNodeToTemplate` is intentionally pure (no ctx) — it
@@ -157,9 +192,9 @@ export function treeToAstro(nodes, options) {
     // (card.props.icon) registers `icon` directly at the call
     // site; this pre-scan picks up the inline `:icon[name]`
     // directives the writer can drop into prose.
-    if (treeContainsInlineIcon(nodes)) {
-        ctx.imports.add("icon");
-    }
+    // Badges and inline buttons are components too, registered the same way.
+    for (const key of inlineComponentsIn(nodes))
+        ctx.imports.add(key);
     const body = nodes.map((n) => nodeToAstro(n, ctx)).filter(Boolean).join("\n");
     const imports = [];
     const seen = new Set();
@@ -181,7 +216,18 @@ export function treeToAstro(nodes, options) {
     };
 }
 // ─── Node dispatcher ──────────────────────────────────────────────
+/**
+ * Dispatch + diff decoration: nodes carrying DiffTree marks (from
+ * @dogsbay/tree-diff, read structurally) decorate the rendered
+ * snippet; unmarked nodes render byte-identically to before.
+ */
 function nodeToAstro(node, ctx) {
+    const rendered = nodeToAstroBase(node, ctx);
+    if (!rendered || !hasDiffMarks(node))
+        return rendered;
+    return decorateDiff(node, rendered, (peer) => nodeToAstroBase(peer, ctx));
+}
+function nodeToAstroBase(node, ctx) {
     switch (node.type) {
         case "prose":
             return proseToAstro(node, ctx);
@@ -193,6 +239,10 @@ function nodeToAstro(node, ctx) {
             return codeToAstro(node, ctx);
         case "callout":
             return calloutToAstro(node, ctx);
+        case "files":
+            return filesToAstro(node, ctx);
+        case "container":
+            return genericContainerToAstro(node, ctx);
         case "details":
             return detailsToAstro(node, ctx);
         case "tabs":
@@ -212,14 +262,23 @@ function nodeToAstro(node, ctx) {
             return wrapBlock("li", "", node, leafContent(node, ctx));
         case "blockquote":
             return wrapBlock("blockquote", "border-l-4 border-border pl-4 italic text-muted-foreground", node, childrenToAstro(node, ctx));
+        // A transparent grouping wrapper: renders its children inside a plain
+        // <div> and adds no semantics of its own. Exists so a caller can carry
+        // an attribute (a class, a data-* flag) for a whole run of blocks —
+        // the release comparison marks a wholly added/removed PAGE once, at
+        // the page level, instead of putting a bar on every block inside it.
+        case "group":
+            return wrapBlock("div", "", node, childrenToAstro(node, ctx));
         case "hr": {
             const classAttr = mergeClassAttr("my-8 border-border", node.props?.class);
             const passthrough = renderPassthroughAttrs(node.props, ["class"]);
             return `<hr${classAttr}${passthrough} />`;
         }
         case "html":
-            // Raw HTML always uses set:html — it may contain anything
-            return `<Fragment set:html={${escapeExpr(node.html ?? "")}} />`;
+            // Raw HTML always uses set:html — it may contain anything. Callouts inside it
+            // (dogsbay-md's HTML table fallback writes `<div role="note" data-callout>`)
+            // render as real callouts
+            return htmlToAstro(node.html ?? "", ctx);
         case "table":
             return tableToAstro(node, ctx);
         case "thead":
@@ -270,9 +329,20 @@ function nodeToAstro(node, ctx) {
             return exampleToAstro(node, ctx);
         case "figure": {
             const caption = node.props?.caption;
+            // A figure of one code block: the caption goes in the code block's header bar,
+            // which then is the figure's caption
+            const only = node.children?.length === 1 ? node.children[0] : undefined;
+            if (caption && only?.type === "code") {
+                return codeToAstro(only, ctx, {
+                    caption: captionToAstro(caption, ctx),
+                    // The figure's attributes, except those the code block has itself (an id twice is invalid)
+                    attrs: renderPassthroughAttrs(node.props, ["caption", "class", ...Object.keys(only.props ?? {})]),
+                    classes: ["my-4", node.props?.class].filter(Boolean).join(" "),
+                });
+            }
             const inner = childrenToAstro(node, ctx);
             const body = caption
-                ? `${inner}\n<figcaption class="text-center text-sm text-muted-foreground mt-2">${escapeTemplate(caption)}</figcaption>`
+                ? `${inner}\n<figcaption class="text-center text-sm text-muted-foreground mt-2">${captionToAstro(caption, ctx)}</figcaption>`
                 : inner;
             return wrapBlock("figure", "my-4", node, body, ["caption"]);
         }
@@ -297,6 +367,8 @@ function nodeToAstro(node, ctx) {
             return standaloneCardToAstro(node, ctx);
         case "link-card":
             return linkCardToAstro(node, ctx);
+        case "link-button":
+            return linkButtonToAstro(node, ctx);
         case "accordion":
             return accordionToAstro(node, ctx);
         case "accordion-item":
@@ -351,6 +423,28 @@ ${childrenToAstro(node, ctx)}
 ${childrenToAstro(node, ctx)}
 </GridItem>`;
         }
+        case "related": {
+            // #384 R3: AsciiDoc [role="_additional-resources"] + .Title + list folds
+            // to this semantic node (maps to DITA <related-links>). Render a titled
+            // section, not a TOC heading. The title is a caption (block title), so a
+            // styled <p>, not an <h2>.
+            const title = node.props?.title;
+            const classAttr = mergeClassAttr("related-resources", node.props?.class);
+            const passthrough = renderPassthroughAttrs(node.props, ["title", "class"]);
+            const titleHtml = title
+                ? `<p class="related-resources-title">${escapeTemplate(title)}</p>\n`
+                : "";
+            return `<section${classAttr}${passthrough}>\n${titleHtml}${childrenToAstro(node, ctx)}\n</section>`;
+        }
+        case "mdx-raw": {
+            // Preserved-but-unmapped MDX component (format-mdx never-drop; see
+            // docs-dev/format-mdx-adapters.md). Rendered as a visible source
+            // block — the content must not silently disappear from the HTML
+            // output. Map the component (adapter / mdx.components config) to
+            // upgrade it to a real widget.
+            const source = String(node.props?.source ?? "");
+            return `<pre class="mdx-raw my-4 overflow-x-auto rounded-md border bg-muted p-4 text-sm"><code>{${escapeExpr(source)}}</code></pre>`;
+        }
         default:
             if (node.html)
                 return `<Fragment set:html={${escapeExpr(node.html)}} />`;
@@ -360,37 +454,74 @@ ${childrenToAstro(node, ctx)}
     }
 }
 // ─── Inline rendering ─────────────────────────────────────────────
-/** Render inline nodes as Astro template markup (clean, editable). */
-function inlineToTemplate(nodes) {
-    return nodes.map(inlineNodeToTemplate).join("");
-}
-function inlineNodeToTemplate(node) {
-    switch (node.type) {
-        case "text": {
-            let text = escapeTemplate(node.text);
-            if (node.bold)
-                text = `<strong>${text}</strong>`;
-            if (node.italic)
-                text = `<em>${text}</em>`;
-            if (node.strikethrough)
-                text = `<s>${text}</s>`;
-            return text;
-        }
-        case "link": {
-            const titleAttr = node.title ? ` title="${escapeAttr(node.title)}"` : "";
-            return `<a href="${escapeAttr(node.href)}"${titleAttr}>${inlineToTemplate(node.children)}</a>`;
-        }
-        case "image":
-            return `<img src="${escapeAttr(node.src)}" alt="${escapeAttr(node.alt ?? "")}" loading="lazy" />`;
-        case "code":
-            return `<code>${escapeTemplate(node.text)}</code>`;
-        case "footnote-ref":
-            return `<sup><a href="#fn-${escapeAttr(node.label)}" id="fnref-${escapeAttr(node.label)}" class="text-primary hover:underline">[${escapeTemplate(node.label)}]</a></sup>`;
-        case "kbd":
-            return node.keys.map((k) => `<kbd>${escapeTemplate(k)}</kbd>`).join("+");
-        case "math":
-            return `<code class="math-inline">${escapeTemplate(node.latex)}</code>`;
-        case "icon": {
+/**
+ * Astro's two inline dialects, as emitters over serialize-core's shared walk.
+ *
+ * These were the THIRD and FOURTH copies of the 11-variant switch (obsidian and
+ * dogsbay-md's html fallback were the other two), and the duplication is
+ * precisely why `highlight` was missing from BOTH of them: adding an arm meant
+ * remembering four places, so `:highlight[…]` rendered as nothing at all on
+ * every Astro page. The walk is now shared, so a variant is handled in one
+ * place per format instead of being silently skippable.
+ *
+ * Only the leaf syntax differs between the two maps: template mode escapes for
+ * Astro's `{}` and emits real components (`<Icon>`, `<Fragment set:html>`),
+ * hybrid mode escapes for plain HTML and emits inert markup.
+ */
+/** Canonical highlight styling — keep in sync with InlineRenderer.astro. */
+const HIGHLIGHT_CLASS = "rounded-sm bg-yellow-200/60 px-0.5 dark:bg-yellow-500/30";
+function templateInlineEmitters() {
+    return {
+        text: (node, ctx) => applyTextFlags(ctx.escape(node.text), node, {
+            bold: (s) => `<strong>${s}</strong>`,
+            italic: (s) => `<em>${s}</em>`,
+            strike: (s) => `<s>${s}</s>`,
+        }),
+        link: (node, ctx) => {
+            // A link node an importer built directly never passed markdown-it's
+            // scheme check: a `javascript:` href keeps its text and loses the link.
+            if (!isSafeHref(node.href)) {
+                ctx.report("link", `unsafe link target dropped (${node.href.slice(0, 40)})`);
+                return ctx.recurse(node.children);
+            }
+            const titleAttr = node.title ? componentAttr("title", node.title) : "";
+            const extraAttrs = renderInlineElementAttrs(node.attrs);
+            // An inline `:button`: the Button component, small, keeping its variant ("primary" is the filled default).
+            if (node.button) {
+                const variant = buttonVariant(node.button.variant);
+                return `<Button${componentAttr("href", node.href)}${componentAttr("variant", variant)} size="sm"${titleAttr}${renderInlineComponentAttrs(node.attrs)}>${ctx.recurse(node.children)}</Button>`;
+            }
+            return `<a href="${escapeAttr(node.href)}"${titleAttr}${extraAttrs}>${ctx.recurse(node.children)}</a>`;
+        },
+        badge: (node, ctx) => `<Badge${componentAttr("variant", node.variant ?? "default")}${renderInlineComponentAttrs(node.attrs)}>${ctx.escape(node.text)}</Badge>`,
+        image: (node, ctx) => {
+            if (!isSafeHref(node.src, "image")) {
+                ctx.report("image", `unsafe image source dropped (${node.src.slice(0, 40)})`);
+                return ctx.escape(node.alt ?? "");
+            }
+            const extraAttrs = renderInlineElementAttrs(node.attrs);
+            return `<img src="${escapeAttr(node.src)}" alt="${escapeAttr(node.alt ?? "")}" loading="lazy"${extraAttrs} />`;
+        },
+        // Code inherits the emphasis around it (`*using the \`dita\` command*`): the parser
+        // flags the code span, and dropping the flags split the italics around the code
+        code: (node, ctx) => applyTextFlags(`<code>${ctx.escape(node.text)}</code>`, node, {
+            bold: (s) => `<strong>${s}</strong>`,
+            italic: (s) => `<em>${s}</em>`,
+            strike: (s) => `<s>${s}</s>`,
+        }),
+        // The arm that did not exist — `:highlight[…]` / `:mark[…]` rendered as
+        // nothing at all. The class list mirrors the canonical rendering in
+        // `packages/ui/src/content-renderer/InlineRenderer.astro`, so a highlight
+        // looks the same however a page is produced. A BARE `<mark>` would have
+        // been "fixed" but unstyled: the generated `.docs-prose` stylesheet had no
+        // `mark` rule, so browsers paint their default yellow — including on dark
+        // pages, where nothing declares `color-scheme`.
+        highlight: (node, ctx) => `<mark class="${HIGHLIGHT_CLASS}">${ctx.recurse(node.children)}</mark>`,
+        "footnote-ref": (node, ctx) => `<sup><a href="#fn-${escapeAttr(node.label)}" id="fnref-${escapeAttr(node.label)}" class="text-primary hover:underline">[${ctx.escape(node.label)}]</a></sup>`,
+        // The Kbd component (keys styled as keycaps); plain <kbd> had no style beyond a monospace font.
+        kbd: (node, ctx) => node.keys.map((k) => `<Kbd>${ctx.escape(k)}</Kbd>`).join("+"),
+        math: (node, ctx) => `<code class="math-inline">${ctx.escape(node.latex)}</code>`,
+        icon: (node) => {
             // Inline icon — emits the platform `<Icon>` component which
             // resolves at build time against Lucide (default) plus any
             // other Iconify pack via the `pack:name` shorthand. Caller
@@ -404,47 +535,37 @@ function inlineNodeToTemplate(node) {
             // to Lucide for everything.
             const fullName = node.library ? `${node.library}:${node.name}` : node.name;
             return `<Icon name="${escapeAttr(fullName)}" class="inline-block size-[1em] align-[-0.125em]" />`;
-        }
-        case "html-inline":
-            // Raw HTML inline — must use set:html to avoid brace issues
-            return `<Fragment set:html={${escapeExpr(node.html)}} />`;
-        case "break":
-            return "<br />";
-        default:
-            return "";
-    }
-}
-/** Render inline nodes as HTML string (for hybrid mode set:html). */
-function inlineToHtml(nodes) {
-    return nodes.map(inlineNodeToHtml).join("");
+        },
+        // Raw HTML inline — must use set:html to avoid brace issues
+        "html-inline": (node) => `<Fragment set:html={${escapeExpr(node.html)}} />`,
+        break: () => "<br />",
+    };
 }
-function inlineNodeToHtml(node) {
-    switch (node.type) {
-        case "text": {
-            let text = escapeHtml(node.text);
-            if (node.bold)
-                text = `<strong>${text}</strong>`;
-            if (node.italic)
-                text = `<em>${text}</em>`;
-            if (node.strikethrough)
-                text = `<s>${text}</s>`;
-            return text;
-        }
-        case "link": {
+function htmlModeInlineEmitters() {
+    return {
+        ...templateInlineEmitters(),
+        // Inherited from the template map, this emitted `title={"…"}` — an
+        // EXPRESSION, inside a string that becomes a `set:html` value. Astro never
+        // parses it as markup, so the reader saw the braces and quotes.
+        link: (node, ctx) => {
+            if (!isSafeHref(node.href)) {
+                ctx.report("link", `unsafe link target dropped (${node.href.slice(0, 40)})`);
+                return ctx.recurse(node.children);
+            }
             const titleAttr = node.title ? ` title="${escapeAttr(node.title)}"` : "";
-            return `<a href="${escapeAttr(node.href)}"${titleAttr}>${inlineToHtml(node.children)}</a>`;
-        }
-        case "image":
-            return `<img src="${escapeAttr(node.src)}" alt="${escapeAttr(node.alt ?? "")}" loading="lazy" />`;
-        case "code":
-            return `<code>${escapeHtml(node.text)}</code>`;
-        case "footnote-ref":
-            return `<sup><a href="#fn-${escapeAttr(node.label)}" id="fnref-${escapeAttr(node.label)}" class="text-primary hover:underline">[${escapeHtml(node.label)}]</a></sup>`;
-        case "kbd":
-            return node.keys.map((k) => `<kbd>${escapeHtml(k)}</kbd>`).join("+");
-        case "math":
-            return `<code class="math-inline">${escapeHtml(node.latex)}</code>`;
-        case "icon": {
+            const extraAttrs = renderInlineElementAttrs(node.attrs);
+            // No components in HTML mode: a marked link (and a marked span for a badge below).
+            const button = node.button ? ` data-button data-variant="${escapeAttr(buttonVariant(node.button.variant))}"` : "";
+            return `<a href="${escapeAttr(node.href)}"${titleAttr}${button}${extraAttrs}>${ctx.recurse(node.children)}</a>`;
+        },
+        kbd: (node, ctx) => node.keys.map((k) => `<kbd>${ctx.escape(k)}</kbd>`).join("+"),
+        badge: (node, ctx) => `<span data-badge data-variant="${escapeAttr(node.variant ?? "default")}"${renderInlineElementAttrs(node.attrs)}>${ctx.escape(node.text)}</span>`,
+        text: (node, ctx) => applyTextFlags(ctx.escape(node.text), node, {
+            bold: (s) => `<strong>${s}</strong>`,
+            italic: (s) => `<em>${s}</em>`,
+            strike: (s) => `<s>${s}</s>`,
+        }),
+        icon: (node) => {
             // Hybrid-mode HTML rendering — fall back to a textual
             // shortcode reference when we can't inline the SVG. Real
             // resolution happens in template mode via the <Icon>
@@ -452,14 +573,19 @@ function inlineNodeToHtml(node) {
             // production output.
             const fullName = node.library ? `${node.library}:${node.name}` : node.name;
             return `<span class="dogsbay-icon" data-icon="${escapeAttr(fullName)}"></span>`;
-        }
-        case "html-inline":
-            return node.html;
-        case "break":
-            return "<br />";
-        default:
-            return "";
-    }
+        },
+        "html-inline": (node) => node.html,
+    };
+}
+const TEMPLATE_INLINE = templateInlineEmitters();
+const HTML_INLINE = htmlModeInlineEmitters();
+/** Render inline nodes as Astro template markup (clean, editable). */
+function inlineToTemplate(nodes) {
+    return walkInline(nodes, { emitters: TEMPLATE_INLINE, escape: escapeTemplate });
+}
+/** Render inline nodes as HTML string (for hybrid mode set:html). */
+function inlineToHtml(nodes) {
+    return walkInline(nodes, { emitters: HTML_INLINE, escape: escapeHtml });
 }
 /** Render inline content in the current mode. */
 function renderInline(nodes, ctx) {
@@ -467,6 +593,8 @@ function renderInline(nodes, ctx) {
         const html = inlineToHtml(nodes);
         return `<Fragment set:html={${escapeExpr(html)}} />`;
     }
+    // Inline parsed from a prop (a caption) is not in the page-level pre-scan; its components are imported here.
+    inlineComponentsIn([{ type: "paragraph", inline: nodes }], ctx.imports);
     return inlineToTemplate(nodes);
 }
 /** Render an HTML string in the current mode. */
@@ -487,18 +615,24 @@ function headingToAstro(node, ctx) {
     // `id` takes precedence over `slug` (slug is auto-generated, id is explicit user override)
     const id = node.props?.id ?? node.props?.slug ?? "";
     const anchor = id
-        ? `<a href="#${escapeAttr(id)}" class="ml-2 text-muted-foreground opacity-0 group-hover:opacity-100 no-underline" aria-hidden="true" tabindex="-1">&para;</a>`
+        ? `<a href="#${escapeAttr(id)}" class="ml-2 text-muted-foreground opacity-0 group-hover:opacity-100 no-underline" aria-hidden="true" tabindex="-1" data-pagefind-ignore>&para;</a>`
         : "";
     const idAttr = id ? ` id="${escapeAttr(id)}"` : "";
-    const classAttr = mergeClassAttr("group scroll-mt-20", node.props?.class);
-    const passthrough = renderPassthroughAttrs(node.props, [
-        "level", "slug", "id", "class", "text",
-    ]);
+    const consumed = ["level", "slug", "id", "class", "text"];
+    const userClass = node.props?.class;
     if (ctx.mode === "template" && node.inline) {
+        // Real Astro markup: expressions are parsed.
+        const classAttr = mergeClassAttr("group scroll-mt-20", userClass);
+        const passthrough = renderPassthroughAttrs(node.props, consumed);
         const text = inlineToTemplate(node.inline);
         return `<h${level}${idAttr}${classAttr}${passthrough}>${text}${anchor}</h${level}>`;
     }
-    // Hybrid or no inline — use set:html for the whole heading
+    // Hybrid or no inline — the whole heading becomes a set:html STRING, where an
+    // expression would be literal text. Every MDX/Mintlify heading takes this
+    // branch (that importer emits `props.text` + children, never `inline`), so
+    // this is the common path, not an edge case.
+    const classAttr = mergeClassAttr("group scroll-mt-20", userClass, "html");
+    const passthrough = renderPassthroughAttrs(node.props, consumed, "html");
     const text = node.inline ? inlineToHtml(node.inline) : node.props?.text ?? "";
     const html = `<h${level}${idAttr}${classAttr}${passthrough}>${text}${anchor}</h${level}>`;
     return `<Fragment set:html={${escapeExpr(html)}} />`;
@@ -515,15 +649,28 @@ function paragraphToAstro(node, ctx) {
         if (meaningful.length === 1 && meaningful[0].type === "image") {
             const img = meaningful[0];
             ctx.imports.add("image");
+            // imageMap is keyed by the unprefixed publicPath built from
+            // `import.meta.glob("/src/assets/**", ...)` at runtime, so
+            // strip the URL prefix back off if rewriteTreeImageSrcs has
+            // already applied it. Keeps the optimized-image lookup working
+            // alongside the prefix-on-emit fix.
+            const lookupKey = ctx.combinedPrefix && img.src.startsWith(`${ctx.combinedPrefix}/`)
+                ? img.src.slice(ctx.combinedPrefix.length)
+                : img.src;
             const imgDataAttr = ctx.imageOptimization
-                ? ` imageData={imageMap[${escapeExpr(img.src)}]}`
+                ? ` imageData={imageMap[${escapeExpr(lookupKey)}]}`
                 : "";
             // Forward arbitrary `data-*` / `aria-*` attrs that plugins
             // may have attached to the wrapping paragraph (e.g.
             // @dogsbay/plugin-image-zoom tags `data-zoomable="true"` so
             // the runtime can attach handlers without scanning the DOM).
             const passthrough = renderPassthroughAttrs(node.props, ["class"]);
-            return `<BlockImage src="${escapeAttr(img.src)}" alt="${escapeAttr(img.alt ?? "")}"${passthrough}${imgDataAttr} />`;
+            // Author-supplied {.class #id ...} on the image itself
+            // (Phase 1.5 of plans/inline-attrs.md).
+            const imageAttrs = renderInlineElementAttrs(img.attrs);
+            // `content.imageCaptions: title`: the figure form of BlockImage, captioned by the title (as dogsbay-ssg).
+            const figure = ctx.imageCaptions && img.title ? ` block${componentAttr("title", img.title)}` : "";
+            return `<BlockImage${componentAttr("src", img.src)}${componentAttr("alt", img.alt ?? "")}${figure}${imageAttrs}${passthrough}${imgDataAttr} />`;
         }
     }
     const classAttr = mergeClassAttr("", node.props?.class);
@@ -550,7 +697,7 @@ function paragraphToAstro(node, ctx) {
     }).join("");
     return `<p${classAttr}${passthrough} set:html={${escapeExpr(html)}} />`;
 }
-function codeToAstro(node, ctx) {
+function codeToAstro(node, ctx, figure) {
     // Code content may live on props.code (Starlight convention) or node.html
     // (dogsbay-md convention). Same for lang — Starlight uses props.lang,
     // dogsbay-md uses props.language.
@@ -561,34 +708,48 @@ function codeToAstro(node, ctx) {
         ?? node.html
         ?? "";
     const title = node.props?.title;
-    const highlights = node.props?.highlights;
+    // The fence's documented `mark`, `ins` and `del` are CodeRich's highlights, diffAdd and diffRemove.
+    const lineSpec = (...values) => values.filter((v) => typeof v === "string" || typeof v === "number").map(String).filter(Boolean).join(",") || undefined;
+    const highlights = lineSpec(node.props?.highlights, node.props?.mark);
     const lineNumbers = node.props?.lineNumbers;
-    const isRich = lineNumbers || highlights || code.includes("[!code");
-    const classAttr = mergeClassAttr("", node.props?.class);
+    const copyText = node.props?.copyText;
+    const diffAdd = lineSpec(node.props?.diffAdd, node.props?.ins);
+    const diffRemove = lineSpec(node.props?.diffRemove, node.props?.del);
+    const isRich = lineNumbers || highlights || code.includes("[!code") || Boolean(diffAdd || diffRemove);
+    const classAttr = mergeClassAttr(figure?.classes ?? "", node.props?.class);
+    const figureAttrs = figure?.attrs ?? "";
+    // The component with its caption slot filled, or self-closing
+    const close = (tag, open) => figure ? `${open}>\n<Fragment slot="caption">${figure.caption}</Fragment>\n</${tag}>` : `${open} />`;
     const consumed = [
         "lang", "language", "code", "title", "highlights", "lineNumbers",
-        "class", "ins", "del", "mark", "collapse",
+        "class", "ins", "del", "mark", "collapse", "copyText", "diffAdd", "diffRemove",
     ];
     const passthrough = renderPassthroughAttrs(node.props, consumed);
     if (isRich) {
         ctx.imports.add("code-rich");
         const attrs = [`code={${escapeExpr(code)}}`, `lang="${escapeAttr(lang)}"`];
         if (title)
-            attrs.push(`title="${escapeAttr(title)}"`);
+            attrs.push(componentAttr("title", title).trimStart());
         if (lineNumbers)
             attrs.push("lineNumbers");
         if (highlights)
             attrs.push(`highlights="${escapeAttr(highlights)}"`);
-        return `<CodeRich ${attrs.join(" ")}${classAttr}${passthrough} />`;
+        if (copyText !== undefined)
+            attrs.push(`copyText={${escapeExpr(copyText)}}`);
+        if (diffAdd)
+            attrs.push(`diffAdd="${escapeAttr(diffAdd)}"`);
+        if (diffRemove)
+            attrs.push(`diffRemove="${escapeAttr(diffRemove)}"`);
+        return close("CodeRich", `<CodeRich ${attrs.join(" ")}${classAttr}${passthrough}${figureAttrs}`);
     }
     ctx.imports.add("code");
     const attrs = [`code={${escapeExpr(code)}}`, `lang="${escapeAttr(lang)}"`];
     if (title)
-        attrs.push(`title="${escapeAttr(title)}"`);
+        attrs.push(componentAttr("title", title).trimStart());
     if (ctx.codeBlockTitle !== true) {
         attrs.push(`showTitle="${ctx.codeBlockTitle}"`);
     }
-    return `<CodeBlock ${attrs.join(" ")}${classAttr}${passthrough} />`;
+    return close("CodeBlock", `<CodeBlock ${attrs.join(" ")}${classAttr}${passthrough}${figureAttrs}`);
 }
 // Map GitHub alert names (and other aliases) to Alert component variants.
 // The Alert variant palette follows MkDocs Material; not every GitHub name
@@ -600,6 +761,71 @@ const CALLOUT_VARIANT_MAP = {
     hint: "tip",
     attention: "warning",
 };
+// Default title shown when a callout has no explicit one, keyed by the type
+// the author wrote: aliases share a look but keep their own name (`:::info` is
+// "Info", not the "Important" of the variant it shares). The same labels as
+// dogsbay-ssg (src/render/icons.ts CALLOUTS). Anything else: the type, capitalised.
+const CALLOUT_LABELS = {
+    note: "Note",
+    info: "Info",
+    tip: "Tip",
+    hint: "Hint",
+    success: "Success",
+    important: "Important",
+    warning: "Warning",
+    attention: "Attention",
+    caution: "Caution",
+    danger: "Danger",
+    error: "Error",
+    failure: "Failure",
+    question: "Question",
+    bug: "Bug",
+    example: "Example",
+    abstract: "Abstract",
+    quote: "Quote",
+};
+const CALLOUT_OPEN = /<div role="note" data-callout="([^"]*)"(?: data-title="([^"]*)")?>/g;
+/**
+ * Raw HTML as set:html fragments, with each marked callout div rendered by
+ * calloutToAstro. The fragments around a callout may hold unbalanced tags
+ * (`<table><tr><td>` before, `</td></tr></table>` after); set:html writes
+ * them verbatim, so the page's HTML is whole again.
+ */
+function htmlToAstro(html, ctx) {
+    const raw = (s) => (s ? `<Fragment set:html={${escapeExpr(s)}} />` : "");
+    const out = [];
+    let rest = html;
+    for (;;) {
+        CALLOUT_OPEN.lastIndex = 0;
+        const open = CALLOUT_OPEN.exec(rest);
+        if (!open)
+            break;
+        // The callout ends at its matching </div>
+        const divs = /<div\b|<\/div>/g;
+        divs.lastIndex = open.index + open[0].length;
+        let depth = 1;
+        let end = -1;
+        for (let m = divs.exec(rest); m; m = divs.exec(rest)) {
+            depth += m[0] === "</div>" ? -1 : 1;
+            if (depth === 0) {
+                end = m.index;
+                break;
+            }
+        }
+        if (end < 0)
+            break;
+        const unescape = (s) => s.replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+        out.push(raw(rest.slice(0, open.index)));
+        out.push(calloutToAstro({
+            type: "callout",
+            props: { type: unescape(open[1]), ...(open[2] !== undefined ? { title: unescape(open[2]) } : {}) },
+            children: [{ type: "html", html: rest.slice(open.index + open[0].length, end) }],
+        }, ctx));
+        rest = rest.slice(end + "</div>".length);
+    }
+    out.push(raw(rest));
+    return out.filter(Boolean).join("\n") || raw(html);
+}
 function calloutToAstro(node, ctx) {
     ctx.imports.add("callout");
     // Callout variant may live on props.variant (Starlight / MkDocs importers)
@@ -608,9 +834,18 @@ function calloutToAstro(node, ctx) {
         ?? node.props?.type
         ?? "note").toLowerCase();
     const variant = CALLOUT_VARIANT_MAP[rawVariant] ?? rawVariant;
-    const title = node.props?.title ?? "";
+    // When the source gives no explicit title, fall back to the type label
+    // (Note / Warning / …) instead of an empty <AlertTitle> — AsciiDoc
+    // admonitions and GitHub-style alerts both show the type next to the icon,
+    // and an empty title leaves the icon standing alone. Issue #004.
+    const explicitTitle = node.props?.title;
+    // The default title names the authored type, not the variant it maps to.
+    const title = explicitTitle && explicitTitle.length > 0
+        ? explicitTitle
+        : CALLOUT_LABELS[rawVariant] ?? rawVariant.charAt(0).toUpperCase() + rawVariant.slice(1);
     const icon = node.props?.icon;
-    const iconAttr = icon ? ` icon="${escapeAttr(icon)}"` : "";
+    // The authored type (`hint`, `caution`) beside the variant it shares, as dogsbay-ssg writes it.
+    const iconAttr = (icon ? ` icon="${escapeAttr(icon)}"` : "") + (node.props?.["data-type"] === undefined ? ` data-type="${escapeAttr(rawVariant)}"` : "");
     // User classes and passthrough attributes (id, data-*, aria-*, style)
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
@@ -629,15 +864,19 @@ ${indentStr(inner, 4)}
  * Concatenates (user classes appended) so utility frameworks like Tailwind
  * resolve conflicts via component-internal class-variance-authority / tv().
  */
-function mergeClassAttr(defaults, userClass) {
+function mergeClassAttr(defaults, userClass, target = "astro") {
     const combined = [defaults, userClass].filter(Boolean).join(" ").trim();
-    return combined ? ` class="${escapeAttr(combined)}"` : "";
+    if (!combined)
+        return "";
+    return target === "html"
+        ? ` class="${escapeAttr(combined)}"`
+        : componentAttr("class", combined);
 }
 /**
  * Render attributes not consumed as component props — `id`, `data-*`, `aria-*`,
  * and `style`. These pass through to the rendered element.
  */
-function renderPassthroughAttrs(props, consumed) {
+function renderPassthroughAttrs(props, consumed, target = "astro") {
     if (!props)
         return "";
     const skip = new Set([...consumed, "source", "children"]);
@@ -652,9 +891,12 @@ function renderPassthroughAttrs(props, consumed) {
         if (value === true) {
             parts.push(key);
         }
-        else {
+        else if (target === "html") {
             parts.push(`${key}="${escapeAttr(String(value))}"`);
         }
+        else {
+            parts.push(componentAttr(key, String(value)).trimStart());
+        }
     }
     return parts.length ? " " + parts.join(" ") : "";
 }
@@ -717,21 +959,59 @@ function wrapBlock(tag, defaultClass, node, content, consumed = []) {
     return `<${tag}${classAttr}${passthrough}>${sep}${content}${sep}</${tag}>`;
     void needsNewline;
 }
+/**
+ * `:::files` around a nested bullet list: FileTree, whose markup (files/markup.ts) dogsbay-ssg
+ * shares. An entry is a folder when it has entries or its name ends in "/".
+ */
+function filesToAstro(node, ctx) {
+    ctx.imports.add("files");
+    const isList = (n) => n.type === "unordered-list" || n.type === "ordered-list";
+    const items = (list) => (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(isList);
+        const text = inline.map((n) => ("text" in n && typeof n.text === "string" ? n.text : "")).join("");
+        return { label: inlineToHtml(inline), folder: !!sub || /\/\s*$/.test(text), children: items(sub) };
+    });
+    const classAttr = mergeClassAttr("", node.props?.class);
+    // Each list is a tree; anything else in the block (an intro, a note) renders as it is.
+    // `<` is escaped in the JSON: a label may hold inline HTML, and a literal `</script>` in an
+    // expression breaks Vite's dependency scan (see escapeExpr).
+    return (node.children ?? [])
+        .map((child) => isList(child)
+        ? `<FileTree items={${JSON.stringify(items(child)).replace(/</g, "\\u003c")}}${classAttr} />`
+        : nodeToAstro(child, ctx))
+        .filter(Boolean)
+        .join("\n");
+}
+/**
+ * A `:::name` block with a name no renderer knows (a generic container): its content in a
+ * marked <div>, the title (text after the name) first.
+ */
+function genericContainerToAstro(node, ctx) {
+    const name = typeof node.meta?.name === "string" ? node.meta.name : "container";
+    const title = typeof node.meta?.title === "string" ? `<p class="font-semibold">${escapeTemplate(node.meta.title)}</p>\n` : "";
+    const classAttr = mergeClassAttr("", node.props?.class);
+    const passthrough = renderPassthroughAttrs(node.props, ["class"]);
+    return `<div data-directive="${escapeAttr(name)}"${classAttr}${passthrough}>\n${title}${childrenToAstro(node, ctx)}\n</div>`;
+}
 function detailsToAstro(node, ctx) {
     ctx.imports.add("details");
-    const variant = node.props?.variant ?? "note";
+    // `variant` as documented; `type` as dogsbay-ssg (and callouts) read it.
+    const variant = node.props?.variant ?? node.props?.type ?? "note";
     const title = node.props?.title ?? "Details";
     const open = node.props?.open;
     const icon = node.props?.icon;
     const inner = childrenToAstro(node, ctx);
-    const attrs = [`variant="${escapeAttr(variant)}"`, `title="${escapeAttr(title)}"`];
+    const attrs = [`variant="${escapeAttr(variant)}"`, componentAttr("title", title).trimStart()];
     if (open)
         attrs.push("open");
     if (icon)
         attrs.push(`icon="${escapeAttr(icon)}"`);
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
-        "variant", "title", "open", "icon", "class", "summary",
+        "variant", "type", "title", "open", "icon", "class", "summary",
     ]);
     return `<CollapsibleAlert ${attrs.join(" ")}${classAttr}${passthrough}>
 ${indentStr(inner, 2)}
@@ -749,29 +1029,98 @@ function tabsToAstro(node, ctx) {
         return { value, label, node: tab };
     });
     const defaultValue = tabItems[0].value;
+    // Diff-trigger indicator: a marked tab panel is invisible until
+    // opened, so its TRIGGER carries a data-diff-tab attribute (styled
+    // as a colored dot by DIFF_CSS) telling the reader WHICH tab to
+    // open. Structural read of @dogsbay/tree-diff marks, same as
+    // diff-decoration; unmarked trees are unaffected.
+    const tabDiffSignal = (tab) => {
+        const own = tab.diff;
+        if (own)
+            return own;
+        const deep = (n) => Boolean(n.diff || n.diffInline) || (n.children ?? []).some(deep);
+        return (tab.children ?? []).some(deep) ? "changed" : undefined;
+    };
+    // The indicator must not live in COLOUR alone (WCAG 1.4.1), and a
+    // background-tinted dot disappears in forced-colors mode. So it is a
+    // GLYPH (shape carries the meaning) plus visually-hidden text, so the
+    // trigger announces "Astro, changed in this comparison" rather than
+    // relying on a `title` screen readers may never speak.
+    const TAB_GLYPH = {
+        added: "+",
+        changed: "•",
+        removed: "−",
+        moved: "→",
+    };
     const triggers = tabItems
-        .map((t) => `    <TabsTrigger value="${escapeAttr(t.value)}">${escapeTemplate(t.label)}</TabsTrigger>`)
+        .map((t) => {
+        const signal = tabDiffSignal(t.node);
+        if (!signal) {
+            return `    <TabsTrigger${componentAttr("value", t.value)}>${escapeTemplate(t.label)}</TabsTrigger>`;
+        }
+        const glyph = TAB_GLYPH[signal] ?? "•";
+        // The glyph and its announced text are ONE element: "Hide
+        // highlights" hides `.db-tab-mark`, and a sibling sr-only span
+        // would survive that — leaving screen-reader users still hearing
+        // "changed in this comparison" on every tab while the visible
+        // marker is gone (code review, 2026-07-13).
+        const marker = `<span class="db-tab-mark" data-diff-tab="${escapeAttr(signal)}">` +
+            `<span aria-hidden="true">${glyph}</span>` +
+            `<span class="sr-only">${escapeTemplate(signal)} in this comparison</span>` +
+            `</span>`;
+        // `value` MUST match TabsContent's, which is a componentAttr expression:
+        // a title containing `&` was emitted `&amp;` here and `&` there, so the
+        // trigger and its panel no longer paired and the tab rendered empty.
+        // `data-diff-tab` is a plain data attribute — entity escaping is right.
+        return `    <TabsTrigger${componentAttr("value", t.value)} data-diff-tab="${escapeAttr(signal)}">${escapeTemplate(t.label)}<Fragment set:html={${escapeExpr(marker)}} /></TabsTrigger>`;
+    })
         .join("\n");
     const contents = tabItems
         .map((t) => {
         const inner = childrenToAstro(t.node, ctx);
-        return `  <TabsContent value="${escapeAttr(t.value)}">\n${indentStr(inner, 4)}\n  </TabsContent>`;
+        return `  <TabsContent${componentAttr("value", t.value)}>\n${indentStr(inner, 4)}\n  </TabsContent>`;
     })
         .join("\n");
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, ["sync", "default", "class"]);
-    return `<Tabs defaultValue="${escapeAttr(defaultValue)}"${classAttr}${passthrough}>
+    // Groups with the same key switch together (db-tabs). Written `syncKey`, `sync-key` or `group`, as dogsbay-ssg reads it.
+    const syncKey = [node.props?.syncKey, node.props?.["sync-key"], node.props?.group].find((v) => typeof v === "string" && v !== "");
+    const syncAttr = syncKey ? componentAttr("syncKey", syncKey) : "";
+    // Same encoding as the trigger/content `value` it selects — see above.
+    return `<Tabs${componentAttr("defaultValue", defaultValue)}${syncAttr}${classAttr}${passthrough}>
   <TabsList>
 ${triggers}
   </TabsList>
 ${contents}
 </Tabs>`;
 }
+/**
+ * A caption is inline Markdown. Plain text renders exactly as before;
+ * formatting (`Sample \`<plugin>\` file`) renders as inline markup.
+ */
+function captionInline(caption) {
+    return parseInline(caption);
+}
+const isPlainCaption = (nodes) => nodes.every((n) => n.type === "text" && !n.bold && !n.italic && !n.strikethrough);
+function captionToAstro(caption, ctx) {
+    const nodes = captionInline(caption);
+    return isPlainCaption(nodes)
+        ? escapeTemplate(nodes.map((n) => (n.type === "text" ? n.text : "")).join(""))
+        : renderInline(nodes, ctx);
+}
 function tableToAstro(node, ctx) {
     ctx.imports.add("table");
     const classAttr = mergeClassAttr("my-4", node.props?.class);
-    const passthrough = renderPassthroughAttrs(node.props, ["class"]);
-    return `<Table${classAttr}${passthrough}>\n${childrenToAstro(node, ctx)}\n</Table>`;
+    const caption = node.props?.caption;
+    const nodes = caption ? captionInline(caption) : [];
+    const plain = isPlainCaption(nodes);
+    // A plain caption stays the `caption` prop; a formatted one fills the table's caption slot
+    const captionAttr = caption && plain
+        ? ` caption={${escapeExpr(nodes.map((n) => (n.type === "text" ? n.text : "")).join(""))}}`
+        : "";
+    const captionSlot = caption && !plain ? `<Fragment slot="caption">${renderInline(nodes, ctx)}</Fragment>\n` : "";
+    const passthrough = renderPassthroughAttrs(node.props, ["class", "caption"]);
+    return `<Table${classAttr}${captionAttr}${passthrough}>\n${captionSlot}${childrenToAstro(node, ctx)}\n</Table>`;
 }
 function diagramToAstro(node, ctx) {
     ctx.imports.add("diagram");
@@ -781,7 +1130,7 @@ function diagramToAstro(node, ctx) {
     const title = node.props?.title;
     const attrs = [`lang="${escapeAttr(lang)}"`, `code={${escapeExpr(code)}}`, `svg={${escapeExpr(svg)}}`];
     if (title)
-        attrs.push(`title="${escapeAttr(title)}"`);
+        attrs.push(componentAttr("title", title).trimStart());
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
         "lang", "code", "svg", "title", "class",
@@ -794,7 +1143,7 @@ function youtubeToAstro(node, ctx) {
     const title = node.props?.title ?? "";
     const classAttr = mergeClassAttr("my-4", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, ["id", "title", "class"]);
-    return `<YouTube id="${escapeAttr(id)}" title="${escapeAttr(title)}"${classAttr}${passthrough} />`;
+    return `<YouTube${componentAttr("id", id)}${componentAttr("title", title)}${classAttr}${passthrough} />`;
 }
 function mathBlockToAstro(node, ctx) {
     ctx.imports.add("math-block");
@@ -837,6 +1186,11 @@ function footnoteListToAstro(node, ctx) {
 function footnoteDefToAstro(node, ctx) {
     const id = node.props?.id ?? "";
     const backrefId = node.props?.backrefId ?? "";
+    // Block content (a list, code): the blocks, with the backref after them
+    if (node.children?.length) {
+        const backref = backrefId ? `\n<a href="#${escapeAttr(backrefId)}" class="text-primary hover:underline">↩</a>` : "";
+        return `<li id="${escapeAttr(id)}" class="text-sm text-muted-foreground">\n${childrenToAstro(node, ctx)}${backref}\n</li>`;
+    }
     if (ctx.mode === "template" && node.inline) {
         const content = inlineToTemplate(node.inline);
         const backref = backrefId ? ` <a href="#${escapeAttr(backrefId)}" class="text-primary hover:underline">↩</a>` : "";
@@ -852,8 +1206,14 @@ function apiSymbolToAstro(node, ctx) {
     const kind = node.props?.kind ?? "func";
     const signature = node.props?.signature;
     const bases = node.props?.bases || [];
-    const level = node.type === "api-class" ? 2 : 3;
-    const attrs = [`name="${escapeAttr(name)}"`, `kind="${escapeAttr(kind)}"`, `level={${level}}`];
+    // By position, not by type (apiSymbolLevels): a module-level function was
+    // an h3 straight under the page's h1, and a class inside a class an h2.
+    const level = ctx.apiSymbolLevels.get(node) ?? (node.type === "api-class" ? 2 : 3);
+    const attrs = [
+        componentAttr("name", name).trimStart(),
+        componentAttr("kind", kind).trimStart(),
+        `level={${level}}`,
+    ];
     if (signature)
         attrs.push(`signature={${escapeExpr(signature)}}`);
     if (bases.length > 0)
@@ -902,11 +1262,17 @@ function endpointToAstro(node, ctx) {
     const path = props.path ?? "";
     const baseUrl = props.baseUrl ?? "";
     const summary = props.summary;
-    const description = props.description;
+    // Descriptions are CommonMark, rendered with raw HTML off: the components
+    // put them in the page with set:html (api-markdown.ts).
+    // (Compared as text first: the card hides a description equal to the
+    // summary, and the rendered HTML never equals it.)
+    const description = typeof props.description === "string" && props.description !== props.summary
+        ? apiBlockHtml(props.description)
+        : undefined;
     const deprecated = props.deprecated === true;
-    const parameters = props.parameters ?? [];
-    const requestBody = props.requestBody ?? [];
-    const responses = props.responses ?? [];
+    const parameters = apiPropertiesHtml(props.parameters) ?? [];
+    const requestBody = apiPropertiesHtml(props.requestBody) ?? [];
+    const responses = (props.responses ?? []).map((r) => r && Array.isArray(r.schema) ? { ...r, schema: apiPropertiesHtml(r.schema) } : r);
     const codeSamples = props.codeSamples ?? [];
     const requestBodyExample = props.requestBodyExample;
     const cardAttrs = [
@@ -946,7 +1312,9 @@ function endpointToAstro(node, ctx) {
     const sectionsBody = sections.length > 0
         ? `\n${indentStr(sections.join("\n"), 4)}\n  `
         : "";
-    // Code column — wrapped in <ApiCodePanel> for consistent vertical
+    // Code column — its titles are labels (<p>), not headings: an operation
+    // page has only its h1 above them, so an h3 skipped a level.
+    // Wrapped in <ApiCodePanel> for consistent vertical
     // rhythm. Code samples first, then a request body example, then one
     // ExampleBlock per response status that carries a concrete example.
     // Each ExampleBlock auto-detects language from the response's
@@ -955,7 +1323,7 @@ function endpointToAstro(node, ctx) {
     const codePanels = [];
     if (codeSamples.length > 0) {
         codePanels.push(`<div>\n` +
-            `  <h3 class="mb-3 text-xs font-semibold uppercase tracking-wider text-white/60">Code samples</h3>\n` +
+            `  <p class="mb-3 text-xs font-semibold uppercase tracking-wider text-white/60">Code samples</p>\n` +
             `  <CodeSamples samples={${JSON.stringify(codeSamples)}} />\n` +
             `</div>`);
     }
@@ -975,7 +1343,8 @@ function endpointToAstro(node, ctx) {
     const codeBody = codePanels.length > 0
         ? `\n${indentStr(codePanels.join("\n"), 4)}\n  `
         : "";
-    return (`<ApiLayout>\n` +
+    const layoutAttrs = ctx.embeddedEndpoints ? ' variant="embedded"' : "";
+    return (`<ApiLayout${layoutAttrs}>\n` +
         `  <EndpointCard ${cardAttrs.join(" ")}>${sectionsBody}</EndpointCard>\n` +
         `  <ApiCodePanel slot="code">${codeBody}</ApiCodePanel>\n` +
         `</ApiLayout>`);
@@ -993,13 +1362,16 @@ function cardsToAstro(node, ctx) {
     if (cardNodes.length > 0) {
         const cards = cardNodes.map((card) => {
             const title = card.props?.title ?? "";
-            const href = card.props?.href ?? "";
+            const href = safeHref(card.props?.href);
             const description = card.props?.description;
             const icon = card.props?.icon;
             // Description sources: inline content, children, or props.description.
-            const inner = childrenToAstro(card, ctx)
+            // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
+            const blocks = childrenToAstro(card, ctx);
+            const inner = blocks
                 || (card.inline ? inlineToTemplate(card.inline) : "")
                 || (description ? escapeTemplate(description) : "");
+            const descTag = blocks ? "div" : "p";
             // Icon renders inline before the title — picks up Lucide
             // SVG via the `icon` import. Resolved at build time; nothing
             // emitted when the name doesn't resolve (silent fallback).
@@ -1007,13 +1379,16 @@ function cardsToAstro(node, ctx) {
             // top of the page.
             let iconHtml = "";
             if (icon) {
-                ctx.imports.add("icon");
-                iconHtml = `<Icon name="${escapeAttr(icon)}" class="size-5 mb-2 text-muted-foreground" />`;
+                iconHtml = cardIconHtml(icon, title, ctx);
             }
             const titleHtml = title ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>` : "";
-            const desc = inner
-                ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</p>`
+            // A description and a body are both shown (the description used to be dropped when a body existed).
+            const lead = blocks && description
+                ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${escapeTemplate(description)}</p>`
                 : "";
+            const desc = lead + (inner
+                ? `<${descTag} class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</${descTag}>`
+                : "");
             const cardDefaultClass = href
                 ? "p-4 hover:border-foreground/20 transition-colors"
                 : "p-4";
@@ -1051,12 +1426,15 @@ function cardsToAstro(node, ctx) {
 function standaloneCardToAstro(node, ctx) {
     ctx.imports.add("card");
     const title = node.props?.title ?? "";
-    const href = node.props?.href ?? "";
+    const href = safeHref(node.props?.href);
     const description = node.props?.description;
     const icon = node.props?.icon;
-    const inner = childrenToAstro(node, ctx)
+    // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
+    const blocks = childrenToAstro(node, ctx);
+    const inner = blocks
         || (node.inline ? inlineToTemplate(node.inline) : "")
         || (description ? escapeTemplate(description) : "");
+    const descTag = blocks ? "div" : "p";
     // Icon renders inline before the title (same shape as the
     // cards-list path). Resolved at build time via @dogsbay/icons.
     let iconHtml = "";
@@ -1067,9 +1445,13 @@ function standaloneCardToAstro(node, ctx) {
     const titleHtml = title
         ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>`
         : "";
-    const desc = inner
-        ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</p>`
+    // A description and a body are both shown (the description used to be dropped when a body existed).
+    const lead = blocks && description
+        ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${escapeTemplate(description)}</p>`
         : "";
+    const desc = lead + (inner
+        ? `<${descTag} class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</${descTag}>`
+        : "");
     const cardDefaultClass = href
         ? "p-4 hover:border-foreground/20 transition-colors"
         : "p-4";
@@ -1089,6 +1471,59 @@ function standaloneCardToAstro(node, ctx) {
  * If the parser kept rich body children instead of folding into description,
  * we fall back to the standalone-card path which can hold arbitrary content.
  */
+/**
+ * `link-button` — a call-to-action link styled as a button.
+ *
+ * There was no case for this at all, so it fell through to rendering the
+ * node's CHILDREN: `<p>Get started</p>`. The label survived, the href did not,
+ * and nothing warned — the reader saw a stray sentence where the page's
+ * primary call to action should be. Every importer that produces one was
+ * affected; `Button.astro` has taken an `href` all along.
+ */
+/**
+ * A card icon is either a registry NAME or a path to an image file.
+ *
+ * `<Icon name>` resolves names and renders NOTHING when the name does not
+ * resolve — so a path handed to it disappeared silently, which is how every
+ * "Related products" card lost its logo without anyone noticing.
+ */
+function cardIconHtml(icon, title, ctx) {
+    if (/\.(svg|png|jpe?g|webp|avif)$/i.test(icon)) {
+        return `<img src="${escapeAttr(icon)}" alt="" class="size-5 mb-2" loading="lazy" />`;
+    }
+    ctx.imports.add("icon");
+    return `<Icon name="${escapeAttr(icon)}" class="size-5 mb-2 text-muted-foreground" />`;
+}
+/**
+ * A button's variant as `Button.astro` names it. The spec's `primary` is its
+ * filled `default` style; `Button.astro` has no `primary`, so it rendered
+ * with no fill at all.
+ */
+function buttonVariant(variant) {
+    return !variant || variant === "primary" ? "default" : variant;
+}
+function linkButtonToAstro(node, ctx) {
+    ctx.imports.add("link-button");
+    const href = safeHref(node.props?.href);
+    const written = node.props?.variant;
+    const variant = written === undefined ? undefined : buttonVariant(written);
+    const classAttr = mergeClassAttr("", node.props?.class);
+    const passthrough = renderPassthroughAttrs(node.props, ["href", "variant", "class"]);
+    // A button's label is phrasing content, so a lone paragraph child is
+    // unwrapped — `<Button><p>Get started</p></Button>` is invalid markup and
+    // renders with the paragraph's block spacing inside the button.
+    const kids = node.children ?? [];
+    const soleParagraph = kids.length === 1 && kids[0].type === "paragraph" ? kids[0] : undefined;
+    const label = soleParagraph
+        ? leafContent(soleParagraph, ctx)
+        : leafContent(node, ctx) || childrenToAstro(node, ctx);
+    return `<Button${componentAttr("href", href)}${variant ? componentAttr("variant", variant) : ""}${classAttr}${passthrough}>${label}</Button>`;
+}
+/** A card or button `href` from an importer, or "" (no link) when its
+ *  scheme could run script: these never passed markdown-it's link check. */
+function safeHref(href) {
+    return typeof href === "string" && isSafeHref(href) ? href : "";
+}
 function linkCardToAstro(node, ctx) {
     const hasRichChildren = (node.children ?? []).length > 0;
     if (hasRichChildren) {
@@ -1097,15 +1532,17 @@ function linkCardToAstro(node, ctx) {
     ctx.imports.add("link-card");
     const title = node.props?.title ?? "";
     const description = node.props?.description;
-    const href = node.props?.href ?? "";
-    const titleAttr = ` title="${escapeAttr(title)}"`;
-    const hrefAttr = ` href="${escapeAttr(href)}"`;
-    const descAttr = description ? ` description="${escapeAttr(description)}"` : "";
+    const href = safeHref(node.props?.href);
+    const titleAttr = componentAttr("title", title);
+    const hrefAttr = componentAttr("href", href);
+    const descAttr = description ? componentAttr("description", description) : "";
+    const icon = node.props?.icon;
+    const iconAttr = icon ? componentAttr("icon", icon) : "";
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
         "title", "description", "href", "icon", "class",
     ]);
-    return `<LinkCard${titleAttr}${descAttr}${hrefAttr}${classAttr}${passthrough} />`;
+    return `<LinkCard${titleAttr}${descAttr}${hrefAttr}${iconAttr}${classAttr}${passthrough} />`;
 }
 /**
  * Render an `accordion` TreeNode and its `accordion-item` children.
@@ -1124,9 +1561,9 @@ function accordionToAstro(node, ctx) {
     const defaultValue = node.props?.defaultValue;
     const typeAttr = ` type="${escapeAttr(type)}"`;
     const defaultAttr = defaultValue !== undefined
-        ? ` defaultValue=${typeof defaultValue === "string"
-            ? `"${escapeAttr(defaultValue)}"`
-            : `{${JSON.stringify(defaultValue)}}`}`
+        ? typeof defaultValue === "string"
+            ? componentAttr("defaultValue", defaultValue)
+            : ` defaultValue={${JSON.stringify(defaultValue)}}`
         : "";
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
@@ -1142,7 +1579,7 @@ function accordionItemToAstro(node, ctx, standalone) {
     ctx.imports.add("accordion");
     const value = node.props?.value ?? "item-1";
     const label = node.props?.label ?? node.props?.title ?? "Item";
-    const valueAttr = ` value="${escapeAttr(value)}"`;
+    const valueAttr = componentAttr("value", value);
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
         "value", "label", "title", "class",
@@ -1169,9 +1606,9 @@ function avatarToAstro(node, ctx) {
     const src = node.props?.src ?? "";
     const alt = node.props?.alt ?? "";
     const fallback = node.props?.fallback;
-    const srcAttr = src ? ` src="${escapeAttr(src)}"` : "";
-    const altAttr = ` alt="${escapeAttr(alt)}"`;
-    const fbAttr = fallback ? ` fallback="${escapeAttr(fallback)}"` : "";
+    const srcAttr = src ? componentAttr("src", src) : "";
+    const altAttr = componentAttr("alt", alt);
+    const fbAttr = fallback ? componentAttr("fallback", fallback) : "";
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
         "src", "alt", "fallback", "class",
@@ -1192,7 +1629,7 @@ function exampleToAstro(node, ctx) {
     const source = String(node.props?.source ?? "");
     const title = node.props?.title;
     const showFallback = node.props?.fallback === true || node.props?.fallback === "true";
-    const titleAttr = title ? ` title="${escapeAttr(title)}"` : "";
+    const titleAttr = title ? componentAttr("title", title) : "";
     const fallbackAttr = showFallback ? " showFallback" : "";
     const inner = childrenToAstro(node, ctx);
     return `<MarkdownExample source={${escapeExpr(source)}}${titleAttr}${fallbackAttr}>\n${inner}\n</MarkdownExample>`;
@@ -1212,24 +1649,25 @@ function htmlContainerToAstro(node, ctx) {
 }
 // ─── Utilities ────────────────────────────────────────────────────
 /**
- * Render a node's content whether it's attached as flat inline (dogsbay-md
- * parser shape) or as wrapped children (Starlight importer shape). Both
- * shapes supported; inline comes before children if both present.
+ * Render a node's content across all THREE TreeNode shapes: flat `inline`
+ * (dogsbay-md parser), wrapped `children[{prose, inline}]` (Starlight
+ * importer), and a node carrying only `html` (MDX/Starlight/MkDocs). Inline
+ * comes before children when both are present.
  *
  * Used for list-item, table cells, step, dt, dd — types that commonly
  * carry leaf text content directly on the node.
+ *
+ * This function is where serialize-core's `renderLeaf` was extracted FROM, so
+ * delegating to it closes the loop: the wrapper-dedup and html-shape handling
+ * the core grew afterwards (from the Docusaurus dogfooding bug) now flow back
+ * here instead of the two implementations continuing to drift apart.
  */
 function leafContent(node, ctx) {
-    const parts = [];
-    if (node.inline && node.inline.length > 0) {
-        parts.push(inlineToTemplate(node.inline));
-    }
-    if (node.children && node.children.length > 0) {
-        const rendered = childrenToAstro(node, ctx);
-        if (rendered)
-            parts.push(rendered);
-    }
-    return parts.join("\n");
+    return renderLeaf(node, {
+        inline: inlineToTemplate,
+        children: () => childrenToAstro(node, ctx),
+        html: (html) => `<Fragment set:html={${escapeExpr(html)}} />`,
+    });
 }
 function childrenToAstro(node, ctx) {
     if (!node.children || node.children.length === 0)
@@ -1243,39 +1681,28 @@ function childrenToAstro(node, ctx) {
  * icon usage on cards registers `icon` at the renderer call site;
  * this is the inline-only path. Returns true on first hit.
  */
-function treeContainsInlineIcon(nodes) {
-    if (!nodes)
-        return false;
-    for (const node of nodes) {
-        if (node.inline) {
-            for (const inl of node.inline) {
-                if (inlineHasIcon(inl))
-                    return true;
-            }
-        }
-        if (treeContainsInlineIcon(node.children))
-            return true;
-    }
-    return false;
-}
-function inlineHasIcon(node) {
-    if (node.type === "icon")
-        return true;
-    if ("children" in node && Array.isArray(node.children)) {
-        for (const child of node.children) {
-            if (inlineHasIcon(child))
-                return true;
-        }
+/** The component imports inline nodes need: `icon`, `badge`, and `link-button` for an inline `:button`. */
+function inlineComponentsIn(nodes, out = new Set()) {
+    const visit = (node) => {
+        if (node.type === "icon")
+            out.add("icon");
+        else if (node.type === "badge")
+            out.add("badge");
+        else if (node.type === "kbd")
+            out.add("kbd");
+        else if (node.type === "link" && node.button)
+            out.add("link-button");
+        if ("children" in node && Array.isArray(node.children))
+            node.children.forEach(visit);
+    };
+    for (const node of nodes ?? []) {
+        node.inline?.forEach(visit);
+        inlineComponentsIn(node.children, out);
     }
-    return false;
-}
-function indentStr(text, spaces) {
-    const prefix = " ".repeat(spaces);
-    return text
-        .split("\n")
-        .map((line) => (line ? `${prefix}${line}` : line))
-        .join("\n");
+    return out;
 }
+/** Indent, via the core's shared implementation (was a fourth local copy). */
+const indentStr = indent;
 function escapeHtml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }