@nifrajs/web-react 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -16,3 +16,11 @@ bun add @nifrajs/web-react
 - AI-readable: <https://nifra.dev/llms.txt>
 
 MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AASjD,6EAA6E;AAC7E,eAAO,MAAM,YAAY,EAAE,aAmB1B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AASjD,6EAA6E;AAC7E,eAAO,MAAM,YAAY,EAAE,aAyB1B,CAAA"}

package/dist/index.js

@@ -3,21 +3,27 @@
  * `renderToReadableStream`; the layout-chain fold is in `./compose`. Client hydration lives in
  * `@nifrajs/web-react/client`. React's JSX is Bun-native — no build plugin needed.
  */
-import { renderToString as reactRenderToString, renderToReadableStream } from "react-dom/server";
 import { compose } from "./compose.js";
+import { reactDomServer } from "./react-dom-server.js";
 /** The React server render adapter — pass to @nifrajs/web's `renderPage`. */
 export const reactAdapter = {
     // Synchronous one-pass render for non-deferred pages (renderPage's buffered fast path). React's
     // `renderToString` emits the same hydration-compatible markup as the Fizz stream for non-Suspense
     // content and is markedly cheaper than `renderToReadableStream` — most visibly on Bun, where Fizz's
     // streaming machinery is the heaviest. A page that defer()s/Suspends takes `renderToStream` below.
-    renderToString(chain, props) {
-        return reactRenderToString(compose(chain, props));
+    //
+    // Async because the `react-dom/server` module is resolved lazily (from the consumer app's node_modules
+    // under Bun runtime SSR — see ./react-dom-server). `RenderAdapter.renderToString` permits a Promise;
+    // renderPage awaits it.
+    async renderToString(chain, props) {
+        const { renderToString } = await reactDomServer();
+        return renderToString(compose(chain, props));
     },
-    renderToStream(chain, props) {
+    async renderToStream(chain, props) {
         // Resolves a Web `ReadableStream<Uint8Array>` once the shell is renderable; Suspense
         // boundaries stream as they resolve. No `bootstrapModules` — nifra injects the client entry in
         // the document tail. React's default `onError` logs to console.error (errors aren't swallowed).
+        const { renderToReadableStream } = await reactDomServer();
         return renderToReadableStream(compose(chain, props));
     },
     // React reconciles against the existing DOM on hydrate, so no per-document bootstrap

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,OAAO,EAAE,cAAc,IAAI,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAChG,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAkB;IACzC,gGAAgG;IAChG,kGAAkG;IAClG,oGAAoG;IACpG,mGAAmG;IACnG,cAAc,CAAC,KAAK,EAAE,KAAK;QACzB,OAAO,mBAAmB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACnD,CAAC;IACD,cAAc,CAAC,KAAK,EAAE,KAAK;QACzB,qFAAqF;QACrF,+FAA+F;QAC/F,gGAAgG;QAChG,OAAO,sBAAsB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,qFAAqF;IACrF,sFAAsF;IACtF,aAAa;QACX,OAAO,EAAE,CAAA;IACX,CAAC;CACF,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAkB;IACzC,gGAAgG;IAChG,kGAAkG;IAClG,oGAAoG;IACpG,mGAAmG;IACnG,EAAE;IACF,uGAAuG;IACvG,qGAAqG;IACrG,wBAAwB;IACxB,KAAK,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK;QAC/B,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,cAAc,EAAE,CAAA;QACjD,OAAO,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IAC9C,CAAC;IACD,KAAK,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK;QAC/B,qFAAqF;QACrF,+FAA+F;QAC/F,gGAAgG;QAChG,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,cAAc,EAAE,CAAA;QACzD,OAAO,sBAAsB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,qFAAqF;IACrF,sFAAsF;IACtF,aAAa;QACX,OAAO,EAAE,CAAA;IACX,CAAC;CACF,CAAA"}

package/dist/react-dom-server.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Resolve `react-dom/server` so it shares ONE React core with the route components — the fix for the
+ * dual-React SSR crash (`resolveDispatcher().useState` is null / "Invalid hook call: mismatching versions
+ * of React and the renderer").
+ *
+ * WHY this exists: under Bun **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process),
+ * a static `import "react-dom/server"` in this adapter is resolved by Bun from THIS package's own
+ * (symlinked) node_modules — which can be a DIFFERENT physical `react` than the one the consumer app's
+ * route components import. Two React cores → two hook dispatchers → the renderer's dispatcher is the wrong
+ * (or null) one → the crash. Resolving `react-dom/server` from the consumer **app root** instead makes
+ * react-dom pull the app's `react` transitively, matching the components' `react`: a single core, a single
+ * dispatcher, no crash. (Empirically verified against a two-copy install fixture — see
+ * test/dual-react.test.ts.)
+ *
+ * Guarding precisely so the PRODUCTION/BUILT path is untouched: when `Bun.resolveSync` is unavailable
+ * (Node / Deno / Cloudflare / Vercel / any bundled output), the build has already bundled+deduped a single
+ * `react-dom` (buildServer's `reactDedupePlugin` pins `react`), so the static `import` is correct AND is
+ * the only thing that works without a Bun resolver. We fall back to it there. The app-root resolution runs
+ * ONLY under the Bun runtime, where the duplication can occur and `Bun.resolveSync` exists.
+ */
+import type { ReactNode } from "react";
+/** The slice of `react-dom/server` this adapter uses. Typed locally so the dynamic import (which Bun
+ * resolves to an absolute path string) stays strict — no `any` crosses the boundary. */
+export interface ReactDomServer {
+    renderToString(node: ReactNode): string;
+    renderToReadableStream(node: ReactNode): Promise<ReadableStream<Uint8Array>>;
+}
+/**
+ * Get `react-dom/server` bound to the consumer app's React. Cached after the first call. Under the Bun
+ * runtime, dynamically imports the copy resolved from the app root; otherwise (built/bundled, or a non-Bun
+ * host) loads the statically-bundled `react-dom/server`.
+ */
+export declare function reactDomServer(): Promise<ReactDomServer>;
+/** A `Bun.resolveSync`-shaped function (specifier, from) → absolute path. */
+type ResolveSync = (specifier: string, from: string) => string;
+/**
+ * Load `react-dom/server`, preferring the app-root-resolved copy under the Bun runtime. Exported for unit
+ * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can
+ * inject a stub that succeeds (re-root branch) or throws (fallback branch) to cover both deterministically
+ * without depending on the machine's node_modules layout.
+ */
+export declare function loadReactDomServer(resolve?: ResolveSync | undefined): Promise<ReactDomServer>;
+export {};
+//# sourceMappingURL=react-dom-server.d.ts.map

package/dist/react-dom-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-dom-server.d.ts","sourceRoot":"","sources":["../src/react-dom-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;wFACwF;AACxF,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;IACvC,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAA;CAC7E;AA4BD;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAAC,cAAc,CAAC,CAIxD;AAED,6EAA6E;AAC7E,KAAK,WAAW,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;AAE9D;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,WAAW,GAAG,SAA2B,GACjD,OAAO,CAAC,cAAc,CAAC,CAiBzB"}

package/dist/react-dom-server.js

@@ -0,0 +1,87 @@
+/**
+ * Resolve `react-dom/server` so it shares ONE React core with the route components — the fix for the
+ * dual-React SSR crash (`resolveDispatcher().useState` is null / "Invalid hook call: mismatching versions
+ * of React and the renderer").
+ *
+ * WHY this exists: under Bun **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process),
+ * a static `import "react-dom/server"` in this adapter is resolved by Bun from THIS package's own
+ * (symlinked) node_modules — which can be a DIFFERENT physical `react` than the one the consumer app's
+ * route components import. Two React cores → two hook dispatchers → the renderer's dispatcher is the wrong
+ * (or null) one → the crash. Resolving `react-dom/server` from the consumer **app root** instead makes
+ * react-dom pull the app's `react` transitively, matching the components' `react`: a single core, a single
+ * dispatcher, no crash. (Empirically verified against a two-copy install fixture — see
+ * test/dual-react.test.ts.)
+ *
+ * Guarding precisely so the PRODUCTION/BUILT path is untouched: when `Bun.resolveSync` is unavailable
+ * (Node / Deno / Cloudflare / Vercel / any bundled output), the build has already bundled+deduped a single
+ * `react-dom` (buildServer's `reactDedupePlugin` pins `react`), so the static `import` is correct AND is
+ * the only thing that works without a Bun resolver. We fall back to it there. The app-root resolution runs
+ * ONLY under the Bun runtime, where the duplication can occur and `Bun.resolveSync` exists.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+const bunResolver = globalThis.Bun;
+const hasBunResolveSync = typeof bunResolver?.resolveSync === "function";
+// Resolve once and cache: the module identity is stable for the process lifetime, and re-resolving per
+// render would pay the import cost on every page. A Promise is cached (not the module) so concurrent
+// first renders share a single in-flight import rather than racing N imports.
+let cached;
+/**
+ * The consumer app root used to re-root `react-dom/server`. `nifra dev` / `nifra start` run with the CLI's
+ * `process.cwd()` set to the app directory, and `nifra_render`'s subprocess `process.chdir`es to the app
+ * dir before SSR (see packages/cli/src/mcp-render.ts), so `process.cwd()` is the app root on every Bun
+ * runtime SSR path. Read lazily (not at module load) so a host that `chdir`s after import still sees the
+ * right root on first render.
+ */
+function appRoot() {
+    return process.cwd();
+}
+/**
+ * Get `react-dom/server` bound to the consumer app's React. Cached after the first call. Under the Bun
+ * runtime, dynamically imports the copy resolved from the app root; otherwise (built/bundled, or a non-Bun
+ * host) loads the statically-bundled `react-dom/server`.
+ */
+export function reactDomServer() {
+    if (cached !== undefined)
+        return cached;
+    cached = loadReactDomServer();
+    return cached;
+}
+/**
+ * Load `react-dom/server`, preferring the app-root-resolved copy under the Bun runtime. Exported for unit
+ * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can
+ * inject a stub that succeeds (re-root branch) or throws (fallback branch) to cover both deterministically
+ * without depending on the machine's node_modules layout.
+ */
+export async function loadReactDomServer(resolve = bunResolverFn()) {
+    if (resolve !== undefined) {
+        // Bun runtime SSR: re-root to the app's copy so react-dom shares the components' React. `react-dom`
+        // is a PEER dependency of this adapter, so a correct install puts it at the app root and this
+        // resolves. If it somehow doesn't (an unusual nested layout), fall through to the bundled specifier
+        // rather than crashing — degraded (possible duplicate) but never a hard failure.
+        try {
+            const resolved = resolve("react-dom/server", appRoot());
+            return (await import(__rewriteRelativeImportExtension(resolved)));
+        }
+        catch {
+            // App-root resolution failed; use the specifier resolved from this module's own location below.
+        }
+    }
+    // Built bundle / Node / Deno / edge (or the Bun-resolve fallback above): the static import is
+    // bundled+deduped (or is the only react-dom present). A bare-specifier dynamic import here lets the
+    // bundler include it (it's a constant), and at runtime resolves the copy visible to this package.
+    return (await import("react-dom/server"));
+}
+/** The ambient `Bun.resolveSync`, or undefined on a non-Bun host (where the static import is the only path). */
+function bunResolverFn() {
+    return hasBunResolveSync && bunResolver?.resolveSync !== undefined
+        ? bunResolver.resolveSync.bind(bunResolver)
+        : undefined;
+}
+//# sourceMappingURL=react-dom-server.js.map

package/dist/react-dom-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-dom-server.js","sourceRoot":"","sources":["../src/react-dom-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;;;;;;;AAkBH,MAAM,WAAW,GAAI,UAA6C,CAAC,GAAG,CAAA;AACtE,MAAM,iBAAiB,GAAG,OAAO,WAAW,EAAE,WAAW,KAAK,UAAU,CAAA;AAExE,uGAAuG;AACvG,qGAAqG;AACrG,8EAA8E;AAC9E,IAAI,MAA2C,CAAA;AAE/C;;;;;;GAMG;AACH,SAAS,OAAO;IACd,OAAO,OAAO,CAAC,GAAG,EAAE,CAAA;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAA;IACvC,MAAM,GAAG,kBAAkB,EAAE,CAAA;IAC7B,OAAO,MAAM,CAAA;AACf,CAAC;AAKD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAmC,aAAa,EAAE;IAElD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,oGAAoG;QACpG,8FAA8F;QAC9F,oGAAoG;QACpG,iFAAiF;QACjF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAA;YACvD,OAAO,CAAC,MAAM,MAAM,kCAAC,QAAQ,EAAC,CAAmB,CAAA;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,gGAAgG;QAClG,CAAC;IACH,CAAC;IACD,8FAA8F;IAC9F,oGAAoG;IACpG,kGAAkG;IAClG,OAAO,CAAC,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAmB,CAAA;AAC7D,CAAC;AAED,gHAAgH;AAChH,SAAS,aAAa;IACpB,OAAO,iBAAiB,IAAI,WAAW,EAAE,WAAW,KAAK,SAAS;QAChE,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC;QAC3C,CAAC,CAAC,SAAS,CAAA;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/web-react",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "React render adapter for @nifrajs/web — SSR + hydration (Bun-native JSX, no Babel).",
   "keywords": [
     "bun",
@@ -75,9 +75,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/i18n": "workspace:*",
-    "@nifrajs/image": "workspace:*",
-    "@nifrajs/web": "workspace:*"
+    "@nifrajs/i18n": "0.1.0-alpha.2",
+    "@nifrajs/image": "0.1.0-alpha.2",
+    "@nifrajs/web": "0.1.0-alpha.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/index.ts

@@ -4,8 +4,8 @@ import type { RenderAdapter } from "@nifrajs/web"
  * `renderToReadableStream`; the layout-chain fold is in `./compose`. Client hydration lives in
  * `@nifrajs/web-react/client`. React's JSX is Bun-native — no build plugin needed.
  */
-import { renderToString as reactRenderToString, renderToReadableStream } from "react-dom/server"
 import { compose } from "./compose.ts"
+import { reactDomServer } from "./react-dom-server.ts"
 
 /** The React server render adapter — pass to @nifrajs/web's `renderPage`. */
 export const reactAdapter: RenderAdapter = {
@@ -13,13 +13,19 @@ export const reactAdapter: RenderAdapter = {
   // `renderToString` emits the same hydration-compatible markup as the Fizz stream for non-Suspense
   // content and is markedly cheaper than `renderToReadableStream` — most visibly on Bun, where Fizz's
   // streaming machinery is the heaviest. A page that defer()s/Suspends takes `renderToStream` below.
-  renderToString(chain, props) {
-    return reactRenderToString(compose(chain, props))
+  //
+  // Async because the `react-dom/server` module is resolved lazily (from the consumer app's node_modules
+  // under Bun runtime SSR — see ./react-dom-server). `RenderAdapter.renderToString` permits a Promise;
+  // renderPage awaits it.
+  async renderToString(chain, props) {
+    const { renderToString } = await reactDomServer()
+    return renderToString(compose(chain, props))
   },
-  renderToStream(chain, props) {
+  async renderToStream(chain, props) {
     // Resolves a Web `ReadableStream<Uint8Array>` once the shell is renderable; Suspense
     // boundaries stream as they resolve. No `bootstrapModules` — nifra injects the client entry in
     // the document tail. React's default `onError` logs to console.error (errors aren't swallowed).
+    const { renderToReadableStream } = await reactDomServer()
     return renderToReadableStream(compose(chain, props))
   },
   // React reconciles against the existing DOM on hydrate, so no per-document bootstrap

package/src/react-dom-server.ts

@@ -0,0 +1,103 @@
+/**
+ * Resolve `react-dom/server` so it shares ONE React core with the route components — the fix for the
+ * dual-React SSR crash (`resolveDispatcher().useState` is null / "Invalid hook call: mismatching versions
+ * of React and the renderer").
+ *
+ * WHY this exists: under Bun **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process),
+ * a static `import "react-dom/server"` in this adapter is resolved by Bun from THIS package's own
+ * (symlinked) node_modules — which can be a DIFFERENT physical `react` than the one the consumer app's
+ * route components import. Two React cores → two hook dispatchers → the renderer's dispatcher is the wrong
+ * (or null) one → the crash. Resolving `react-dom/server` from the consumer **app root** instead makes
+ * react-dom pull the app's `react` transitively, matching the components' `react`: a single core, a single
+ * dispatcher, no crash. (Empirically verified against a two-copy install fixture — see
+ * test/dual-react.test.ts.)
+ *
+ * Guarding precisely so the PRODUCTION/BUILT path is untouched: when `Bun.resolveSync` is unavailable
+ * (Node / Deno / Cloudflare / Vercel / any bundled output), the build has already bundled+deduped a single
+ * `react-dom` (buildServer's `reactDedupePlugin` pins `react`), so the static `import` is correct AND is
+ * the only thing that works without a Bun resolver. We fall back to it there. The app-root resolution runs
+ * ONLY under the Bun runtime, where the duplication can occur and `Bun.resolveSync` exists.
+ */
+
+import type { ReactNode } from "react"
+
+/** The slice of `react-dom/server` this adapter uses. Typed locally so the dynamic import (which Bun
+ * resolves to an absolute path string) stays strict — no `any` crosses the boundary. */
+export interface ReactDomServer {
+  renderToString(node: ReactNode): string
+  renderToReadableStream(node: ReactNode): Promise<ReadableStream<Uint8Array>>
+}
+
+// `globalThis.Bun` isn't in the ambient lib types; narrow exactly the one method we need so we never
+// reach for `any`. `resolveSync(specifier, from)` returns the absolute path the specifier resolves to
+// when required from `from` — Bun's runtime resolver, the only lever that re-roots a BARE specifier
+// (a runtime `Bun.plugin` onResolve does NOT fire for bare specifiers like `react-dom/server`, verified).
+interface BunResolver {
+  resolveSync(specifier: string, from: string): string
+}
+const bunResolver = (globalThis as { Bun?: Partial<BunResolver> }).Bun
+const hasBunResolveSync = typeof bunResolver?.resolveSync === "function"
+
+// Resolve once and cache: the module identity is stable for the process lifetime, and re-resolving per
+// render would pay the import cost on every page. A Promise is cached (not the module) so concurrent
+// first renders share a single in-flight import rather than racing N imports.
+let cached: Promise<ReactDomServer> | undefined
+
+/**
+ * The consumer app root used to re-root `react-dom/server`. `nifra dev` / `nifra start` run with the CLI's
+ * `process.cwd()` set to the app directory, and `nifra_render`'s subprocess `process.chdir`es to the app
+ * dir before SSR (see packages/cli/src/mcp-render.ts), so `process.cwd()` is the app root on every Bun
+ * runtime SSR path. Read lazily (not at module load) so a host that `chdir`s after import still sees the
+ * right root on first render.
+ */
+function appRoot(): string {
+  return process.cwd()
+}
+
+/**
+ * Get `react-dom/server` bound to the consumer app's React. Cached after the first call. Under the Bun
+ * runtime, dynamically imports the copy resolved from the app root; otherwise (built/bundled, or a non-Bun
+ * host) loads the statically-bundled `react-dom/server`.
+ */
+export function reactDomServer(): Promise<ReactDomServer> {
+  if (cached !== undefined) return cached
+  cached = loadReactDomServer()
+  return cached
+}
+
+/** A `Bun.resolveSync`-shaped function (specifier, from) → absolute path. */
+type ResolveSync = (specifier: string, from: string) => string
+
+/**
+ * Load `react-dom/server`, preferring the app-root-resolved copy under the Bun runtime. Exported for unit
+ * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can
+ * inject a stub that succeeds (re-root branch) or throws (fallback branch) to cover both deterministically
+ * without depending on the machine's node_modules layout.
+ */
+export async function loadReactDomServer(
+  resolve: ResolveSync | undefined = bunResolverFn(),
+): Promise<ReactDomServer> {
+  if (resolve !== undefined) {
+    // Bun runtime SSR: re-root to the app's copy so react-dom shares the components' React. `react-dom`
+    // is a PEER dependency of this adapter, so a correct install puts it at the app root and this
+    // resolves. If it somehow doesn't (an unusual nested layout), fall through to the bundled specifier
+    // rather than crashing — degraded (possible duplicate) but never a hard failure.
+    try {
+      const resolved = resolve("react-dom/server", appRoot())
+      return (await import(resolved)) as ReactDomServer
+    } catch {
+      // App-root resolution failed; use the specifier resolved from this module's own location below.
+    }
+  }
+  // Built bundle / Node / Deno / edge (or the Bun-resolve fallback above): the static import is
+  // bundled+deduped (or is the only react-dom present). A bare-specifier dynamic import here lets the
+  // bundler include it (it's a constant), and at runtime resolves the copy visible to this package.
+  return (await import("react-dom/server")) as ReactDomServer
+}
+
+/** The ambient `Bun.resolveSync`, or undefined on a non-Bun host (where the static import is the only path). */
+function bunResolverFn(): ResolveSync | undefined {
+  return hasBunResolveSync && bunResolver?.resolveSync !== undefined
+    ? bunResolver.resolveSync.bind(bunResolver)
+    : undefined
+}