blume 2.0.1 → 2.0.3

package/src/components/content/Expandable.astro

@@ -1,7 +1,11 @@
 ---
+import data from "blume:data";
+
 import AccordionItem from "./AccordionItem.astro";
+import { contentStrings } from "./content-strings.ts";
 
-const { defaultOpen = false, title = "Show more" } = Astro.props;
+const { content: strings } = contentStrings(data, Astro.currentLocale);
+const { defaultOpen = false, title = strings.showMore } = Astro.props;
 ---
 
 <div class="not-prose my-4 overflow-hidden rounded-blume border border-border">

package/src/components/content/Frame.astro

@@ -1,7 +1,5 @@
 ---
-import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
-
-import { escapeRawHtml, unwrapParagraph } from "./inline-markdown.ts";
+import { renderInlineMarkdown } from "./inline-markdown.ts";
 
 interface Props {
   caption?: string;
@@ -10,10 +8,7 @@ interface Props {
 
 const { caption, hint } = Astro.props;
 
-const markdownProcessor = await createSatteriMarkdownProcessor();
-const captionHtml = caption
-  ? unwrapParagraph((await markdownProcessor.render(escapeRawHtml(caption))).code)
-  : undefined;
+const captionHtml = caption ? await renderInlineMarkdown(caption) : undefined;
 ---
 
 <blume-frame class="not-prose my-6 block">

package/src/components/content/GithubInfo.astro

@@ -9,6 +9,7 @@ import { NEW_TAB_ATTRS } from "../../core/new-tab.ts";
 import { resolveIcon } from "../../theme/icons.ts";
 import data from "blume:data";
 import { GITHUB_MARK } from "../github-mark.ts";
+import { contentStrings } from "./content-strings.ts";
 import { fetchRepositoryInfo } from "./github-info.ts";
 
 // Star/fork glyphs resolve from Lucide at build time; the `<svg>` wrappers below
@@ -63,6 +64,9 @@ const numbers = new Intl.NumberFormat("en", {
 
 const statIcon =
   "size-3.5 shrink-0 text-muted-foreground"; /* shared classes for stat icons */
+// The glyphs are decorative, so each count carries a text label for screen
+// readers ("Stars: 1.2K"), in the page's language.
+const { content: strings } = contentStrings(data, Astro.currentLocale);
 ---
 
 {
@@ -108,7 +112,10 @@ const statIcon =
               width="14"
               set:html={starIcon}
             />
-            <span>{numbers.format(info.stars)}</span>
+            <span>
+              <span class="sr-only">{strings.stars}: </span>
+              {numbers.format(info.stars)}
+            </span>
           </span>
           <span class="flex items-center gap-1.5">
             <svg
@@ -124,7 +131,10 @@ const statIcon =
               width="14"
               set:html={forkIcon}
             />
-            <span>{numbers.format(info.forks)}</span>
+            <span>
+              <span class="sr-only">{strings.forks}: </span>
+              {numbers.format(info.forks)}
+            </span>
           </span>
         </span>
       )}

package/src/components/content/Prompt.astro

@@ -1,9 +1,8 @@
 ---
-import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
 import data from "blume:data";
 
 import { contentStrings } from "./content-strings.ts";
-import { escapeRawHtml, unwrapParagraph } from "./inline-markdown.ts";
+import { renderInlineMarkdown } from "./inline-markdown.ts";
 import { promptMarkdown } from "./prompt-markdown.ts";
 
 interface Props {
@@ -24,11 +23,7 @@ const normalizeActions = (value: Props["actions"]): string[] => {
 };
 
 const enabledActions = new Set(normalizeActions(actions));
-const markdownProcessor = await createSatteriMarkdownProcessor();
-const renderedDescription = await markdownProcessor.render(
-  escapeRawHtml(description)
-);
-const descriptionHtml = unwrapParagraph(renderedDescription.code);
+const descriptionHtml = await renderInlineMarkdown(description);
 // The prompt as Markdown, for the copy button and the Cursor link: the rendered
 // body's text alone would drop its links, list markers, and code fences.
 const promptSource = Astro.slots.has("default")

package/src/components/content/Tab.astro

@@ -44,7 +44,6 @@ const tabId = id ?? componentSlug(title);
   data-tab-id={tabId}
   data-title={title}
   id={id}
-  role="tabpanel"
 >
   <slot />
   {

package/src/components/content/Tabs.astro

@@ -1,4 +1,8 @@
 ---
+import data from "blume:data";
+
+import { contentStrings } from "./content-strings.ts";
+
 interface Props {
   borderBottom?: boolean;
   defaultTabIndex?: number;
@@ -45,6 +49,8 @@ const hashEnabled = String(hash) !== "false";
 // The dropdown (select) affordance belongs to the boxed layout; inline always
 // renders a tab strip.
 const useDropdown = dropdown && !inline;
+// The labels the client script builds the strip with, in the page's locale.
+const { content: strings } = contentStrings(data, Astro.currentLocale);
 ---
 
 <blume-tabs
@@ -58,6 +64,8 @@ const useDropdown = dropdown && !inline;
   data-default-tab-index={defaultTabIndex}
   data-dropdown={useDropdown ? "true" : "false"}
   data-hash={hashEnabled ? "true" : "false"}
+  data-i18n-select-tab={strings.selectTab}
+  data-i18n-tab={strings.tab}
   data-param={param}
   data-sync={sync ? "true" : "false"}
   data-sync-key={syncKey}
@@ -112,8 +120,12 @@ const useDropdown = dropdown && !inline;
   // in several <Tabs> instances on one page.
   let instanceCount = 0;
 
+  // An untitled panel is numbered with its group's localized `Tab {n}`.
   const panelTitle = (panel: HTMLElement, index: number) =>
-    panel.dataset.title ?? `Tab ${index + 1}`;
+    panel.dataset.title ??
+    (
+      panel.closest<HTMLElement>("blume-tabs")?.dataset.i18nTab ?? "Tab {n}"
+    ).replace("{n}", String(index + 1));
   const panelId = (panel: HTMLElement) => panel.dataset.tabId ?? panel.id;
   const boundedIndex = (value: number, length: number) =>
     Math.min(Math.max(value, 0), Math.max(length - 1, 0));
@@ -149,6 +161,8 @@ const useDropdown = dropdown && !inline;
       // CodeGroup passes raw code fences instead of <Tab> elements, so adopt
       // the content wrapper's direct code blocks as panels. The tab label comes
       // from each block's title (the text after the language in the fence).
+      // A ts2js fence arrives as its own TypeScript/JavaScript group; it is
+      // one panel too, labeled by the fence title both of its blocks carry.
       if (panels.length === 0) {
         const wrapper = this.querySelector<HTMLElement>(
           ":scope > [data-blume-tab-content]"
@@ -156,11 +170,19 @@ const useDropdown = dropdown && !inline;
         const blocks = wrapper
           ? Array.from(wrapper.children).filter(
               (child): child is HTMLElement =>
-                child instanceof HTMLElement && child.matches("pre, figure")
+                child instanceof HTMLElement &&
+                child.matches("pre, figure, blume-tabs")
             )
           : [];
         for (const block of blocks) {
           block.setAttribute("data-blume-tab-panel", "");
+          const fenceTitle = block.matches("blume-tabs")
+            ? block.querySelector<HTMLElement>("pre[data-title]")?.dataset
+                .title
+            : undefined;
+          if (fenceTitle && !block.dataset.title) {
+            block.dataset.title = fenceTitle;
+          }
         }
         panels = blocks;
       }
@@ -184,7 +206,10 @@ const useDropdown = dropdown && !inline;
         this.#select = document.createElement("select");
         this.#select.className = SELECT_CLASS;
         // Neutral default: tab sets aren't necessarily code examples.
-        this.#select.setAttribute("aria-label", "Select tab");
+        this.#select.setAttribute(
+          "aria-label",
+          this.dataset.i18nSelectTab ?? "Select tab"
+        );
         panels.forEach((panel, index) => {
           const option = document.createElement("option");
           option.value = String(index);
@@ -212,6 +237,10 @@ const useDropdown = dropdown && !inline;
           }
           trigger.id = `blume-tab-${slug}-${instance}`;
           trigger.setAttribute("aria-controls", panel.id);
+          // The role rides with the labelling tab: adopted panels (CodeGroup
+          // fences, ts2js pairs, nested groups) have none of their own, and
+          // dropdown mode renders no tabs, so its panels take no role.
+          panel.setAttribute("role", "tabpanel");
           panel.setAttribute("aria-labelledby", trigger.id);
           trigger.setAttribute(
             "aria-selected",
@@ -298,6 +327,14 @@ const useDropdown = dropdown && !inline;
       }
     }
 
+    /**
+     * Re-pick the tab from the current URL, as on first load. Neither syncs
+     * other groups nor writes history, exactly like the initial selection.
+     */
+    selectFromUrl() {
+      this.activate(this.#initialIndex(), false, false);
+    }
+
     #activateByHash() {
       if (!this.#hashEnabled()) {
         return false;
@@ -348,10 +385,12 @@ const useDropdown = dropdown && !inline;
 
     #onTriggerKeydown(event: KeyboardEvent, index: number) {
       const lastIndex = this.#triggers.length - 1;
+      // The strip runs right to left under dir="rtl", so the arrows swap.
+      const rtl = getComputedStyle(this).direction === "rtl";
       let nextIndex: number | undefined;
-      if (event.key === "ArrowRight") {
+      if (event.key === (rtl ? "ArrowLeft" : "ArrowRight")) {
         nextIndex = index === lastIndex ? 0 : index + 1;
-      } else if (event.key === "ArrowLeft") {
+      } else if (event.key === (rtl ? "ArrowRight" : "ArrowLeft")) {
         nextIndex = index === 0 ? lastIndex : index - 1;
       } else if (event.key === "Home") {
         nextIndex = 0;
@@ -414,5 +453,19 @@ const useDropdown = dropdown && !inline;
 
   if (!customElements.get("blume-tabs")) {
     customElements.define("blume-tabs", BlumeTabs);
+
+    // The client router inserts the next page (connecting its tabs, which
+    // read the URL then) before it moves history to that page's URL, so
+    // those tabs saw the previous page's hash and query. `astro:after-swap`
+    // fires once the URL is the new page's and before the reader can
+    // interact, so selecting again here honors `?install=windows` and
+    // `#windows` deep links as a full load does.
+    document.addEventListener("astro:after-swap", () => {
+      for (const tabs of document.querySelectorAll("blume-tabs")) {
+        if (tabs instanceof BlumeTabs) {
+          tabs.selectFromUrl();
+        }
+      }
+    });
   }
 </script>

package/src/components/content/Tile.astro

@@ -28,7 +28,7 @@ const previewPattern =
         <p class="m-0! flex items-center gap-1.5 font-semibold">
           {title}
           {href && (
-            <Icon class="text-muted-foreground" name="arrow-right" size={14} />
+            <Icon class="text-muted-foreground rtl:-scale-x-100" name="arrow-right" size={14} />
           )}
         </p>
       )

package/src/components/content/Tooltip.astro

@@ -38,7 +38,7 @@ const tooltipId = tooltipIdFor(Astro.locals, [
     set:html={labelHtml}
   />
   <span
-    class="absolute bottom-full left-1/2 z-20 mb-2 w-max max-w-xs -translate-x-1/2 rounded-blume border border-border bg-background p-3 text-start font-sans text-foreground text-sm shadow-lg"
+    class="absolute bottom-full left-1/2 z-20 mb-2 w-max max-w-[min(20rem,calc(100vw-1rem))] -translate-x-1/2 rounded-blume border border-border bg-background p-3 text-start font-sans text-foreground text-sm shadow-lg"
     data-blume-tooltip-panel
     id={tooltipId}
     role="tooltip"
@@ -60,23 +60,33 @@ const tooltipId = tooltipIdFor(Astro.locals, [
 </span>
 
 <style>
+  /* Out of layout while hidden, not just invisible: a hidden panel past the
+     inline end of a line would otherwise still widen the page. */
   [data-blume-tooltip-panel] {
-    pointer-events: none;
-    visibility: hidden;
+    display: none;
   }
 
   /* Focus anywhere inside keeps it open, so a keyboard reader can Tab from
      the trigger to the call-to-action link without the panel vanishing. */
   [data-blume-tooltip]:hover [data-blume-tooltip-panel],
   [data-blume-tooltip]:focus-within [data-blume-tooltip-panel] {
-    pointer-events: auto;
-    visibility: visible;
+    display: block;
+  }
+
+  /* Bridge the gap down to the trigger, so the pointer keeps the tooltip
+     hovered on its way to the panel's link (WCAG 1.4.13). The extra pixel is
+     the bottom border, which top: 100% starts inside. */
+  [data-blume-tooltip-panel]::after {
+    content: "";
+    height: calc(0.5rem + 1px);
+    inset-inline: 0;
+    position: absolute;
+    top: 100%;
   }
 
   /* Escape hides it until the pointer or focus leaves (WCAG 1.4.13). */
   [data-blume-tooltip][data-dismissed] [data-blume-tooltip-panel] {
-    pointer-events: none;
-    visibility: hidden;
+    display: none;
   }
 </style>
 
@@ -110,4 +120,56 @@ const tooltipId = tooltipIdFor(Astro.locals, [
   };
   document.addEventListener("focusout", rearm);
   document.addEventListener("pointerout", rearm);
+
+  // The panel centers over its trigger, so near either edge of the viewport
+  // it would run off-screen. As it shows, shift it in by the overhang.
+  const VIEWPORT_MARGIN = 8;
+  const place = (tooltip: Element) => {
+    const panel = tooltip.querySelector<HTMLElement>(
+      "[data-blume-tooltip-panel]"
+    );
+    if (!panel) {
+      return true;
+    }
+    // Measure it parked off the side the page can't scroll toward: a panel
+    // laid out past the viewport's end even for a moment leaves WebKit's page
+    // scroll width stuck wide.
+    const rtl = getComputedStyle(document.documentElement).direction === "rtl";
+    panel.style.marginLeft = rtl ? "100vw" : "-100vw";
+    const { width } = panel.getBoundingClientRect();
+    // Zero width: not showing (yet, or any more).
+    if (width === 0) {
+      return false;
+    }
+    const anchor = tooltip.getBoundingClientRect();
+    const left = anchor.left + anchor.width / 2 - width / 2;
+    const end = document.documentElement.clientWidth - VIEWPORT_MARGIN;
+    let shift = 0;
+    if (left < VIEWPORT_MARGIN) {
+      shift = VIEWPORT_MARGIN - left;
+    } else if (left + width > end) {
+      shift = end - left - width;
+    }
+    panel.style.marginLeft = `${shift}px`;
+    return true;
+  };
+
+  // Hover and focus styles already apply when these events fire; should the
+  // panel not show yet, place it in the next frame, before it paints.
+  const show = (event: FocusEvent | PointerEvent) => {
+    const tooltip =
+      event.target instanceof Element ? event.target.closest(TOOLTIP) : null;
+    const { relatedTarget } = event;
+    if (
+      tooltip &&
+      !(relatedTarget instanceof Node && tooltip.contains(relatedTarget)) &&
+      !place(tooltip)
+    ) {
+      requestAnimationFrame(() => {
+        place(tooltip);
+      });
+    }
+  };
+  document.addEventListener("focusin", show);
+  document.addEventListener("pointerover", show);
 </script>

package/src/components/content/Tree.astro

@@ -239,6 +239,11 @@
       }
 
       const folder = folderForItem(item);
+      // Deeper items sit further toward the inline end (the left under
+      // dir="rtl"), so the expand and collapse arrows swap there.
+      const rtl = getComputedStyle(this).direction === "rtl";
+      const expandKey = rtl ? "ArrowLeft" : "ArrowRight";
+      const collapseKey = rtl ? "ArrowRight" : "ArrowLeft";
       if (event.key === "ArrowDown") {
         event.preventDefault();
         this.#move(1);
@@ -251,7 +256,7 @@
       } else if (event.key === "End") {
         event.preventDefault();
         this.#moveToEdge("last");
-      } else if (event.key === "ArrowRight" && folder) {
+      } else if (event.key === expandKey && folder) {
         event.preventDefault();
         if (isOpenableDetails(folder) && !folder.open) {
           folder.open = true;
@@ -259,7 +264,7 @@
         } else {
           this.#setActive(this.#firstChild(folder), true);
         }
-      } else if (event.key === "ArrowLeft") {
+      } else if (event.key === collapseKey) {
         const parent = this.#parentItem(item);
         if (isOpenableDetails(folder) && folder.open) {
           event.preventDefault();

package/src/components/content/TypeTable.astro

@@ -4,7 +4,11 @@
 // the accent-colored prop name (with a `?` suffix when optional) and its type;
 // expanded, the row lifts into a card showing the description and a Type/Default
 // detail grid. Uses native <details>/<summary> so the core stays React-free.
+import data from "blume:data";
+
 import { resolveIcon } from "../../theme/icons.ts";
+import { contentHref } from "./base-href.ts";
+import { contentStrings } from "./content-strings.ts";
 
 // The row disclosure caret; resolved from Lucide at build time and injected into
 // the summary's `<svg>` (which supplies size and the rotate-on-open transition).
@@ -25,6 +29,7 @@ interface Props {
 
 const { type = {} } = Astro.props;
 const entries = Object.entries(type);
+const { content: strings } = contentStrings(data, Astro.currentLocale);
 
 // Shared column track so the header, every summary, and the detail grid align.
 const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
@@ -34,8 +39,8 @@ const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
   entries.length > 0 && (
     <div class="not-prose my-6 rounded-blume border border-border bg-muted/30 p-1.5">
       <div class={`${columns} px-3 py-2 font-medium text-muted-foreground text-xs`}>
-        <span>Prop</span>
-        <span>Type</span>
+        <span>{strings.prop}</span>
+        <span>{strings.type}</span>
         <span aria-hidden="true" class="size-3.5" />
       </div>
 
@@ -50,7 +55,7 @@ const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
             {info.typeDescriptionLink ? (
               <a
                 class="break-words font-mono text-foreground text-xs underline-offset-2 hover:underline"
-                href={info.typeDescriptionLink}
+                href={contentHref(info.typeDescriptionLink)}
               >
                 {info.type}
               </a>
@@ -85,7 +90,7 @@ const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
             )}
             <div class="space-y-1.5">
               <div class={columns}>
-                <span class="text-muted-foreground">Type</span>
+                <span class="text-muted-foreground">{strings.type}</span>
                 <code class="break-words font-mono text-foreground">
                   {info.type}
                 </code>
@@ -93,7 +98,7 @@ const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
               </div>
               {info.default && (
                 <div class={columns}>
-                  <span class="text-muted-foreground">Default</span>
+                  <span class="text-muted-foreground">{strings.default}</span>
                   <code class="break-words font-mono text-foreground">
                     {info.default}
                   </code>

package/src/components/content/Update.astro

@@ -1,6 +1,9 @@
 ---
+import data from "blume:data";
+
 import { componentSlug } from "../slug.ts";
 import { contentHref } from "./base-href.ts";
+import { contentStrings } from "./content-strings.ts";
 
 interface RssMetadata {
   description?: string;
@@ -32,8 +35,11 @@ const {
   tags,
   title,
 } = Astro.props;
-const updateLabel = label ?? title ?? "Update";
-const id = providedId ?? (componentSlug(updateLabel) || "update");
+const { content: strings } = contentStrings(data, Astro.currentLocale);
+const updateLabel = label ?? title ?? strings.update;
+// The anchor comes from the authored label only: the localized fallback
+// heading would give an unlabeled update a different anchor per locale.
+const id = providedId ?? (componentSlug(label ?? title ?? "") || "update");
 const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
 ---
 

package/src/components/content/auto-type-table.ts

@@ -128,8 +128,11 @@ export const extractTypeTable = async (
   return checker.getPropertiesOfType(type).map((symbol) => {
     const decl = symbol.declarations?.[0];
     const signature = decl && ts.isPropertySignature(decl) ? decl : undefined;
+    // Slice the text from the file that declares the property: an inherited
+    // member (`Props extends Base`, Base imported) lives in another file, and
+    // its positions mean nothing in the documented one.
     const typeText = signature?.type
-      ? signature.type.getText(sourceFile)
+      ? signature.type.getText(signature.getSourceFile())
       : checker.typeToString(
           checker.getTypeOfSymbolAtLocation(symbol, decl ?? declaration)
         );

package/src/components/content/badge-color.ts

@@ -0,0 +1,20 @@
+/**
+ * The named color each documented Badge `variant` paints with; `accent` is
+ * the site's theme accent rather than a fixed hue.
+ */
+const VARIANT_COLOR = new Map([
+  ["accent", "accent"],
+  ["danger", "red"],
+  ["default", "gray"],
+  ["success", "green"],
+  ["warning", "orange"],
+]);
+
+/**
+ * The color a badge renders with: an explicit `color` wins, then the
+ * variant's hue. MDX props aren't type-checked, so a variant Badge doesn't
+ * know (`info`, which Callout accepts) renders as the default gray badge
+ * instead of failing the page build.
+ */
+export const badgeColorName = (variant: string, color?: string): string =>
+  color ?? VARIANT_COLOR.get(variant) ?? "gray";

package/src/components/content/base-href.ts

@@ -1,33 +1,25 @@
 import data from "blume:data";
 
 import {
-  isInternalPath,
   normalizeBasePath,
-  withComposedBasePath,
+  withAuthoredBasePath,
 } from "../../core/base-path.ts";
-
-// Mirrors `markdown/base-links.ts`: a path whose final segment carries a file
-// extension is a `public/` asset, served at the site root and never moved
-// under `basePath`.
-const ASSET_PATH = /\.[a-z0-9]+$/iu;
-
-/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
-const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
+import { routeSetFor, servesRoute } from "../../core/locale-links.ts";
 
 /**
  * Rebase a component-emitted `href` the way `markdown/base-links.ts` rebases
  * `[x](/guide)`: a root-relative internal page link gains the composed
- * `deployment.base` + `basePath` prefix, so authors write component links
- * (`<Card href="/guide">`) under the same "as if mounted at root" contract as
- * markdown links. Idempotent per layer (a hand-written `/docs/x` isn't
- * double-prefixed) and inert for external URLs, fragments, relative paths, and
- * asset links.
+ * `deployment.base` + `basePath` prefix, and a public asset (`/spec.pdf`, with
+ * no page served there) the deployment base alone, so authors write component
+ * links (`<Card href="/guide">`) under the same "as if mounted at root"
+ * contract as markdown links (see `withAuthoredBasePath`). Idempotent per
+ * layer (a hand-written `/docs/x` isn't double-prefixed) and inert for
+ * external URLs, fragments, and relative paths.
  */
 export const contentHref = (href: string): string =>
-  isInternalPath(href) && !ASSET_PATH.test(pathOf(href))
-    ? withComposedBasePath(
-        normalizeBasePath(import.meta.env.BASE_URL),
-        data.config.basePath,
-        href
-      )
-    : href;
+  withAuthoredBasePath(
+    normalizeBasePath(import.meta.env.BASE_URL),
+    data.config.basePath,
+    href,
+    (route) => servesRoute(routeSetFor(data.routes), route)
+  );

package/src/components/content/inline-markdown.ts

@@ -1,3 +1,6 @@
+import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
+import { defineMdastPlugin } from "satteri";
+
 /**
  * Shared helpers for components that render a short Markdown prop (a caption,
  * a description, a tooltip label) into inline HTML injected via `set:html`.
@@ -5,14 +8,19 @@
  */
 
 /**
- * Neutralize raw HTML in a Markdown-rendered text prop by escaping only
- * `<`/`>`. `&` deliberately stays: CommonMark already renders a bare `&` as
- * `&amp;` and resolves real entity references, so leaving it alone keeps
- * `&copy;`-style authoring working — a full HTML escape would render it as
- * the literal text `&copy;`.
+ * Neutralize raw HTML in a Markdown-rendered text prop: each raw HTML node
+ * the parser finds (an inline tag, a block, a comment) renders as its literal
+ * text instead. Deciding in the tree rather than escaping `<`/`>` in the
+ * source keeps what only looks like HTML intact — a code span's
+ * `` `Array<string>` `` and an autolink's `<https://…>` — and `&` entity
+ * references keep resolving (`&copy;` renders as ©).
  */
-export const escapeRawHtml = (value: string): string =>
-  value.replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+export const rawHtmlAsTextPlugin = defineMdastPlugin({
+  html(node, ctx) {
+    ctx.replaceNode(node, { type: "text", value: node.value });
+  },
+  name: "blume-raw-html-as-text",
+});
 
 /**
  * Unwrap the `<p>` a block-level Markdown render wraps around single-line
@@ -26,3 +34,15 @@ export const unwrapParagraph = (html: string): string => {
   const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
   return match?.groups?.content ?? trimmed;
 };
+
+/**
+ * Render a short Markdown text prop to inline HTML, its raw HTML shown as
+ * text (see {@link rawHtmlAsTextPlugin}) and a single paragraph unwrapped.
+ */
+export const renderInlineMarkdown = async (value: string): Promise<string> => {
+  const processor = await createSatteriMarkdownProcessor({
+    mdastPlugins: [rawHtmlAsTextPlugin],
+  });
+  const rendered = await processor.render(value);
+  return unwrapParagraph(rendered.code);
+};