blume 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -29,7 +29,8 @@
     "src",
     "bin",
     "docs",
-    "skills"
+    "skills",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "types": "./dist/types/index.d.ts",
@@ -71,6 +72,7 @@
     "@astrojs/node": "^11.0.0",
     "@astrojs/react": "^6.0.0",
     "@astrojs/vercel": "^11.0.0",
+    "@clack/prompts": "^1.7.0",
     "@iconify-json/lucide": "^1.2.115",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.3",
@@ -92,7 +94,6 @@
     "babel-plugin-react-compiler": "^1.0.0",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
-    "deepmerge": "^4.3.1",
     "dompurify": "^3.4.11",
     "epub-gen-memory": "^1.1.2",
     "github-slugger": "^2.0.0",
@@ -106,11 +107,12 @@
     "pathe": "^2.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "satteri": "^0.9.5",
     "shiki": "^4.2.0",
     "simple-icons": "^13.0.0",
     "tailwindcss": "^4",
     "tinyglobby": "^0.2.10",
-    "typescript": "^5.7.0",
+    "typescript": "^6.0.3",
     "undici": "^8.6.0",
     "zod": "^3.24.0"
   },
@@ -124,6 +126,8 @@
   },
   "peerDependencies": {
     "@ai-sdk/openai-compatible": "^1.0.41",
+    "@astrojs/cloudflare": "^14.0.0",
+    "@astrojs/netlify": "^8.0.0",
     "@mixedbread/sdk": "^0.76.0",
     "@notionhq/client": "^2.2.15",
     "@openrouter/ai-sdk-provider": "^1.5.4",
@@ -137,6 +141,12 @@
     "@ai-sdk/openai-compatible": {
       "optional": true
     },
+    "@astrojs/cloudflare": {
+      "optional": true
+    },
+    "@astrojs/netlify": {
+      "optional": true
+    },
     "@mixedbread/sdk": {
       "optional": true
     },

package/skills/blume/SKILL.md

@@ -18,7 +18,7 @@ The core idea: **the framework _is_ the template.** There's no starter to clone
 
 ## Quickstart
 
-Blume needs **Node.js 22 or newer**. From an empty or existing project:
+Blume needs **Node.js 22.12 or newer**. From an empty or existing project:
 
 ```bash
 npm i blume      # install the package
@@ -41,7 +41,9 @@ description: Welcome to my docs.
 
 Welcome! Use **Markdown** and built-in components — no imports required:
 
-:::note Blume ships callouts, cards, tabs, steps, and more. :::
+:::note
+Blume ships callouts, cards, tabs, steps, and more.
+:::
 ```
 
 Navigation, search, and page metadata are inferred from your files as you add them.
@@ -50,7 +52,7 @@ Navigation, search, and page metadata are inferred from your files as you add th
 
 - **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with no imports.
 - **Local search** — Orama in dev and production; Pagefind is one flag away for large sites. No hosted index.
-- **AI** — `llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server.
+- **AI** — `llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an Ask AI assistant, and an MCP server endpoint served by the docs site itself.
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD.
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.

package/skills/blume-update-docs/SKILL.md

@@ -5,7 +5,7 @@ description: Keep a Blume docs site in sync with the product it documents. Audit
 
 # Update Blume Docs
 
-Blume is a **markdown-first** documentation framework on Astro/Vite: content lives as Markdown/MDX under a content root (default `docs/`), navigation derives from the file tree plus optional `meta.ts` files, and `blume build` validates links, anchors, frontmatter, and routes.
+Blume is a **markdown-first** documentation framework on Astro/Vite: content lives as Markdown/MDX under a content root (default `docs/`), navigation derives from the file tree plus optional `meta.ts` files, `blume build` validates frontmatter and duplicate routes, and `blume validate` checks links and anchors.
 
 Your job is **docs maintenance, not docs authorship**: find where shipped, user-facing behavior has drifted from what the docs claim, fix exactly that, prove the site still builds, and deliver the result as a pull request. A run that finds nothing actionable ends with a short report and **no branch, no commit, no PR** — prefer a no-op over a noisy PR.
 
@@ -39,7 +39,8 @@ Your job is **docs maintenance, not docs authorship**: find where shipped, user-
    - Match the surrounding pages: frontmatter shape, Blume components already in use, code-fence style, root-relative internal links.
 
 5. **Verify.**
-   - Run the docs build (`blume build` or the repo's documented docs QA) — it validates links, anchors, frontmatter, and duplicate routes.
+   - Run the docs build (`blume build` or the repo's documented docs QA) — it validates frontmatter and duplicate routes.
+   - Run `blume validate` to check internal links and anchors.
    - Run lint/format/typecheck when the repo's conventions call for them on docs changes.
    - Fix failures your edits caused; report pre-existing failures separately instead of fixing them in this PR.
 

package/src/ai/agent-readability.ts

@@ -32,7 +32,8 @@ const usagePolicy = (
  * agent-facing surface — llms.txt, the raw-Markdown mirrors, the MCP server,
  * Ask AI, sitemap, and feeds — so agents can discover and cite the docs without
  * scraping HTML. URLs are absolute when a `site` is configured and root-relative
- * otherwise. Returns null when the manifest is disabled.
+ * (still under `deployment.base`) otherwise. Returns null when the manifest is
+ * disabled.
  */
 export const buildAgentReadability = (
   project: BlumeProject
@@ -43,13 +44,13 @@ export const buildAgentReadability = (
   }
 
   const site = config.deployment.site ?? null;
-  // Every artifact is served under `deployment.base`; concatenate rather than
-  // `new URL()` so the subpath is preserved.
+  // Every artifact is served under `deployment.base` — with or without a
+  // `site`; concatenate rather than `new URL()` so the subpath is preserved.
   const deployBase = normalizeBasePath(config.deployment.base);
-  const abs = (path: string): string =>
-    site
-      ? `${site.replace(/\/+$/u, "")}${withBasePath(deployBase, path)}`
-      : path;
+  const abs = (path: string): string => {
+    const based = withBasePath(deployBase, path);
+    return site ? `${site.replace(/\/+$/u, "")}${based}` : based;
+  };
 
   const artifacts: Record<string, unknown> = {
     markdown: {
@@ -57,7 +58,7 @@ export const buildAgentReadability = (
       pattern: abs("/{route}.md"),
     },
   };
-  if (config.ai.llmsTxt) {
+  if (config.ai.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
   }

package/src/ai/ask-context.ts

@@ -124,8 +124,9 @@ const lastUserMessage = (messages: AskMessage[]): string => {
  * where "How does Ask AI work?" retrieves the right page but only sees its
  * opening paragraph. This centers the window on the densest cluster of query
  * terms so the injected text is the part that actually answers the question.
+ * Exported for testing; {@link createAskContext} is the runtime entry point.
  */
-const relevantExcerpt = (
+export const relevantExcerpt = (
   content: string,
   query: string,
   max: number
@@ -177,7 +178,11 @@ const relevantExcerpt = (
       best = start;
     }
   }
-  return withEllipsis(Math.max(0, best - EXCERPT_LEAD));
+  // Cap the lead-in at half the window: under a tight remaining budget `max`
+  // can be smaller than EXCERPT_LEAD, and an uncapped `best - EXCERPT_LEAD`
+  // start would end the slice before the very match it centered on.
+  const lead = Math.min(EXCERPT_LEAD, Math.floor(max / 2));
+  return withEllipsis(Math.max(0, best - lead));
 };
 
 /**

package/src/ai/ask-data.ts

@@ -9,9 +9,12 @@ import type { AskData } from "./ask-context.ts";
  * MCP snapshot) so retrieval can be filtered to the current page's language, and
  * content is kept as Markdown so grounding sees fenced code examples — the model
  * answers "what does the config look like?" from the docs instead of declining.
+ * The reader is an AI agent, so `<Visibility>` resolves for the agents audience
+ * (web-only content removed, agents-only unwrapped), matching llms-full.txt.
  */
 export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
   const documents = await buildSearchDocuments(project, {
+    audience: "agents",
     content: "markdown",
     includeWhenDisabled: true,
   });

package/src/ai/component-markdown.ts

@@ -0,0 +1,461 @@
+import { mdxToMdast } from "satteri";
+
+import { parseYouTubeId } from "../components/content/youtube.ts";
+
+/**
+ * Downlevel Blume's MDX components to plain Markdown for agent-facing output
+ * (the `/<route>.md` mirror, llms-full.txt, MCP `get_page`). Each supported
+ * component has a serializer — its "toString" — that renders the same
+ * information as the Astro component, but as portable Markdown: `<TypeTable>`
+ * becomes a GFM table, `<Callout>` a blockquote, `<Steps>` an ordered list,
+ * `<Tabs>` labeled sections, `<YouTube>` a link.
+ *
+ * The transform is a position splice, not a re-stringify: the MDX source is
+ * parsed to MDAST (via Satteri, which stamps byte offsets on every node) and
+ * only the matched component ranges are replaced, so all surrounding Markdown
+ * stays byte-identical to what the author wrote. Anything the serializers
+ * can't faithfully convert — an unknown component, a prop bound to an import —
+ * is left as JSX, and fenced code that merely *shows* component markup is
+ * naturally untouched because it parses as a `code` node.
+ */
+
+/** Minimal structural MDAST types — we model only what this module reads. */
+interface Offset {
+  offset: number;
+}
+
+interface MdastNode {
+  attributes?: MdxAttribute[];
+  children?: MdastNode[];
+  name?: string;
+  position?: { end: Offset; start: Offset };
+  type: string;
+}
+
+interface MdxAttribute {
+  name?: string;
+  type: string;
+  value?: string | { type: string; value: string } | null;
+}
+
+/** A single source replacement: `[start, end)` byte range → `text`. */
+interface Splice {
+  end: number;
+  start: number;
+  text: string;
+}
+
+/** Evaluated props plus whether any attribute resisted static evaluation. */
+interface EvaluatedProps {
+  lossy: boolean;
+  props: Record<string, unknown>;
+}
+
+/** A child component extracted by name (e.g. each `<Step>` under `<Steps>`). */
+export interface ComponentMarkdownChild extends EvaluatedProps {
+  /** The child's body, downleveled and dedented. */
+  children: string;
+}
+
+/** What a serializer receives for one component usage. */
+export interface ComponentMarkdownContext extends EvaluatedProps {
+  /** Direct child components of `name`, each with evaluated props and body. */
+  childComponents: (name: string) => ComponentMarkdownChild[];
+  /** The element's body, downleveled and dedented (empty if self-closing). */
+  children: string;
+}
+
+/**
+ * A component's Markdown serializer. Return the replacement Markdown, or
+ * `null` to leave the component's JSX in the output verbatim (the safe
+ * fallback when the props can't be recovered statically).
+ */
+export type ComponentMarkdown = (
+  context: ComponentMarkdownContext
+) => string | null;
+
+/**
+ * Statically evaluate an MDX attribute expression (`prop={...}`). Component
+ * data props are object/array/number literals in practice; evaluation runs at
+ * build time over the author's own content — the same trust level as the MDX
+ * itself, which Astro compiles and executes. Expressions that reference
+ * imports or scope throw and report as not evaluable.
+ */
+const evaluateExpression = (raw: string): { ok: boolean; value: unknown } => {
+  try {
+    // Build-time eval of the author's own attribute literals; a throw falls
+    // back to leaving the JSX verbatim.
+    // oxlint-disable-next-line no-new-func
+    const value = new Function(`"use strict"; return (${raw});`)();
+    return { ok: true, value };
+  } catch {
+    return { ok: false, value: undefined };
+  }
+};
+
+/** Evaluate an element's attributes into a plain props object. */
+const readProps = (node: MdastNode): EvaluatedProps => {
+  const props: Record<string, unknown> = {};
+  let lossy = false;
+  for (const attribute of node.attributes ?? []) {
+    // A spread ({...props}) can't be recovered statically.
+    if (attribute.type !== "mdxJsxAttribute" || !attribute.name) {
+      lossy = true;
+      continue;
+    }
+    if (attribute.value === null || attribute.value === undefined) {
+      // Boolean shorthand: `<Steps compact>`.
+      props[attribute.name] = true;
+    } else if (typeof attribute.value === "string") {
+      props[attribute.name] = attribute.value;
+    } else {
+      const result = evaluateExpression(attribute.value.value);
+      if (result.ok) {
+        props[attribute.name] = result.value;
+      } else {
+        lossy = true;
+      }
+    }
+  }
+  return { lossy, props };
+};
+
+const hasOffsets = (
+  node: MdastNode
+): node is MdastNode & { position: { end: Offset; start: Offset } } =>
+  typeof node.position?.start?.offset === "number" &&
+  typeof node.position?.end?.offset === "number";
+
+/** Apply non-overlapping splices to `text` (offsets relative to `text`). */
+const applySplices = (text: string, splices: Splice[]): string => {
+  let result = text;
+  for (const splice of [...splices].toSorted((a, b) => b.start - a.start)) {
+    // An element indented under a parent starts mid-line after whitespace;
+    // repeat that indent on the replacement's continuation lines so the block
+    // stays uniformly indented (and dedents cleanly with its siblings).
+    const lineStart = result.lastIndexOf("\n", splice.start - 1) + 1;
+    const prefix = result.slice(lineStart, splice.start);
+    const indent = /^[\t ]+$/u.test(prefix) ? prefix : "";
+    const replacement = indent
+      ? splice.text
+          .split("\n")
+          .map((line, index) =>
+            index === 0 || line === "" ? line : `${indent}${line}`
+          )
+          .join("\n")
+      : splice.text;
+    result =
+      result.slice(0, splice.start) + replacement + result.slice(splice.end);
+  }
+  return result;
+};
+
+/**
+ * Strip the common indentation JSX children carry in source (`<Step>` bodies
+ * are typically indented two spaces under their tag). The first line starts
+ * mid-line at the slice boundary, so the common prefix is measured on the
+ * following lines only.
+ */
+const dedent = (text: string): string => {
+  const lines = text.split("\n");
+  const rest = lines.slice(1).filter((line) => line.trim() !== "");
+  if (rest.length === 0) {
+    return text;
+  }
+  const indent = Math.min(
+    ...rest.map((line) => line.length - line.trimStart().length)
+  );
+  if (indent === 0) {
+    return text;
+  }
+  return [
+    lines[0],
+    ...lines
+      .slice(1)
+      .map((line) => (line.trim() === "" ? "" : line.slice(indent))),
+  ].join("\n");
+};
+
+const isJsxElement = (node: MdastNode): boolean =>
+  node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement";
+
+/** Flatten a value to a single Markdown table cell (pipes escaped). */
+const cellText = (value: unknown): string =>
+  String(value ?? "")
+    .replaceAll(/\s*\n\s*/gu, " ")
+    .replaceAll("|", "\\|")
+    .trim();
+
+/** A cell rendered as inline code, unless the value itself uses backticks. */
+const cellCode = (value: unknown): string => {
+  const text = cellText(value);
+  return text && !text.includes("`") ? `\`${text}\`` : text;
+};
+
+/** One `<TypeTable type={{...}}>` entry, matching the component's shape. */
+interface TypeEntry {
+  default?: unknown;
+  description?: unknown;
+  required?: unknown;
+  type?: unknown;
+  typeDescription?: unknown;
+  typeDescriptionLink?: unknown;
+}
+
+const typeTable: ComponentMarkdown = ({ children, props }) => {
+  const { type } = props;
+  if (type === null || typeof type !== "object") {
+    // The data prop is missing or wasn't statically evaluable.
+    return null;
+  }
+  const entries = Object.entries(type as Record<string, TypeEntry>);
+  const rows = entries.map(([name, info]) => {
+    const prop = cellCode(`${name}${info.required ? "" : "?"}`);
+    const typeCell = info.typeDescriptionLink
+      ? `[${cellCode(info.type)}](${cellText(info.typeDescriptionLink)})`
+      : cellCode(info.type);
+    const defaultCell =
+      info.default === undefined ? "-" : cellCode(info.default);
+    const description = cellText(
+      [info.description, info.typeDescription]
+        .filter((part) => typeof part === "string" && part !== "")
+        .join(" ")
+    );
+    return `| ${prop} | ${typeCell} | ${defaultCell} | ${description} |`;
+  });
+  const table =
+    rows.length > 0
+      ? [
+          "| Prop | Type | Default | Description |",
+          "| --- | --- | --- | --- |",
+          ...rows,
+        ].join("\n")
+      : "";
+  // The component renders its slot after the table.
+  return [table, children].filter(Boolean).join("\n\n");
+};
+
+const callout: ComponentMarkdown = ({ children, props }) => {
+  const type = typeof props.type === "string" ? props.type : "info";
+  const label =
+    typeof props.title === "string" && props.title !== ""
+      ? props.title
+      : type.charAt(0).toUpperCase() + type.slice(1);
+  if (!children) {
+    return `> **${label}**`;
+  }
+  const body = children
+    .split("\n")
+    .map((line) => (line.trim() === "" ? ">" : `> ${line}`))
+    .join("\n");
+  return `> **${label}**\n>\n${body}`;
+};
+
+/** Format `content` as one ordered-list item, continuation lines indented. */
+const listItem = (index: number, content: string): string => {
+  const marker = `${index}. `;
+  return content
+    .split("\n")
+    .map((line, lineIndex) => {
+      if (lineIndex === 0) {
+        return `${marker}${line}`;
+      }
+      return line === "" ? "" : `    ${line}`;
+    })
+    .join("\n");
+};
+
+const steps: ComponentMarkdown = ({ childComponents, children }) => {
+  const items = childComponents("Step");
+  if (items.length === 0) {
+    return children;
+  }
+  return items
+    .map((step, index) => {
+      const title =
+        typeof step.props.title === "string" && step.props.title !== ""
+          ? `**${step.props.title}**`
+          : "";
+      const content = [title, step.children].filter(Boolean).join("\n\n");
+      return listItem(index + 1, content);
+    })
+    .join("\n\n");
+};
+
+const tabs: ComponentMarkdown = ({ childComponents, children }) => {
+  const items = childComponents("Tab");
+  if (items.length === 0) {
+    return children;
+  }
+  return items
+    .map((tab, index) => {
+      const title =
+        typeof tab.props.title === "string" && tab.props.title !== ""
+          ? tab.props.title
+          : `Tab ${index + 1}`;
+      return tab.children ? `**${title}**\n\n${tab.children}` : `**${title}**`;
+    })
+    .join("\n\n");
+};
+
+const youtube: ComponentMarkdown = ({ props }) => {
+  let input = "";
+  if (typeof props.id === "string") {
+    input = props.id;
+  } else if (typeof props.url === "string") {
+    input = props.url;
+  }
+  const videoId = parseYouTubeId(input);
+  if (!videoId) {
+    return null;
+  }
+  const start =
+    typeof props.start === "number" && props.start > 0
+      ? `&t=${Math.floor(props.start)}s`
+      : "";
+  const title =
+    typeof props.title === "string" && props.title !== ""
+      ? props.title
+      : "Watch on YouTube";
+  return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
+};
+
+/**
+ * The built-in serializer registry, keyed by JSX name. `Step` and `Tab` are
+ * intentionally absent: they only carry meaning inside their containers,
+ * which extract them via `childComponents`; a stray one stays verbatim.
+ */
+const SERIALIZERS: Record<string, ComponentMarkdown> = {
+  Callout: callout,
+  Steps: steps,
+  Tabs: tabs,
+  TypeTable: typeTable,
+  YouTube: youtube,
+};
+
+const escapeRegExp = (value: string): string =>
+  value.replaceAll(/[$()*+.?[\\\]^{|}]/gu, String.raw`\$&`);
+
+// Skip the MDX parse when no serializable component name appears at all —
+// the common case for prose pages, and it keeps plain-Markdown sources (where
+// `<`/`{` may be literal text MDX would reject) out of the parser entirely.
+const componentHint = (registry: Record<string, ComponentMarkdown>): RegExp =>
+  new RegExp(
+    `<(?:${Object.keys(registry).map(escapeRegExp).join("|")})[\\s/>]`,
+    "u"
+  );
+
+const BUILT_IN_HINT = componentHint(SERIALIZERS);
+
+/** One downlevel pass's inputs: the full source and the active registry. */
+interface Walk {
+  registry: Record<string, ComponentMarkdown>;
+  source: string;
+}
+
+/**
+ * The element's body as Markdown: the verbatim source slice covering its
+ * children, with any serializable descendant components downleveled in place.
+ * Mutually recursive with {@link collectSplices} (a container's children may
+ * hold further serializable components), hence the forward reference.
+ */
+const renderChildren = (walk: Walk, node: MdastNode): string => {
+  const children = (node.children ?? []).filter(hasOffsets);
+  const [first] = children;
+  if (!first) {
+    return "";
+  }
+  const start = first.position.start.offset;
+  const end = children.at(-1)?.position.end.offset ?? start;
+  const splices: Splice[] = [];
+  // oxlint-disable-next-line no-use-before-define
+  collectSplices(walk, children, splices);
+  const spliced = applySplices(
+    walk.source.slice(start, end),
+    splices.map((splice) => ({
+      ...splice,
+      end: splice.end - start,
+      start: splice.start - start,
+    }))
+  );
+  return dedent(spliced).trim();
+};
+
+/** Serialize one component usage, or `null` to keep its JSX verbatim. */
+const serializeElement = (
+  serializer: ComponentMarkdown,
+  walk: Walk,
+  node: MdastNode
+): string | null =>
+  serializer({
+    ...readProps(node),
+    childComponents: (name) =>
+      (node.children ?? [])
+        .filter((child) => isJsxElement(child) && child.name === name)
+        .map((child) => ({
+          ...readProps(child),
+          children: renderChildren(walk, child),
+        })),
+    children: renderChildren(walk, node),
+  });
+
+/**
+ * Walk the tree collecting replacements. A replaced element's subtree is
+ * owned by its serializer (which downlevels its own children), so the walk
+ * doesn't descend into it; when a serializer declines, the walk continues
+ * inside so nested serializable components still convert.
+ */
+const collectSplices = (
+  walk: Walk,
+  nodes: MdastNode[],
+  out: Splice[]
+): void => {
+  for (const node of nodes) {
+    const serializer =
+      node.type === "mdxJsxFlowElement" && node.name
+        ? walk.registry[node.name]
+        : undefined;
+    if (serializer && hasOffsets(node)) {
+      const text = serializeElement(serializer, walk, node);
+      if (text !== null) {
+        out.push({
+          end: node.position.end.offset,
+          start: node.position.start.offset,
+          text,
+        });
+        continue;
+      }
+    }
+    collectSplices(walk, node.children ?? [], out);
+  }
+};
+
+/**
+ * Downlevel supported components in an MDX source to plain Markdown. Sources
+ * with no supported components — and sources Satteri can't parse as MDX, e.g.
+ * plain `.md` with literal `<`/`{` — are returned byte-identical.
+ *
+ * `components` adds user serializers from `ai.markdownComponents`, layered
+ * over the built-ins: a same-name entry replaces the built-in serializer, and
+ * one that always returns `null` effectively opts that component out.
+ */
+export const downlevelComponents = (
+  source: string,
+  components?: Record<string, ComponentMarkdown>
+): string => {
+  const custom = components && Object.keys(components).length > 0;
+  const registry = custom ? { ...SERIALIZERS, ...components } : SERIALIZERS;
+  const hint = custom ? componentHint(registry) : BUILT_IN_HINT;
+  if (!hint.test(source)) {
+    return source;
+  }
+  let tree: MdastNode;
+  try {
+    tree = mdxToMdast(source) as MdastNode;
+  } catch {
+    return source;
+  }
+  const splices: Splice[] = [];
+  collectSplices({ registry, source }, tree.children ?? [], splices);
+  return splices.length > 0 ? applySplices(source, splices) : source;
+};