@dogsbay/format-astro 0.2.0-beta.16 → 0.2.0-beta.161

package/dist/serialize.js

@@ -1,32 +1,10 @@
-/**
- * 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.
- *
- * Exported because the scaffolded site's `global.css` must safelist
- * these classes via `@source inline()` — they only appear in
- * markdown-generated `.astro` pages, which Tailwind's content
- * scanner doesn't always pick up reliably (and consumers who put
- * their content/ outside the scanned globs won't pick them up at
- * all). See generateGlobalCss in project.ts.
- */
-export 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, renderAroundGroup, isDetailsSheet, isEmptyTableHead, cardBodyHasLink, stepLead, stepTitle, } from "@dogsbay/serialize-core";
+import { parseInline } from "@dogsbay/format-dogsbay-md";
+import { decorateDiff, hasDiffMarks } from "./diff-decoration.js";
+import { TAB_GLYPH, tabDiffSignal } from "@dogsbay/render-html/diff";
+import { TONE_CLASSES, CARD_TONE_CLASSES, TAB_VARIANTS, THEME_SCOPES, lookup } 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";',
@@ -39,6 +17,9 @@ const COMPONENT_IMPORTS = {
     details: [
         'import CollapsibleAlert from "@ui/alert/CollapsibleAlert.astro";',
     ],
+    "details-sheet": [
+        'import DetailsSheet from "@ui/details-sheet/DetailsSheet.astro";',
+    ],
     code: [
         'import CodeBlock from "@ui/code-block/CodeBlock.astro";',
     ],
@@ -62,6 +43,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";'],
@@ -103,6 +87,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";',
     ],
@@ -116,12 +103,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 = "";
@@ -151,11 +176,19 @@ export function escapeTemplate(s) {
 export function treeToAstro(nodes, options) {
     const ctx = {
         imports: new Set(),
+        diagramIds: new Map(),
         indent: 0,
         scripts: new Set(),
         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
@@ -164,9 +197,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();
@@ -188,7 +221,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);
@@ -200,10 +244,27 @@ 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 "theme": {
+            // A scoped theme: `.dark` re-declares the tokens for its subtree, so a
+            // plain wrapper is enough (THEME_SCOPES); an unknown name keeps the content
+            const name = node.props?.name;
+            const scope = lookup(THEME_SCOPES, name);
+            const inner = childrenToAstro(node, ctx);
+            if (!scope)
+                return inner;
+            const passthrough = renderPassthroughAttrs(node.props, ["name", "class", "data-theme"]);
+            // The default (expression) form: an entity-escaped `[&amp;>…]` is not a
+            // class Tailwind's scanner recognises, so the rule was never generated
+            return `<div${mergeClassAttr(scope, node.props?.class)} data-theme="${escapeAttr(name)}"${passthrough}>\n${indentStr(inner, 2)}\n</div>`;
+        }
         case "tabs":
-            return tabsToAstro(node, ctx);
+            return renderAroundGroup(node, "tab", (n) => tabsToAstro(n, ctx), (c) => nodeToAstro(c, ctx), "\n");
         case "ordered-list":
             return wrapBlock("ol", "", node, childrenToAstro(node, ctx), ["start"])
                 .replace(/^<ol(\s[^>]*)?>/, (m) => {
@@ -215,21 +276,43 @@ function nodeToAstro(node, ctx) {
             });
         case "unordered-list":
             return wrapBlock("ul", "", node, childrenToAstro(node, ctx));
-        case "list-item":
-            return wrapBlock("li", "", node, leafContent(node, ctx));
+        case "list-item": {
+            // a task item: a disabled checkbox before its text, as render-html draws it
+            const c = node.props?.checked;
+            if (typeof c !== "boolean")
+                return wrapBlock("li", "", node, leafContent(node, ctx));
+            // the checkbox labelled by the item's text (axe: a form control needs a label); nested blocks after
+            const text = node.inline && node.inline.length ? leafContent({ ...node, children: undefined }, ctx) : "";
+            const rest = node.children?.length ? childrenToAstro({ ...node, inline: undefined }, ctx) : "";
+            // no text of its own: the checkbox is named "Task"
+            const lead = text ? `<label><input type="checkbox" disabled${c ? " checked" : ""} /> ${text}</label>` : `<input type="checkbox" disabled${c ? " checked" : ""} aria-label="Task" />`;
+            return wrapBlock("li", "", node, `${lead}${rest}`);
+        }
         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":
+            // a header row with no text (`| | |`, a headerless table) is no header (as render-html)
+            if (isEmptyTableHead(node))
+                return "";
             ctx.imports.add("table");
             return `<TableHeader>\n${childrenToAstro(node, ctx)}\n</TableHeader>`;
         case "tbody":
@@ -238,9 +321,13 @@ function nodeToAstro(node, ctx) {
         case "tr":
             ctx.imports.add("table");
             return `<TableRow>\n${childrenToAstro(node, ctx)}\n</TableRow>`;
-        case "th":
+        case "th": {
             ctx.imports.add("table");
-            return `<TableHead>${leafContent(node, ctx)}</TableHead>`;
+            // An empty header cell is no header (axe `empty-table-header`): a plain cell in the header row
+            const content = leafContent(node, ctx);
+            // Written here, not through TableHead: a site keeps the component it was scaffolded with
+            return content.trim() ? `<TableHead>${content}</TableHead>` : `<td class="${EMPTY_HEADER_CELL_CLASS}"></td>`;
+        }
         case "td":
             ctx.imports.add("table");
             return `<TableCell>${leafContent(node, ctx)}</TableCell>`;
@@ -277,18 +364,36 @@ 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"]);
         }
         case "steps":
             ctx.imports.add("steps");
             return `<Steps>\n${childrenToAstro(node, ctx)}\n</Steps>`;
-        case "step":
+        case "step": {
             ctx.imports.add("steps");
-            return `<Step>\n${leafContent(node, ctx)}\n</Step>`;
+            // A `title` prop (Mintlify `<Step title>`) leads the step in bold, as render-html draws it
+            // The title on its own line (Steps.astro: `.step-title` is a block): from the prop, or the
+            // step's leading bold run (stepLead), which Markdown otherwise runs into the detail
+            const title = stepTitle(node);
+            const split = title ? undefined : stepLead(node.inline);
+            const lead = title ? `<strong class="step-title">${escapeTemplate(title)}</strong>\n` : split ? `<strong class="step-title">${renderInline(split.title, ctx)}</strong>\n` : "";
+            return `<Step>\n${lead}${leafContent(split ? { ...node, inline: split.rest } : node, ctx)}\n</Step>`;
+        }
         case "substeps":
             ctx.imports.add("substeps");
             ctx.imports.add("steps");
@@ -304,8 +409,10 @@ 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);
+            return renderAroundGroup(node, "accordion-item", (n) => accordionToAstro(n, ctx), (c) => nodeToAstro(c, ctx), "\n");
         case "accordion-item":
             // Bare accordion-item outside an :::accordion wrapper. Wrap it in an
             // Accordion shell so the output is still a valid widget.
@@ -349,7 +456,7 @@ ${childrenToAstro(node, ctx)}
             // controls the bg/text combo (see TONE_CLASSES). Authors can also pass
             // their own `class` to override.
             if (label !== undefined) {
-                const toneClasses = TONE_CLASSES[tone] ?? TONE_CLASSES["primary-light"];
+                const toneClasses = lookup(TONE_CLASSES, tone) ?? TONE_CLASSES["primary-light"];
                 return `<GridItem ${attrParts.join(" ")}${classAttr}${passthrough}>
   <div class="flex h-full min-h-16 items-center justify-center rounded-lg font-mono text-sm font-medium ${toneClasses}">${escapeTemplate(label)}</div>
 </GridItem>`;
@@ -358,6 +465,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)}} />`;
@@ -367,37 +496,77 @@ ${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) => {
+            // Inside a whole-card link, a link is its text (wholeCardLink)
+            if (cardLinkDepth > 0)
+                return ctx.recurse(node.children);
+            // 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
@@ -411,47 +580,39 @@ 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 (cardLinkDepth > 0)
+                return ctx.recurse(node.children);
+            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>
@@ -459,14 +620,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) {
@@ -474,6 +640,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. */
@@ -489,23 +657,39 @@ function proseToAstro(node, ctx) {
         return renderHtml(node.html, ctx);
     return "";
 }
+/** TableHead's classes, for a header row's empty cell written as a plain `td`. */
+const EMPTY_HEADER_CELL_CLASS = "px-2 py-2 text-left align-bottom font-semibold text-muted-foreground";
+/**
+ * A card's title is text styled as one, not a heading (as render-html): a grid of cards is not a
+ * section of the page, and as headings its titles filled the outline and a reader's heading list.
+ */
+function cardTitleTag(_ctx) {
+    return "div";
+}
 function headingToAstro(node, ctx) {
     const level = node.props?.level ?? 1;
+    ctx.lastHeading = level;
     // `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)}} />`;
@@ -522,15 +706,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);
@@ -557,7 +754,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.
@@ -568,34 +765,52 @@ 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);
+    // Expressive Code's `collapse`: line runs folded behind a toggle (`{2-4, 9}` or `2-4,9`)
+    const collapse = lineSpec(node.props?.collapse)?.replace(/[{}\s]/g, "") || undefined;
+    const isRich = lineNumbers || highlights || code.includes("[!code") || Boolean(diffAdd || diffRemove) || Boolean(collapse);
+    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)}"`);
+        if (collapse)
+            attrs.push(`collapse="${escapeAttr(collapse)}"`);
+        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
@@ -607,6 +822,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)
@@ -615,36 +895,90 @@ 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, [
         "type", "variant", "title", "icon", "class",
     ]);
     const inner = childrenToAstro(node, ctx);
+    // An authored title is inline Markdown (`Before \`harbor init\``), as render-html reads it (MD-002);
+    // the default label is text
+    const titleNodes = explicitTitle && explicitTitle.length > 0 ? titleInline(title) : [{ type: "text", text: title }];
+    const plainTitle = isPlainCaption(titleNodes);
+    // `collapsed` / `collapsible`: a disclosure, as render-html draws it (MD-001)
+    if (isCollapsibleCallout(node.props)) {
+        ctx.imports.add("details");
+        const attrs = [`variant="${escapeAttr(collapsibleVariant(variant))}"`, componentAttr("title", plainTitle ? captionText(titleNodes) : title).trimStart()];
+        if (calloutStartsOpen(node.props))
+            attrs.push("open");
+        const slot = plainTitle ? "" : `\n  <Fragment slot="title">${renderInline(titleNodes, ctx)}</Fragment>`;
+        const collapsiblePassthrough = renderPassthroughAttrs(node.props, ["type", "variant", "title", "icon", "class", "collapsed", "collapsible", "open"]);
+        return `<CollapsibleAlert ${attrs.join(" ")}${iconAttr}${classAttr}${collapsiblePassthrough}>${slot}
+${indentStr(inner, 2)}
+</CollapsibleAlert>`;
+    }
     return `<Alert variant="${escapeAttr(variant)}"${iconAttr}${classAttr}${passthrough}>
-  <AlertTitle>${escapeTemplate(title)}</AlertTitle>
+  <AlertTitle>${plainTitle ? escapeTemplate(captionText(titleNodes)) : renderInline(titleNodes, ctx)}</AlertTitle>
   <AlertDescription>
 ${indentStr(inner, 4)}
   </AlertDescription>
 </Alert>`;
 }
+/**
+ * A presence flag: `open`, `open=""`, `open="true"` and `true` are on; absent, `false` and `"false"` are
+ * off. A bare `{open}` parses as "" (falsy), and "false" is truthy, so a plain truth test got both wrong
+ * (MD-003). render-html reads flags with the same rule (`flagOn`).
+ */
+function flagOn(v) {
+    return v !== undefined && v !== null && v !== false && v !== "false";
+}
+/** CollapsibleAlert's variants; `plain` is chrome (no tint, icon or role). */
+const COLLAPSIBLE_VARIANTS = new Set(["plain", "destructive", "note", "abstract", "info", "tip", "success", "question", "warning", "failure", "danger", "bug", "example", "quote"]);
+/** A disclosure's variant: lower-cased, aliases mapped, anything CollapsibleAlert does not draw → note. */
+function collapsibleVariant(raw) {
+    const v = raw.toLowerCase();
+    const mapped = CALLOUT_VARIANT_MAP[v] ?? v;
+    return COLLAPSIBLE_VARIANTS.has(mapped) ? mapped : "note";
+}
+/** A callout with `collapsible` on or any `collapsed` is a disclosure (render-html's `callout`). */
+function isCollapsibleCallout(props) {
+    return flagOn(props?.collapsible) || (props?.collapsed !== undefined && props?.collapsed !== null);
+}
+/** It starts open when `collapsed` is off (`collapsed="false"`) or `open` is on. */
+function calloutStartsOpen(props) {
+    const c = props?.collapsed;
+    return c === false || c === "false" || flagOn(props?.open);
+}
 /**
  * Merge a default class string with an optional user-provided class string.
  * 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"]);
@@ -659,9 +993,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(" ") : "";
 }
@@ -724,25 +1061,78 @@ 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"]);
+    // Nested props (a `---` block on an unknown directive) reach the page as one JSON attribute,
+    // so a site's own component or script can read them; scalar props pass through as before.
+    const nested = Object.fromEntries(Object.entries(node.props ?? {}).filter(([, v]) => v !== null && typeof v === "object"));
+    const dataProps = Object.keys(nested).length ? ` data-props="${escapeAttr(JSON.stringify(nested))}"` : "";
+    return `<div data-directive="${escapeAttr(name)}"${classAttr}${passthrough}${dataProps}>\n${title}${childrenToAstro(node, ctx)}\n</div>`;
+}
 function detailsToAstro(node, ctx) {
     ctx.imports.add("details");
-    const variant = node.props?.variant ?? "note";
-    const title = node.props?.title ?? "Details";
-    const open = node.props?.open;
+    // `variant` as documented; `type` as dogsbay-ssg (and callouts) read it.
+    // Aliases (`caution` → danger) and unknown names (→ note) as render-html maps them
+    const variant = collapsibleVariant(node.props?.variant ?? node.props?.type ?? "note");
+    // `summary` is dogsbay-md's alias for the title (`:::details{summary="…"}`)
+    const title = node.props?.title ?? node.props?.summary ?? "Details";
+    const open = flagOn(node.props?.open);
     const icon = node.props?.icon;
     const inner = childrenToAstro(node, ctx);
-    const attrs = [`variant="${escapeAttr(variant)}"`, `title="${escapeAttr(title)}"`];
+    // The title is inline Markdown, as in render-html: plain text stays the `title` prop
+    const titleNodes = titleInline(title);
+    const plainTitle = isPlainCaption(titleNodes);
+    const attrs = [`variant="${escapeAttr(variant)}"`, componentAttr("title", plainTitle ? captionText(titleNodes) : 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", "sheet",
     ]);
-    return `<CollapsibleAlert ${attrs.join(" ")}${classAttr}${passthrough}>
+    const slot = plainTitle ? "" : `\n  <Fragment slot="title">${renderInline(titleNodes, ctx)}</Fragment>`;
+    const alert = `<CollapsibleAlert ${attrs.join(" ")}${classAttr}${passthrough}>${slot}
 ${indentStr(inner, 2)}
 </CollapsibleAlert>`;
+    // `sheet`: the same details, opened as a side sheet by <db-details-sheet>
+    if (!isDetailsSheet(node.props))
+        return alert;
+    ctx.imports.add("details-sheet");
+    return `<DetailsSheet>\n${indentStr(alert, 2)}\n</DetailsSheet>`;
 }
 function tabsToAstro(node, ctx) {
     ctx.imports.add("tabs");
@@ -750,45 +1140,162 @@ function tabsToAstro(node, ctx) {
     if (tabs.length === 0)
         return "";
     const tabItems = tabs.map((tab, i) => {
-        const title = tab.props?.title || tab.props?.label || tab.props?.value || `Tab ${i + 1}`;
+        // The same order as render-html: `label` is ours, `title` what a Comark import wrote
+        const title = tab.props?.label || tab.props?.title || tab.props?.value || `Tab ${i + 1}`;
         const value = tab.props?.value || title;
         const label = title;
         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.
+    // 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. (TAB_GLYPH and
+    // tabDiffSignal are shared with render-html.)
+    // A variant's class strings are complete (TAB_VARIANTS): TabsList and
+    // TabsTrigger merge a `class` over their base with tailwind-variants
+    const variant = lookup(TAB_VARIANTS, node.props?.variant);
+    const triggerClass = variant ? ` class="${escapeAttr(variant.trigger)}"` : "";
     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)}${triggerClass}>${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)}${triggerClass} 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}>
-  <TabsList>
+    // 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${variant ? ` class="${escapeAttr(variant.list)}"` : ""}>
 ${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);
+/**
+ * Formatting tags with no attributes, the HTML a title keeps (a raw `<details><summary><code>x</code>`
+ * becomes the title `<code>x</code>`). render-html has the same list.
+ */
+const TITLE_TAG = /^<\/?(?:code|kbd|b|strong|i|em|s|del|mark|sub|sup|br)\s*\/?>$/i;
+/**
+ * A callout or details title: inline Markdown, and any other raw HTML is TEXT. Importers write
+ * plain-text titles with angle brackets (`Map<K, V>`, `List<String>`), which as HTML dropped words,
+ * and a title with `<img onerror=…>` ran a script in the summary. render-html reads titles the same way.
+ */
+function titleInline(title) {
+    const nodes = captionInline(title);
+    const kept = balancedTitleTags(nodes);
+    return nodes.map((n, i) => (n.type === "html-inline" && !kept.has(i) ? { type: "text", text: n.html } : n));
+}
+/**
+ * The indexes of the formatting tags a title keeps: a bare `TITLE_TAG` that is one half of a
+ * matched pair (or `<br>`). An unclosed `<em>` was kept, and the browser carried it past the
+ * title's element into the rest of the page (render-html has the same rule).
+ */
+function balancedTitleTags(nodes) {
+    const kept = new Set();
+    const open = [];
+    nodes.forEach((n, i) => {
+        if (n.type !== "html-inline")
+            return;
+        const html = n.html.trim();
+        if (!TITLE_TAG.test(html))
+            return;
+        const name = /^<\/?\s*(\w+)/.exec(html)[1].toLowerCase();
+        if (name === "br")
+            kept.add(i);
+        else if (!html.startsWith("</"))
+            open.push({ name, at: i });
+        else if (open.length && open[open.length - 1].name === name) {
+            kept.add(open.pop().at);
+            kept.add(i);
+        }
+    });
+    return kept;
+}
+/** A plain caption's text (escapes undone by the parse). */
+const captionText = (nodes) => nodes.map((n) => (n.type === "text" ? n.text : "")).join("");
+function captionToAstro(caption, ctx) {
+    // Raw HTML other than balanced formatting tags is text, as in a title (an imported repo's caption
+    // is someone else's; render-html draws captions the same way).
+    const nodes = titleInline(caption);
+    return isPlainCaption(nodes)
+        ? escapeTemplate(captionText(nodes))
+        : 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");
     const lang = node.props?.lang || "mermaid";
     const code = node.props?.code ?? "";
-    const svg = node.props?.svg ?? "";
+    let svg = node.props?.svg ?? "";
     const title = node.props?.title;
+    // A Pele SVG's ids (`<prefix>-title`, `<prefix>-desc`, for aria-labelledby) are unique within
+    // its source page. A book view or an include can show the same diagram twice on one page, so
+    // the later copies are renamed; the prefix appears nowhere else in the SVG.
+    const prefix = /^<svg[^>]*\bclass="pele\b/.test(svg) ? /\sid="(dg-[0-9a-f]{12}(?:-\d+)?)-/.exec(svg)?.[1] : undefined;
+    if (prefix) {
+        const n = (ctx.diagramIds.get(prefix) ?? 0) + 1;
+        ctx.diagramIds.set(prefix, n);
+        if (n > 1)
+            svg = svg.split(prefix).join(`${prefix}-p${n}`);
+    }
     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",
@@ -801,7 +1308,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");
@@ -844,6 +1351,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>` : "";
@@ -859,8 +1371,15 @@ 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);
+    ctx.lastHeading = level;
+    const attrs = [
+        componentAttr("name", name).trimStart(),
+        componentAttr("kind", kind).trimStart(),
+        `level={${level}}`,
+    ];
     if (signature)
         attrs.push(`signature={${escapeExpr(signature)}}`);
     if (bases.length > 0)
@@ -909,11 +1428,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 = [
@@ -953,7 +1478,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
@@ -962,7 +1489,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>`);
     }
@@ -982,31 +1509,75 @@ 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>`);
 }
+/**
+ * Whole-card links being emitted. Inside one, a link in the card's body is its text: a browser
+ * ends the outer <a> at an inner one, so the rest of the card fell out of the link (and lost
+ * not-prose). The serializer is synchronous, so a depth count is enough.
+ */
+let cardLinkDepth = 0;
+function wholeCardLink(yes, fn) {
+    if (!yes)
+        return fn();
+    cardLinkDepth++;
+    try {
+        return fn();
+    }
+    finally {
+        cardLinkDepth--;
+    }
+}
+/** A card's title: not-prose, or docs.css's h3 rule (1.25rem, 2rem above) applies inside the card. */
+const CARD_TITLE_CLASS = "not-prose m-0 border-0 p-0 text-base font-semibold";
+/** Marks a card title for styles and tests (it is a div, not a heading). */
+const CARD_TITLE_ATTR = "data-card-title";
+/**
+ * A card group's columns, responsive as render-html draws them (its GRID_COLS): one column on a
+ * phone, then up to `cols` (1–6) by Grid's breakpoints (0, 640, 768, 1024). Default 2. A list
+ * (`cols="1,2,3"`) is the author's own breakpoints and passes through.
+ */
+function cardCols(raw) {
+    const list = coerceNumericList(raw, [2]);
+    if (list.length > 1)
+        return list;
+    const n = Math.min(6, Math.max(1, Math.round(list[0]) || 2));
+    return n === 1 ? [1] : n === 2 ? [1, 2] : n <= 4 ? [1, 2, 2, n] : [1, 3, 3, n];
+}
 function cardsToAstro(node, ctx) {
     ctx.imports.add("grid");
     ctx.imports.add("card");
     // Grid-level attributes on the :::cards container
     const outerClass = mergeClassAttr("", node.props?.class);
     const outerPass = renderPassthroughAttrs(node.props, [
-        "cols", "gap", "rows", "class",
+        "cols", "gap", "rows", "class", "tone",
     ]);
     // MDX pattern: children are card nodes with title/href/icon props
     const cardNodes = (node.children ?? []).filter((c) => c.type === "card");
     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;
+            // The title's level before the body is written: a heading inside it must not move this
+            // card's title, nor the next card's (each starts from the level before the group)
+            const tag = cardTitleTag(ctx);
+            const before = ctx.lastHeading;
             // Description sources: inline content, children, or props.description.
-            const inner = childrenToAstro(card, ctx)
-                || (card.inline ? inlineToTemplate(card.inline) : "")
+            // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
+            // A body with links of its own: the title links, not the whole card (cardBodyHasLink)
+            const whole = !!href && (!title || !cardBodyHasLink([card.children, card.inline]));
+            const blocks = wholeCardLink(whole, () => childrenToAstro(card, ctx));
+            ctx.lastHeading = before;
+            const inner = blocks
+                || (card.inline ? wholeCardLink(whole, () => 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).
@@ -1014,26 +1585,33 @@ 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>`
+            const titleText = href && !whole ? `<a href="${escapeAttr(href)}">${escapeTemplate(title)}</a>` : escapeTemplate(title);
+            const titleHtml = title ? `<${tag} class="${CARD_TITLE_CLASS}" ${CARD_TITLE_ATTR}>${titleText}</${tag}>` : "";
+            // 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 cardDefaultClass = href
-                ? "p-4 hover:border-foreground/20 transition-colors"
-                : "p-4";
+            const desc = lead + (inner
+                ? `<${descTag} class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</${descTag}>`
+                : "");
+            // A tone (TONES; the card's own, else the group's) sets the card's
+            // border and tint: Card's tailwind-variants merge replaces bg-card
+            const toned = lookup(CARD_TONE_CLASSES, card.props?.tone ?? node.props?.tone);
+            const cardDefaultClass = whole
+                ? toned ? `p-4 ${toned} hover:shadow-md transition-colors` : "p-4 hover:border-foreground/20 transition-colors"
+                : toned ? `p-4 ${toned}` : "p-4";
             const cardClassAttr = mergeClassAttr(cardDefaultClass, card.props?.class);
             const cardPass = renderPassthroughAttrs(card.props, [
-                "title", "href", "description", "icon", "variant", "class",
+                "title", "href", "description", "icon", "variant", "class", "tone",
             ]);
-            if (href) {
-                return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+            if (whole) {
+                return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" data-variant="card" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
             }
             return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n${iconHtml}\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
         }).join("\n");
-        return `<Grid cols={[1, 2]} gap={4}${outerClass}${outerPass}>\n${cards}\n</Grid>`;
+        return `<Grid cols={[${cardCols(node.props?.cols).join(", ")}]} gap={4}${outerClass}${outerPass}>\n${cards}\n</Grid>`;
     }
     // MkDocs pattern: children are unordered-list items
     const items = (node.children ?? [])
@@ -1043,10 +1621,10 @@ function cardsToAstro(node, ctx) {
         const cards = items
             .map((item) => `<Card>\n<CardContent>\n${childrenToAstro(item, ctx)}\n</CardContent>\n</Card>`)
             .join("\n");
-        return `<Grid cols={[1, 2]} gap={4}>\n${cards}\n</Grid>`;
+        return `<Grid cols={[${cardCols(node.props?.cols).join(", ")}]} gap={4}>\n${cards}\n</Grid>`;
     }
     // Fallback: render children directly in grid
-    return `<Grid cols={[1, 2]} gap={4}>\n${childrenToAstro(node, ctx)}\n</Grid>`;
+    return `<Grid cols={[${cardCols(node.props?.cols).join(", ")}]} gap={4}>\n${childrenToAstro(node, ctx)}\n</Grid>`;
 }
 /**
  * Render a standalone `card` TreeNode (outside `:::cards`).
@@ -1058,34 +1636,43 @@ 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)
-        || (node.inline ? inlineToTemplate(node.inline) : "")
+    // The title's level before the body is written (a heading inside it must not move it)
+    const tag = cardTitleTag(ctx);
+    const before = ctx.lastHeading;
+    // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
+    const whole = !!href && (!title || !cardBodyHasLink([node.children, node.inline]));
+    const blocks = wholeCardLink(whole, () => childrenToAstro(node, ctx));
+    ctx.lastHeading = before;
+    const inner = blocks
+        || (node.inline ? wholeCardLink(whole, () => inlineToTemplate(node.inline)) : "")
         || (description ? escapeTemplate(description) : "");
-    // Icon renders inline before the title (same shape as the
-    // cards-list path). Resolved at build time via @dogsbay/icons.
-    let iconHtml = "";
-    if (icon) {
-        ctx.imports.add("icon");
-        iconHtml = `<Icon name="${escapeAttr(icon)}" class="size-5 mb-2 text-muted-foreground" />`;
-    }
+    const descTag = blocks ? "div" : "p";
+    // Icon renders inline before the title, a name or an image path, as in a card group
+    const iconHtml = icon ? cardIconHtml(icon, title, ctx) : "";
     const titleHtml = title
-        ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>`
+        ? `<${tag} class="${CARD_TITLE_CLASS}" ${CARD_TITLE_ATTR}>${href && !whole ? `<a href="${escapeAttr(href)}">${escapeTemplate(title)}</a>` : escapeTemplate(title)}</${tag}>`
         : "";
-    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 cardDefaultClass = href
-        ? "p-4 hover:border-foreground/20 transition-colors"
-        : "p-4";
+    const desc = lead + (inner
+        ? `<${descTag} class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${inner}</${descTag}>`
+        : "");
+    // A tone (TONES), as on a card in a group (cardsToAstro)
+    const toned = lookup(CARD_TONE_CLASSES, node.props?.tone);
+    const cardDefaultClass = whole
+        ? toned ? `p-4 ${toned} hover:shadow-md transition-colors` : "p-4 hover:border-foreground/20 transition-colors"
+        : toned ? `p-4 ${toned}` : "p-4";
     const classAttr = mergeClassAttr(cardDefaultClass, node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
-        "title", "href", "description", "icon", "variant", "class",
+        "title", "href", "description", "icon", "variant", "class", "tone",
     ]);
-    if (href) {
-        return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+    if (whole) {
+        return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" data-variant="card" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
     }
     return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n${iconHtml}\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
 }
@@ -1096,6 +1683,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) {
@@ -1104,15 +1744,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.
@@ -1131,9 +1773,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, [
@@ -1141,15 +1783,18 @@ function accordionToAstro(node, ctx) {
     ]);
     const items = (node.children ?? [])
         .filter((c) => c.type === "accordion-item")
-        .map((item) => accordionItemToAstro(item, ctx, /*standalone*/ false))
+        .map((item, i) => accordionItemToAstro(item, ctx, /*standalone*/ false, i + 1))
         .join("\n");
     return `<Accordion${typeAttr}${defaultAttr}${classAttr}${passthrough}>\n${items}\n</Accordion>`;
 }
-function accordionItemToAstro(node, ctx, standalone) {
+function accordionItemToAstro(node, ctx, standalone, 
+/** 1-based position: an item with no `value` must not share one with its siblings */
+index = 1) {
     ctx.imports.add("accordion");
-    const value = node.props?.value ?? "item-1";
+    // Items are matched by value: a shared fallback opened and closed them together
+    const value = node.props?.value ?? `item-${index}`;
     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",
@@ -1176,9 +1821,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",
@@ -1199,7 +1844,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>`;
@@ -1214,29 +1859,34 @@ function htmlContainerToAstro(node, ctx) {
         const inner = childrenToAstro(node, ctx);
         return `<div class="columns-1 sm:columns-2 gap-4 [&_ul]:m-0">\n${inner}\n</div>`;
     }
+    // A container parsed from raw HTML (a one-line `<details>` body) carries
+    // its content in `html`, not children — rendering only children dropped it
+    if (!node.children?.length && node.html)
+        return htmlToAstro(node.html, ctx);
     const inner = childrenToAstro(node, ctx);
     return `<div>\n${inner}\n</div>`;
 }
 // ─── 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)
@@ -1250,40 +1900,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;");
 }
-//# sourceMappingURL=serialize.js.map