@blogmcp/mdx-render-react 0.9.0 → 0.9.1

package/README.md

@@ -1,35 +1,40 @@
 # @blogmcp/mdx-render-react
 
-**Status: scaffold only.** Implementation deferred until a React consumer exists (blog or md-editor React port).
+React renderer for MDX components. Consumers: the Next.js managed blog (`apps/knowledge-base/blog-next`),
+`@blogmcp/sdk/react` (`KbMdxContent`) and `@blogmcp/render-embed-react`.
 
 This package mirrors [`@blogmcp/mdx-render-vue`](../mdx-render-vue/) against the shared
 [`@blogmcp/mdx-schema`](../mdx-schema/) contract. Authoring stays identical across frameworks
 (same MDX syntax, same metadata, same MCP tool output) — only the renderer swaps.
 
-## Contract to implement
-
-```ts
-import { componentMetadata } from '@blogmcp/mdx-schema'
-import type { ComponentType } from 'react'
-
-export interface ReactComponentRegistration {
-  metadata: ComponentMetadata         // from @blogmcp/mdx-schema
-  render: Record<string, () => Promise<{ default: ComponentType<any> }>>
-  edit: () => Promise<{ default: ComponentType<any> }>
-}
-
-export const reactRegistry: Record<string, ReactComponentRegistration>
-```
-
-Implementation mirrors [`packages/mdx-render-vue/src/registry.ts`](../mdx-render-vue/src/registry.ts)
-— same keys (`Callout`, `YouTube`, `Gallery`, `CodeBlock`, `AudioPlayer`), same variants, React
-components instead of Vue SFCs. Prefer Ark UI React primitives where Vue uses Ark UI Vue; share
-Tailwind classes verbatim.
-
-## When to implement
-
-When the first React consumer appears (blog-react or editor-react). Until then, keep the package
-empty so the schema contract proves framework-neutral by construction.
+## Two artifacts (design D4)
+
+- **`MdxContent`** (`src/MdxContent.tsx`) — the render path. An async Server Component: strips
+  frontmatter, fast-paths pure markdown through `marked`, otherwise extracts the MDX components and
+  renders each through `wrappedServerRenderMap` (`src/server-render-map.ts`: direct static imports,
+  every component's props run through the schema's `prepareProps`), recursing into children that
+  contain MDX. Unknown components get the yellow fallback.
+- **`reactRegistry`** (`src/registry.ts`, export `./registry`) — lazy `import()` loaders with the same
+  keys and variants as the Vue registry, for tooling (dynamic resolution, a future React editor);
+  the blog does not use it. `edit` is optional.
+
+Parity selector: every component root carries `data-mdx-component="<Name>"` in both renderers, and
+the class strings come from `@blogmcp/mdx-schema/styles`, so they cannot drift (`test/style-parity.spec.tsx`).
+
+## Server Components and client islands
+
+Button, Card, Alert, Badge, Callout and Icon are plain Server Components (no client JS). Tooltip
+(`@ark-ui/react`), AudioPlayer, YouTube (thumbnail facade → iframe), CodeBlock (copy button),
+Gallery (lightbox) and TripMap (MapLibre loaded lazily) are client islands, each with its own
+`'use client'` banner. The build (`vite` with `preserveModules` + `rollup-plugin-preserve-directives`,
+then `tsc --emitDeclarationOnly`) keeps those banners per file, so a Next.js consumer ships them as
+islands; do not collapse the output into one bundle. Each island's initial DOM and classes match the
+Vue component.
+
+**Icon renders nothing in SSR.** `@iconify/react` resolves icon names from the API on the client, so
+the server HTML holds an empty `<span>` — no `<svg>` and no `data-mdx-component` marker until
+hydration (`test/ssr.spec.tsx`). A parity check must assert Icon after hydration; an app that needs
+server-rendered icons must bundle the icon set. The same holds for `@iconify/vue`.
 
 ## Real-browser tests
 

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

@@ -2,7 +2,7 @@
  * 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)
+ * PascalCase component name. The client islands (Tooltip, AudioPlayer, YouTube, CodeBlock, Gallery, TripMap)
  * are referenced here too — a Next.js consumer ships them as islands because
  * each carries its own `'use client'` banner.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blogmcp/mdx-render-react",
-  "version": "0.9.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).",
+  "version": "0.9.1",
+  "description": "React renderer for MDX components — implements the @blogmcp/mdx-schema contract alongside @blogmcp/mdx-render-vue. Server-Component-first with client islands (Tooltip, AudioPlayer).",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -38,10 +38,10 @@
   },
   "dependencies": {
     "@ark-ui/react": "^5.0.0",
-    "@blogmcp/mdx-schema": "^0.9.0",
+    "@blogmcp/mdx-schema": "^0.9.1",
     "@blogmcp/tripmap-core": "^0.1.2",
-    "@blogmcp/sanitize": "^0.9.0",
-    "@blogmcp/sdk": "^0.9.0",
+    "@blogmcp/sanitize": "^0.9.1",
+    "@blogmcp/sdk": "^0.9.1",
     "@iconify/react": "^6.0.0",
     "marked": "^15.0.7"
   },

package/src/server-render-map.ts

@@ -2,7 +2,7 @@
  * 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)
+ * PascalCase component name. The client islands (Tooltip, AudioPlayer, YouTube, CodeBlock, Gallery, TripMap)
  * are referenced here too — a Next.js consumer ships them as islands because
  * each carries its own `'use client'` banner.
  *