fix: SSR render prefetched React embeds (#8)

## Summary
- render pre-fetched `MemoEmbed` and `MemoEmbedList` markup during
SSR/SSG instead of waiting for hydration
- replace imperative `innerHTML` injection with direct render output and
memoized HTML generation
- add server-render regression tests and document the SSR behavior

## Testing
- pnpm validate

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Server-renders pre-fetched `MemoEmbed` and `MemoEmbedList` in
`@memos-embed/react` so SSR/SSG pages include full embed HTML without
waiting for hydration. Also replaces `innerHTML` injection with direct
render output for safer, faster markup.

- **Bug Fixes**
- SSR/SSG now outputs full embed HTML when `memo`/`memos` props are
provided.
- Removed imperative `innerHTML`; use memoized HTML and a small
`renderHtml` helper.
- Added SSR regression tests and updated docs/READMEs; published a patch
changeset.

<sup>Written for commit a121dfc.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

Author: markbang

.changeset/slow-pandas-help.md

@@ -0,0 +1,5 @@
+---
+"@memos-embed/react": patch
+---
+
+Render pre-fetched `MemoEmbed` and `MemoEmbedList` markup during SSR/SSG instead of waiting for client-side hydration.

README.md

@@ -150,6 +150,8 @@ const memo = await fetchMemo({
 <MemoEmbed memo={memo} />
 ```
 
+When you pass a pre-fetched `memo`, the React component now renders the full embed HTML during SSR/SSG instead of waiting for hydration.
+
 ### React roundup component
 ```tsx
 import { MemoEmbedList } from '@memos-embed/react'
@@ -208,7 +210,7 @@ const [heroMemo, roundupMemos] = await Promise.all([
 </MemoClientProvider>
 ```
 
-Passing `memo` or `memos` while a `MemoClientProvider` is active primes the shared client cache, so later embeds for the same ids can reuse already-fetched data.
+Passing `memo` or `memos` while a `MemoClientProvider` is active primes the shared client cache, so later embeds for the same ids can reuse already-fetched data. Those pre-fetched props also render immediately in the initial HTML response for SSR/SSG pages.
 
 ### Web Component
 ```html

packages/memos-embed-react/README.md

@@ -92,6 +92,8 @@ const [heroMemo, roundupMemos] = await Promise.all([
 
 Passing `memo` or `memos` while a `MemoClientProvider` is active primes the shared client cache, so later embeds for the same memo ids can reuse that data.
 
+When you pass pre-fetched `memo` or `memos`, the component now renders full embed markup during SSR/SSG instead of waiting for client-side hydration.
+
 ## Pre-fetched usage
 ```tsx
 import { fetchMemo } from 'memos-embed'
@@ -105,6 +107,8 @@ const memo = await fetchMemo({
 <MemoEmbed memo={memo} className="my-8" />
 ```
 
+This path is ideal for MDX, Next.js, Astro, and other SSR setups because the rendered memo HTML is included in the initial response.
+
 ## Styling with your blog theme
 ```tsx
 import { extendTheme } from 'memos-embed'

packages/memos-embed-react/src/__tests__/index.test.ts

@@ -1,5 +1,6 @@
 import { act, createElement } from "react";
 import { createRoot } from "react-dom/client";
+import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it, vi } from "vitest";
 import * as memosEmbed from "memos-embed";
 import {
@@ -138,6 +139,27 @@ describe("@memos-embed/react", () => {
 		renderSnippetSpy.mockRestore();
 	});
 
+	it("server-renders a provided memo immediately for prefetched data", () => {
+		const html = renderToStaticMarkup(
+			createElement(MemoEmbed, {
+				memo: {
+					id: "ssr-1",
+					name: "memos/ssr-1",
+					content: "SSR memo",
+					tags: [],
+					attachments: [],
+					reactions: [],
+				},
+				className: "memo-ssr",
+				includeStyles: false,
+			}),
+		);
+
+		expect(html).toContain('class="memo-ssr"');
+		expect(html).toContain("SSR memo");
+		expect(html).not.toContain("Loading memo");
+	});
+
 	it("renders memo roundups through shared list helpers", async () => {
 		const customFetcher = vi.fn<typeof fetch>();
 		const memos = [
@@ -294,6 +316,40 @@ describe("@memos-embed/react", () => {
 		coreFetchMemosSpy.mockRestore();
 	});
 
+	it("server-renders provided memo lists immediately for prefetched data", () => {
+		const html = renderToStaticMarkup(
+			createElement(MemoEmbedList, {
+				memos: [
+					{
+						id: "ssr-1",
+						name: "memos/ssr-1",
+						content: "SSR one",
+						tags: [],
+						attachments: [],
+						reactions: [],
+					},
+					{
+						id: "ssr-2",
+						name: "memos/ssr-2",
+						content: "SSR two",
+						tags: [],
+						attachments: [],
+						reactions: [],
+					},
+				],
+				className: "memo-list-ssr",
+				includeStyles: false,
+				layout: "grid",
+			}),
+		);
+
+		expect(html).toContain('class="memo-list-ssr"');
+		expect(html).toContain("SSR one");
+		expect(html).toContain("SSR two");
+		expect(html).toContain("memos-embed-list--grid");
+		expect(html).not.toContain("Loading memos");
+	});
+
 	it("primes both single and list caches when provider receives prefetched data", async () => {
 		const memo = {
 			id: "1",

packages/memos-embed-react/src/index.tsx

@@ -4,11 +4,9 @@ import {
 	createContext,
 	type CSSProperties,
 	type ReactNode,
-	type RefObject,
 	useContext,
 	useEffect,
 	useMemo,
-	useRef,
 	useState,
 } from "react";
 import type {
@@ -108,26 +106,39 @@ export const MemoClientProvider = ({
 export const useMemoClient = (client?: MemoClient) =>
 	client ?? useContext(MemoClientContext);
 
-const renderState = ({
-	message,
+const renderHtml = ({
+	html,
 	className,
 	style,
-	includeStyles,
 }: {
-	message: string;
+	html: string;
 	className?: string;
 	style?: CSSProperties;
-	includeStyles?: boolean;
 }) => (
 	<div
 		className={className}
 		style={style}
-		dangerouslySetInnerHTML={{
-			__html: renderMemoStateHtmlSnippet(message, { includeStyles }),
-		}}
+		dangerouslySetInnerHTML={{ __html: html }}
 	/>
 );
 
+const renderState = ({
+	message,
+	className,
+	style,
+	includeStyles,
+}: {
+	message: string;
+	className?: string;
+	style?: CSSProperties;
+	includeStyles?: boolean;
+}) =>
+	renderHtml({
+		html: renderMemoStateHtmlSnippet(message, { includeStyles }),
+		className,
+		style,
+	});
+
 const useEmbedHtmlOptions = ({
 	theme,
 	density,
@@ -228,22 +239,6 @@ const useMemoListHtmlOptions = ({
 	);
 };
 
-const useInjectedHtml = ({
-	containerRef,
-	html,
-}: {
-	containerRef: RefObject<HTMLDivElement | null>;
-	html: string | null;
-}) => {
-	useEffect(() => {
-		if (!html || !containerRef.current) {
-			return;
-		}
-
-		containerRef.current.innerHTML = html;
-	}, [containerRef, html]);
-};
-
 export const MemoEmbed = ({
 	memo: providedMemo,
 	memoId,
@@ -267,7 +262,6 @@ export const MemoEmbed = ({
 }: MemoEmbedProps) => {
 	const [fetchedMemo, setFetchedMemo] = useState<Memo | null>(null);
 	const [error, setError] = useState<Error | null>(null);
-	const containerRef = useRef<HTMLDivElement | null>(null);
 	const memoClient = useMemoClient(client);
 	const htmlOptions = useEmbedHtmlOptions({
 		theme,
@@ -283,9 +277,13 @@ export const MemoEmbed = ({
 
 	const resolvedMemo = providedMemo ?? fetchedMemo;
 	const canFetch = !providedMemo && Boolean(baseUrl) && Boolean(memoId);
-	const html = resolvedMemo
-		? renderMemoHtmlSnippet(resolvedMemo, htmlOptions)
-		: null;
+	const html = useMemo(
+		() =>
+			resolvedMemo
+				? renderMemoHtmlSnippet(resolvedMemo, htmlOptions)
+				: null,
+		[resolvedMemo, htmlOptions],
+	);
 
 	useEffect(() => {
 		if (!providedMemo) {
@@ -380,8 +378,6 @@ export const MemoEmbed = ({
 		memoClient,
 	]);
 
-	useInjectedHtml({ containerRef, html });
-
 	if (!providedMemo && (!baseUrl || !memoId)) {
 		return renderState({
 			message: "baseUrl and memoId are required when memo is not provided.",
@@ -400,7 +396,7 @@ export const MemoEmbed = ({
 		});
 	}
 
-	if (!resolvedMemo) {
+	if (!resolvedMemo || !html) {
 		return renderState({
 			message: "Loading memo…",
 			className,
@@ -409,7 +405,11 @@ export const MemoEmbed = ({
 		});
 	}
 
-	return <div className={className} style={style} ref={containerRef} />;
+	return renderHtml({
+		html,
+		className,
+		style,
+	});
 };
 
 export const MemoEmbedList = ({
@@ -437,7 +437,6 @@ export const MemoEmbedList = ({
 }: MemoEmbedListProps) => {
 	const [fetchedMemos, setFetchedMemos] = useState<Memo[] | null>(null);
 	const [error, setError] = useState<Error | null>(null);
-	const containerRef = useRef<HTMLDivElement | null>(null);
 	const memoClient = useMemoClient(client);
 	const memoIdsKey = memoIds.join("\u001f");
 	const stableMemoIds = useMemo(() => Array.from(memoIds), [memoIdsKey]);
@@ -455,13 +454,15 @@ export const MemoEmbedList = ({
 		gap,
 	});
 
-	const resolvedMemos = providedMemos
-		? Array.from(providedMemos)
-		: fetchedMemos;
+	const resolvedMemos = providedMemos ?? fetchedMemos;
 	const canFetch = !providedMemos && Boolean(baseUrl) && stableMemoIds.length > 0;
-	const html = resolvedMemos
-		? renderMemoListHtmlSnippet(resolvedMemos, htmlOptions)
-		: null;
+	const html = useMemo(
+		() =>
+			resolvedMemos
+				? renderMemoListHtmlSnippet(resolvedMemos, htmlOptions)
+				: null,
+		[resolvedMemos, htmlOptions],
+	);
 
 	useEffect(() => {
 		if (!providedMemos) {
@@ -556,8 +557,6 @@ export const MemoEmbedList = ({
 		memoClient,
 	]);
 
-	useInjectedHtml({ containerRef, html });
-
 	if (!providedMemos && !baseUrl) {
 		return renderState({
 			message: "baseUrl is required when memos are not provided.",
@@ -585,7 +584,7 @@ export const MemoEmbedList = ({
 		});
 	}
 
-	if (!resolvedMemos) {
+	if (!resolvedMemos || !html) {
 		return renderState({
 			message: "Loading memos…",
 			className,
@@ -598,5 +597,9 @@ export const MemoEmbedList = ({
 		return null;
 	}
 
-	return <div className={className} style={style} ref={containerRef} />;
+	return renderHtml({
+		html,
+		className,
+		style,
+	});
 };