@dogsbay/format-openknowledge 0.2.0-beta.101

package/dist/serialize.js

@@ -0,0 +1,738 @@
+import { walkInline, applyTextFlags, renderLeaf, indent, prefixLines, pickCodeFence, stripHtml, inlineHtmlToMarkdown, headingLevel, headingText, slugifyHeadingText, inlinePlainText, codeSpan, ExportLedger, } from "@dogsbay/serialize-core";
+/** GFM alert types OpenKnowledge renders natively (remark-github-alerts). */
+const VARIANT_TO_ALERT = {
+    note: "note",
+    info: "note",
+    question: "note",
+    abstract: "note",
+    tip: "tip",
+    hint: "tip",
+    success: "tip",
+    example: "tip",
+    important: "important",
+    warning: "warning",
+    attention: "warning",
+    danger: "caution",
+    error: "caution",
+    failure: "caution",
+    bug: "caution",
+    caution: "caution",
+};
+export function treeToOpenKnowledge(nodes, options = {}) {
+    const ctx = {
+        href: options.href ?? defaultHref,
+        ledger: options.ledger ?? new ExportLedger(),
+        page: options.page ?? "",
+        depth: 0,
+    };
+    return nodes.map((n) => nodeToMdx(n, ctx)).filter(Boolean).join("\n\n");
+}
+/** Root-absolute `.md` shape without page knowledge: `/a/b/` → `/a/b.md`, `#x` kept, external kept. */
+export function defaultHref(href) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("#") || href.startsWith("//"))
+        return href;
+    const [pathPart, frag] = splitFragment(href);
+    let p = pathPart.replace(/\/+$/, "");
+    if (!p)
+        return frag ? `#${frag}` : "/";
+    if (!p.startsWith("/"))
+        p = `/${p}`;
+    if (!/\.[a-z0-9]+$/i.test(p))
+        p = `${p}.md`;
+    return frag ? `${p}#${frag}` : p;
+}
+export function splitFragment(href) {
+    const i = href.indexOf("#");
+    return i < 0 ? [href, ""] : [href.slice(0, i), href.slice(i + 1)];
+}
+/* ── MDX text escaping ─────────────────────────────────────────────────── */
+/**
+ * MDX treats `{`/`}` as expressions and `<` followed by anything but
+ * whitespace as a tag start (`<3`, `<=`, `<-` are all errors); a backslash
+ * escape renders literally in both the strict MDX stack and OpenKnowledge's
+ * (which restores backslash escapes). Backslashes are escaped FIRST so a
+ * literal `\{` in prose does not become `\\{` (= escaped backslash + a LIVE
+ * expression). Text starting a paragraph with `import`/`export` is ESM in
+ * strict MDX — see `noEsmStart`.
+ */
+export function escapeMdxText(text) {
+    return text
+        .replace(/\\/g, "\\\\")
+        .replace(/[{}]/g, "\\$&")
+        // a `<` at the END of a text node is followed by the next inline node (a code span, a link…): escape it too
+        .replace(/<(?=\S|$)/g, "\\<");
+}
+/** A paragraph may not begin with `import`/`export` in strict MDX (ESM); a char-ref renders the same letter. */
+function noEsmStart(text) {
+    return text.replace(/^(import|export)(?=\s|$)/, (m) => (m[0] === "i" ? "&#105;" + m.slice(1) : "&#101;" + m.slice(1)));
+}
+/**
+ * JSX attribute value. OpenKnowledge does NOT decode HTML entities inside
+ * JSX attributes (its `destructureAttrs` copies the raw string; only
+ * text/url/title/alt are restored), and JSX string attributes have no
+ * backslash escapes. So: a plain `"…"` when the value is simple, otherwise
+ * an EXPRESSION holding a JSON string with `{ } < > & "` written as
+ * `\uXXXX` — acorn accepts it and OpenKnowledge `JSON.parse`s it back to
+ * the exact value (verified against both parsers).
+ */
+function attr(value) {
+    const v = value.replace(/\r?\n/g, " ");
+    if (!/["\\{}<>&]/.test(v))
+        return `"${v}"`;
+    const json = JSON.stringify(v).replace(/[{}<>&"]/g, (ch) => (ch === '"' ? '"' : `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`));
+    // JSON.stringify keeps the outer quotes; inner quotes are already \"-escaped
+    return `{${json}}`;
+}
+/** Fence meta `title="…"` is never entity-decoded: drop what it cannot carry. */
+function metaTitle(value) {
+    const clean = value.replace(/[{}"]/g, "").replace(/\r?\n/g, " ").trim();
+    return `title="${clean}"`;
+}
+/* ── Block dispatcher ──────────────────────────────────────────────────── */
+function nodeToMdx(node, ctx) {
+    switch (node.type) {
+        case "frontmatter":
+            // the project layer writes page frontmatter from ExportPage; an inline
+            // frontmatter node inside a tree is source noise, not content
+            return "";
+        case "references":
+            return referencesToMdx(node, ctx);
+        case "heading":
+            return headingToMdx(node, ctx);
+        case "paragraph":
+            return noEsmStart(leaf(node, ctx));
+        case "prose":
+            return noEsmStart(proseToMdx(node, ctx));
+        case "callout":
+            return calloutToMdx(node, ctx);
+        case "details":
+            return detailsToMdx(node, ctx);
+        case "tabs":
+            return tabsToMdx(node, ctx);
+        case "code":
+            return codeToMdx(node, ctx);
+        case "diagram":
+            return diagramToMdx(node);
+        case "math-block":
+            return `$$\n${String(node.props?.latex ?? "")}\n$$`;
+        case "table":
+            return tableToMdx(node, ctx);
+        case "blockquote":
+            return prefixLines(children(node, ctx), "> ");
+        case "ordered-list":
+            return orderedListToMdx(node, ctx);
+        case "unordered-list":
+            return unorderedListToMdx(node, ctx);
+        case "list-item":
+            return listItemToMdx(node, ctx);
+        case "deflist":
+            return deflistToMdx(node, ctx);
+        case "dt":
+            return `**${leaf(node, ctx)}**`;
+        case "dd":
+            return leaf(node, ctx);
+        case "steps":
+            return stepsToMdx(node, ctx);
+        case "step":
+            return children(node, ctx);
+        case "substeps":
+            return children(node, ctx);
+        case "annotation-list":
+            return children(node, ctx);
+        case "link-button": {
+            // navigational: a plain link feeds their graph/backlinks (§3.3)
+            const href = ctx.href(String(node.props?.href ?? ""));
+            const text = children(node, ctx) || leaf(node, ctx) || href;
+            ctx.ledger.record({ feature: "link-button", page: ctx.page, action: "degraded", detail: "rendered as a plain markdown link" });
+            return `[${text}](${href})`;
+        }
+        case "hr":
+            return "---";
+        case "html":
+            ctx.ledger.record({ feature: "html", page: ctx.page, action: "degraded", detail: "raw HTML converted to markdown (MDX cannot take unbalanced HTML)" });
+            return htmlToMdx(node.html ?? "");
+        case "html-container":
+            return children(node, ctx);
+        case "figure":
+            return figureToMdx(node, ctx);
+        case "card":
+            return cardToMdx(node, ctx);
+        case "cards":
+        case "grid":
+            return cardsToMdx(node, ctx);
+        case "youtube":
+            return youtubeToMdx(node);
+        case "api-class":
+        case "api-member":
+            return apiSymbolToMdx(node, ctx);
+        case "api-doc":
+            return apiDocToMdx(node, ctx);
+        case "api-params":
+            return apiParamsToMdx(node, ctx);
+        case "api-source":
+            return apiSourceToMdx(node, ctx);
+        case "footnote-list":
+            return (node.children ?? []).map((c) => nodeToMdx(c, ctx)).join("\n");
+        case "footnote-def": {
+            const label = String(node.props?.label ?? "1");
+            const body = node.inline?.length ? inlineToMdx(node.inline, ctx) : children(node, ctx);
+            const [first, ...rest] = body.split("\n");
+            return rest.length ? `[^${label}]: ${first}\n${rest.map((l) => (l ? `    ${l}` : l)).join("\n")}` : `[^${label}]: ${first}`;
+        }
+        case "mdx-raw":
+            // an importer's never-drop raw JSX/MDX: OpenKnowledge's wildcard renders it as an editable raw-MDX block
+            ctx.ledger.record({ feature: "mdx-raw", page: ctx.page, action: "degraded", detail: `raw MDX <${String(node.props?.component ?? "…")}> passed through to the wildcard` });
+            return String(node.props?.source ?? "");
+        case "accordion-group":
+            return children(node, ctx);
+        case "related": {
+            const title = String(node.props?.title ?? "").trim();
+            const body = children(node, ctx);
+            if (!title)
+                return body;
+            return `**${escapeMdxText(title.replace(/([*\\])/g, "\\$1"))}**\n\n${body}`;
+        }
+        default:
+            ctx.ledger.record({ feature: node.type, page: ctx.page, action: node.children || node.html || node.inline ? "degraded" : "dropped", detail: `no OpenKnowledge mapping for "${node.type}"; children emitted` });
+            if (node.html)
+                return htmlToMdx(node.html);
+            if (node.children)
+                return children(node, ctx);
+            if (node.inline)
+                return inlineToMdx(node.inline, ctx);
+            return "";
+    }
+}
+/* ── Inline ─────────────────────────────────────────────────────────────── */
+const inlineEmitters = (ctx) => ({
+    text: (node) => applyTextFlags(escapeMdxText(node.text), node, {
+        bold: (s) => `**${s}**`,
+        italic: (s) => `*${s}*`,
+        strike: (s) => `~~${s}~~`,
+    }),
+    link: (node, c) => {
+        const title = node.title ? ` "${node.title.replace(/"/g, '\\"')}"` : "";
+        return `[${c.recurse(node.children)}](${urlSafe(ctx.href(node.href))}${title})`;
+    },
+    image: (node) => `![${(node.alt ?? "").replace(/[[\]]/g, "\\$&")}](${urlSafe(node.src)})`,
+    code: (node) => codeSpan(node.text),
+    highlight: (node, c) => `==${c.recurse(node.children)}==`,
+    "footnote-ref": (node) => `[^${node.label}]`,
+    // OpenKnowledge shows a literal `<kbd>` (lowercase tags other than img/video/audio/mark are sentinelled): keys as code spans
+    kbd: (node) => {
+        ctx.ledger.record({ feature: "kbd", page: ctx.page, action: "degraded", detail: "keys rendered as code spans (no <kbd> in OpenKnowledge)" });
+        return node.keys.map((k) => codeSpan(k)).join("+");
+    },
+    math: (node) => `$${node.latex}$`,
+    icon: (node) => {
+        ctx.ledger.record({ feature: "icon", page: ctx.page, action: "degraded", detail: `icon ":${node.name}:" rendered as text` });
+        return escapeMdxText(`:${node.name}:`);
+    },
+    "html-inline": (node) => inlineHtmlToMdx(node.html ?? ""),
+    break: () => "  \n",
+});
+function inlineToMdx(nodes, ctx) {
+    return walkInline(pairInlineHtml(nodes, ctx), { emitters: inlineEmitters(ctx) });
+}
+/**
+ * markdown-it hands an inline `<abbr title="…">ORM</abbr>` over as THREE
+ * nodes — html-inline open, text, html-inline close — and stripping each
+ * tag alone loses the semantics (43 <abbr> + 50 <dfn> on FastAPI). Pair
+ * open/close across the array and rewrite the span: <a href> → link,
+ * <b>/<strong> → bold, <i>/<em> → italic, <code> → code span, <abbr>/<dfn
+ * title> → "text (title)", <s>/<del> → strike, other known tags → unwrapped.
+ * OpenKnowledge shows lowercase tags other than img/video/audio/mark as
+ * literal text, so JSX passthrough is not an option here.
+ */
+function pairInlineHtml(nodes, ctx) {
+    const out = [];
+    for (let i = 0; i < nodes.length; i++) {
+        const n = nodes[i];
+        if (n.type !== "html-inline") {
+            out.push(n);
+            continue;
+        }
+        const open = /^<([a-z][a-z0-9]*)(\s[^>]*)?>$/i.exec((n.html ?? "").trim());
+        if (!open) {
+            out.push(n);
+            continue;
+        }
+        const tag = open[1].toLowerCase();
+        if (!PAIRABLE.has(tag)) {
+            out.push(n);
+            continue;
+        }
+        // find the matching close at the same depth
+        let depth = 0;
+        let close = -1;
+        for (let j = i + 1; j < nodes.length; j++) {
+            const m = nodes[j];
+            if (m.type !== "html-inline")
+                continue;
+            const h = (m.html ?? "").trim();
+            if (new RegExp(`^<${tag}(\\s[^>]*)?>$`, "i").test(h))
+                depth++;
+            else if (new RegExp(`^</${tag}\\s*>$`, "i").test(h)) {
+                if (depth === 0) {
+                    close = j;
+                    break;
+                }
+                depth--;
+            }
+        }
+        if (close < 0) {
+            out.push(n);
+            continue;
+        }
+        const inner = pairInlineHtml(nodes.slice(i + 1, close), ctx);
+        const attrs = open[2] ?? "";
+        const attrOf = (name) => new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i").exec(attrs)?.slice(1).find((v) => v !== undefined);
+        const flag = (f) => inner.map((x) => (x.type === "text" || x.type === "code" ? { ...x, [f]: true } : x));
+        switch (tag) {
+            case "a": {
+                const href = attrOf("href") ?? "";
+                out.push({ type: "link", href, children: inner });
+                break;
+            }
+            case "b":
+            case "strong":
+                out.push(...flag("bold"));
+                break;
+            case "i":
+            case "em":
+                out.push(...flag("italic"));
+                break;
+            case "s":
+            case "del":
+            case "strike":
+                out.push(...flag("strikethrough"));
+                break;
+            case "code":
+            case "kbd":
+            case "samp":
+            case "tt":
+                out.push({ type: "code", text: inner.map((x) => inlinePlainText(x, (t) => t)).join("") });
+                break;
+            case "abbr":
+            case "dfn": {
+                const title = attrOf("title");
+                out.push(...inner);
+                if (title) {
+                    ctx.ledger.record({ feature: "html-inline", page: ctx.page, action: "degraded", detail: `<${tag} title> expanded inline as "text (title)"` });
+                    out.push({ type: "text", text: ` (${title})` });
+                }
+                break;
+            }
+            case "mark":
+                out.push({ type: "highlight", children: inner });
+                break;
+            default:
+                ctx.ledger.record({ feature: "html-inline", page: ctx.page, action: "degraded", detail: `<${tag}> unwrapped (no OpenKnowledge inline equivalent)` });
+                out.push(...inner);
+        }
+        i = close;
+    }
+    return out;
+}
+const PAIRABLE = new Set(["a", "b", "strong", "i", "em", "s", "del", "strike", "code", "kbd", "samp", "tt", "abbr", "dfn", "mark", "sup", "sub", "span", "u", "small", "cite", "var", "q"]);
+/** A URL in `[](…)` may not contain spaces or unbalanced parens: percent-encode them. */
+function urlSafe(url) {
+    return url.replace(/ /g, "%20").replace(/\(/g, "%28").replace(/\)/g, "%29");
+}
+/**
+ * Inline HTML: convert the unambiguous tags to markdown, strip the rest
+ * (MDX would choke on `<br>`). A lone tag-shaped placeholder that is not
+ * a known HTML element (`<cluster-name>`, `<your-token>`) is PROSE the
+ * writer meant literally — keep it, escaped, instead of stripping it.
+ */
+function inlineHtmlToMdx(html) {
+    const placeholder = /^<([a-z][a-z0-9-]*)>$/i.exec(html.trim());
+    if (placeholder && !KNOWN_HTML.has(placeholder[1].toLowerCase()))
+        return escapeMdxText(html.trim());
+    return escapeMdxText(stripHtml(inlineHtmlToMarkdown(html)));
+}
+const KNOWN_HTML = new Set(["a", "abbr", "b", "bdi", "bdo", "br", "cite", "code", "data", "del", "dfn", "em", "i", "img", "ins", "kbd", "mark", "q", "s", "samp", "small", "span", "strong", "sub", "sup", "time", "u", "var", "wbr", "p", "div", "pre", "ul", "ol", "li", "table", "tr", "td", "th", "thead", "tbody", "hr", "h1", "h2", "h3", "h4", "h5", "h6", "blockquote", "details", "summary", "figure", "figcaption", "video", "audio", "source", "iframe", "button", "input", "label", "select", "option", "textarea", "form", "nav", "section", "article", "aside", "header", "footer", "main", "dl", "dt", "dd"]);
+function htmlToMdx(html) {
+    const cleaned = html
+        .replace(/<(style|script)\b[\s\S]*?<\/\1\s*>/gi, "")
+        // block boundaries become whitespace so `</td><td>` cannot glue words
+        .replace(/<\/(td|th)\s*>\s*<(td|th)\b/gi, "</$1> | <$2")
+        .replace(/<\/(tr|p|div|li|h[1-6]|blockquote|section|article|dd|dt)\s*>/gi, "$&\n")
+        .replace(/<br\s*\/?>/gi, "\n");
+    const text = escapeMdxText(stripHtml(inlineHtmlToMarkdown(cleaned)).replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim());
+    // converted HTML yields several paragraphs; each may not start with import/export (ESM in strict MDX)
+    return text.split(/\n\n/).map(noEsmStart).join("\n\n");
+}
+function proseToMdx(node, ctx) {
+    if (node.inline)
+        return inlineToMdx(node.inline, ctx);
+    if (node.html)
+        return htmlToMdx(node.html);
+    return "";
+}
+/* ── Callouts / details / tabs (§3.1) ──────────────────────────────────── */
+function calloutToMdx(node, ctx) {
+    const variant = String(node.props?.variant ?? node.props?.type ?? "note").toLowerCase();
+    const alert = VARIANT_TO_ALERT[variant] ?? "note";
+    if (alert !== variant)
+        ctx.ledger.record({ feature: "callout", page: ctx.page, action: "degraded", detail: `variant "${variant}" mapped to "${alert}" (GFM alert enum)` });
+    const title = node.props?.title;
+    const autoTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
+    const inner = children(node, ctx);
+    if (title && title !== autoTitle) {
+        // a custom title needs the component (GFM alerts have no title slot); a JSX string is not markdown
+        return `<Callout type=${attr(alert)} title=${attr(plainTitle(title))}>\n\n${inner}\n\n</Callout>`;
+    }
+    const opener = `> [!${alert.toUpperCase()}]`;
+    if (!inner)
+        return opener;
+    return `${opener}\n${prefixLines(inner, "> ")}`;
+}
+/** Markdown emphasis/code markers have no meaning inside a JSX string attribute. */
+function plainTitle(title) {
+    return title.replace(/\*\*|__|`|~~/g, "").replace(/(^|\s)[*_](\S)/g, "$1$2").replace(/(\S)[*_](\s|$)/g, "$1$2").trim();
+}
+function detailsToMdx(node, ctx) {
+    const title = plainTitle(String(node.props?.title ?? "Details"));
+    const open = node.props?.open === true || node.props?.open === "" || node.props?.open === "true";
+    const variant = node.props?.variant ?? node.props?.type;
+    if (variant && variant !== "note")
+        ctx.ledger.record({ feature: "details", page: ctx.page, action: "degraded", detail: `fold variant "${String(variant)}" not representable (Accordion has no variant)` });
+    const inner = children(node, ctx);
+    return `<Accordion title=${attr(title)}${open ? " defaultOpen" : ""}>\n\n${inner}\n\n</Accordion>`;
+}
+function tabsToMdx(node, ctx) {
+    const tabs = node.children ?? [];
+    const inner = ctx.depth++;
+    const body = tabs
+        .map((tab) => {
+        const label = String(tab.props?.title || tab.props?.label || tab.props?.value || "Tab");
+        const content = children(tab, ctx);
+        return `<Tab label=${attr(label)}>\n\n${content}\n\n</Tab>`;
+    })
+        .join("\n\n");
+    ctx.depth = inner;
+    return `<Tabs>\n\n${body}\n\n</Tabs>`;
+}
+/* ── Code (§2.3: plain fences, never an envelope) ───────────────────────── */
+function codeToMdx(node, ctx) {
+    const lang = String(node.props?.lang || node.props?.language || "");
+    const code = String(node.props?.code ?? node.html ?? "").replace(/\n$/, "");
+    const title = node.props?.title;
+    const highlights = node.props?.highlights;
+    const annotations = node.props?.annotations;
+    const fence = fenceFor(code, ctx);
+    const meta = [];
+    if (title)
+        meta.push(metaTitle(title));
+    if (highlights) {
+        ctx.ledger.record({ feature: "code", page: ctx.page, action: "degraded", detail: `line highlights "${highlights}" have no OpenKnowledge affordance (block kept)` });
+    }
+    if (annotations && Object.keys(annotations).length) {
+        ctx.ledger.record({ feature: "code", page: ctx.page, action: "degraded", detail: `${Object.keys(annotations).length} code annotation(s) have no OpenKnowledge affordance (block kept)` });
+    }
+    const info = [lang, ...meta].filter(Boolean).join(" ");
+    return `${fence}${info}\n${code}\n${fence}`;
+}
+/** Fence for a code body: longest-run-safe. JSX containers are not fences, so no alternation is needed inside `<Tabs>`. */
+function fenceFor(code, _ctx) {
+    return pickCodeFence(code);
+}
+function diagramToMdx(node) {
+    const lang = String(node.props?.lang ?? "mermaid");
+    const code = String(node.props?.code ?? "").replace(/\n$/, "");
+    const f = pickCodeFence(code);
+    return `${f}${lang}\n${code}\n${f}`;
+}
+/* ── Tables (GFM) ───────────────────────────────────────────────────────── */
+function tableToMdx(node, ctx) {
+    const rows = [];
+    let headerCount = 0;
+    const cell = (c) => (children(c, ctx) || proseToMdx(c, ctx)).replace(/\n+/g, " ").replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+    for (const child of node.children ?? []) {
+        if ((child.type === "thead" || child.type === "tbody") && child.children) {
+            for (const tr of child.children) {
+                if (tr.type !== "tr" || !tr.children)
+                    continue;
+                const cells = tr.children.map(cell);
+                rows.push(cells);
+                if (child.type === "thead")
+                    headerCount = cells.length;
+            }
+        }
+        else if (child.type === "tr" && child.children) {
+            const cells = child.children.map(cell);
+            rows.push(cells);
+            if (headerCount === 0 && child.children.some((c) => c.type === "th"))
+                headerCount = cells.length;
+        }
+    }
+    if (!rows.length)
+        return "";
+    const colCount = Math.max(headerCount, ...rows.map((r) => r.length));
+    const widths = Array(colCount).fill(3);
+    for (const row of rows)
+        row.forEach((c, i) => (widths[i] = Math.max(widths[i], c.length)));
+    const lines = [];
+    rows.forEach((row, r) => {
+        const padded = row.map((c, i) => c.padEnd(widths[i]));
+        while (padded.length < colCount)
+            padded.push(" ".repeat(widths[padded.length]));
+        lines.push(`| ${padded.join(" | ")} |`);
+        if (r === 0)
+            lines.push(`| ${widths.map((w) => "-".repeat(w)).join(" | ")} |`);
+    });
+    const caption = node.props?.caption;
+    if (caption) {
+        ctx.ledger.record({ feature: "table", page: ctx.page, action: "degraded", detail: "caption rendered as italic text below the table" });
+        lines.push("", `*${escapeMdxText(caption)}*`);
+    }
+    return lines.join("\n");
+}
+/* ── Lists ──────────────────────────────────────────────────────────────── */
+function orderedListToMdx(node, ctx) {
+    const start = node.props?.start || 1;
+    return (node.children ?? [])
+        .map((child, i) => {
+        const marker = `${start + i}. `;
+        const text = nodeToMdx(child, ctx);
+        const [first, ...rest] = text.split("\n");
+        const pad = " ".repeat(marker.length);
+        return rest.length ? `${marker}${first}\n${rest.map((l) => (l ? pad + l : l)).join("\n")}` : `${marker}${first}`;
+    })
+        .join("\n");
+}
+function unorderedListToMdx(node, ctx) {
+    return (node.children ?? [])
+        .map((child) => {
+        const text = nodeToMdx(child, ctx);
+        const [first, ...rest] = text.split("\n");
+        return rest.length ? `- ${first}\n${rest.map((l) => (l ? `  ${l}` : l)).join("\n")}` : `- ${first}`;
+    })
+        .join("\n");
+}
+function listItemToMdx(node, ctx) {
+    const parts = [];
+    if (node.inline?.length)
+        parts.push(inlineToMdx(node.inline, ctx));
+    if (node.children)
+        parts.push(...node.children.map((c) => nodeToMdx(c, ctx)).filter(Boolean));
+    return parts.filter(Boolean).join("\n\n");
+}
+/* ── Definition lists: readable markdown, never a code block ────────────── */
+/**
+ * `- **term**` with the definition body nested under it. OpenKnowledge has no
+ * `<dl>` component and no `: definition` syntax; a JSX wildcard block would
+ * turn PROSE into an opaque raw-MDX box for the corpus's most common
+ * construct. A term list keeps it readable, editable and re-importable
+ * (as a list — declared `partial`).
+ */
+function deflistToMdx(node, ctx) {
+    ctx.ledger.record({ feature: "deflist", page: ctx.page, action: "degraded", detail: "definition list rendered as a bulleted term list (no <dl> in OpenKnowledge)" });
+    const items = [];
+    let current = null;
+    for (const child of node.children ?? []) {
+        if (child.type === "dt") {
+            if (current)
+                items.push(renderTerm(current));
+            current = { term: leaf(child, ctx).trim(), defs: [] };
+        }
+        else if (child.type === "dd") {
+            const body = (children(child, ctx) || leaf(child, ctx)).trim();
+            if (!current)
+                current = { term: "", defs: [] };
+            if (body)
+                current.defs.push(body);
+        }
+        else {
+            const other = nodeToMdx(child, ctx).trim();
+            if (!other)
+                continue;
+            if (!current)
+                current = { term: "", defs: [] };
+            current.defs.push(other);
+        }
+    }
+    if (current)
+        items.push(renderTerm(current));
+    return items.join("\n");
+}
+function renderTerm(t) {
+    const head = t.term ? `- **${t.term}**` : "-";
+    if (!t.defs.length)
+        return head;
+    return `${head}\n\n${indent(t.defs.join("\n\n"), 2)}`;
+}
+/* ── Steps / cards (wildcard JSX, Fumadocs vocabulary) ─────────────────── */
+function stepsToMdx(node, ctx) {
+    ctx.ledger.record({ feature: "steps", page: ctx.page, action: "degraded", detail: "<Steps> lands on OpenKnowledge's wildcard (editable raw MDX, not rendered)" });
+    const inner = ctx.depth++;
+    const body = (node.children ?? [])
+        .map((step) => {
+        const title = (step.inline?.length ? step.inline.map((n) => inlinePlainText(n, (t) => t)).join("") : "") || String(step.props?.title ?? "");
+        const kids = step.children ?? [];
+        const firstText = kids[0] ? headingText(kids[0]).trim() : "";
+        const body = title && firstText && firstText === title.trim() ? kids.slice(1) : kids;
+        const content = body.map((c) => nodeToMdx(c, ctx)).filter(Boolean).join("\n\n");
+        const open = title ? `<Step title=${attr(title)}>` : "<Step>";
+        return content ? `${open}\n\n${content}\n\n</Step>` : `${open}</Step>`;
+    })
+        .join("\n\n");
+    ctx.depth = inner;
+    return `<Steps>\n\n${body}\n\n</Steps>`;
+}
+function cardToMdx(node, ctx) {
+    const title = String(node.props?.title ?? "");
+    const href = node.props?.href;
+    const icon = node.props?.icon;
+    const content = children(node, ctx);
+    const props = [title ? `title=${attr(title)}` : "", href ? `href=${attr(ctx.href(href))}` : "", icon ? `icon=${attr(icon)}` : ""].filter(Boolean).join(" ");
+    const open = props ? `<Card ${props}>` : "<Card>";
+    return content ? `${open}\n\n${content}\n\n</Card>` : `${open}</Card>`;
+}
+function cardsToMdx(node, ctx) {
+    ctx.ledger.record({ feature: node.type, page: ctx.page, action: "degraded", detail: "<Cards> lands on OpenKnowledge's wildcard (editable raw MDX, not rendered)" });
+    const inner = ctx.depth++;
+    const body = (node.children ?? []).map((c) => nodeToMdx(c, ctx)).filter(Boolean).join("\n\n");
+    ctx.depth = inner;
+    return `<Cards>\n\n${body}\n\n</Cards>`;
+}
+/* ── Media ──────────────────────────────────────────────────────────────── */
+function figureToMdx(node, ctx) {
+    const caption = node.props?.caption;
+    const findImage = (n) => {
+        const hit = (n.inline ?? []).find((i) => i.type === "image");
+        if (hit)
+            return hit;
+        for (const c of n.children ?? []) {
+            const h = findImage(c);
+            if (h)
+                return h;
+        }
+        if (n.html) {
+            const m = /<img\b[^>]*\bsrc="([^"]+)"[^>]*(?:\balt="([^"]*)")?/i.exec(n.html);
+            if (m)
+                return { src: m[1], alt: m[2] ?? "" };
+        }
+        return undefined;
+    };
+    const img = findImage(node);
+    if (img?.src && caption) {
+        return `<Image src=${attr(img.src)} alt=${attr(img.alt ?? "")} caption=${attr(caption)} />`;
+    }
+    const inner = children(node, ctx);
+    return caption ? `${inner}\n\n*${escapeMdxText(caption)}*` : inner;
+}
+function youtubeToMdx(node) {
+    const id = String(node.props?.id || node.props?.videoId || "");
+    return `<Video src=${attr(`https://www.youtube.com/watch?v=${id}`)} />`;
+}
+/* ── API nodes (same shape as the Obsidian target: markdown + an HTML-free table) ── */
+function apiSymbolToMdx(node, ctx) {
+    const name = String(node.props?.name ?? "");
+    const kind = String(node.props?.kind ?? "class");
+    const level = node.type === "api-class" ? 3 : 4;
+    const sig = String(node.props?.signature ?? "");
+    const basesRaw = node.props?.bases;
+    const bases = Array.isArray(basesRaw) ? basesRaw.join(", ") : basesRaw;
+    const parts = [`${"#".repeat(level)} ${kind} ${codeSpan(name)}`];
+    if (bases)
+        parts.push(`Bases: ${codeSpan(bases)}`);
+    if (sig) {
+        const f = pickCodeFence(sig);
+        parts.push(`${f}python\n${sig}\n${f}`);
+    }
+    if (node.children)
+        parts.push(children(node, ctx));
+    return parts.filter(Boolean).join("\n\n");
+}
+function apiParamsToMdx(node, ctx) {
+    const params = (node.props?.params ?? []);
+    if (!params.length)
+        return "";
+    ctx.ledger.record({ feature: "api-params", page: ctx.page, action: "degraded", detail: "parameter table flattened to a GFM table (one line per cell)" });
+    const rows = params.map((p) => {
+        const meta = [p.type ? `type: \`${p.type}\`` : "", p.default != null ? `default: \`${String(p.default)}\`` : "", p.required ? "required" : ""].filter(Boolean).join(" · ");
+        const desc = [escapeMdxText(String(p.doc ?? p.description ?? "")).replace(/\s+/g, " ").trim(), meta].filter(Boolean).join(" — ");
+        return `| \`${p.name}\` | ${desc.replace(/\|/g, "\\|")} |`;
+    });
+    return ["| Parameter | Description |", "| --- | --- |", ...rows].join("\n");
+}
+function apiDocToMdx(node, ctx) {
+    const html = String(node.props?.html ?? "");
+    return html ? htmlToMdx(html) : children(node, ctx);
+}
+function apiSourceToMdx(node, ctx) {
+    const code = String(node.props?.code ?? "");
+    const file = String(node.props?.file ?? "");
+    const line = node.props?.line;
+    const parts = [];
+    if (file)
+        parts.push(`*Source: \`${line ? `${file}:${line}` : file}\`*`);
+    if (code) {
+        const body = code.replace(/\n$/, "");
+        const f = pickCodeFence(body);
+        parts.push(`${f}python\n${body}\n${f}`);
+    }
+    else if (node.children?.length)
+        parts.push(children(node, ctx));
+    return parts.join("\n\n");
+}
+/* ── Headings / references ──────────────────────────────────────────────── */
+/**
+ * The headings a page WILL emit, in emit order, as OpenKnowledge will see
+ * their text — headings nested in callouts/tabs/lists included, and the
+ * `### class \`name\`` lines api-class/api-member emit (whose textContent
+ * is "class name"). Anchors must be computed from THIS, not from an
+ * importer's `page.headings` (top-level only, importer-defined text).
+ */
+export function collectEmittedHeadings(nodes) {
+    const out = [];
+    const walk = (n) => {
+        if (n.type === "heading") {
+            out.push({ slug: String(n.props?.slug ?? ""), text: headingText(n) });
+        }
+        else if (n.type === "api-class" || n.type === "api-member") {
+            const name = String(n.props?.name ?? "");
+            const kind = String(n.props?.kind ?? "class");
+            // the Dogsbay id an importer's TOC gives an api symbol is the slug of its bare NAME
+            // (mkdocs `Heading.text = name`); the emitted heading text is `kind name`
+            out.push({ slug: String(n.props?.slug || slugifyHeadingText(name)), text: `${kind} ${name}` });
+        }
+        // a `frontmatter` node has no headings; a `code` node's text is not a heading
+        if (n.children && n.type !== "code" && n.type !== "html")
+            n.children.forEach(walk);
+    };
+    nodes.forEach(walk);
+    return out;
+}
+function headingToMdx(node, ctx) {
+    const hashes = "#".repeat(headingLevel(node));
+    // three shapes: flat `inline` (dogsbay-md), `children:[prose{inline}]` (mkdocs/html importers), `props.text`
+    const text = node.inline?.length
+        ? inlineToMdx(node.inline, ctx)
+        : node.children?.length
+            ? node.children.map((c) => (c.inline?.length ? inlineToMdx(c.inline, ctx) : c.html ? htmlToMdx(c.html) : "")).join("").replace(/\n+/g, " ").trim() || escapeMdxText(headingText(node))
+            : escapeMdxText(headingText(node));
+    // NO `^anchor`, no `{#id}`: OpenKnowledge computes anchors from the text
+    return `${hashes} ${text}`;
+}
+function referencesToMdx(node, ctx) {
+    const entries = (node.props?.entries ?? []);
+    return entries.map((e) => `[${e.label}]: ${ctx.href(e.href)}${e.title ? ` "${e.title}"` : ""}`).join("\n");
+}
+/* ── Utilities ──────────────────────────────────────────────────────────── */
+function children(node, ctx) {
+    if (!node.children?.length)
+        return "";
+    return node.children.map((c) => nodeToMdx(c, ctx)).filter(Boolean).join("\n\n");
+}
+function leaf(node, ctx) {
+    return renderLeaf(node, {
+        inline: (nodes) => inlineToMdx(nodes, ctx),
+        children: (nodes) => nodes.map((c) => nodeToMdx(c, ctx)).filter(Boolean).join("\n\n"),
+        html: htmlToMdx,
+        join: "\n\n",
+    });
+}
+//# sourceMappingURL=serialize.js.map