@blogmcp/mdx-render-react 0.1.0

package/dist/render/youtube/YouTubeDefault.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsxs as a, jsx as e } from "react/jsx-runtime";
+import { useState as c } from "react";
+import { YOUTUBE_IFRAME_ALLOW as r, thumbnailUrl as d, embedUrl as n } from "./youtube.js";
+function b({ id: o, title: t }) {
+  const l = t || "YouTube video", s = d(o), [i, u] = c(!1);
+  return /* @__PURE__ */ a("div", { className: "youtube-embed my-6", "data-mdx-component": "YouTube", "data-allow": r, children: [
+    /* @__PURE__ */ e("div", { className: "relative w-full rounded-lg overflow-hidden shadow-md", style: { paddingBottom: "56.25%" }, children: i ? /* @__PURE__ */ e(
+      "iframe",
+      {
+        src: `${n(o)}?autoplay=1`,
+        title: l,
+        className: "absolute inset-0 w-full h-full",
+        frameBorder: "0",
+        allow: r,
+        allowFullScreen: !0
+      }
+    ) : /* @__PURE__ */ a(
+      "button",
+      {
+        type: "button",
+        className: "absolute inset-0 w-full h-full cursor-pointer border-0 p-0 bg-black group",
+        "aria-label": `Play ${l}`,
+        onClick: () => u(!0),
+        children: [
+          /* @__PURE__ */ e("img", { src: s, alt: l, className: "absolute inset-0 w-full h-full object-cover" }),
+          /* @__PURE__ */ a(
+            "svg",
+            {
+              className: "absolute inset-0 m-auto w-16 h-16 text-white drop-shadow-lg opacity-90 group-hover:opacity-100 transition-opacity",
+              viewBox: "0 0 68 48",
+              "aria-hidden": "true",
+              children: [
+                /* @__PURE__ */ e(
+                  "path",
+                  {
+                    d: "M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55C3.97 2.33 2.27 4.81 1.48 7.74.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z",
+                    fill: "red"
+                  }
+                ),
+                /* @__PURE__ */ e("path", { d: "M45 24L27 14v20", fill: "white" })
+              ]
+            }
+          )
+        ]
+      }
+    ) }),
+    t ? /* @__PURE__ */ e("p", { className: "text-center text-sm text-gray-600 mt-3", children: t }) : null
+  ] });
+}
+export {
+  b as default
+};

package/dist/render/youtube/youtube.d.ts

@@ -0,0 +1,8 @@
+/**
+ * YouTube URL helpers — mirrored from
+ * `@blogmcp/mdx-render-vue/src/composables/useYouTube.ts`.
+ */
+export declare const YOUTUBE_EMBED_BASE = "https://www.youtube.com/embed/";
+export declare const YOUTUBE_IFRAME_ALLOW = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture";
+export declare function embedUrl(id: string): string;
+export declare function thumbnailUrl(id: string): string;

package/dist/render/youtube/youtube.js

@@ -0,0 +1,13 @@
+const t = "https://www.youtube.com/embed/", r = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture";
+function o(e) {
+  return `${t}${e}`;
+}
+function u(e) {
+  return e ? `https://img.youtube.com/vi/${e}/maxresdefault.jpg` : "";
+}
+export {
+  t as YOUTUBE_EMBED_BASE,
+  r as YOUTUBE_IFRAME_ALLOW,
+  o as embedUrl,
+  u as thumbnailUrl
+};

package/dist/server-render-map.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Static render map used by MdxContent.
+ *
+ * Direct (non-lazy) imports of every render component, keyed by the schema's
+ * PascalCase component name. The two client islands (Tooltip, AudioPlayer)
+ * are referenced here too — a Next.js consumer ships them as islands because
+ * each carries its own `'use client'` banner.
+ *
+ * `default` variants only; the registry (registry.ts) carries the full
+ * variant map (e.g. Callout `minimal`) for future tooling.
+ *
+ * Two maps are exported:
+ *
+ * - `serverRenderMap` — raw components. Kept as an escape hatch for
+ *   tooling that needs the bare component reference (snapshot fixtures,
+ *   manual instantiation in tests). PRODUCTION CODE SHOULD NOT USE IT.
+ *
+ * - `wrappedServerRenderMap` — `prepareProps`-aware components. Each
+ *   entry is the raw component wrapped in a tiny HOC that runs every
+ *   incoming prop through `prepareProps(props, metadata)` before
+ *   forwarding to the real component. This makes the schema's render-
+ *   time shim impossible to forget at call sites: any consumer doing
+ *   `<Comp {...item.props}>` gets normalized props automatically,
+ *   including for recursively-rendered nested MDX children.
+ */
+import { type ComponentType, type ReactNode } from 'react';
+import { type ComponentMetadata } from '@blogmcp/mdx-schema';
+export declare const serverRenderMap: Record<string, ComponentType<any>>;
+/**
+ * Sentinel property name read by the per-renderer "prepareProps is
+ * wired" integration test. Wrapped components carry this with the
+ * component's schema name so the test can confirm wrapping end-to-end
+ * (vs the historical regex-grep on registry source, which was easily
+ * defeated by commented-out code and unused imports).
+ */
+export declare const MDX_PREPARED_SENTINEL: "__mdxPreparePropsAppliedFor";
+/**
+ * HOC that wraps a render component so every invocation runs incoming
+ * props through `prepareProps(props, metadata)` before forwarding to
+ * the inner component. Re-rendered components from nested MDX go
+ * through the same wrapped reference, so recursion does not bypass
+ * the shim.
+ *
+ * Children are forwarded untouched — `prepareProps` operates on the
+ * named props only; the `children` slot is a structural concern.
+ *
+ * The wrapper sets a `displayName` for React DevTools and stamps the
+ * `MDX_PREPARED_SENTINEL` property so the CI integration test can
+ * confirm the wrapper was applied.
+ */
+export declare function wrapReactComponentForMdx<P extends Record<string, any>>(Inner: ComponentType<P>, metadata: ComponentMetadata): ComponentType<P & {
+    children?: ReactNode;
+}>;
+export declare const wrappedServerRenderMap: Record<string, ComponentType<any>>;

package/dist/server-render-map.js

@@ -0,0 +1,56 @@
+import { createElement as p } from "react";
+import { componentMetadata as d, prepareProps as i } from "@blogmcp/mdx-schema";
+import c from "./render/callout/CalloutDefault.js";
+import f from "./render/youtube/YouTubeDefault.js";
+import l from "./render/gallery/GalleryGrid.js";
+import s from "./render/codeblock/CodeBlockDefault.js";
+import u from "./render/audioplayer/AudioPlayerDefault.js";
+import M from "./render/button/Button.js";
+import h from "./render/card/Card.js";
+import P from "./render/alert/Alert.js";
+import x from "./render/badge/Badge.js";
+import y from "./render/icon/Icon.js";
+import w from "./render/tooltip/Tooltip.js";
+const E = {
+  Callout: c,
+  YouTube: f,
+  Gallery: l,
+  CodeBlock: s,
+  AudioPlayer: u,
+  Button: M,
+  Card: h,
+  Alert: P,
+  Badge: x,
+  Icon: y,
+  Tooltip: w
+}, R = "__mdxPreparePropsAppliedFor";
+function A(r, e) {
+  const o = function(t) {
+    const { children: a, ...n } = t, m = i(n, e);
+    return p(r, m, a);
+  };
+  return o[R] = e.name, o.displayName = `MdxPrepared(${e.name})`, o;
+}
+const C = new Map(
+  d.map((r) => [r.name, r])
+);
+function D(r) {
+  const e = C.get(r);
+  if (!e)
+    throw new Error(
+      `[mdx-render-react] No componentMetadata for "${r}" — the React render map has a component the schema does not know about. Add an entry in packages/mdx-schema/src/metadata/index.ts or remove the entry from serverRenderMap.`
+    );
+  return e;
+}
+const Y = Object.fromEntries(
+  Object.entries(E).map(([r, e]) => [
+    r,
+    A(e, D(r))
+  ])
+);
+export {
+  R as MDX_PREPARED_SENTINEL,
+  E as serverRenderMap,
+  A as wrapReactComponentForMdx,
+  Y as wrappedServerRenderMap
+};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@blogmcp/mdx-render-react",
+  "version": "0.1.0",
+  "description": "React renderer for MDX components — implements the @blogmcp/mdx-schema contract alongside @blogmcp/mdx-render-vue. Server-Component-first with two client islands (Tooltip, AudioPlayer).",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./render": {
+      "types": "./dist/render/index.d.ts",
+      "import": "./dist/render/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ark-ui/react": "^5.0.0",
+    "@blogmcp/mdx-schema": "^0.1.0",
+    "@blogmcp/sanitize": "^0.1.0",
+    "@blogmcp/sdk": "^0.1.0",
+    "@iconify/react": "^6.0.0",
+    "marked": "^15.0.7"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^20.10.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "happy-dom": "^17.4.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "rollup-plugin-preserve-directives": "^0.4.0",
+    "typescript": "^5.3.3",
+    "vite": "^7.3.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "mdx",
+    "react",
+    "components",
+    "markdown"
+  ],
+  "license": "MIT"
+}

package/src/MdxContent.tsx

@@ -0,0 +1,105 @@
+import { Fragment, type ReactNode } from 'react'
+import { stripFrontmatter, extractMdxComponents, HAS_MDX_RE } from '@blogmcp/mdx-schema/composables/parsing'
+import type { ImageHtmlRenderer, SanitizeFn } from '@blogmcp/sdk'
+import { createMarked } from './marked'
+// `wrappedServerRenderMap` runs every component's incoming props through
+// `prepareProps(props, metadata)` before forwarding to the inner component.
+// Recursive `MdxContent` invocations below see the same wrapped map, so
+// nested-MDX children also get normalized props — no per-call-site wiring
+// to forget. See server-render-map.ts for the HOC.
+import { wrappedServerRenderMap } from './server-render-map'
+
+export interface MdxContentProps {
+  /** Raw MDX/markdown source (frontmatter allowed; it is stripped). */
+  content: string
+  /** Optional custom image HTML renderer (IPX, Cloudinary, …). */
+  imageRenderer?: ImageHtmlRenderer
+  /**
+   * Optional HTML sanitizer override. Defaults to `sanitizeHtml` from
+   * `@blogmcp/sanitize` (DOMPurify with our strict config). Pass `null`
+   * to opt out for trusted-self surfaces.
+   */
+  sanitize?: SanitizeFn | null
+}
+
+/**
+ * Renders MDX content as a tree of React Server Components.
+ *
+ * Mirrors the Vue blog renderer (KbMdxContent.vue):
+ *  - strips frontmatter
+ *  - fast-paths pure markdown via `marked` → dangerouslySetInnerHTML
+ *  - otherwise splits via `extractMdxComponents`, rendering html chunks via
+ *    `marked` and components via `serverRenderMap[name]`
+ *  - recurses into component children by rendering a nested <MdxContent>
+ *    (React equivalent of Vue's raw-string default slot)
+ *  - unknown component → the same yellow fallback box the Vue renderer shows
+ *
+ * Async Server Component: safe to `await` in RSC; works synchronously in tests.
+ */
+export default async function MdxContent({ content, imageRenderer, sanitize }: MdxContentProps): Promise<ReactNode> {
+  const marked = createMarked({ imageRenderer, sanitize })
+
+  if (!content) {
+    return <div className="mdx-content" />
+  }
+
+  const source = stripFrontmatter(content)
+
+  // Fast path: pure markdown (no MDX components)
+  if (!HAS_MDX_RE.test(source)) {
+    const html = (await marked.parse(source)) as string
+    return <div className="mdx-content" dangerouslySetInnerHTML={{ __html: html }} />
+  }
+
+  const items = extractMdxComponents(source)
+
+  // Fallback: parser found no components despite the HAS_MDX_RE match.
+  if (items.length === 1 && items[0].type === 'html') {
+    const html = (await marked.parse(items[0].content)) as string
+    return <div className="mdx-content" dangerouslySetInnerHTML={{ __html: html }} />
+  }
+
+  const nodes: ReactNode[] = []
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+    if (item.type === 'html') {
+      const html = (await marked.parse(item.content)) as string
+      nodes.push(<div key={i} dangerouslySetInnerHTML={{ __html: html }} />)
+      continue
+    }
+
+    const Comp = wrappedServerRenderMap[item.name]
+    if (!Comp) {
+      nodes.push(
+        <div
+          key={i}
+          className="bg-yellow-50 border border-yellow-200 rounded-lg p-4 my-4 text-yellow-800"
+        >
+          {`Unknown component: ${item.name}`}
+        </div>,
+      )
+      continue
+    }
+
+    // Recurse into children: render nested MDX (markdown + components) exactly
+    // like the Vue renderer passes the raw children string back through itself.
+    // Sanitize policy propagates so nested chunks inherit the same trust contract.
+    const childNode = item.children
+      ? await MdxContent({ content: item.children, imageRenderer, sanitize })
+      : undefined
+
+    nodes.push(
+      <Comp key={i} {...item.props}>
+        {childNode}
+      </Comp>,
+    )
+  }
+
+  return (
+    <div className="mdx-content">
+      {nodes.map((node, i) => (
+        <Fragment key={i}>{node}</Fragment>
+      ))}
+    </div>
+  )
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @blogmcp/mdx-render-react
+ *
+ * React renderer for MDX components. Implements the same contract as
+ * @blogmcp/mdx-render-vue against the shared @blogmcp/mdx-schema. Authoring
+ * (MDX syntax, metadata, MCP tool output) is identical across frameworks —
+ * only the renderer swaps.
+ *
+ * The blog/RSC path uses `MdxContent` (async Server Component) + the static
+ * `serverRenderMap`. `reactRegistry` mirrors the Vue registry for future
+ * tooling (lazy variant resolution, an eventual React md-editor).
+ */
+
+// Primary render entry point
+export { default as MdxContent } from './MdxContent'
+export type { MdxContentProps } from './MdxContent'
+
+// Static render map (used internally by MdxContent; exported for consumers)
+export { serverRenderMap } from './server-render-map'
+
+// Registry (schema metadata + React lazy loaders)
+export {
+  reactRegistry,
+  componentMetadata,
+  getComponentMetadata,
+  getComponentNames,
+  getComponentVariants,
+  getRenderComponentAsync,
+  type ReactComponentRegistration,
+} from './registry'
+
+// Marked instance + helpers
+export { createMarked, marked, defaultImageHtml } from './marked'
+export type { ImageHtmlRenderer } from './marked'
+
+// Render components (named) + their prop types
+export * from './render/index'

package/src/marked.ts

@@ -0,0 +1,49 @@
+/**
+ * Configured `marked` instance for the React renderer.
+ *
+ * Reuses the SDK's `createMarkedInstance` so the image/link renderers, table
+ * wrap, and `th scope` post-processing match the Vue blog (KbMdxContent.vue)
+ * exactly. Consumers may pass a custom image renderer (IPX, Cloudinary, etc.)
+ * and an optional HTML sanitizer.
+ *
+ * Sanitization is wired by default via `@blogmcp/sanitize` — the reference
+ * renderer ships safe-by-default. Callers can opt out by passing `null`
+ * (intentional, grep-able) for trusted-self surfaces or when a downstream
+ * renderer applies its own sanitization.
+ */
+import {
+  createMarkedInstance,
+  defaultImageHtml,
+  type ImageHtmlRenderer,
+  type SanitizeFn,
+} from '@blogmcp/sdk'
+import { sanitizeHtml } from '@blogmcp/sanitize'
+import type { Marked } from 'marked'
+
+export { defaultImageHtml, sanitizeHtml }
+export type { ImageHtmlRenderer, SanitizeFn }
+
+export interface CreateMarkedOptions {
+  /** Custom image renderer. Defaults to plain <img> with lazy loading. */
+  imageRenderer?: ImageHtmlRenderer
+  /**
+   * HTML sanitizer applied as the last step of `marked.parse()`. Defaults
+   * to `sanitizeHtml` from `@blogmcp/sanitize` (DOMPurify with our strict
+   * config). Pass `null` to opt out — only do this for trusted-self surfaces
+   * or when a downstream renderer applies its own sanitization. The opt-out
+   * is explicit and grep-able.
+   */
+  sanitize?: SanitizeFn | null
+}
+
+/** Create a configured Marked instance (sanitize-on by default). */
+export function createMarked(opts: CreateMarkedOptions = {}): Marked {
+  const imageRenderer = opts.imageRenderer ?? defaultImageHtml
+  // `null` is the explicit opt-out; `undefined` falls back to the default.
+  const sanitize =
+    opts.sanitize === null ? undefined : (opts.sanitize ?? sanitizeHtml)
+  return createMarkedInstance({ imageRenderer, sanitize })
+}
+
+/** Shared default instance for the common case (no custom options). */
+export const marked: Marked = createMarked()

package/src/registry.ts

@@ -0,0 +1,131 @@
+/**
+ * React MDX Component Registry.
+ *
+ * Mirrors `@blogmcp/mdx-render-vue/src/registry.ts` against the shared schema.
+ * Attaches React-specific lazy render loaders to the framework-agnostic
+ * metadata published by `@blogmcp/mdx-schema`. Schema is the single source of
+ * truth for component descriptions, prop shapes, and MCP-facing examples.
+ *
+ * This registry is for future tooling (dynamic resolution, editor previews).
+ * The blog/RSC render path uses the static `serverRenderMap` instead.
+ */
+
+import {
+  componentMetadata,
+  getComponentMetadata,
+  getComponentNames,
+  type ComponentMetadata,
+} from '@blogmcp/mdx-schema/metadata'
+
+// Re-export schema helpers so callers that already have the registry can reach
+// metadata without a second import.
+export { componentMetadata, getComponentMetadata, getComponentNames }
+
+export interface ReactComponentRegistration {
+  metadata: ComponentMetadata
+  /** Render variants: variant name → async loader. Must include 'default'. */
+  render: Record<string, () => Promise<{ default: unknown }>>
+  /**
+   * Optional edit component loader. The blog only needs `render`; an editor
+   * (React md-editor port) would populate this later.
+   */
+  edit?: () => Promise<{ default: unknown }>
+}
+
+/** Per-component React wiring (lazy render loaders), keyed by component name. */
+interface ReactWiring {
+  render: Record<string, () => Promise<{ default: unknown }>>
+}
+
+const reactWiring: Record<string, ReactWiring> = {
+  Callout: {
+    render: {
+      default: () => import('./render/callout/CalloutDefault'),
+      minimal: () => import('./render/callout/CalloutMinimal'),
+    },
+  },
+  YouTube: {
+    render: {
+      default: () => import('./render/youtube/YouTubeDefault'),
+    },
+  },
+  Gallery: {
+    render: {
+      default: () => import('./render/gallery/GalleryGrid'),
+      grid: () => import('./render/gallery/GalleryGrid'),
+    },
+  },
+  CodeBlock: {
+    render: {
+      default: () => import('./render/codeblock/CodeBlockDefault'),
+    },
+  },
+  AudioPlayer: {
+    render: {
+      default: () => import('./render/audioplayer/AudioPlayerDefault'),
+    },
+  },
+  Button: {
+    render: {
+      default: () => import('./render/button/Button'),
+    },
+  },
+  Card: {
+    render: {
+      default: () => import('./render/card/Card'),
+    },
+  },
+  Alert: {
+    render: {
+      default: () => import('./render/alert/Alert'),
+    },
+  },
+  Badge: {
+    render: {
+      default: () => import('./render/badge/Badge'),
+    },
+  },
+  Icon: {
+    render: {
+      default: () => import('./render/icon/Icon'),
+    },
+  },
+  Tooltip: {
+    render: {
+      default: () => import('./render/tooltip/Tooltip'),
+    },
+  },
+}
+
+/** Merged registry: schema metadata + React wiring, keyed by component name. */
+export const reactRegistry: Record<string, ReactComponentRegistration> = Object.fromEntries(
+  componentMetadata.map((metadata) => {
+    const wiring = reactWiring[metadata.name]
+    if (!wiring) {
+      throw new Error(
+        `[mdx-render-react] No React wiring registered for component "${metadata.name}". ` +
+          `Add an entry to reactWiring in registry.ts or remove the schema entry.`,
+      )
+    }
+    return [metadata.name, { metadata, ...wiring }] as const
+  }),
+)
+
+/** Get available render variant names for a component. */
+export function getComponentVariants(name: string): string[] {
+  const reg = reactRegistry[name]
+  return reg ? Object.keys(reg.render) : []
+}
+
+/** Async resolver — loads only the requested render component. */
+export async function getRenderComponentAsync(
+  name: string,
+  variant = 'default',
+): Promise<unknown | undefined> {
+  const reg = reactRegistry[name]
+  if (!reg) return undefined
+  const loader = reg.render[variant] || reg.render.default
+  if (!loader) return undefined
+  const mod = await loader()
+  return mod.default
+}

package/src/render/alert/Alert.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react'
+import { Icon } from '@iconify/react'
+import { alertStyles, type AlertSeverity } from '@blogmcp/mdx-schema/styles'
+
+export interface AlertProps {
+  severity?: AlertSeverity
+  title?: string
+  children?: ReactNode
+}
+
+/**
+ * Inline notice — flatter/smaller than Callout. Mirrors Vue Alert.vue:
+ * severity → wrap classes + iconify icon + icon color (shared table),
+ * optional bold title, children inside a `prose-sm` body.
+ */
+export default function Alert({ severity = 'info', title, children }: AlertProps) {
+  const cfg = alertStyles.severity[severity]
+
+  return (
+    <div
+      className={[alertStyles.base, cfg.wrap].join(' ')}
+      role="alert"
+      data-mdx-component="Alert"
+    >
+      <Icon icon={cfg.icon} className={['mt-0.5 shrink-0', cfg.iconClass].join(' ')} width={18} height={18} />
+      <div className="min-w-0 flex-1">
+        {title ? <div className="mb-0.5 font-semibold">{title}</div> : null}
+        <div className="prose-sm">{children}</div>
+      </div>
+    </div>
+  )
+}