@dogsbay/format-astro 0.2.0-beta.1 → 0.2.0-beta.100

package/dist/serialize.js

@@ -1,9 +1,18 @@
+import { walkInline, applyTextFlags, renderLeaf, indent, } from "@dogsbay/serialize-core";
+import { decorateDiff, hasDiffMarks } from "./diff-decoration.js";
 /**
  * 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.
  */
-const TONE_CLASSES = {
+export const TONE_CLASSES = {
     // Primary scale (intensity)
     "primary": "bg-primary text-primary-foreground",
     "primary-strong": "bg-primary/80 text-primary-foreground",
@@ -96,9 +105,15 @@ 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";',
     ],
+    icon: [
+        'import Icon from "@ui/icon/Icon.astro";',
+    ],
 };
 // ─── Escaping helpers ─────────────────────────────────────────────
 /** Escape for use inside an Astro {expression}. Uses JSON.stringify for safety. */
@@ -112,6 +127,30 @@ export function escapeExpr(s) {
 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.
+ */
+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 = "";
@@ -146,7 +185,23 @@ export function treeToAstro(nodes, options) {
         mode: options?.mode ?? "template",
         imageOptimization: options?.imageOptimization ?? false,
         codeBlockTitle: options?.codeBlockTitle ?? true,
+        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: nodes.some((n) => n.type === "endpoint") &&
+            nodes.some((n) => n.type !== "endpoint" && n.type !== "heading" && n.type !== "hr"),
     };
+    // Pre-scan for inline `icon` nodes anywhere in the tree.
+    // `inlineNodeToTemplate` is intentionally pure (no ctx) — it
+    // gets called from many block-level renderers — so the icon
+    // import has to be registered up front. Block-level icon usage
+    // (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");
+    }
     const body = nodes.map((n) => nodeToAstro(n, ctx)).filter(Boolean).join("\n");
     const imports = [];
     const seen = new Set();
@@ -168,7 +223,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);
@@ -199,6 +265,13 @@ 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"]);
@@ -284,6 +357,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":
@@ -338,6 +413,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)}} />`;
@@ -347,86 +444,107 @@ ${childrenToAstro(node, ctx)}
     }
 }
 // ─── Inline rendering ─────────────────────────────────────────────
-/** Render inline nodes as Astro template markup (clean, editable). */
-function inlineToTemplate(nodes) {
-    return nodes.map(inlineNodeToTemplate).join("");
+/**
+ * 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) => {
+            const titleAttr = node.title ? componentAttr("title", node.title) : "";
+            const extraAttrs = renderInlineElementAttrs(node.attrs);
+            return `<a href="${escapeAttr(node.href)}"${titleAttr}${extraAttrs}>${ctx.recurse(node.children)}</a>`;
+        },
+        image: (node) => {
+            const extraAttrs = renderInlineElementAttrs(node.attrs);
+            return `<img src="${escapeAttr(node.src)}" alt="${escapeAttr(node.alt ?? "")}" loading="lazy"${extraAttrs} />`;
+        },
+        code: (node, ctx) => `<code>${ctx.escape(node.text)}</code>`,
+        // 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>`,
+        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
+            // is responsible for adding `icon` to ctx.imports; the
+            // codepath that traverses inline nodes registers it once.
+            //
+            // The parser splits `:icon[lucide:rocket]` into
+            // `{ name: "rocket", library: "lucide" }`, so reconstruct
+            // the `pack:name` form before emitting — otherwise the
+            // pack hint would be lost and the resolver would default
+            // 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]" />`;
+        },
+        // Raw HTML inline — must use set:html to avoid brace issues
+        "html-inline": (node) => `<Fragment set:html={${escapeExpr(node.html)}} />`,
+        break: () => "<br />",
+    };
 }
-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": {
+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) => {
             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":
-            return `:${node.name}:`;
-        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 "";
-    }
+            const extraAttrs = renderInlineElementAttrs(node.attrs);
+            return `<a href="${escapeAttr(node.href)}"${titleAttr}${extraAttrs}>${ctx.recurse(node.children)}</a>`;
+        },
+        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>
+            // component (case above). Hybrid mode is rarely used in
+            // production output.
+            const fullName = node.library ? `${node.library}:${node.name}` : node.name;
+            return `<span class="dogsbay-icon" data-icon="${escapeAttr(fullName)}"></span>`;
+        },
+        "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 nodes.map(inlineNodeToHtml).join("");
-}
-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": {
-            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":
-            return `:${node.name}:`;
-        case "html-inline":
-            return node.html;
-        case "break":
-            return "<br />";
-        default:
-            return "";
-    }
+    return walkInline(nodes, { emitters: HTML_INLINE, escape: escapeHtml });
 }
 /** Render inline content in the current mode. */
 function renderInline(nodes, ctx) {
@@ -457,15 +575,21 @@ function headingToAstro(node, ctx) {
         ? `<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>`
         : "";
     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)}} />`;
@@ -482,15 +606,26 @@ 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);
+            return `<BlockImage${componentAttr("src", img.src)}${componentAttr("alt", img.alt ?? "")}${imageAttrs}${passthrough}${imgDataAttr} />`;
         }
     }
     const classAttr = mergeClassAttr("", node.props?.class);
@@ -530,28 +665,37 @@ function codeToAstro(node, ctx) {
     const title = node.props?.title;
     const highlights = node.props?.highlights;
     const lineNumbers = node.props?.lineNumbers;
-    const isRich = lineNumbers || highlights || code.includes("[!code");
+    const copyText = node.props?.copyText;
+    const diffAdd = node.props?.diffAdd;
+    const diffRemove = node.props?.diffRemove;
+    const isRich = lineNumbers || highlights || code.includes("[!code") || Boolean(diffAdd || diffRemove);
     const classAttr = mergeClassAttr("", node.props?.class);
     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)}"`);
+        if (copyText !== undefined)
+            attrs.push(`copyText={${escapeExpr(copyText)}}`);
+        if (diffAdd)
+            attrs.push(`diffAdd="${escapeAttr(diffAdd)}"`);
+        if (diffRemove)
+            attrs.push(`diffRemove="${escapeAttr(diffRemove)}"`);
         return `<CodeRich ${attrs.join(" ")}${classAttr}${passthrough} />`;
     }
     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}"`);
     }
@@ -567,6 +711,17 @@ const CALLOUT_VARIANT_MAP = {
     hint: "tip",
     attention: "warning",
 };
+// Default title shown when a callout has no explicit one (post-variant-map).
+// Keyed by the mapped variant. Falls back to a capitalised variant otherwise.
+const CALLOUT_LABELS = {
+    note: "Note",
+    tip: "Tip",
+    info: "Important",
+    warning: "Warning",
+    danger: "Caution",
+    failure: "Error",
+    success: "Success",
+};
 function calloutToAstro(node, ctx) {
     ctx.imports.add("callout");
     // Callout variant may live on props.variant (Starlight / MkDocs importers)
@@ -575,7 +730,14 @@ 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;
+    const title = explicitTitle && explicitTitle.length > 0
+        ? explicitTitle
+        : CALLOUT_LABELS[variant] ?? variant.charAt(0).toUpperCase() + variant.slice(1);
     const icon = node.props?.icon;
     const iconAttr = icon ? ` icon="${escapeAttr(icon)}"` : "";
     // User classes and passthrough attributes (id, data-*, aria-*, style)
@@ -596,15 +758,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"]);
@@ -619,9 +785,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(" ") : "";
 }
@@ -691,7 +860,7 @@ function detailsToAstro(node, ctx) {
     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)
@@ -716,18 +885,62 @@ 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}>
+    // Same encoding as the trigger/content `value` it selects — see above.
+    return `<Tabs${componentAttr("defaultValue", defaultValue)}${classAttr}${passthrough}>
   <TabsList>
 ${triggers}
   </TabsList>
@@ -737,8 +950,10 @@ ${contents}
 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 captionAttr = caption ? ` caption={${escapeExpr(caption)}}` : "";
+    const passthrough = renderPassthroughAttrs(node.props, ["class", "caption"]);
+    return `<Table${classAttr}${captionAttr}${passthrough}>\n${childrenToAstro(node, ctx)}\n</Table>`;
 }
 function diagramToAstro(node, ctx) {
     ctx.imports.add("diagram");
@@ -748,7 +963,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",
@@ -761,7 +976,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");
@@ -820,7 +1035,11 @@ function apiSymbolToAstro(node, ctx) {
     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}}`];
+    const attrs = [
+        componentAttr("name", name).trimStart(),
+        componentAttr("kind", kind).trimStart(),
+        `level={${level}}`,
+    ];
     if (signature)
         attrs.push(`signature={${escapeExpr(signature)}}`);
     if (bases.length > 0)
@@ -942,7 +1161,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>`);
@@ -962,10 +1182,20 @@ function cardsToAstro(node, ctx) {
             const title = card.props?.title ?? "";
             const href = 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)
                 || (card.inline ? inlineToTemplate(card.inline) : "")
                 || (description ? escapeTemplate(description) : "");
+            // 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).
+            // Icon is registered when present so the import lands at the
+            // top of the page.
+            let iconHtml = "";
+            if (icon) {
+                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>`
@@ -978,9 +1208,9 @@ function cardsToAstro(node, ctx) {
                 "title", "href", "description", "icon", "variant", "class",
             ]);
             if (href) {
-                return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="[text-decoration:none] text-foreground">\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+                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>`;
             }
-            return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n${titleHtml}\n${desc}\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>`;
     }
@@ -1009,9 +1239,17 @@ function standaloneCardToAstro(node, ctx) {
     const title = node.props?.title ?? "";
     const href = node.props?.href ?? "";
     const description = node.props?.description;
+    const icon = node.props?.icon;
     const inner = childrenToAstro(node, ctx)
         || (node.inline ? 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 titleHtml = title
         ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>`
         : "";
@@ -1026,9 +1264,9 @@ function standaloneCardToAstro(node, ctx) {
         "title", "href", "description", "icon", "variant", "class",
     ]);
     if (href) {
-        return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="[text-decoration:none] text-foreground">\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+        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>`;
     }
-    return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
+    return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n${iconHtml}\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
 }
 /**
  * Render a `link-card` TreeNode as the dedicated `<LinkCard>` component.
@@ -1037,6 +1275,45 @@ 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" />`;
+}
+function linkButtonToAstro(node, ctx) {
+    ctx.imports.add("link-button");
+    const href = node.props?.href ?? "";
+    const variant = node.props?.variant;
+    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>`;
+}
 function linkCardToAstro(node, ctx) {
     const hasRichChildren = (node.children ?? []).length > 0;
     if (hasRichChildren) {
@@ -1046,9 +1323,9 @@ function linkCardToAstro(node, ctx) {
     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 titleAttr = componentAttr("title", title);
+    const hrefAttr = componentAttr("href", href);
+    const descAttr = description ? componentAttr("description", description) : "";
     const classAttr = mergeClassAttr("", node.props?.class);
     const passthrough = renderPassthroughAttrs(node.props, [
         "title", "description", "href", "icon", "class",
@@ -1072,9 +1349,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, [
@@ -1090,7 +1367,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",
@@ -1117,9 +1394,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",
@@ -1140,7 +1417,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>`;
@@ -1160,37 +1437,66 @@ 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)
         return "";
     return node.children.map((n) => nodeToAstro(n, ctx)).filter(Boolean).join("\n");
 }
-function indentStr(text, spaces) {
-    const prefix = " ".repeat(spaces);
-    return text
-        .split("\n")
-        .map((line) => (line ? `${prefix}${line}` : line))
-        .join("\n");
+/**
+ * Walk the tree looking for inline `icon` nodes (the `:icon[name]`
+ * directive form) so the `<Icon>` component import can be
+ * pre-registered at the top-level of `treeToAstro`. Block-level
+ * 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;
+        }
+    }
+    return false;
 }
+/** 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;");
 }