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

package/dist/adapters/cloudflare.js

@@ -6,10 +6,15 @@
  *
  * Source: https://github.com/cloudflare/cloudflare-docs/tree/production/src/components
  */
-import { readFileSync, existsSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { readFileSync, existsSync, readdirSync, realpathSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
 import TOML from "@iarna/toml";
 import { parse as jsoncParse } from "jsonc-parser";
+import matter from "gray-matter";
+import { FIXED_SLUG, githubSlug } from "../github-slug.js";
+import { outsideFences, outsideInlineCode } from "../fences.js";
+import { findSelfClosingTags, parseJsLiteral } from "../js-literal.js";
+import { componentPropDefaults, jsValueToJinja, renderComponentTemplate, splitTopLevel } from "../jsx-to-jinja.js";
 // ── Indentation helper ─────────────────────────────────
 /**
  * Indent all lines of content to match the indentation of the original tag.
@@ -83,6 +88,23 @@ function getCommand(mgr, type, pkg, opts = {}) {
  * Resolve `<PackageManagers>` to Tabs with npm/yarn/pnpm/bun commands.
  */
 function resolvePackageManagers(source) {
+    if (!source.includes("<PackageManagers"))
+        return source;
+    // A tag opening a LIST ITEM (`1.  <PackageManagers … />`): the marker stays
+    // on its own line and the tabs sit at the item's content column. A tag in a
+    // BLOCKQUOTE (`> <PackageManagers` over `> `-prefixed lines): the prefixes
+    // come off to read it and go back on every line of the result. Both were
+    // left as written (reported) — only a tag at the start of a line was read.
+    source = source.replace(/^([ \t]*)((?:\d+\.|[-*+])[ \t]+)(<PackageManagers\s[\s\S]*?\/>)[ \t]*$/gm, (_m, indent, marker, tag) => {
+        const inner = resolvePackageManagers(tag).replace(/^\n/, "");
+        return `${indent}${marker.trimEnd()}\n\n${indentContent(inner, indent + " ".repeat(marker.length))}`;
+    });
+    source = source.replace(/^([ \t]*>[ \t]?)(<PackageManagers\s(?:[^\n]|\n[ \t]*>)*?\/>)[ \t]*$/gm, (_m, prefix, tag) => {
+        const bare = tag.replace(/\n[ \t]*>[ \t]?/g, "\n");
+        const inner = resolvePackageManagers(bare).replace(/^\n/, "");
+        // An empty quote line first: after a paragraph line `<Tabs>` cannot open a block.
+        return ["", ...inner.split("\n")].map((l) => `${prefix}${l}`.trimEnd()).join("\n");
+    });
     return source.replace(/^([ \t]*)<PackageManagers\s+([\s\S]*?)\/>/gm, (_match, indent, attrsStr) => {
         // Parse attributes
         const type = (attrsStr.match(/type\s*=\s*"([^"]*)"/)?.[1] || "add");
@@ -98,7 +120,10 @@ function resolvePackageManagers(source) {
         })
             .filter(Boolean)
             .join("\n");
-        return indentContent(`<Tabs>\n${tabs}\n</Tabs>`, indent);
+        // Blank line first: written straight after a prose line (as the source
+        // often does, where MDX renders it inline), `<Tabs>` cannot open a block
+        // and the tabs were lost.
+        return "\n" + indentContent(`<Tabs>\n${tabs}\n</Tabs>`, indent);
     });
 }
 // ── WranglerConfig resolution ───────────────────────────
@@ -143,22 +168,31 @@ function resolveWranglerConfig(source) {
                 toml = toml.replace(/^(\s*)(.*compatibility_date.*)/m, "$1# Set this to today's date\n$1$2");
                 jsonc = jsonc.replace(/^(\s*)(.*compatibility_date.*)/m, "$1// Set this to today's date\n$1$2");
             }
+            // A closing fence MUST be on its own line. It wasn't for the TOML
+            // half — `TOML.stringify` returns no trailing newline, so the fence
+            // was glued to the last config line (`remote = true```). The block
+            // then never closed and SWALLOWED THE REST OF THE PAGE: on
+            // ai-search/get-started/workers, everything after the binding config
+            // — prose, headings and three more components — became one giant code
+            // block. Normalising both halves means neither depends on what its
+            // serializer happens to append.
             const result = `<Tabs>
 <TabItem label="wrangler.jsonc">
 
 \`\`\`jsonc
-${jsonc}
+${jsonc.replace(/\s*$/, "")}
 \`\`\`
 
 </TabItem>
 <TabItem label="wrangler.toml">
 
 \`\`\`toml
-${toml}\`\`\`
+${toml.replace(/\s*$/, "")}
+\`\`\`
 
 </TabItem>
 </Tabs>`;
-            return indentContent(result, indent);
+            return "\n" + indentContent(result, indent); // a blank line first, as for PackageManagers
         }
         catch {
             // If conversion fails, output the original code block
@@ -202,45 +236,175 @@ function resolveJsxSwitch(content) {
  * substituting `{X}` with the file content in the source.
  * Vite/Astro's ?raw imports file contents as strings.
  */
-function resolveRawImports(source, partialsDir) {
+function resolveRawImports(source, partialsDir, pageDir) {
     if (!partialsDir)
         return source;
     // src/content/partials/ → src/ (go up two levels to repo src/)
     const srcDir = dirname(dirname(partialsDir));
-    const importRegex = /^import\s+(\w+)\s+from\s+["']~\/([^"']+)\?raw["']\s*;?\s*$/gm;
+    // `~/x?raw` is the site's src/; `./x?raw` (or `../`) is the page's own
+    // directory. Either must stay inside src/ once symlinks are resolved: the
+    // path is author-controlled, and an import is a file READ.
+    const importRegex = /^import\s+(\w+)\s+from\s+["'](~\/|\.{1,2}\/)([^"']+)\?raw["']\s*;?\s*$/gm;
     let result = source;
     let match;
     while ((match = importRegex.exec(source)) !== null) {
         const varName = match[1];
-        const filePath = join(srcDir, match[2]);
-        if (existsSync(filePath)) {
-            try {
-                const content = readFileSync(filePath, "utf-8");
-                result = result.replace(match[0], ""); // remove import line
-                // If used in <Code code={X} lang="..." />, replace with a fenced code block
-                const codeTagRegex = new RegExp(`<Code\\s+code=\\{${varName}\\}[^>]*(?:lang=["']([^"']*)["'])?[^>]*/>`);
-                const codeMatch = result.match(codeTagRegex);
-                if (codeMatch) {
-                    const lang = codeMatch[1] || "plaintext";
-                    // Use a fence that doesn't appear in the content
-                    let fence = "```";
-                    const backtickRuns = content.match(/`{3,}/g);
-                    if (backtickRuns) {
-                        const maxLen = Math.max(...backtickRuns.map((r) => r.length));
-                        fence = "`".repeat(maxLen + 1);
-                    }
-                    result = result.replace(codeMatch[0], `${fence}${lang}\n${content}\n${fence}`);
-                }
-                else {
-                    // Fallback: substitute {X} directly
-                    result = result.replace(new RegExp(`\\{${varName}\\}`, "g"), content);
+        const base = match[2] === "~/" ? srcDir : pageDir;
+        if (!base)
+            continue;
+        const filePath = within(srcDir, resolve(base, match[2] === "~/" ? match[3] : match[2] + match[3]));
+        if (!filePath)
+            continue;
+        try {
+            const content = readFileSync(filePath, "utf-8");
+            result = result.replace(match[0], ""); // remove import line
+            // `<Markdown text={X} />`: the file IS Markdown (third-party license
+            // pages); left to the fallback it became `<Markdown text=…whole file…`.
+            const mdTag = new RegExp(`<Markdown\\s+text=\\{${varName}\\}[^>]*?/>`, "g");
+            if (new RegExp(mdTag.source).test(result)) {
+                result = result.replace(mdTag, () => content.trim());
+                continue;
+            }
+            // If used in <Code code={X} lang="..." />, replace with a fenced code block
+            const codeTagRegex = new RegExp(`<Code\\s+code=\\{${varName}\\}[^>]*(?:lang=["']([^"']*)["'])?[^>]*/>`);
+            const codeMatch = result.match(codeTagRegex);
+            if (codeMatch) {
+                const lang = codeMatch[1] || "plaintext";
+                // Use a fence that doesn't appear in the content
+                let fence = "```";
+                const backtickRuns = content.match(/`{3,}/g);
+                if (backtickRuns) {
+                    const maxLen = Math.max(...backtickRuns.map((r) => r.length));
+                    fence = "`".repeat(maxLen + 1);
                 }
+                result = result.replace(codeMatch[0], () => `${fence}${lang}\n${content}\n${fence}`);
+            }
+            else {
+                // Fallback: substitute {X} directly
+                result = result.replace(new RegExp(`\\{${varName}\\}`, "g"), () => content);
             }
-            catch { /* ignore read errors */ }
         }
+        catch { /* ignore read errors */ }
     }
     return result;
 }
+/**
+ * Page-level string constants: `export const x = "…";` (or a backtick
+ * template with no `${}`), used as `{x}`, `<Code code={x} lang="…" />` or
+ * `<Markdown text={x} />`. ESM is never rendered, but nothing read it: the
+ * statement showed as text, `{owaspCrsVersion}` literally, and a JSON-mode
+ * page's three code samples were missing (5 pages). Other values are left
+ * alone.
+ */
+export function resolvePageConstants(source) {
+    if (!/^export\s+const\s/m.test(source))
+        return source;
+    const values = new Map();
+    // Pass 1: read and remove the statements. Not inside inline code — a
+    // template literal STARTS with a backtick.
+    let result = outsideFences(source, (text) => {
+        let out = "";
+        let last = 0;
+        for (const m of text.matchAll(/^export\s+const\s+(\w+)\s*=\s*/gm)) {
+            // Not a line inside a template-literal attribute (`code={`…`}`): the
+            // backticks before it are unbalanced there.
+            if ((text.slice(0, m.index).match(/(?<!\\)`/g)?.length ?? 0) % 2)
+                continue;
+            const at = m.index + m[0].length;
+            const q = text[at];
+            if (q !== '"' && q !== "'" && q !== "`")
+                continue;
+            let i = at + 1;
+            while (i < text.length && text[i] !== q)
+                i += text[i] === "\\" ? 2 : 1;
+            const tail = /^;?[ \t]*(?:\n|$)/.exec(text.slice(i + 1));
+            if (i >= text.length || !tail)
+                continue;
+            const value = parseJsLiteral(text.slice(at, i + 1));
+            if (typeof value !== "string")
+                continue;
+            values.set(m[1], value);
+            out += text.slice(last, m.index);
+            last = i + 1 + tail[0].length;
+        }
+        return out + text.slice(last);
+    });
+    if (!values.size)
+        return source;
+    // Pass 2: the uses. `{x}` in text first — never inside an open tag, where
+    // `params={{ x }}` is an object shorthand and `code={x}` is taken below.
+    // JSX prints a string as TEXT: it is entity-encoded, which reads the same
+    // in Markdown and in a raw HTML block (a `\_` shows its backslash there).
+    const asText = (v) => v.replace(/[&<>|*_`[\]\\#+\-!~]/g, (c) => `&#${c.charCodeAt(0)};`);
+    result = outsideFences(result, (text) => outsideInlineCode(text, (t) => t.replace(/\{\s*(\w+)\s*\}/g, (whole, name, offset) => {
+        const value = values.get(name);
+        if (value === undefined || /<[A-Za-z][^<>]*$/.test(t.slice(0, offset)))
+            return whole;
+        return asText(value);
+    })));
+    result = outsideFences(result, (text) => {
+        for (const tag of findSelfClosingTags(text, "Code").reverse()) {
+            const name = /^\{\s*(\w+)\s*\}$/.exec(String(tag.attrs.code ?? ""))?.[1];
+            const value = name !== undefined ? values.get(name) : undefined;
+            const lineStart = text.lastIndexOf("\n", tag.start - 1) + 1;
+            const indent = text.slice(lineStart, tag.start);
+            if (value === undefined || !/^[ \t]*$/.test(indent))
+                continue;
+            const lang = typeof tag.attrs.lang === "string" ? tag.attrs.lang : "";
+            const runs = value.match(/`{3,}/g);
+            const fence = "`".repeat(runs ? Math.max(...runs.map((r) => r.length)) + 1 : 3);
+            const body = `${fence}${lang}\n${value.replace(/^\n+|\s+$/g, "")}\n${fence}`.split("\n").join(`\n${indent}`);
+            text = text.slice(0, tag.start) + body + text.slice(tag.end);
+        }
+        for (const tag of findSelfClosingTags(text, "Markdown").reverse()) {
+            const name = /^\{\s*(\w+)\s*\}$/.exec(String(tag.attrs.text ?? ""))?.[1];
+            const value = name !== undefined ? values.get(name) : undefined;
+            if (value === undefined)
+                continue;
+            text = text.slice(0, tag.start) + value.trim().replace(/\s*\n\s*/g, " ") + text.slice(tag.end);
+        }
+        return text;
+    });
+    return result;
+}
+/**
+ * A `<LinkButton>` inside RAW HTML (a `<DashButton>` in an `<ol><li>`, which
+ * becomes a LinkButton above) is not a component there, it is a leaked tag.
+ * In HTML the button is a link: `<a href>label</a>`.
+ */
+export function linkButtonsInHtml(tree) {
+    const fix = (html) => html.includes("<LinkButton")
+        ? html.replace(/<LinkButton\b([^>]*)>([\s\S]*?)<\/LinkButton>/g, (whole, attrs, label) => {
+            const href = /\bhref=("[^"]*"|'[^']*')/.exec(attrs)?.[1];
+            return href ? `<a href=${href}>${label}</a>` : whole;
+        })
+        : html;
+    const walk = (value) => {
+        if (Array.isArray(value))
+            return value.forEach(walk);
+        if (!value || typeof value !== "object")
+            return;
+        const node = value;
+        if (typeof node.html === "string")
+            node.html = fix(node.html);
+        for (const [k, v] of Object.entries(node))
+            if (k !== "props" && typeof v === "object")
+                walk(v);
+    };
+    walk(tree);
+    return tree;
+}
+/** `path` if it resolves (symlinks included) inside `root`, else undefined. */
+function within(root, path) {
+    try {
+        const real = realpathSync(path);
+        const top = realpathSync(root);
+        return real === top || real.startsWith(top + sep) ? real : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ── Render partial resolution ──────────────────────────
 /**
  * Resolve `<Render>` tags by inlining partial MDX content.
@@ -296,6 +460,211 @@ function resolveRenderTags(source, partialsDir, depth = 0) {
         }
     });
 }
+/**
+ * Template mode (plans/page-templates.md): each `<Render>` becomes
+ *
+ *   {% with a="x", b=true %}{% include "/_partials/<product>/<file>.md" %}{% endwith %}
+ *
+ * on its own line at the tag's indent. The partial itself is converted by
+ * the caller (cli.ts). A tag whose params fall outside the convertible
+ * subset is left for `resolveRenderTags`, which inlines it as before, and is
+ * reported; a tag whose partial does not exist is left for the same path.
+ */
+function renderTagsToTemplates(source, partialsDir, options) {
+    if (!partialsDir)
+        return source;
+    let out = "";
+    let last = 0;
+    for (const [start, end] of findRenderTags(source)) {
+        const whole = source.slice(start, end);
+        const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+        const lineEnd = source.indexOf("\n", end);
+        const alone = /^[ \t]*$/.test(source.slice(lineStart, start)) && /^[ \t]*$/.test(source.slice(end, lineEnd < 0 ? source.length : lineEnd));
+        const directive = renderTagToDirective(whole.slice("<Render".length, -2), partialsDir, options);
+        out += source.slice(last, start);
+        last = end;
+        if (directive === undefined) {
+            out += whole;
+            continue;
+        }
+        const token = options.directives ? options.directives.token(directive) : directive;
+        if (alone) {
+            // In place of the tag, at the Markdown indent of its surroundings. NOT
+            // padded with blank lines: after a footnote label (`[^1]:`) a blank line
+            // turned the indented line into an indented code block.
+            out = out.slice(0, out.length - (start - lineStart)) + markdownIndent(source, start, source.slice(lineStart, start)) + token;
+        }
+        else {
+            // Mid-sentence (`add two entries: <Render file="ipv4" …/>`): inline.
+            out += token;
+        }
+    }
+    return out + source.slice(last);
+}
+/** One `<Render>` tag's attributes → its directive, or undefined when it stays a tag (reported). */
+function renderTagToDirective(attrsStr, partialsDir, options) {
+    const file = attrsStr.match(/\bfile\s*=\s*"([^"]*)"/)?.[1];
+    const product = attrsStr.match(/\bproduct\s*=\s*"([^"]*)"/)?.[1] ?? options.defaultProduct;
+    if (!file)
+        return undefined;
+    if (!product) {
+        // Inside a partial, Cloudflare takes a missing product= from the PAGE
+        // being built, which a shared partial cannot know. Reported, not guessed
+        // (none in the corpus: 0 of 289).
+        options.onInlined?.({ product: "?", file, reason: "no product= inside a partial (Cloudflare uses the page's product)" });
+        return undefined;
+    }
+    if (!existsSync(join(partialsDir, product, `${file}.mdx`))) {
+        options.onInlined?.({ product, file, reason: "partial not found" });
+        return undefined;
+    }
+    let assignments = [];
+    const paramsAt = attrsStr.search(/\bparams\s*=\s*\{/);
+    if (paramsAt >= 0) {
+        const open = attrsStr.indexOf("{", paramsAt);
+        const obj = balanced(attrsStr, open)?.trim();
+        if (!obj || !obj.startsWith("{") || !obj.endsWith("}")) {
+            options.onInlined?.({ product, file, reason: "params is not an object literal" });
+            return undefined;
+        }
+        const converted = paramsToAssignments(obj.slice(1, -1), options.names);
+        if (!converted.ok) {
+            options.onInlined?.({ product, file, reason: converted.reason });
+            return undefined;
+        }
+        assignments = converted.assignments;
+    }
+    options.onTemplateInclude?.({ product, file, params: assignments.map((a) => a.slice(0, a.indexOf("="))) });
+    const include = `{% include "/_partials/${product}/${file}.md" %}`;
+    return assignments.length ? `{% with ${assignments.join(", ")} %}${include}{% endwith %}` : include;
+}
+/** `<Render …/>` tags outside code, as [start, end) offsets; mid-line tags included. */
+export function findRenderTags(src) {
+    const out = [];
+    let i = 0;
+    let lineStart = true;
+    let fence = null;
+    while (i < src.length) {
+        if (lineStart) {
+            const m = /^[ \t]*(`{3,}|~{3,})/.exec(src.slice(i, i + 200));
+            if (m) {
+                if (!fence)
+                    fence = m[1];
+                else if (m[1][0] === fence[0] && m[1].length >= fence.length)
+                    fence = null;
+                const nl = src.indexOf("\n", i);
+                i = nl < 0 ? src.length : nl + 1;
+                continue;
+            }
+        }
+        const c = src[i];
+        lineStart = c === "\n";
+        if (fence) {
+            i++;
+            continue;
+        }
+        if (c === "`") {
+            const run = /^`+/.exec(src.slice(i))[0];
+            const close = src.indexOf(run, i + run.length);
+            i = close < 0 ? i + run.length : close + run.length;
+            continue;
+        }
+        if (c === "<" && src.startsWith("<Render", i) && /[\s/]/.test(src[i + 7] ?? "")) {
+            const end = selfClosingEnd(src, i);
+            if (end > 0) {
+                out.push([i, end]);
+                i = end;
+                continue;
+            }
+        }
+        i++;
+    }
+    return out;
+}
+/** End (exclusive) of a self-closing tag at `i`, skipping strings and `{…}` groups; -1 if none. */
+function selfClosingEnd(src, i) {
+    let depth = 0;
+    for (let j = i + 1; j < src.length; j++) {
+        const c = src[j];
+        if (c === '"' || c === "'" || c === "`") {
+            const close = src.indexOf(c, j + 1);
+            if (close < 0)
+                return -1;
+            j = close;
+        }
+        else if (c === "{")
+            depth++;
+        else if (c === "}")
+            depth--;
+        else if (depth === 0 && c === "/" && src[j + 1] === ">")
+            return j + 2;
+        else if (depth === 0 && c === ">")
+            return -1;
+    }
+    return -1;
+}
+/**
+ * The indent a directive may keep where the tag stood. In MDX, whitespace
+ * before a JSX element means nothing — Cloudflare writes
+ * `         <Render …/>` inside a <TabItem> after unindented prose. In
+ * Markdown four spaces after a blank line open an INDENTED CODE BLOCK, and
+ * the include came out as a literal code sample. So the indent is capped at
+ * the content column of the previous non-blank line: a list item's text
+ * column (the directive stays in the item), otherwise that line's indent.
+ */
+export function markdownIndent(source, offset, indent) {
+    const before = source.slice(0, offset).split("\n");
+    before.pop(); // the tag's own line
+    let prev = "";
+    while (before.length && !(prev = before.pop()).trim())
+        ;
+    if (!prev.trim())
+        return "";
+    const m = /^(\s*)(?:([-*+]|\d+[.)])\s+)?/.exec(prev);
+    const column = m[0].length;
+    return indent.length > column ? " ".repeat(column) : indent;
+}
+/** The text of the `{…}` group opening at `open` (inclusive), or undefined. */
+function balanced(src, open) {
+    let depth = 0;
+    let q = null;
+    for (let i = open; i < src.length; i++) {
+        const c = src[i];
+        if (q) {
+            if (c === "\\")
+                i++;
+            else if (c === q)
+                q = null;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`")
+            q = c;
+        else if (c === "{")
+            depth++;
+        else if (c === "}" && --depth === 0)
+            return src.slice(open + 1, i);
+    }
+    return undefined;
+}
+/** `key: value, …` → Jinja `key=value` assignments, or why not. */
+function paramsToAssignments(src, names) {
+    const assignments = [];
+    for (const part of splitTopLevel(src)) {
+        if (!part.trim())
+            continue;
+        const m = /^\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*:\s*([\s\S]+)$/.exec(part);
+        if (!m)
+            return { ok: false, reason: `unsupported param entry: ${part.trim().slice(0, 60)}` };
+        const key = m[1] ?? m[2] ?? m[3];
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            return { ok: false, reason: `param name "${key}" is not a template identifier` };
+        const value = jsValueToJinja(m[4], names);
+        if (value === undefined)
+            return { ok: false, reason: `param "${key}" value outside the convertible subset: ${m[4].trim().slice(0, 60)}` };
+        assignments.push(`${key}=${value}`);
+    }
+    return { ok: true, assignments };
+}
 function parseRenderAttrs(str) {
     const file = str.match(/file\s*=\s*"([^"]*)"/)?.[1];
     const product = str.match(/product\s*=\s*"([^"]*)"/)?.[1];
@@ -311,8 +680,1396 @@ function parseRenderAttrs(str) {
     return { file, product, params };
 }
 // ── Adapter export ─────────────────────────────────────
+/**
+ * The SDK ids of `id="x"`, `id={["a", "b"]}` — and `id={"a", "b"}`, which is
+ * a JS COMMA expression: its value is the LAST string, so upstream shows that
+ * snippet for "b" only (2 corpus uses). Anything else (a variable) has no
+ * ids and lands in an "other" tab rather than inventing an SDK name.
+ */
+function rtkIds(raw) {
+    const strings = [...raw.matchAll(/"([^"]*)"|'([^']*)'/g)].map((m) => m[1] ?? m[2]);
+    if (!raw.startsWith("{"))
+        return raw ? [raw] : [];
+    if (/^\{\s*\[/.test(raw))
+        return strings;
+    return strings.length ? [strings[strings.length - 1]] : [];
+}
+/**
+ * Markdown for ONE table cell: a cell is one line, so paragraphs and list
+ * items keep apart with <br> (upstream renders real <p>/<ul> there; spaces
+ * ran "…in time. - Bookmarks are…" together), and pipes are escaped.
+ */
+function tableCell(value) {
+    if (value === undefined || value === null)
+        return "";
+    return String(value)
+        .trim()
+        .split(/\n\s*\n/)
+        .map((para) => para.split(/\n(?=\s*(?:[-*+]|\d+[.)])\s)/).map((l) => l.replace(/\s*\n\s*/g, " ").trim()).join("<br>"))
+        .join("<br><br>")
+        .replace(/\|/g, "\\|");
+}
+// ── Plans (FeatureTable, ProductFeatures) ───────────────
+// Per process, like the glossary cache: a one-shot import reads the file once;
+// a long-lived host (a watch mode) would need to drop it on change.
+const plansCache = new Map();
+/** `src/content/plans/index.json`, a sibling of the partials dir. */
+function loadPlans(partialsDir) {
+    const file = partialsDir ? join(dirname(partialsDir), "plans", "index.json") : "";
+    if (!plansCache.has(file)) {
+        let data;
+        try {
+            data = file && existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : undefined;
+        }
+        catch {
+            data = undefined; // unreadable: tags stay, and are reported
+        }
+        plansCache.set(file, data);
+    }
+    return plansCache.get(file);
+}
+const byPath = (obj, path) => path.split(".").reduce((acc, key) => (acc && typeof acc === "object" ? acc[key] : undefined), obj);
+/** `<FeatureTable id>`: the plan comparison table FeatureTable.astro renders. */
+function featureTable(plan) {
+    const features = Object.values((plan.properties ?? {}));
+    if (!features.length)
+        return undefined;
+    const cols = [
+        ["free", "Free"],
+        ["pro", "Pro"],
+        ["biz", "Business"],
+        ["ent", "Enterprise"],
+        ["ent_plus", String(plan.ent_plus ?? "Enterprise Plus")],
+    ];
+    const present = cols.filter(([k]) => features.some((f) => f[k]));
+    return [
+        `|  | ${present.map(([, label]) => label).join(" | ")} |`,
+        `| --- | ${present.map(() => "---").join(" | ")} |`,
+        // Row titles are header cells upstream (<th>): bold here.
+        ...features.map((f) => `| ${f.title ? `**${tableCell(f.title)}**` : ""} | ${present.map(([k]) => tableCell(f[k])).join(" | ")} |`),
+    ];
+}
+/** `<ProductFeatures id additional_descriptions>`: each feature's per-plan availability. */
+function productFeatures(product, more) {
+    const out = [];
+    for (const [key, value] of Object.entries(product)) {
+        if (key === "title" || key === "link" || !value || typeof value !== "object")
+            continue;
+        const feature = value;
+        out.push(anchorHeading(String(feature.title ?? key), 3), "");
+        if (feature.link)
+            out.push(`**Link:** [${feature.title ?? key}](${feature.link})`, "");
+        for (const p of Object.values(feature.properties ?? {})) {
+            out.push(`**${p.title === "Availability" ? "Feature availability" : p.title ?? ""}**`, "");
+            if (p.title !== "Availability" && p.summary)
+                out.push(String(p.summary).trim(), "");
+            const items = [
+                ["Free", p.free],
+                ...(more ? [["Lite", p.lite ?? p.free]] : []),
+                ["Pro", p.pro],
+                ...(more ? [["Pro Plus", p.pro_plus ?? p.pro]] : []),
+                ["Business", p.biz],
+                ["Enterprise", p.ent],
+            ];
+            for (const [label, v] of items)
+                if (v !== undefined)
+                    out.push(`- **${label}:** ${String(v).replace(/\s*\n\s*/g, " ")}`);
+            out.push("");
+        }
+    }
+    return out.length ? out : undefined;
+}
+/**
+ * Cloudflare's plan components, from `src/content/plans/index.json` at
+ * import, outside fenced and inline code. An unknown id leaves the tag, which
+ * is reported (both are lossy strips in the component map).
+ */
+export function resolvePlans(source, partialsDir) {
+    if (!/<(?:FeatureTable|ProductFeatures)\b/.test(source))
+        return source;
+    const plans = loadPlans(partialsDir);
+    if (!plans)
+        return source;
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/^([ \t]*)<(FeatureTable|ProductFeatures)\b([^>]*?)\/>/gm, (whole, indent, tag, attrs) => {
+        const id = attr(attrs, "id");
+        const entry = id ? byPath(plans, id) : undefined;
+        if (!entry || typeof entry !== "object")
+            return whole;
+        const lines = tag === "FeatureTable"
+            ? featureTable(entry)
+            : productFeatures(entry, /\badditional_descriptions\b(?!\s*=\s*\{\s*false\s*\})/.test(attrs));
+        // Every LINE takes the indent (a multi-line summary is one entry).
+        return lines ? `\n${lines.join("\n").split("\n").map((l) => (l ? indent + l : l)).join("\n")}\n` : whole;
+    })));
+}
+/** `<Plan type>` labels, as `components/cf/Plan.astro` maps them. */
+const PLAN_TYPES = {
+    all: "Available on all plans",
+    paid: "Available on Paid plans",
+    pro: "Pro and above",
+    business: "Business and above",
+    enterprise: "Enterprise-only",
+    "add-on": "Add-on feature",
+    "ent-add-on": "Enterprise-only paid add-on",
+    "workers-all": "Available on Free and Paid plans",
+    "workers-paid": "Available on Workers Paid plan",
+    beta: "Available in open beta",
+};
+/**
+ * `<Plan type="…" />` → its label, `<Plan id="a.b.c" />` → that string from
+ * `plans/index.json` — in bold, as the component's emphasised line (a
+ * `<div>`: alone on its line it ends its paragraph). The old transform
+ * printed the raw type (`**ent-add-on plan**`) and never read `id=` (7
+ * reported). An unresolved tag is left to the parser: alone on a line it is
+ * dropped and reported as an unknown component; mid-line the leak scan
+ * reports it.
+ */
+export function resolvePlanBadges(source, partialsDir) {
+    if (!source.includes("<Plan"))
+        return source;
+    let plans = null;
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/<Plan\s+(type|id)=["']([^"']+)["']\s*\/?>/g, (whole, kind, key, offset, all) => {
+        let label;
+        if (kind === "type")
+            label = PLAN_TYPES[key];
+        else {
+            if (plans === null)
+                plans = loadPlans(partialsDir);
+            label = plans ? byPath(plans, key) : undefined;
+        }
+        if (typeof label !== "string" || !label.trim())
+            return whole;
+        const bold = `**${label.trim().replace(/[*_`[\]\\<]/g, "\\$&")}**`;
+        // Alone on its line with text on the next: a blank line, so the
+        // following text does not join the badge's paragraph.
+        const lineStart = all.lastIndexOf("\n", offset - 1) + 1;
+        const lineEnd = all.indexOf("\n", offset);
+        const alone = !all.slice(lineStart, offset).trim() && !all.slice(offset + whole.length, lineEnd < 0 ? all.length : lineEnd).trim();
+        const next = lineEnd < 0 ? "" : all.slice(lineEnd + 1, all.indexOf("\n", lineEnd + 1) < 0 ? all.length : all.indexOf("\n", lineEnd + 1));
+        return alone && next.trim() ? `${bold}\n` : bold;
+    })));
+}
+/**
+ * A YAML data file, via gray-matter's YAML engine (no new dependency). The
+ * files may open with their own `---` document marker; left in, the wrapper
+ * read as EMPTY front matter (every glossary term was once lost to that).
+ */
+function readYaml(file) {
+    const yaml = readFileSync(file, "utf8").replace(/^\uFEFF?---[ \t]*\r?\n/, "");
+    return matter(`---\n${yaml}\n---\n`).data;
+}
+const yamlCache = new Map();
+function cachedYaml(file) {
+    if (!yamlCache.has(file)) {
+        let data;
+        try {
+            data = existsSync(file) ? readYaml(file) : undefined;
+        }
+        catch {
+            data = undefined; // unreadable: the tags stay, and are reported
+        }
+        yamlCache.set(file, data);
+    }
+    return yamlCache.get(file);
+}
+/** Re-indent a block of lines to a tag's own indent (every line). */
+/**
+ * A heading written for COMPONENT data (flags, notifications, changelog
+ * dates, plan features): upstream renders these as `<AnchorHeading>`, whose
+ * id is its own and takes no slot in the page's dedupe — so they are emitted
+ * as one too, not as `##` Markdown.
+ */
+const anchorHeading = (title, depth) => `<AnchorHeading ${jsxAttr("title", title.replace(/\s+/g, " ").trim())} depth={${depth}} />`;
+const indented = (block, indent) => block.split("\n").map((l) => (l ? indent + l : l)).join("\n");
+/**
+ * A JSX attribute value, quoted so it survives: the attribute parser does not
+ * decode `&quot;`, so a value holding `"` is single-quoted instead.
+ */
+const jsxAttr = (name, s) => (s.includes('"') && !s.includes("'") ? `${name}='${s}'` : `${name}="${s.replace(/"/g, "'")}"`);
+/**
+ * `<AvailableNotifications product notificationFilter />` → a `<Details>`
+ * per notification (grouped under `##` product headings when unfiltered), as
+ * AvailableNotifications.astro renders, from `notifications/index.yaml`. The
+ * Details go through the normal component mapping.
+ */
+export function resolveNotifications(source, partialsDir) {
+    if (!source.includes("<AvailableNotifications"))
+        return source;
+    const data = partialsDir ? cachedYaml(join(dirname(partialsDir), "notifications", "index.yaml")) : undefined;
+    const all = data?.entries;
+    if (!Array.isArray(all))
+        return source;
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/^([ \t]*)<AvailableNotifications\b([^>]*?)\/>/gm, (whole, indent, attrs) => {
+        const product = attr(attrs, "product");
+        const filter = attr(attrs, "notificationFilter");
+        let list = all;
+        if (product)
+            list = list.filter((n) => String(n.associatedProducts ?? "").toLowerCase() === product.toLowerCase());
+        if (filter)
+            list = list.filter((n) => String(n.name ?? "").toLowerCase() === filter.toLowerCase());
+        if (!list.length)
+            return whole;
+        const groups = new Map();
+        for (const n of list) {
+            const k = String(n.associatedProducts ?? "");
+            if (!groups.has(k))
+                groups.set(k, []);
+            groups.get(k).push(n);
+        }
+        const out = [];
+        const headings = !product && !filter;
+        // Code-unit order, as upstream's `.sort()` ("SSL/TLS" before "Security Center").
+        for (const [group, entries] of [...groups.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) {
+            if (headings)
+                out.push(anchorHeading(group, 2), "");
+            for (const n of entries) {
+                out.push(`<Details ${jsxAttr("header", String(n.name ?? ""))}>`, "");
+                const part = (label, v) => {
+                    if (v)
+                        out.push(`**${label}**`, "", String(v).trim(), "");
+                };
+                part("Who is it for?", n.audience);
+                part("Other options / filters", n.otherFilters);
+                part("Included with", n.availability);
+                part("What should you do if you receive one?", n.nextSteps);
+                part("Additional information", n.additional_information);
+                part("Limitations", n.limitations);
+                out.push("</Details>", "");
+            }
+        }
+        return indented(out.join("\n").trimEnd(), indent);
+    })));
+}
+/** Inline code for a table cell: a backtick fence long enough, pipes escaped. */
+function codeCell(value) {
+    const s = String(value ?? "");
+    if (!s)
+        return "";
+    const run = Math.max(0, ...[...s.matchAll(/`+/g)].map((m) => m[0].length)) + 1;
+    const fence = "`".repeat(run);
+    return `${fence}${run > 1 ? " " : ""}${s.replace(/\|/g, "\\|")}${run > 1 ? " " : ""}${fence}`;
+}
+/**
+ * `<PagesBuildPreset framework />` → its configuration table, and
+ * `<PagesBuildPresetsTable />` → every preset, as the components render them,
+ * from `pages-framework-presets/index.yaml`. An unknown framework leaves the
+ * tag, which is reported.
+ */
+export function resolvePagesPresets(source, partialsDir) {
+    if (!/<PagesBuildPreset/.test(source))
+        return source;
+    const data = partialsDir
+        ? cachedYaml(join(dirname(partialsDir), "pages-framework-presets", "index.yaml"))
+        : undefined;
+    const presets = data?.build_configs;
+    if (!presets || typeof presets !== "object")
+        return source;
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/^([ \t]*)<(PagesBuildPresetsTable|PagesBuildPreset)\b([^>]*?)\/>/gm, (whole, indent, tag, attrs) => {
+        let lines;
+        if (tag === "PagesBuildPresetsTable") {
+            lines = [
+                "| Framework/tool | Build command | Build directory |",
+                "| --- | --- | --- |",
+                ...Object.values(presets).map((p) => `| ${tableCell(p.display_name)} | ${codeCell(p.build_command)} | ${codeCell(p.build_output_directory)} |`),
+            ];
+        }
+        else {
+            const name = attr(attrs, "framework") ?? "";
+            // Own keys only: `framework="constructor"` is not a preset.
+            const preset = Object.hasOwn(presets, name) ? presets[name] : undefined;
+            if (!preset || typeof preset !== "object")
+                return whole;
+            lines = [
+                "| Configuration option | Value |",
+                "| --- | --- |",
+                `| Production branch | ${codeCell("main")} |`,
+                `| Build command | ${codeCell(preset.build_command)} |`,
+                `| Build directory | ${codeCell(preset.build_output_directory)} |`,
+            ];
+        }
+        // Blank lines around: a table must not merge with an adjacent table or
+        // take the next line as a row.
+        return `\n${indented(lines.join("\n"), indent)}\n`;
+    })));
+}
+// ── GitHubCode ──────────────────────────────────────────
+/**
+ * `<GitHubCode repo commit file lines tag lang />` fetches a file from GitHub
+ * at build time and shows it (or its `lines`, or a tagged region). An import
+ * does not reach the network, so it becomes a LINK to exactly that file at
+ * that commit (and those lines), and is counted as degraded — the reader
+ * can still get the code; the page no longer shows it.
+ */
+export function resolveGitHubCode(source, onDegraded) {
+    if (!source.includes("<GitHubCode"))
+        return source;
+    return outsideFences(source, (text) => {
+        const tags = findSelfClosingTags(text, "GitHubCode");
+        if (!tags.length)
+            return text;
+        let out = "";
+        let last = 0;
+        for (const tag of tags) {
+            const a = tag.attrs;
+            const str = (k) => (typeof a[k] === "string" && !a[k].startsWith("{") ? a[k] : undefined);
+            const repo = str("repo");
+            const commit = str("commit");
+            const file = str("file");
+            const lineStart = text.lastIndexOf("\n", tag.start - 1) + 1;
+            const indent = text.slice(lineStart, tag.start);
+            if (!repo || !commit || !file || !/^[\w.-]+\/[\w.-]+$/.test(repo) || !/^[\w./-]+$/.test(commit) || !/^[ \t]*$/.test(indent))
+                continue;
+            // Upstream: 1-based, inclusive; a single number means from there on.
+            const lines = /^(\d+)(?:-(\d+))?$/.exec(str("lines") ?? "");
+            const anchor = lines ? (lines[2] ? `#L${lines[1]}-L${lines[2]}` : `#L${lines[1]}`) : "";
+            const path = file.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
+            // In <…>: a `)` in a path would otherwise end the destination.
+            const url = `https://github.com/${repo}/blob/${commit}/${path}${anchor}`;
+            const range = lines ? (lines[2] ? ` (lines ${lines[1]}–${lines[2]})` : ` (from line ${lines[1]})`) : "";
+            const what = `${file}${range}${str("tag") ? ` (region "${str("tag")}")` : ""}`;
+            onDegraded?.("GitHubCode", "a link to the source: the content is fetched at build time upstream");
+            out += text.slice(last, tag.start) + `Code: [\`${what.replace(/`/g, "")}\` in ${repo}](<${url}>)`;
+            last = tag.end;
+        }
+        return out + text.slice(last);
+    });
+}
+// ── BuildAgentsCallout ──────────────────────────────────
+/**
+ * `<AutoconfigDiagram framework configs={[…]}>` draws DATA — the framework,
+ * the configuration Wrangler generates, Workers — so it becomes that sentence
+ * and a File / Setting / Value table (nothing lost, not reported). Other
+ * diagrams are illustrations: the CLI's `describeComponent` keeps the
+ * description their component declares, reported as degraded.
+ */
+export function resolveDiagrams(source) {
+    if (!source.includes("<AutoconfigDiagram"))
+        return source;
+    return outsideFences(source, (text) => {
+        for (const tag of findSelfClosingTags(text, "AutoconfigDiagram").reverse()) {
+            const lineStart = text.lastIndexOf("\n", tag.start - 1) + 1;
+            const indent = text.slice(lineStart, tag.start);
+            const framework = tag.attrs.framework;
+            const configs = typeof tag.attrs.configs === "string" && tag.attrs.configs.startsWith("{") ? parseJsLiteral(tag.attrs.configs.slice(1, -1)) : undefined;
+            const rows = Array.isArray(configs)
+                ? configs.filter((c) => !!c && typeof c === "object" && ["label", "file", "value"].every((k) => typeof c[k] === "string"))
+                : [];
+            // `framework={…}` is an expression (the attribute keeps its braces): not read.
+            if (!/^[ \t]*$/.test(indent) || typeof framework !== "string" || framework.startsWith("{") || !Array.isArray(configs) || rows.length !== configs.length || !rows.length)
+                continue;
+            const md = [
+                `Wrangler detects **${framework.replace(/[*_`[\]\\<]/g, "\\$&")}** and generates the configuration below, then deploys to Workers.`,
+                "",
+                "| File | Setting | Value |",
+                "| --- | --- | --- |",
+                ...rows.map((r) => `| ${codeCell(r.file.replace(/\s+/g, " "))} | ${codeCell(r.label.replace(/\s+/g, " "))} | ${codeCell(r.value.replace(/\s+/g, " "))} |`),
+            ].join("\n");
+            text = text.slice(0, tag.start) + `\n${indented(md, indent)}\n` + text.slice(tag.end);
+        }
+        return text;
+    });
+}
+/** pretty-bytes' output for the sizes it is given here (base 1000, 3 significant digits). */
+function prettyBytes(n) {
+    const units = ["B", "kB", "MB", "GB", "TB"];
+    let i = 0;
+    while (n >= 1000 && i < units.length - 1) {
+        n /= 1000;
+        i++;
+    }
+    return `${Number(n.toPrecision(3))} ${units[i]}`;
+}
+/**
+ * `<TypeScriptExample omitTabs>` inside a `<Tabs>` contributes its tabs to
+ * THAT group (upstream: JavaScript, generated from the TypeScript, then
+ * TypeScript). Stripped like the plain form, it left a bare code block as a
+ * direct child of the tab group, which broke the group. It becomes a
+ * TypeScript tab; the JavaScript variant is not generated by the import.
+ */
+export function resolveOmitTabsTypeScript(source) {
+    if (!/<TypeScriptExample\b[^>]*\bomitTabs\b/.test(source))
+        return source;
+    // Line by line with fence tracking: the TypeScript fence sits BETWEEN the
+    // opener and closer, so a per-chunk outsideFences pass never sees both.
+    const lines = source.split("\n");
+    let fence = null;
+    let open = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const f = /^[ \t]*(`{3,}|~{3,})/.exec(line);
+        if (fence) {
+            if (f && f[1][0] === fence[0] && f[1].length >= fence.length && line.trim() === f[1])
+                fence = null;
+            continue;
+        }
+        if (f) {
+            fence = f[1];
+            continue;
+        }
+        const opener = /^([ \t]*)<TypeScriptExample\b([^>]*)>[ \t]*$/.exec(line);
+        if (opener) {
+            // Any other TypeScriptExample opener ends a pending one: a stray
+            // omitTabs opener must not pair with a later, unrelated closer.
+            open = !opener[2].trimEnd().endsWith("/") && /\bomitTabs\b(?!\s*=\s*\{\s*false\s*\})/.test(opener[2]) ? i : -1;
+            continue;
+        }
+        if (/^[ \t]*<\/Tabs>/.test(line))
+            open = -1;
+        const closer = /^([ \t]*)<\/TypeScriptExample>[ \t]*$/.exec(line);
+        // The closer at the opener's indent.
+        if (closer && open >= 0 && closer[1] === /^[ \t]*/.exec(lines[open])[0]) {
+            lines[open] = `${/^[ \t]*/.exec(lines[open])[0]}<TabItem label="TypeScript">`;
+            lines[i] = `${closer[1]}</TabItem>`;
+            open = -1;
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Three small components over LOCAL data, read at import:
+ * - `<RSSButton href|changelog text?>` → a link (it renders one).
+ * - `<WARPReleases track>` → the latest release open and the rest in a
+ *   collapsed history, from `src/content/warp-releases/<track>/*.yaml`.
+ *   Upstream keeps the releases of the year before NOW; an import keeps the
+ *   year before the LATEST release, so the output does not depend on the day
+ *   it runs. The Linux distribution picker becomes one link per distribution.
+ * - `<CompatibilityFlags experimental?>` → each flag (`src/content/
+ *   compatibility-flags/*.md`) as a heading, its dates and flags, and its
+ *   body, newest first.
+ * Anything unreadable leaves the tag, which is reported.
+ */
+export function resolveLocalDataComponents(source, partialsDir) {
+    if (!/<(RSSButton|WARPReleases|CompatibilityFlags|PagesBuildEnvironment\w*)\b/.test(source))
+        return source;
+    const content = partialsDir ? dirname(partialsDir) : undefined;
+    const src = content ? dirname(content) : undefined;
+    const warp = (track, indent) => {
+        if (!content || !/^[a-z]+\/[a-z]+$/.test(track))
+            return undefined;
+        const dir = join(content, "warp-releases", track);
+        let releases;
+        try {
+            const files = readdirSync(dir).filter((f) => /\.(ya?ml|json)$/.test(f));
+            releases = files.map((f) => {
+                // Symlinks resolved and contained: a corpus is untrusted input.
+                const file = within(content, join(dir, f));
+                if (!file)
+                    throw new Error("outside");
+                const d = (f.endsWith(".json") ? JSON.parse(readFileSync(file, "utf8")) : readYaml(file));
+                return { ...d, releaseDate: d.releaseDate instanceof Date ? d.releaseDate : new Date(String(d.releaseDate)) };
+            });
+        }
+        catch {
+            return undefined;
+        }
+        // Upstream's schema fails the build on a malformed release: leave the tag
+        // (reported) rather than drop the entry silently.
+        if (releases.some((r) => typeof r.version !== "string" || typeof r.releaseNotes !== "string" || typeof r.platformName !== "string" || Number.isNaN(r.releaseDate.getTime())))
+            return undefined;
+        releases.sort((a, b) => b.releaseDate.getTime() - a.releaseDate.getTime());
+        const latest = releases[0];
+        if (!latest)
+            return undefined;
+        const cutoff = new Date(latest.releaseDate);
+        cutoff.setFullYear(cutoff.getFullYear() - 1);
+        const shown = releases.filter((r) => r.releaseDate >= cutoff);
+        // Notes are Markdown upstream (marked), but here they join the MDX
+        // stream: anything that would be read as STRUCTURE (a heading, `:::`,
+        // a tag, a brace expression) leaves the tag rather than reshape the page.
+        const risky = /^\s*(:::|#{1,6}\s)|<\/?[A-Za-z]|[{}]/m;
+        if (shown.some((r) => risky.test(outsideFences(r.releaseNotes, (t) => t.replace(/`[^`\n]*`/g, "")))))
+            return undefined;
+        let names = {};
+        try {
+            const list = JSON.parse(readFileSync(join(src, "util", "warp-platforms.json"), "utf8"));
+            names = Object.fromEntries(list.map((p) => [p.platform, p.display_name]));
+        }
+        catch {
+            // Platform ids are shown as they are.
+        }
+        const one = (r, header, open) => {
+            const facts = [
+                `**Version:** ${r.platformName} ${r.version}`,
+                `**Date:** ${r.releaseDate.toISOString().split("T")[0]}`,
+                ...(typeof r.packageSize === "number" ? [`**Size:** ${prettyBytes(r.packageSize)}`] : []),
+            ].join(" · ");
+            const linux = Object.keys(r.linuxPlatforms ?? {})
+                .map((p) => [names[p] ?? p, p])
+                .sort((a, b) => a[0].localeCompare(b[0]));
+            const download = linux.length
+                ? ["Download:", "", ...linux.map(([name, p]) => `- [${name}](https://downloads.cloudflareclient.com/v1/download/${p}/version/${r.version})`)]
+                : r.packageURL
+                    ? [`[Download](${r.packageURL})`]
+                    : [];
+            return [
+                `<Details ${jsxAttr("header", header)}${open ? " open" : ""}>`,
+                "",
+                facts,
+                "",
+                ...download,
+                "",
+                // Not a heading: upstream's is an <h4> with no id, and 48 stamped
+                // `{#release-notes}` ids on one page are duplicate DOM ids.
+                "**Release notes**",
+                "",
+                r.releaseNotes.trim(),
+                "",
+                "</Details>",
+            ].join("\n");
+        };
+        const md = [
+            one(latest, "Latest release", true),
+            "",
+            `<Details header="Previous version history (${shown.length - 1})">`,
+            "",
+            ...shown.slice(1).flatMap((r) => [one(r, `${latest.platformName} ${r.version}`, false), ""]),
+            "</Details>",
+        ].join("\n");
+        return indented(md, indent);
+    };
+    const flags = (experimental, indent) => {
+        if (!content)
+            return undefined;
+        const dir = join(content, "compatibility-flags");
+        let entries;
+        try {
+            entries = readdirSync(dir)
+                .filter((f) => /\.mdx?$/.test(f))
+                .map((f) => {
+                const file = within(content, join(dir, f));
+                if (!file)
+                    throw new Error("outside");
+                const parsed = matter(readFileSync(file, "utf8"));
+                // The body's own imports go (the page's are stripped the same way).
+                const body = outsideFences(parsed.content, (t) => t.replace(/^import\s[^\n]*from\s*["'][^"']+["'];?[ \t]*$/gm, ""));
+                return { data: parsed.data, body: body.trim() };
+            });
+        }
+        catch {
+            return undefined;
+        }
+        // A flag with no name: upstream fails the build; leave the tag (reported).
+        if (entries.some((e) => typeof e.data.name !== "string"))
+            return undefined;
+        if (experimental)
+            entries = entries.filter((e) => e.data.experimental === true);
+        const date = (v) => (v instanceof Date ? v.toISOString().split("T")[0] : v == null ? "" : String(v));
+        entries.sort((a, b) => new Date(date(b.data.sort_date)).getTime() - new Date(date(a.data.sort_date)).getTime());
+        if (!entries.length)
+            return undefined;
+        const md = entries
+            .map((e) => {
+            const facts = [
+                e.data.enable_date ? `- **Default as of:** ${date(e.data.enable_date)}` : "",
+                e.data.enable_flag ? `- **Flag to enable:** ${codeCell(e.data.enable_flag)}` : "",
+                e.data.disable_flag ? `- **Flag to disable:** ${codeCell(e.data.disable_flag)}` : "",
+            ].filter(Boolean);
+            return [anchorHeading(String(e.data.name), 3), "", ...(facts.length ? [...facts, ""] : []), e.body].join("\n");
+        })
+            .join("\n\n");
+        return indented(md, indent);
+    };
+    // `<PagesBuildEnvironment{,Languages,Tools} />` — the Pages build image,
+    // one tab per version (newest first, as upstream reverses the glob order),
+    // from content/pages-build-environment/v*.yaml.
+    const buildEnv = (tag, indent) => {
+        if (!content)
+            return undefined;
+        const dir = join(content, "pages-build-environment");
+        let versions;
+        try {
+            versions = readdirSync(dir)
+                .filter((f) => /\.ya?ml$/.test(f))
+                .sort()
+                .map((f) => {
+                const file = within(content, join(dir, f));
+                if (!file)
+                    throw new Error("outside");
+                return { id: f.replace(/\.ya?ml$/, ""), data: readYaml(file) };
+            })
+                .reverse();
+        }
+        catch {
+            return undefined;
+        }
+        const cell = (v) => tableCell(v == null ? "" : String(v));
+        const tab = (label, body) => [`<TabItem label="${label}">`, "", ...body, "", "</TabItem>"];
+        const tabs = [];
+        for (const { id, data } of versions) {
+            if (tag === "PagesBuildEnvironment") {
+                const env = data.build_environment;
+                if (!env)
+                    continue; // upstream skips a version without one
+                tabs.push(...tab(id, ["| | |", "| --- | --- |", `| **Build environment** | ${String(env.operating_system ?? "").replace(/\|/g, "\\|")} |`, `| **Architecture** | ${cell(env.architecture)} |`]));
+            }
+            else {
+                const langs = tag === "PagesBuildEnvironmentLanguages";
+                const rows = (langs ? data.languages : data.tools);
+                if (!Array.isArray(rows))
+                    return undefined;
+                tabs.push(...tab(id, [
+                    `| Tool | Default version | Supported versions | Environment variable |${langs ? " File |" : ""}`,
+                    `| --- | --- | --- | --- |${langs ? " --- |" : ""}`,
+                    ...rows.map((r) => `| **${cell(r.name)}** | ${cell(r.default)} | ${cell(r.supported)} | ${r.environment_variable ? codeCell(r.environment_variable) : ""} |` +
+                        (langs ? ` ${Array.isArray(r.file) ? r.file.map(String).map(tableCell).join(", ") : ""} |` : "")),
+                ]));
+            }
+            tabs.push("");
+        }
+        if (!tabs.length)
+            return undefined;
+        return indented(["<Tabs>", "", ...tabs, "</Tabs>"].join("\n"), indent);
+    };
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => {
+        text = text.replace(/^([ \t]*)<(PagesBuildEnvironment(?:Languages|Tools)?)\s*\/>[ \t]*$/gm, (whole, indent, tag) => {
+            const md = buildEnv(tag, indent);
+            return md === undefined ? whole : `\n${md}\n`;
+        });
+        text = text.replace(/<RSSButton\b([^>]*?)\/>/g, (whole, attrs) => {
+            const a = (n) => new RegExp(`(?<![\\w-])${n}=["']([^"']*)["']`).exec(attrs)?.[1];
+            // `changelog` wins over `href`, as upstream's schema reads them.
+            const href = a("changelog") !== undefined ? `/changelog/rss/${a("changelog").toLowerCase().replaceAll(" ", "-")}.xml` : a("href");
+            if (!href)
+                return whole;
+            return `[${(a("text") ?? "Subscribe to RSS").replace(/[[\]\\]/g, "\\$&")}](<${href}>)`;
+        });
+        return text.replace(/^([ \t]*)<(WARPReleases|CompatibilityFlags)\b([^>]*?)\/>[ \t]*$/gm, (whole, indent, tag, attrs) => {
+            const md = tag === "WARPReleases"
+                ? warp(/\btrack=["']([^"']*)["']/.exec(attrs)?.[1] ?? "", indent)
+                : flags(/\bexperimental\b(?!\s*=\s*\{\s*false\s*\})/.test(attrs), indent);
+            return md === undefined ? whole : `\n${md}\n`;
+        });
+    }));
+}
+/**
+ * The value of `const NAME = [ … ]` / `{ … }` in a component or TS source,
+ * read with the no-eval literal reader. Brackets are matched OUTSIDE strings
+ * and comments (a `]` in a description must not end the array).
+ */
+export function readConstLiteral(src, name) {
+    const declRe = new RegExp(`const\\s+${name}\\b[^=]*=\\s*([[{])`, "g");
+    const decls = [...src.matchAll(declRe)];
+    // Two declarations (one commented out, say) is ambiguous: refuse rather
+    // than read a stale one.
+    if (decls.length !== 1)
+        return undefined;
+    const decl = decls[0];
+    const start = decl.index + decl[0].length - 1;
+    const open = decl[1];
+    const close = open === "[" ? "]" : "}";
+    let depth = 0;
+    let end = start;
+    let quote = null;
+    for (; end < src.length; end++) {
+        const ch = src[end];
+        if (quote) {
+            if (ch === "\\")
+                end++;
+            else if (ch === quote)
+                quote = null;
+        }
+        else if (src.startsWith("//", end))
+            end = src.indexOf("\n", end) < 0 ? src.length : src.indexOf("\n", end);
+        else if (src.startsWith("/*", end))
+            end = src.indexOf("*/", end) < 0 ? src.length : src.indexOf("*/", end) + 1;
+        else if (ch === '"' || ch === "'" || ch === "`")
+            quote = ch;
+        else if (ch === open)
+            depth++;
+        else if (ch === close && --depth === 0)
+            break;
+    }
+    // parseJsLiteral skips comments itself (prompts.ts has `// AI applications`).
+    return parseJsLiteral(src.slice(start, end + 1));
+}
+/**
+ * The agent-setup pages (8): `<AgentHeader slug>`, `<OtherAgents currentSlug>`,
+ * `<ExamplePromptsList />`, `<RandomPrompt />` and `<PlatformAccess />`, from
+ * `components/agent-setup/{agents,prompts,definitions}.ts` and the section's
+ * own markup, read — never run. Upstream picks prompts at RANDOM per build;
+ * an import picks deterministically (the first ones). The skills and MCP
+ * server lists inside `<PlatformAccess>` are fetched at build time upstream,
+ * so they become links to where those lists live (reported as degraded).
+ */
+export function resolveAgentSetup(source, partialsDir, onDegraded) {
+    if (!partialsDir || !/<(AgentHeader|OtherAgents|ExamplePromptsList|RandomPrompt|PlatformAccess)\b/.test(source))
+        return source;
+    const dir = join(dirname(dirname(partialsDir)), "components", "agent-setup");
+    const read = (f) => {
+        try {
+            return readFileSync(join(dir, f), "utf8");
+        }
+        catch {
+            return "";
+        }
+    };
+    const agentsRaw = readConstLiteral(read("agents.ts"), "AGENTS");
+    // Only well-formed entries: a missing field must not print "undefined".
+    const isStr = (v) => typeof v === "string";
+    const agents = (Array.isArray(agentsRaw) ? agentsRaw : []).filter((a) => a && isStr(a.name) && isStr(a.vendor) && isStr(a.slug) && isStr(a.description));
+    const promptsRaw = readConstLiteral(read("prompts.ts"), "SHARED_PROMPTS");
+    const prompts = Array.isArray(promptsRaw) && promptsRaw.every(isStr) ? promptsRaw : [];
+    // Upstream picks at random per build. Deterministically: five spread over
+    // the list (not five of one group), and a RandomPrompt that is not one of them.
+    const examples = [...new Set(Array.from({ length: Math.min(5, prompts.length) }, (_, i) => Math.floor((i * prompts.length) / Math.min(5, prompts.length))))].map((i) => prompts[i]);
+    const single = prompts.length ? (prompts.find((p) => !examples.includes(p)) ?? prompts[0]) : undefined;
+    const labelsRaw = readConstLiteral(read("definitions.ts"), "capabilityLabels");
+    const labels = labelsRaw && typeof labelsRaw === "object" ? labelsRaw : {};
+    const txt = (p) => ["```txt", p, "```"].join("\n");
+    const header = (slug) => {
+        const a = agents.find((x) => x.slug === slug);
+        if (!a)
+            return undefined;
+        const caps = Object.entries(a.capabilities ?? {}).filter(([, v]) => v).map(([k]) => labels[k] ?? k);
+        const l = Object.fromEntries(Object.entries(a.links ?? {}).filter(([, v]) => isStr(v)));
+        const links = [
+            l.skills && `[Cloudflare Skills](${l.skills})`,
+            l.mcp_server && `[Cloudflare Code Mode API MCP](${l.mcp_server})`,
+            l.mcp_server_domain && `[Cloudflare Domain Specific MCPs](${l.mcp_server_domain})`,
+            l.cli && `[CLI](${l.cli})`,
+            l.docs && `[${a.name} Docs](${l.docs})`,
+        ].filter(Boolean);
+        return [
+            "[← All agents](/agent-setup/)",
+            "",
+            `**${a.vendor}**`,
+            "",
+            a.description,
+            ...(caps.length ? ["", caps.join(" · ")] : []),
+            ...(links.length ? ["", links.join(" · ")] : []),
+        ].join("\n");
+    };
+    const others = (slug) => {
+        const rest = agents.filter((x) => x.slug !== slug);
+        if (!rest.length)
+            return undefined;
+        return rest
+            .map((a) => `<LinkCard ${jsxAttr("title", a.vendor && a.vendor !== a.name ? `${a.name} (${a.vendor})` : a.name)} ${jsxAttr("href", `/agent-setup/${a.slug}/`)} ${jsxAttr("description", a.description)} />`)
+            .join("\n\n");
+    };
+    // A component of this folder rendered for its props (prop conditionals,
+    // ternaries, and ./Local.astro sub-components, recursively) — read, never
+    // run. The section's markup gained `{showCliSelector && …}` and a
+    // `<PlatformCliDetails cli="wrangler" />` sub-component upstream; the
+    // literal-markup reader refused it (10 pages reported).
+    const KEEP_AS_TAGS = new Set(["PlatformAccessDetails", "SkillsList", "McpServerList"]);
+    const renderLocal = (file, attrs, depth = 0) => {
+        const src = read(file);
+        if (!src)
+            return undefined;
+        const fmEnd = src.startsWith("---") ? src.indexOf("\n---", 3) : -1;
+        const fm = fmEnd < 0 ? "" : src.slice(3, fmEnd);
+        const defaults = componentPropDefaults(fm);
+        if (!defaults)
+            return undefined;
+        // Same-folder `./X.astro` only: a nested path would resolve against this folder, not its own.
+        const imports = new Map([...fm.matchAll(/import\s+(\w+)\s+from\s+["']\.\/([^/"']+\.astro)["']/g)].map((m) => [m[1], m[2]]));
+        return renderComponentTemplate(src.slice(fmEnd < 0 ? 0 : fmEnd + 4), { ...defaults, ...attrs }, (tag, a) => {
+            if (tag === "CornerMarks")
+                return ""; // decorative
+            if (KEEP_AS_TAGS.has(tag))
+                return undefined;
+            const f = imports.get(tag);
+            return f && depth < 3 ? renderLocal(f, a, depth + 1) : undefined;
+        });
+    };
+    const platformAccess = () => {
+        const template = renderLocal("PlatformAccessSection.astro", {});
+        if (template === undefined)
+            return undefined;
+        const sectionRe = /<PlatformAccessDetails\s+header="([^"]*)"\s*>([\s\S]*?)<\/PlatformAccessDetails>/g;
+        const sections = [...template.matchAll(sectionRe)];
+        // Everything must be accounted for: a section with another attribute
+        // (`open`), or content between sections, would otherwise vanish.
+        if (!sections.length || (template.match(/<PlatformAccessDetails\b/g) ?? []).length !== sections.length)
+            return undefined;
+        const before = template.slice(0, sections[0].index);
+        const introP = /<p\b[^>]*>([\s\S]*?)<\/p>/.exec(before);
+        const leftover = template
+            .replace(sectionRe, "")
+            .replace(introP?.[0] ?? "\u0000", "")
+            .replace(/<\/?div\b[^>]*>|<CornerMarks\s*\/>/g, "")
+            .trim();
+        if (leftover)
+            return undefined;
+        const intro = introP?.[1].replace(/\s+/g, " ").trim();
+        const degradedHere = [];
+        const html = (body) => body
+            // The lead line is emphasised upstream (by class): keep it as bold.
+            .replace(/<p\s+class="[^"]*\bfont-medium\b[^"]*"\s*>([\s\S]*?)<\/p>/g, "<p><strong>$1</strong></p>")
+            .replace(/\s+class=("[^"]*"|\{[^}]*\})/g, "")
+            .replace(/\{" "\}/g, " ")
+            .replace(/<SkillsList\s*\/>/g, () => {
+            degradedHere.push("SkillsList");
+            return '<p>The skills are listed in <a href="https://github.com/cloudflare/skills">cloudflare/skills</a>.</p>';
+        })
+            .replace(/<McpServerList\b[^>]*\/>/g, () => {
+            degradedHere.push("McpServerList");
+            return '<p>The servers are listed in <a href="/agents/model-context-protocol/cloudflare/servers-for-cloudflare/">MCP servers for Cloudflare</a>.</p>';
+        })
+            .replace(/\s+/g, " ")
+            .replace(/\s*(<\/?(?:p|ul|li|aside|strong)\b[^>]*>)\s*/g, "$1")
+            .replace(/<(\w+) >/g, "<$1>")
+            .trim();
+        // Once per section: html() records the degraded lists, reported only on success.
+        const bodies = sections.map(([, title, body]) => [title, html(body)]);
+        const unreadable = /[{}`]|<[A-Z]|<pre\b/;
+        if (bodies.some(([, body]) => unreadable.test(body)) || (intro && unreadable.test(intro)))
+            return undefined;
+        for (const t of degradedHere)
+            onDegraded?.(t, "a link to where the list lives: it is fetched at build time upstream");
+        return [
+            ...(intro ? [intro, ""] : []),
+            ...bodies.flatMap(([title, body]) => [`<PlatformAccessDetails ${jsxAttr("header", title)}>`, "", body, "", "</PlatformAccessDetails>", ""]),
+        ]
+            .join("\n")
+            .trimEnd();
+    };
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/^([ \t]*)<(AgentHeader|OtherAgents|ExamplePromptsList|RandomPrompt|PlatformAccess)\b([^>]*?)\/>[ \t]*$/gm, (whole, indent, tag, attrs) => {
+        const attr = (n) => new RegExp(`\\b${n}=["']([^"']*)["']`).exec(attrs)?.[1];
+        const md = tag === "AgentHeader"
+            ? header(attr("slug") ?? "")
+            : tag === "OtherAgents"
+                ? others(attr("currentSlug") ?? "")
+                : tag === "ExamplePromptsList"
+                    ? examples.length
+                        ? examples.map(txt).join("\n\n")
+                        : undefined
+                    : tag === "RandomPrompt"
+                        ? single !== undefined
+                            ? txt(single)
+                            : undefined
+                        : // Attributes on the page (`showCliSelector`) would change what renders: refused, not ignored.
+                            attrs.trim()
+                                ? undefined
+                                : platformAccess();
+        return md === undefined ? whole : `\n${indented(md, indent)}\n`;
+    })));
+}
+/**
+ * `<BuildAgentsCallout />` → its intro sentence and its cards, read from the
+ * component's own source (`const cards = [ … ]`, by the no-eval literal
+ * reader; the sentence is its first `<p>`). A component that cannot be read
+ * leaves the tag, which is reported.
+ */
+export function resolveBuildAgentsCallout(source, partialsDir) {
+    if (!source.includes("<BuildAgentsCallout") || !partialsDir)
+        return source;
+    const file = join(dirname(dirname(partialsDir)), "components", "agent-setup", "BuildAgentsCallout.astro");
+    let md;
+    try {
+        const src = readFileSync(file, "utf8");
+        const cards = readConstLiteral(src, "cards");
+        // The template starts after the frontmatter's CLOSING fence.
+        const fmEnd = src.startsWith("---") ? src.indexOf("\n---", 3) : -1;
+        const intro = /<p\b[^>]*>([\s\S]*?)<\/p>/.exec(src.slice(fmEnd < 0 ? 0 : fmEnd + 4))?.[1].replace(/\s+/g, " ").trim();
+        if (Array.isArray(cards) && cards.length) {
+            md = [
+                ...(intro && !intro.includes("{") ? [intro, ""] : []),
+                ...cards.flatMap((c) => {
+                    const card = c;
+                    return [`<LinkCard ${jsxAttr("title", String(card.title ?? ""))} ${jsxAttr("href", String(card.href ?? ""))} ${jsxAttr("description", String(card.desc ?? ""))} />`, ""];
+                }),
+            ].join("\n").trimEnd();
+        }
+    }
+    catch {
+        md = undefined;
+    }
+    if (!md)
+        return source;
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/^([ \t]*)<BuildAgentsCallout\b[^>]*\/>/gm, (_w, indent) => `\n${indented(md, indent)}\n`)));
+}
+const changelogCache = new Map();
+/**
+ * `<Image src={x} alt="…" />` → `![alt](path)`, where `x` is an image the
+ * source IMPORTS (`import x from "~/assets/…png"`). A relative import is
+ * resolved against `file` and, under an `assets/` folder, rewritten to the `~/assets`
+ * alias (which becomes `/_assets` later). Unresolvable ones are left.
+ */
+export function resolveImageImports(source, file) {
+    if (!source.includes("<Image"))
+        return source;
+    const images = new Map();
+    for (const m of source.matchAll(/^import\s+(\w+)\s+from\s+["']([^"']+\.(?:png|jpe?g|gif|svg|webp|avif))["'];?\s*$/gm)) {
+        let path = m[2];
+        if (path.startsWith(".") && file) {
+            const abs = join(dirname(file), path);
+            const at = abs.lastIndexOf("/assets/");
+            path = at >= 0 ? `~/assets/${abs.slice(at + "/assets/".length)}` : path;
+        }
+        images.set(m[1], path);
+    }
+    if (!images.size)
+        return source;
+    return outsideFences(source, (text) => text.replace(/<Image\b([^>]*?)\/>/g, (whole, attrs) => {
+        const name = /\bsrc\s*=\s*\{\s*(\w+)\s*\}/.exec(attrs)?.[1];
+        const path = name ? images.get(name) : undefined;
+        return path ? `![${(attr(attrs, "alt") ?? "").replace(/[[\]]/g, "")}](${path})` : whole;
+    }));
+}
+/**
+ * An entry's MDX body for splicing into a page: image imports resolved, then
+ * its `import` statements removed OUTSIDE code (samples keep theirs: 154
+ * import lines in 67 entries' fences were deleted by a plain regex), and a
+ * fence it leaves open CLOSED — upstream compiles each entry alone, so an
+ * unclosed fence ends with it instead of swallowing the entries after it.
+ */
+function entryBody(content, file) {
+    const withImages = resolveImageImports(content, file);
+    const stripped = outsideFences(withImages, (text) => text.replace(/^import\s+(?:[\s\S]*?\s+from\s+)?["'][^"'\n]+["'];?[ \t]*$/gm, ""));
+    let fence = null;
+    for (const line of stripped.split("\n")) {
+        const m = /^[ \t]*(`{3,}|~{3,})/.exec(line);
+        if (!m)
+            continue;
+        if (fence) {
+            if (m[1][0] === fence[0] && m[1].length >= fence.length && line.trim() === m[1])
+                fence = null;
+        }
+        else if (!(m[1][0] === "`" && line.slice(line.indexOf(m[1]) + m[1].length).includes("`")))
+            fence = m[1];
+    }
+    return (fence ? `${stripped.trimEnd()}\n${fence}` : stripped).trim();
+}
+/** `src/content/changelog/<product>/*.mdx`; each entry also belongs to its folder's product, as upstream adds. */
+function loadChangelog(dir) {
+    const hit = changelogCache.get(dir);
+    if (hit)
+        return hit;
+    const out = [];
+    if (existsSync(dir)) {
+        for (const folder of readdirSync(dir).sort()) {
+            const sub = join(dir, folder);
+            let files;
+            try {
+                files = readdirSync(sub).filter((f) => f.endsWith(".mdx") || f.endsWith(".md"));
+            }
+            catch {
+                continue;
+            }
+            for (const file of files.sort()) {
+                try {
+                    const parsed = matter(readFileSync(join(sub, file), "utf8"));
+                    const fm = parsed.data;
+                    const d = fm.date instanceof Date ? fm.date : new Date(String(fm.date ?? ""));
+                    if (Number.isNaN(d.getTime()))
+                        continue;
+                    const products = (Array.isArray(fm.products) ? fm.products : []).map((p) => String(p));
+                    if (!products.includes(folder))
+                        products.push(folder);
+                    out.push({
+                        slug: file.replace(/\.mdx?$/, ""),
+                        title: String(fm.title ?? ""),
+                        date: d.toISOString().slice(0, 10),
+                        time: d.getTime(),
+                        products,
+                        hidden: fm.hidden === true,
+                        futureOk: fm.publish_future_dated_entry === true,
+                        body: entryBody(parsed.content, join(sub, file)),
+                    });
+                }
+                catch {
+                    /* unreadable entry: skipped */
+                }
+            }
+        }
+    }
+    changelogCache.set(dir, out);
+    return out;
+}
+/**
+ * `<ProductChangelog product="x" hideEntry publish_future_dated_entry numberOfEntries />`
+ * (or `area="Group"`, via the product directory's `entry.group`) → the
+ * product's changelog entries, newest first: `## date`, **title**, and the
+ * entry's MDX body spliced in, so its components are resolved like the
+ * page's own (this runs first in resolveIncludes). As upstream: hidden entries
+ * and future-dated ones are left out, `hideEntry` names one to skip. Not
+ * carried: the RSS button, per-entry product pills, WARP release entries.
+ */
+export function resolveProductChangelog(source, partialsDir) {
+    if (!source.includes("<ProductChangelog") || !partialsDir)
+        return source;
+    const content = dirname(partialsDir);
+    const entries = loadChangelog(join(content, "changelog"));
+    if (!entries.length)
+        return source;
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/^([ \t]*)<ProductChangelog\b([^>]*?)\/?>(?:\s*<\/ProductChangelog>)?/gm, (whole, indent, attrs) => {
+        const product = attr(attrs, "product");
+        const area = attr(attrs, "area");
+        const hide = attr(attrs, "hideEntry");
+        const future = /\bpublish_future_dated_entry\b(?!\s*=\s*\{\s*false\s*\})/.test(attrs);
+        const limit = Number(/\bnumberOfEntries\s*=\s*\{\s*(\d+)\s*\}/.exec(attrs)?.[1] ?? NaN);
+        let ids;
+        if (product)
+            ids = new Set([product]);
+        else if (area) {
+            ids = new Set();
+            const dir = join(content, "directory");
+            if (existsSync(dir)) {
+                for (const f of readdirSync(dir).filter((x) => /\.ya?ml$/.test(x))) {
+                    const d = cachedYaml(join(dir, f));
+                    const id = f.replace(/\.ya?ml$/, "");
+                    if (d?.entry?.group === area && id !== hide)
+                        ids.add(id);
+                }
+            }
+        }
+        if (!ids)
+            return whole;
+        const now = Date.now();
+        let list = entries.filter((e) => e.products.some((p) => ids.has(p)) &&
+            (area || (!e.hidden && e.slug !== hide && e.futureOk === future)) &&
+            (e.futureOk || e.time <= now));
+        list = list.sort((a, b) => b.time - a.time);
+        if (Number.isFinite(limit) && limit > 0)
+            list = list.slice(0, limit);
+        const out = list.length
+            ? list.flatMap((e) => [anchorHeading(e.date, 2), "", ...(e.title ? [`**${e.title}**`, ""] : []), e.body, ""])
+            : ["There are no scheduled entries at this time.", ""];
+        return `\n${indented(out.join("\n").trimEnd(), indent)}\n`;
+    })));
+}
+/**
+ * `<ProductReleaseNotes />` → the page's release notes (its front matter
+ * `release_notes_file_name`, from `release-notes/<name>.yaml`), newest date
+ * first, as ProductReleaseNotes.astro renders. An entry with its own page
+ * links to it: upstream EMBEDS that page's body, which would duplicate a page
+ * the site already has. `api-deprecations` is its own file, as upstream.
+ */
+export function resolveReleaseNotes(source, partialsDir, frontmatter) {
+    if (!source.includes("<ProductReleaseNotes"))
+        return source;
+    const names = frontmatter?.release_notes_file_name;
+    const name = Array.isArray(names) && names.length === 1 ? String(names[0]) : undefined;
+    if (!name || !partialsDir || /[\\/]|\.\./.test(name))
+        return source;
+    const data = cachedYaml(join(dirname(partialsDir), "release-notes", `${name}.yaml`));
+    const entries = data?.entries;
+    if (!Array.isArray(entries))
+        return source;
+    const byDate = new Map();
+    for (const e of entries) {
+        const d = String(e.publish_date ?? "");
+        if (!byDate.has(d))
+            byDate.set(d, []);
+        byDate.get(d).push(e);
+    }
+    const out = [];
+    for (const [date, list] of [...byDate.entries()].sort((a, b) => b[0].localeCompare(a[0]))) {
+        out.push(anchorHeading(date, 2), "");
+        for (const e of list) {
+            if (e.individual_page && e.link) {
+                out.push(`**[${e.title ?? e.link}](${e.link})**`, "");
+            }
+            else {
+                if (e.title)
+                    out.push(`**${e.title}**`, "");
+                if (e.description)
+                    out.push(String(e.description).trim(), "");
+            }
+        }
+    }
+    const md = out.join("\n").trimEnd();
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text.replace(/^([ \t]*)<ProductReleaseNotes\b[^>]*?\/>/gm, (_whole, indent) => indented(md, indent))));
+}
+const glossaryCache = new Map();
+/**
+ * `src/content/glossary/<product>.yaml` (a sibling of the partials folder):
+ * `{ productName, entries: [{ term, general_definition }] }`, keyed by the
+ * file's name, which is what `<Glossary product=…>` names.
+ */
+function loadGlossary(partialsDir) {
+    const dir = partialsDir ? join(dirname(partialsDir), "glossary") : "";
+    const hit = glossaryCache.get(dir);
+    if (hit)
+        return hit;
+    const out = new Map();
+    if (dir && existsSync(dir)) {
+        for (const file of readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)).sort()) {
+            try {
+                // gray-matter's YAML engine, rather than a new dependency.
+                // The files open with a YAML `---` document marker of their own; left
+                // in, the wrapper read as EMPTY front matter and every term was lost.
+                const data = readYaml(join(dir, file));
+                const product = String(data.productName ?? file.replace(/\.ya?ml$/, ""));
+                out.set(file.replace(/\.ya?ml$/, ""), (data.entries ?? [])
+                    .filter((e) => typeof e.term === "string" && typeof e.general_definition === "string")
+                    .map((e) => ({ term: e.term, definition: e.general_definition.trim(), product })));
+            }
+            catch {
+                /* an unreadable file contributes nothing; its terms stay unresolved and reported */
+            }
+        }
+    }
+    glossaryCache.set(dir, out);
+    return out;
+}
+/** As the component does: the prepend, then the definition, first letter upper-cased. */
+function glossaryText(entry, prepend) {
+    const text = (prepend ?? "") + entry.definition;
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+const attr = (attrs, name) => new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(attrs)?.slice(1).find((v) => v !== undefined);
+/**
+ * Cloudflare's glossary components, from the glossary data at import:
+ * - `<GlossaryDefinition term prepend>` → the definition itself;
+ * - `<Glossary product>` → a table of terms (a Product column when unfiltered);
+ * - `<GlossaryTooltip term link>text</…>` → the text, linked when `link` is a
+ *   string. The tooltip itself cannot travel to a static page.
+ * An unknown term leaves the tag as written, so it is REPORTED as unmapped
+ * rather than silently becoming nothing. Code is left alone.
+ */
+export function resolveGlossary(source, partialsDir) {
+    if (!/<Glossary/.test(source))
+        return source;
+    const glossary = loadGlossary(partialsDir);
+    const byTerm = new Map();
+    for (const entries of glossary.values())
+        for (const e of entries)
+            if (!byTerm.has(e.term))
+                byTerm.set(e.term, e);
+    return outsideFences(source, (block) => outsideInlineCode(block, (text) => text
+        // The line's own prefix — indent, and `> ` for a blockquote — repeats on
+        // every line of a multi-line definition, or it falls out of the quote.
+        .replace(/^([ \t]*(?:>[ \t]?)*)<GlossaryDefinition\b([^>]*?)\/>/gm, (whole, prefix, attrs) => {
+        const entry = byTerm.get(attr(attrs, "term") ?? "");
+        if (!entry)
+            return whole;
+        return prefix + glossaryText(entry, attr(attrs, "prepend")).replace(/\n/g, `\n${prefix}`);
+    })
+        .replace(/<GlossaryDefinition\b([^>]*?)\/>/g, (whole, attrs) => {
+        const entry = byTerm.get(attr(attrs, "term") ?? "");
+        return entry ? glossaryText(entry, attr(attrs, "prepend")).replace(/\s*\n\s*/g, " ") : whole;
+    })
+        .replace(/^([ \t]*)<Glossary\b([^>]*?)\/>/gm, (whole, indent, attrs) => {
+        const product = attr(attrs, "product");
+        const rows = product
+            ? (glossary.get(product) ?? []).map((e) => ({ ...e, product: "" }))
+            : [...glossary.values()].flat();
+        if (!rows.length)
+            return whole;
+        // A table cell is one line: paragraphs and list items keep apart with
+        // <br> (upstream renders real <p>/<ul> there; collapsing them to spaces
+        // ran "…in time. - Bookmarks are…" together).
+        const cell = tableCell;
+        rows.sort((a, b) => a.term.localeCompare(b.term));
+        const head = product ? ["| Term | Definition |", "| --- | --- |"] : ["| Term | Definition | Product |", "| --- | --- | --- |"];
+        const body = rows.map((e) => product ? `| ${cell(e.term)} | ${cell(glossaryText(e))} |` : `| ${cell(e.term)} | ${cell(glossaryText(e))} | ${cell(e.product)} |`);
+        return `\n${[...head, ...body].map((l) => indent + l).join("\n")}\n`;
+    })
+        // `</ GlossaryTooltip>` (a space after the slash) is valid JSX; 2 corpus uses.
+        // An opener with a `term=`, and a body holding no other opener: a bare
+        // tag name in prose is not the start of a tooltip.
+        .replace(/<GlossaryTooltip\b(?=[^>]*\bterm\s*=)([^>]*)>((?:(?!<GlossaryTooltip\b)[\s\S])*?)<\/\s*GlossaryTooltip\s*>/g, (whole, attrs, inner) => {
+        // An unknown term stays as written, so it is reported (upstream throws).
+        if (!byTerm.has(attr(attrs, "term") ?? ""))
+            return whole;
+        const link = attr(attrs, "link");
+        return link ? `[${inner}](${link})` : inner;
+    })));
+}
+// ── APIRequest ──────────────────────────────────────────
+/**
+ * `<APIRequest path method parameters json form />` → the curl command
+ * Cloudflare's component renders (APIRequest.astro + CURL.astro), built
+ * from the tag's own props. The component also fetches the OpenAPI schema
+ * over the network at build time, for two things we therefore do not
+ * produce: the "Required API token permissions" panel, and the block title
+ * (the operation summary). An import does not reach the network.
+ *
+ * Without the schema, a parameter is a PATH parameter when the path names it
+ * (`{zone_id}`) and a query parameter otherwise; unfilled path parameters
+ * become `$ZONE_ID`, as upstream writes them; auth is the API token (what
+ * nearly every operation takes). A tag whose props cannot be READ (a
+ * variable, a spread) is left as written and reported, never guessed.
+ *
+ * With the schema (`--api-schema <openapi.json>`, a local copy — the import
+ * still does not fetch): the operation summary titles the block, the auth
+ * headers follow the operation's security (email + key where it takes no
+ * token), and `roles` adds the "Required API token permissions" panel,
+ * filtered by a `roles="…"` string as upstream filters it.
+ */
+export function resolveApiRequest(source, onApiRequest, schema, onMissing) {
+    if (!source.includes("<APIRequest"))
+        return source;
+    return outsideFences(source, (text) => {
+        const tags = findSelfClosingTags(text, "APIRequest");
+        if (!tags.length)
+            return text;
+        let out = "";
+        let last = 0;
+        for (const tag of tags) {
+            const pathAttr = typeof tag.attrs.path === "string" && !tag.attrs.path.startsWith("{") ? tag.attrs.path : undefined;
+            const methodAttr = typeof tag.attrs.method === "string" && !tag.attrs.method.startsWith("{") ? tag.attrs.method : undefined;
+            const key = pathAttr && methodAttr ? `${methodAttr.toUpperCase()} /${pathAttr.replace(/^\//, "")}` : undefined;
+            const op = schema && key ? schema.get(key) : undefined;
+            if (schema && key && !op)
+                onMissing?.(key);
+            const curl = apiRequestCurl(tag.attrs, op);
+            const lineStart = text.lastIndexOf("\n", tag.start - 1) + 1;
+            const indent = text.slice(lineStart, tag.start);
+            const lineEnd = text.indexOf("\n", tag.end);
+            const rest = text.slice(tag.end, lineEnd < 0 ? text.length : lineEnd);
+            // Alone on its line: text after `/>` would sit on the closing fence,
+            // which then does not close, and the block swallows the page.
+            if (curl === undefined || !/^[ \t]*$/.test(indent) || !/^[ \t]*$/.test(rest)) {
+                onApiRequest?.(false);
+                continue;
+            }
+            onApiRequest?.(true);
+            // The fence info is read raw (`title="…"`, no unescaping): the
+            // characters that would break it are dropped, never escaped.
+            const title = op?.summary?.replace(/["`{}\\\n\r\t]/g, "").trim();
+            const fence = title ? `\`\`\`bash title="${title}"` : "```bash";
+            // Inside raw HTML (`<details><summary>API example</summary>` around the
+            // tag), a `<Details>` component is not parsed: it leaked as a tag. There
+            // the panel is raw HTML itself, on ONE line (indentation cannot break it).
+            const before = text.slice(0, tag.start).replace(/\s+$/, "");
+            const inHtml = /<\/?[a-z][\w-]*\b[^<>]*>$/.test(before.slice(before.lastIndexOf("\n") + 1).trim());
+            const panel = op ? permissionsPanel(op, tag.attrs.roles, inHtml) : undefined;
+            const block = [...(panel ? [...panel.split("\n"), ""] : []), fence, ...curl.split("\n"), "```"].map((l, k) => (k === 0 || !l ? l : indent + l)).join("\n");
+            out += text.slice(last, tag.start) + block;
+            last = tag.end;
+        }
+        return out + text.slice(last);
+    });
+}
+/**
+ * Upstream: `roles` defaults to TRUE — the panel shows unless `roles={false}`
+ * (or `""`); a string filters the groups. (It was read the other way round:
+ * 430 corpus tags lost their panel and 54 `roles={false}` tags gained one.)
+ */
+function permissionsPanel(op, roles, html = false) {
+    if (!op.tokenGroups?.length)
+        return undefined;
+    const r = typeof roles === "string" ? roles.trim() : roles;
+    if (r === "" || (typeof r === "string" && /^\{\s*(false|null|undefined|""|'')\s*\}$/.test(r)))
+        return undefined;
+    const filter = typeof r === "string" && !r.startsWith("{") ? r.toLowerCase() : undefined;
+    const groups = filter ? op.tokenGroups.filter((g) => g.toLowerCase().includes(filter)) : op.tokenGroups;
+    if (html) {
+        const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;");
+        return `<details><summary>Required API token permissions</summary><p>At least one of the following <a href="/fundamentals/api/reference/permissions/">token permissions</a> is required:</p><ul>${groups.map((g) => `<li><code>${esc(g)}</code></li>`).join("")}</ul></details>`;
+    }
+    return [
+        '<Details header="Required API token permissions">',
+        "",
+        "At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:",
+        "",
+        ...groups.map((g) => `- \`${g.replace(/`/g, "")}\``),
+        "",
+        "</Details>",
+    ].join("\n");
+}
+function apiRequestCurl(attrs, op) {
+    const read = (name) => {
+        const raw = attrs[name];
+        if (raw === undefined)
+            return undefined;
+        if (raw === true)
+            return true;
+        return raw.startsWith("{") ? parseJsLiteral(raw.slice(1, -1)) ?? REFUSED : raw;
+    };
+    const path = read("path");
+    const method = read("method");
+    const parameters = read("parameters");
+    const json = read("json");
+    const form = read("form");
+    if (typeof path !== "string" || typeof method !== "string")
+        return undefined;
+    if ([parameters, json, form].includes(REFUSED))
+        return undefined;
+    if (parameters !== undefined && (typeof parameters !== "object" || parameters === null || Array.isArray(parameters)))
+        return undefined;
+    let p = path.replace(/^\//, "");
+    const query = new URLSearchParams();
+    for (const [name, value] of Object.entries((parameters ?? {}))) {
+        if (!value)
+            continue; // upstream: `if (value)` — 0 and false are dropped too
+        if (p.includes(`{${name}}`))
+            p = p.replace(`{${name}}`, String(value));
+        else
+            for (const v of Array.isArray(value) ? value : [value])
+                query.append(name, String(v));
+    }
+    p = p.replace(/\{([^}]+)\}/g, (_m, n) => `$${n.toUpperCase()}`);
+    const qs = query.toString();
+    const lines = [`curl "https://api.cloudflare.com/client/v4/${p}${qs ? `?${qs}` : ""}"`, `\t--request ${method.toUpperCase()}`];
+    // Upstream reads the OPERATION's security: the token when it takes one,
+    // else email + key, else no auth header. Without the schema: the token.
+    if (!op || op.security?.includes("api_token"))
+        lines.push(`\t--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"`);
+    else if (op.security?.includes("api_key"))
+        lines.push(`\t--header "X-Auth-Email: $CLOUDFLARE_EMAIL"`, `\t--header "X-Auth-Key: $CLOUDFLARE_API_KEY"`);
+    if (json !== undefined && typeof json === "object" && json !== null) {
+        const jsonLines = JSON.stringify(json, null, "\t\t").split("\n");
+        jsonLines[jsonLines.length - 1] = "\t" + jsonLines[jsonLines.length - 1];
+        lines.push(`\t--json '${jsonLines.join("\n").replaceAll("'", "'\\''")}'`);
+    }
+    if (form !== undefined && typeof form === "object" && form !== null) {
+        for (const [key, value] of Object.entries(form))
+            lines.push(`\t--form "${key}=${String(value).replaceAll('"', '\\"')}"`);
+    }
+    return lines.join(" \\\n");
+}
+const REFUSED = Symbol("refused");
+/** RealtimeKit SDK ids → tab labels, in the order the selector lists them. */
+const RTK_SDKS = {
+    "web-react": "React",
+    "web-web-components": "Web Components",
+    "web-angular": "Angular",
+    "mobile-android": "Android",
+    "mobile-ios": "iOS",
+    "mobile-flutter": "Flutter",
+    "mobile-react-native": "React Native",
+    web: "Web",
+    mobile: "Mobile",
+};
+/**
+ * Each run of consecutive `rtk-snippet` siblings → one `tabs` group, synced
+ * on `realtimekit-sdk`, one tab per SDK. A snippet for several SDKs appears
+ * in each of their tabs, so picking an SDK in any group shows its code in
+ * every group. Recursive: snippets also sit in list items and steps.
+ */
+export function groupRtkSnippets(nodes) {
+    const out = [];
+    let run = [];
+    const flush = () => {
+        if (!run.length)
+            return;
+        const tabs = new Map();
+        for (const snippet of run) {
+            const ids = (snippet.props?.ids ?? []).filter(Boolean);
+            for (const id of ids.length ? ids : ["other"]) {
+                if (!tabs.has(id))
+                    tabs.set(id, []);
+                tabs.get(id).push(...structuredClone(snippet.children ?? []));
+            }
+        }
+        const order = Object.keys(RTK_SDKS);
+        const ids = [...tabs.keys()].sort((a, b) => (order.indexOf(a) + 1 || 99) - (order.indexOf(b) + 1 || 99));
+        out.push({
+            type: "tabs",
+            props: { syncKey: "realtimekit-sdk" },
+            children: ids.map((id) => ({ type: "tab", props: { title: RTK_SDKS[id] ?? id }, children: tabs.get(id) })),
+        });
+        run = [];
+    };
+    for (const node of nodes) {
+        if (node.type === "rtk-snippet") {
+            run.push({ ...node, children: groupRtkSnippets(node.children ?? []) });
+            continue;
+        }
+        flush();
+        out.push(node.children ? { ...node, children: groupRtkSnippets(node.children) } : node);
+    }
+    flush();
+    return out;
+}
 export const cloudflareAdapter = {
     name: "cloudflare",
+    transformTree: (tree) => linkButtonsInHtml(groupRtkSnippets(tree)),
     components: {
         // ── Mapped components ─────────────────────────────────
         Feature: {
@@ -323,19 +2080,56 @@ export const cloudflareAdapter = {
                 href: attrs.href,
             }),
         },
+        // Cloudflare's own alias: `export { default as LinkTitleCard } from
+        // "./components/cf/LinkCard.astro"` — the SAME component under a second
+        // name, used when the card wraps its description as children rather than
+        // passing it as an attribute. Unmapped, it leaked its opening tag onto the
+        // page as visible text (`<LinkTitleCard title="Get started" href=…`) and
+        // its body rendered as a code block. 300 uses across the corpus.
+        // `/realtime`'s guide cards: a grid of linked cards. The icon is a
+        // Phosphor name the Dogsbay icon set does not carry, and is dropped.
+        GuideCardGrid: { type: "cards", container: true },
+        GuideCard: {
+            type: "card",
+            container: false,
+            propsFromAttrs: (attrs) => ({ title: attrs.title || "", description: attrs.description, href: attrs.href }),
+        },
+        LinkTitleCard: {
+            type: "card",
+            container: true,
+            propsFromAttrs: (attrs) => ({
+                title: attrs.title || "",
+                href: attrs.href,
+                icon: attrs.icon,
+            }),
+        },
         RelatedProduct: {
             type: "card",
             container: true,
             propsFromAttrs: (attrs) => ({
                 title: attrs.header || "",
                 href: attrs.href,
-                icon: attrs.product ? `icons/${attrs.product}.svg` : undefined,
+                // `/_assets/icons/…` — the mount convention, so the file the importer
+                // copies is the file this reference names. It used to be a bare
+                // `icons/x.svg`, which existed in neither output: Astro's <Icon> takes
+                // a registry NAME and silently rendered nothing, and Obsidian built an
+                // <img> against a vault path with no file behind it, so every related
+                // product showed a broken image with its title stretched down the page.
+                icon: attrs.product ? `/_assets/icons/${attrs.product}.svg` : undefined,
             }),
         },
         Description: {
             type: "description",
             container: true,
         },
+        // A bordered box around a demonstration ("to showcase something without
+        // it being confused by the surrounding text"). The example callout is the
+        // same idea; with no title it is labelled "Example". 338 uses.
+        Example: {
+            type: "callout",
+            container: true,
+            propsFromAttrs: (attrs) => ({ variant: "example", ...(attrs.title ? { title: attrs.title } : {}) }),
+        },
         Details: {
             type: "details",
             container: true,
@@ -351,13 +2145,48 @@ export const cloudflareAdapter = {
             container: false,
             propsFromAttrs: (attrs) => ({ id: attrs.id || "" }),
         },
+        // RealtimeKit's per-SDK code: each <RTKCodeSnippet id="web-react"> is
+        // shown only while that SDK is picked in the page's <RTKSDKSelector>.
+        // Consecutive snippets become ONE tab group per run, synced page-wide on
+        // the SDK — the same switch, without the widget (transformTree below).
+        // 771 snippets on 33 pages leaked as raw tags.
+        RTKCodeSnippet: {
+            type: "rtk-snippet",
+            container: true,
+            propsFromAttrs: (attrs) => ({ ids: rtkIds(String(attrs.id ?? "")) }),
+        },
+        // The selector itself: the synced tab groups ARE the selector now.
+        RTKSDKSelector: { type: "", container: false, strip: true, silent: true },
+        // Starlight's <FileTree> styles a nested Markdown list of paths as a
+        // tree. The list IS the content, so the wrapper goes and the list stays
+        // (44 uses; they leaked as raw tags around it).
+        FileTree: { type: "", container: true, strip: true },
+        // Agent-setup pages: the lists wrap content written on the page, and each
+        // FAQ / troubleshooting item is an accordion with a title.
+        TipsList: { type: "", container: true, strip: true },
+        FAQList: { type: "", container: true, strip: true },
+        TroubleshootingList: { type: "", container: true, strip: true },
+        FAQItem: { type: "details", container: true, propsFromAttrs: (attrs) => ({ title: attrs.question || "" }) },
+        TroubleshootingItem: { type: "details", container: true, propsFromAttrs: (attrs) => ({ title: attrs.issue || "" }) },
+        // The sections of <PlatformAccess> (resolveAgentSetup).
+        PlatformAccessDetails: { type: "details", container: true, propsFromAttrs: (attrs) => ({ title: attrs.header || "" }) },
+        // A width constraint around content: the content is what matters.
+        Width: { type: "", container: true, strip: true },
+        // A flex-row layout wrapper (`<div class="flex …"><slot /></div>`): lossless.
+        Flex: { type: "", container: true, strip: true, silent: true },
+        // Known ids are replaced by their figure (inline transforms); any other is reported.
+        PublicStats: { type: "", container: false, strip: true },
         // ── Stripped components (data-driven, can't resolve) ──
+        // FeatureTable / ProductFeatures: resolvePlans, from plans/index.json. A
+        // tag left (unknown id) is stripped and reported.
         FeatureTable: { type: "", container: false, strip: true },
+        ProductFeatures: { type: "", container: false, strip: true },
         // PackageManagers resolved by resolveIncludes → Tabs with code blocks
         // WranglerConfig resolved by resolveIncludes → Tabs with JSONC + TOML
         WranglerCommand: { type: "", container: true, strip: true },
         TypeScriptExample: { type: "", container: true, strip: true },
-        APIRequest: { type: "", container: true, strip: true },
+        // APIRequest: resolveApiRequest → a curl block. NOT stripped: one whose
+        // props cannot be read is left as a tag, so it is reported as unmapped.
         AvailableNotifications: { type: "", container: false, strip: true },
         CompatibilityFlags: { type: "", container: false, strip: true },
         RSSButton: { type: "", container: false, strip: true },
@@ -365,21 +2194,78 @@ export const cloudflareAdapter = {
         // ── Workers/Pages-specific (strip) ───────────────────
         AutoconfigDiagram: { type: "", container: false, strip: true },
         GitHubCode: { type: "", container: false, strip: true },
-        ResourcesBySelector: { type: "", container: false, strip: true },
-        MetaInfo: { type: "", container: false, strip: true },
-        DirectoryListing: { type: "", container: false, strip: true },
+        // A query over the docs: pages whose `pcx_content_type` is one of
+        // `types`, under `directory`, for `products`. The component's filter UI
+        // and its video / learning-path sources do not travel; the docs pages do,
+        // as a `child-links` match (plans/child-links.md). 36 uses.
+        ResourcesBySelector: {
+            type: "child-links",
+            container: false,
+            propsFromAttrs: (attrs) => {
+                const list = (raw) => [...String(raw ?? "").matchAll(/"([^"]+)"|'([^']+)'/g)].map((m) => m[1] ?? m[2]);
+                const types = list(attrs.types);
+                const products = list(attrs.products);
+                const match = [types.length ? `pcx_content_type:${types.join(",")}` : "", products.length ? `products:${products.join(",")}` : ""]
+                    .filter(Boolean)
+                    .join(";");
+                return {
+                    folder: attrs.directory ? `/${attrs.directory.replace(/^\/+/, "")}` : "/",
+                    ...(match ? { match } : {}),
+                    ...(attrs.showDescriptions === "{false}" ? {} : { descriptions: true }),
+                    style: "cards",
+                };
+            },
+        },
+        // `<MetaInfo text="…">` becomes its text (inline transform); a form with
+        // no text renders nothing.
+        MetaInfo: { type: "", container: false, strip: true, silent: true },
+        // Lists the page's (or `folder`'s) child pages. It was STRIPPED — 594
+        // uses, and silently: a strip is not an unmapped component, so nothing
+        // reported it. Now a `child-links` node, resolved from the nav at build
+        // time (plans/child-links.md). `path=` is not a prop the component reads,
+        // so it lists the current page like the bare form; `tag=` has no use in
+        // the corpus and is carried, not applied.
+        DirectoryListing: {
+            type: "child-links",
+            container: false,
+            propsFromAttrs: (attrs) => {
+                const depth = Number(String(attrs.maxDepth ?? "").replace(/[{}]/g, ""));
+                return {
+                    ...(attrs.folder ? { folder: attrs.folder } : {}),
+                    ...(depth > 1 ? { depth } : {}),
+                    ...(attrs.descriptions === "true" ? { descriptions: true } : {}),
+                    ...(attrs.button === "true" ? { style: "cards" } : {}),
+                    ...(attrs.tag ? { tag: attrs.tag } : {}),
+                };
+            },
+        },
         ExternalResources: { type: "", container: false, strip: true },
         YouTubeVideos: { type: "", container: false, strip: true },
-        ListTutorials: { type: "", container: false, strip: true },
+        // Every tutorial in the page's top-level section (or `directory`).
+        // Upstream sorts by `reviewed` date and shows a table with difficulty;
+        // the list is by title. 17 uses.
+        ListTutorials: {
+            type: "child-links",
+            container: false,
+            propsFromAttrs: (attrs) => ({
+                ...(attrs.directory ? { folder: `/${attrs.directory.replace(/^\/+/, "")}` } : { scope: "section" }),
+                match: "pcx_content_type:tutorial",
+                descriptions: true,
+            }),
+        },
         WorkersTemplates: { type: "", container: false, strip: true },
         // ── Heading variant (map to heading) ─────────────────
         AnchorHeading: {
             type: "heading",
             container: true,
             propsFromAttrs: (attrs) => ({
-                level: parseInt(attrs.level || "2", 10),
+                // Upstream's prop is `depth` (every AnchorHeading came out as an H2),
+                // and its id is `GithubSlug(slug ?? title)`, not deduped with the page.
+                // `depth={3}` arrives with its braces.
+                level: Math.min(6, Math.max(1, parseInt(String(attrs.depth || attrs.level || "2").replace(/[{}\s"']/g, ""), 10) || 2)),
                 text: attrs.title || "",
-                slug: (attrs.title || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
+                slug: githubSlug(String(attrs.slug || attrs.title || "")),
+                [FIXED_SLUG]: true,
             }),
         },
     },
@@ -389,7 +2275,6 @@ export const cloudflareAdapter = {
         "Stream",
         "WranglerCommand",
         "TypeScriptExample",
-        "APIRequest",
         "AvailableNotifications",
         "RSSButton",
         "ProductReleaseNotes",
@@ -406,35 +2291,85 @@ export const cloudflareAdapter = {
     ],
     // Inline components — transformed in source text before block parsing
     inlineTransforms: [
-        // <GlossaryTooltip term="..." link="...">text</GlossaryTooltip> → [text](link) or just text
-        [
-            /<GlossaryTooltip\s+term="([^"]*)"(?:\s+link="([^"]*)")?[^>]*>([\s\S]*?)<\/GlossaryTooltip>/g,
-            "$3",
-        ],
-        // <Plan type="all" /> → **Available on all plans**
-        [/<Plan\s+type="all"\s*\/?>/g, "**Available on all plans**"],
-        [/<Plan\s+type="([^"]*)"\s*\/?>/g, "**$1 plan**"],
+        // <GlossaryTooltip>, <GlossaryDefinition>, <Glossary>: resolveGlossary.
+        // <Plan type|id>: resolvePlanBadges. These entries serve the legacy
+        // parser, which does not run resolveIncludes (known types only).
+        ...Object.entries(PLAN_TYPES).map(([type, label]) => [new RegExp(`<Plan\\s+type="${type}"\\s*\\/?>`, "g"), `**${label}**`]),
+        // <Type text="string" /> → `string`
+        //
+        // An inline type-annotation badge next to a parameter or method — the
+        // component renders it as a styled <code>, so inline code is the faithful
+        // mapping, not an approximation. 249 uses in the AI Search partials alone
+        // (`string` ×93, `boolean` ×38, `object` ×28), all inside API reference
+        // parameter lists where the type IS the content.
+        [/<Type\s+text\s*=\s*"([^"]*)"\s*\/>/g, "`$1`"],
+        // Single-quoted when the type itself holds double quotes (a union of
+        // string literals: `"asc" | "desc"`). 99 uses leaked as raw tags.
+        [/<Type\s+text\s*=\s*'([^']*)'\s*\/>/g, "`$1`"],
+        // <RuleID id="…" /> → `…`: a copy-to-clipboard pill of a WAF / DDoS rule
+        // id. The pill shows only the last 8 characters, but the value copied is
+        // the whole id, and the whole id is what a reader needs. 158 uses.
+        [/<RuleID\s+id\s*=\s*"([^"`]*)"\s*\/>/g, "`$1`"],
+        // <RTKPill>Beta</RTKPill>: RealtimeKit's status pill — a badge.
+        [/<RTKPill>([^<"]*)<\/RTKPill>/g, '<Badge text="$1" />'],
+        // <PublicStats id="…" />: three fixed figures, as the component has them.
+        [/<PublicStats\s+id\s*=\s*"data_center_cities"\s*\/>/g, "over 330 cities"],
+        [/<PublicStats\s+id\s*=\s*"total_bandwidth"\s*\/>/g, "over 405 Tbps network capacity"],
+        [/<PublicStats\s+id\s*=\s*"network_peers"\s*\/>/g, "over 13,000 network peers"],
+        // <MetaInfo text="optional" /> → optional
+        //
+        // The companion annotation: "optional", "default: 10", a units hint. It
+        // was being DELETED, which reads as though every parameter is required.
+        // The component is a muted inline span, so plain text is the mapping.
+        [/<MetaInfo\s+text="([^"]*)"\s*\/>/g, "$1"],
         // <InlineBadge ... /> → strip
         [/<InlineBadge\s[^>]*\/>/g, ""],
-        // Fallback strip for self-closing components that may appear deeply indented
-        // where the block rule can't reach (inside Steps > list items etc.)
-        // PackageManagers resolved by resolveIncludes (not stripped)
-        [/<AutoconfigDiagram[\s\S]*?\/>/g, ""],
-        [/<GitHubCode\s[^>]*\/>/g, ""],
-        [/<ResourcesBySelector[\s\S]*?\/>/g, ""],
-        [/<MetaInfo\s[^>]*\/>/g, ""],
-        [/<DirectoryListing[\s\S]*?\/>/g, ""],
-        [/<ExternalResources\s[^>]*\/>/g, ""],
-        [/<YouTubeVideos\s[^>]*\/>/g, ""],
+        // The regex strips that stood here (AutoconfigDiagram, GitHubCode,
+        // ResourcesBySelector, ExternalResources, YouTubeVideos) deleted the tag
+        // before anything could report it. Those now reach the component map,
+        // whose strips are reported. Only lossless forms stay.
+        [/<MetaInfo\s[^>]*\/>/g, ""], // fallback: forms with no `text` attribute
         [/<SUBCOMMAND\s[^>]*\/>/g, ""],
     ],
     // Resolve <Render> partials and <DashButton> links
-    resolveIncludes(source, partialsDir) {
-        let result = resolveRawImports(source, partialsDir);
+    resolveIncludes(source, partialsDir, options, frontmatter) {
+        // Changelog entries first: their bodies are MDX, and every resolver below
+        // (Render, glossary, tables, …) must see them as it sees the page.
+        let result = resolveProductChangelog(source, partialsDir);
+        // Upstream renders a GENERATED JavaScript tab beside every example's
+        // TypeScript (ts-blank-space + prettier at build); the import keeps the
+        // TypeScript only — a loss, so it is counted, not silent.
+        if (options?.onDegraded && result.includes("TypeScriptExample")) {
+            outsideFences(result, (t) => {
+                for (const _ of t.matchAll(/^[ \t]*<TypeScriptExample\b(?:\s[^>]*)?(?<!\/)>[ \t]*$/gm))
+                    options.onDegraded("TypeScriptExample", "the TypeScript only: upstream also shows a JavaScript tab generated from it at build time");
+                return t;
+            });
+        }
+        result = resolveOmitTabsTypeScript(result);
+        // Also first: compatibility-flag bodies are MDX (one holds a <Render>).
+        result = resolveLocalDataComponents(result, partialsDir);
+        result = resolveRawImports(result, partialsDir, options?.pageDir);
+        result = resolvePageConstants(result);
+        if (options?.mode === "template")
+            result = renderTagsToTemplates(result, partialsDir, options);
         result = resolveRenderTags(result, partialsDir);
         result = resolveDashButton(result, partialsDir);
         result = resolvePackageManagers(result);
         result = resolveWranglerConfig(result);
+        result = resolveGlossary(result, partialsDir);
+        result = resolvePlans(result, partialsDir);
+        result = resolvePlanBadges(result, partialsDir);
+        result = resolveNotifications(result, partialsDir);
+        result = resolvePagesPresets(result, partialsDir);
+        result = resolveReleaseNotes(result, partialsDir, frontmatter);
+        // `<Image src={x}>` whose `x` the page imports from `~/assets` (13 uses).
+        result = resolveImageImports(result);
+        result = resolveBuildAgentsCallout(result, partialsDir);
+        result = resolveAgentSetup(result, partialsDir, options?.onDegraded);
+        result = resolveDiagrams(result);
+        result = resolveGitHubCode(result, options?.onDegraded);
+        result = resolveApiRequest(result, options?.onApiRequest, options?.apiSchema, options?.onApiMissing);
         return result;
     },
     // Redirect pages use external_link in frontmatter