fix(site): pre-bundle react-dom so dev islands hydrate (#1711)

Co-authored-by: Claude <noreply@anthropic.com>

site/CLAUDE.md

@@ -581,17 +581,32 @@ vi.mock('@/types/docs', async () => {
 
 ## Technology Stack
 
-- **[Astro 5.14.4](https://astro.build)**: Static site generation with island architecture
+- **[Astro 6.3.1](https://astro.build)**: Static site generation with island architecture
+- **[Vite 7](https://vite.dev)**: Underlying dev server and bundler (Astro 6 adopts Vite's Environment API — see "Dependency Optimization" gotcha below)
 - **[React 19](https://react.dev)**: Client-side interactive components (`client:load`)
 - **[React Compiler](https://react.dev/learn/react-compiler)**: Enabled via `babel-plugin-react-compiler` targeting React 19
 - **[Tailwind v4](https://tailwindcss.com)**: CSS utility classes via `@tailwindcss/vite`
 - **[Nanostores 1.0.1](https://github.com/nanostores/nanostores)**: Cross-island state
 - **[Base UI 1.2.0](https://base-ui.com)**: Headless accessible components
 - **[Algolia DocSearch v4](https://docsearch.algolia.com)**: Search via Algolia-hosted indexes (docs + blog)
-- **[Shiki 3.13.0](https://shiki.style)**: Syntax highlighting
-- **[Vitest 3.2.4](https://vitest.dev)**: Testing framework
+- **[Shiki 4](https://shiki.style)**: Syntax highlighting
+- **[Vitest 4](https://vitest.dev)**: Testing framework
 - **[clsx](https://github.com/lukeed/clsx)**: Class name concatenation utility
 
+### Dependency Optimization (Vite) — gotcha
+
+`astro.config.mjs` sets `vite.optimizeDeps` (e.g. `exclude` for the workspace
+`@videojs/*` packages and the native `@resvg/resvg-js` binding). Since the
+Astro 6 / Vite 7 upgrade, this root-level `optimizeDeps` **shadows** the
+per-environment `optimizeDeps.include` that renderer integrations
+(`@astrojs/react`) inject via Vite's Environment API — so React's CJS deps stop
+being pre-bundled in **dev only**. The symptom is every React island failing to
+hydrate with `SyntaxError: Importing binding name 'createRoot' is not found`
+(prod is unaffected — Rollup bundles everything). Fix: re-declare the needed
+entries in the site's own `optimizeDeps.include` (currently `react-dom` and
+`react-dom/client`). If you add another renderer integration, include its
+client deps here too.
+
 ## API Reference Generation
 
 > **Source of truth:** [`scripts/api-docs-builder/src/tests/e2e.test.ts`](scripts/api-docs-builder/src/tests/e2e.test.ts)

site/astro.config.mjs

@@ -172,6 +172,11 @@ export default defineConfig({
       // @resvg/resvg-js loads a native .node binding for the server-only OG
       // image route, so Vite's dev optimizer must leave it external.
       exclude: ['@videojs/react', '@videojs/html', '@resvg/resvg-js'],
+      // react-dom (CJS) must be pre-bundled so its named exports (createRoot,
+      // hydrateRoot) are exposed as ESM bindings to the @astrojs/react client
+      // renderer. Excluding @videojs/react above shadows the include list the
+      // React integration injects, so re-declare them here.
+      include: ['react-dom', 'react-dom/client'],
     },
     resolve: {
       dedupe: ['react', 'react-dom'],