@ripple-ts/vite-plugin 0.2.213 → 0.2.215

package/src/index.js

@@ -1,11 +1,10 @@
 /** @import {PackageJson} from 'type-fest' */
 /** @import {Plugin, ResolvedConfig, ViteDevServer} from 'vite' */
-/** @import {RipplePluginOptions, RippleConfigOptions, Route, Middleware, RenderRoute} from '@ripple-ts/vite-plugin' */
+/** @import {RipplePluginOptions, RippleConfigOptions, ResolvedRippleConfig, Route, Middleware, RenderRoute} from '@ripple-ts/vite-plugin' */
 
 /// <reference types="ripple/compiler/internal/rpc" />
 
 import { compile } from 'ripple/compiler';
-import { AsyncLocalStorage } from 'node:async_hooks';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
@@ -15,6 +14,16 @@ import { createRouter } from './server/router.js';
 import { createContext, runMiddlewareChain } from './server/middleware.js';
 import { handleRenderRoute } from './server/render-route.js';
 import { handleServerRoute } from './server/server-route.js';
+import { generateServerEntry } from './server/virtual-entry.js';
+import {
+	getRippleConfigPath,
+	loadRippleConfig,
+	resolveRippleConfig,
+	rippleConfigExists,
+} from './load-config.js';
+import { ENTRY_FILENAME } from './constants.js';
+
+import { patch_global_fetch, is_rpc_request, handle_rpc_request } from '@ripple-ts/adapter/rpc';
 
 // Re-export route classes
 export { RenderRoute, ServerRoute } from './routes.js';
@@ -22,57 +31,41 @@ export { RenderRoute, ServerRoute } from './routes.js';
 const VITE_FS_PREFIX = '/@fs/';
 const IS_WINDOWS = process.platform === 'win32';
 
-// AsyncLocalStorage for request-scoped fetch patching
-const rpcContext = new AsyncLocalStorage();
-
-// Patch fetch once at module level to support relative URLs in #server blocks
-const originalFetch = globalThis.fetch;
+// Dev server always runs in Node — use node:async_hooks as default runtime
+// If the user provides adapter.runtime in their config, that will be used instead.
+import { AsyncLocalStorage } from 'node:async_hooks';
 
-/**
- * Quick check whether a string looks like it already has a URL scheme (e.g. "http://", "https://", "data:").
- * @param {string} url
- * @returns {boolean}
- */
-function hasScheme(url) {
-	return /^[a-z][a-z0-9+\-.]*:/i.test(url);
-}
+/** @type {import('@ripple-ts/adapter/rpc').AsyncContext | null} */
+let devAsyncContext = null;
 
 /**
- * Patch global fetch to resolve relative URLs based on the current request context.
- * This allows server functions in #server blocks to use relative URLs
- * (root-relative like "/api/foo" or path-relative like "api/foo", "./api/foo", "../api/foo")
- * that are resolved against the incoming request's origin.
- * // TODO: a similar logic needs to be ported to the adapters
- * @param {string | Request | URL} input
- * @param {RequestInit} [init]
- * @returns {Promise<Response>}
+ * Get (or lazily create) the dev server's async context.
+ * Uses adapter.runtime.createAsyncContext() if available, otherwise
+ * falls back to Node.js AsyncLocalStorage (always available in dev).
+ *
+ * @param {RippleConfigOptions | null} config
+ * @returns {import('@ripple-ts/adapter/rpc').AsyncContext}
  */
-globalThis.fetch = function (input, init) {
-	const context = rpcContext.getStore();
-
-	if (context?.origin) {
-		// Handle string URLs — resolve any non-absolute URL against the origin
-		if (typeof input === 'string' && !hasScheme(input)) {
-			input = new URL(input, context.origin).href;
-		}
-		// Handle Request objects
-		else if (input instanceof Request) {
-			const url = input.url;
-			if (!hasScheme(url)) {
-				input = new Request(new URL(url, context.origin).href, input);
-			}
-		}
-		// Handle URL objects constructed with relative paths
-		else if (input instanceof URL) {
-			if (!input.protocol || input.protocol === '' || input.origin === 'null') {
-				const relative = input.pathname + (input.search || '') + (input.hash || '');
-				input = new URL(relative, context.origin);
-			}
-		}
+function getDevAsyncContext(config) {
+	if (devAsyncContext) return devAsyncContext;
+
+	const adapterRuntime = config?.adapter?.runtime;
+	if (adapterRuntime?.createAsyncContext) {
+		devAsyncContext = adapterRuntime.createAsyncContext();
+	} else {
+		// Fallback: dev always runs in Node
+		const als = new AsyncLocalStorage();
+		devAsyncContext = {
+			run: (store, fn) => als.run(store, fn),
+			getStore: () => als.getStore(),
+		};
 	}
 
-	return originalFetch(input, init);
-};
+	// Patch fetch once using the async context
+	patch_global_fetch(devAsyncContext);
+
+	return devAsyncContext;
+}
 
 /**
  * @param {string} filename
@@ -317,11 +310,23 @@ export function ripple(inlineOptions = {}) {
 	const ripplePackages = new Set();
 	const cssCache = new Map();
 
-	/** @type {RippleConfigOptions | null} */
+	/** @type {ResolvedRippleConfig | null} */
 	let rippleConfig = null;
 	/** @type {ReturnType<typeof createRouter> | null} */
 	let router = null;
 
+	/** @type {boolean} */
+	let isBuild = false;
+	/** @type {boolean} */
+	let isSSRBuild = false;
+
+	/** @type {string[]} Render route entry paths for client hydration import map */
+	let renderRouteEntries = [];
+	/** @type {ResolvedRippleConfig | null} Cached config from buildStart (reused in closeBundle) */
+	let loadedRippleConfig = null;
+	/** @type {Set<string>} File paths (relative to root) of .ripple modules with #server blocks */
+	const serverBlockModules = new Set();
+
 	/** @type {Plugin[]} */
 	const plugins = [
 		{
@@ -330,7 +335,78 @@ export function ripple(inlineOptions = {}) {
 			enforce: 'pre',
 			api,
 
-			async config(userConfig) {
+			async config(userConfig, { command }) {
+				isBuild = command === 'build';
+				isSSRBuild = !!userConfig.build?.ssr;
+
+				// In build mode (client build, not the SSR sub-build), configure for production
+				if (isBuild && !isSSRBuild) {
+					const projectRoot = userConfig.root || process.cwd();
+
+					if (rippleConfigExists(projectRoot)) {
+						const htmlInput = path.join(projectRoot, 'index.html');
+						if (!fs.existsSync(htmlInput)) {
+							throw new Error(
+								'[@ripple-ts/vite-plugin] index.html not found. ' +
+									'Required for SSR builds with ripple.config.ts.',
+							);
+						}
+
+						console.log(
+							'[@ripple-ts/vite-plugin] Detected ripple.config.ts — configuring client build',
+						);
+
+						// Load ripple.config.ts early so build options (e.g. minify) can
+						// influence the client build config returned from this hook.
+						// The loaded config is cached and reused by
+						// buildStart and closeBundle.
+						loadedRippleConfig = await loadRippleConfig(projectRoot);
+
+						const outDir = loadedRippleConfig.build.outDir;
+
+						// Build Rollup inputs: HTML template + each page entry as a
+						// separate input. This gives Vite proper per-page code splitting
+						// and produces manifest entries for each page chunk.
+						/** @type {Record<string, string>} */
+						const rollupInput = { main: htmlInput };
+
+						const renderRoutes = loadedRippleConfig.router.routes.filter(
+							(/** @type {Route} */ r) => r.type === 'render',
+						);
+						const uniqueEntries = [
+							...new Set(renderRoutes.map((/** @type {RenderRoute} */ r) => r.entry)),
+						];
+						for (const entry of uniqueEntries) {
+							const sourcePath = entry.startsWith('/') ? entry.slice(1) : entry;
+							rollupInput[sourcePath] = path.join(projectRoot, sourcePath);
+						}
+						console.log(
+							`[@ripple-ts/vite-plugin] Adding ${uniqueEntries.length} page entry/entries as Rollup inputs`,
+						);
+
+						/** @type {import('vite').UserConfig['build']} */
+						const buildConfig = {
+							outDir: `${outDir}/client`,
+							emptyOutDir: true,
+							manifest: true,
+							rollupOptions: {
+								input: rollupInput,
+							},
+						};
+
+						// Only override minify when explicitly set in ripple.config.ts;
+						// otherwise let Vite's default (esbuild) apply.
+						if (loadedRippleConfig.build.minify !== undefined) {
+							buildConfig.minify = loadedRippleConfig.build.minify;
+						}
+
+						return {
+							appType: 'custom',
+							build: buildConfig,
+						};
+					}
+				}
+
 				if (excludeRippleExternalModules) {
 					return {
 						optimizeDeps: {
@@ -374,6 +450,32 @@ export function ripple(inlineOptions = {}) {
 				config = resolvedConfig;
 			},
 
+			/**
+			 * Load render route entries before the client build so virtual:ripple-hydrate
+			 * can generate static import() calls that Vite will bundle.
+			 */
+			async buildStart() {
+				if (!isBuild || isSSRBuild) return;
+
+				// Reuse config loaded in the config hook if available;
+				// otherwise load it now as a fallback.
+				if (!loadedRippleConfig) {
+					if (!rippleConfigExists(root)) return;
+					loadedRippleConfig = await loadRippleConfig(root);
+				}
+
+				renderRouteEntries = loadedRippleConfig.router.routes
+					.filter((/** @type {Route} */ r) => r.type === 'render')
+					.map((/** @type {RenderRoute} */ r) => r.entry);
+
+				// Deduplicate entries (multiple routes can share the same component)
+				renderRouteEntries = [...new Set(renderRouteEntries)];
+
+				console.log(
+					`[@ripple-ts/vite-plugin] Found ${renderRouteEntries.length} render route(s) for client hydration`,
+				);
+			},
+
 			/**
 			 * Configure the dev server with SSR middleware
 			 * @param {ViteDevServer} vite
@@ -381,21 +483,10 @@ export function ripple(inlineOptions = {}) {
 			configureServer(vite) {
 				// Return a function to be called after Vite's internal middlewares
 				return async () => {
-					// Load ripple.config.ts
-					const configPath = path.join(root, 'ripple.config.ts');
-					if (!fs.existsSync(configPath)) {
-						console.log('[@ripple-ts/vite-plugin] No ripple.config.ts found, skipping SSR setup');
-						return;
-					}
+					if (!rippleConfigExists(root)) return;
 
 					try {
-						const configModule = await vite.ssrLoadModule(configPath);
-						rippleConfig = configModule.default;
-
-						if (!rippleConfig?.router?.routes) {
-							console.log('[@ripple-ts/vite-plugin] No routes defined in ripple.config.ts');
-							return;
-						}
+						rippleConfig = await loadRippleConfig(root, { vite });
 
 						// Create router from config
 						router = createRouter(rippleConfig.router.routes);
@@ -421,13 +512,13 @@ export function ripple(inlineOptions = {}) {
 							const method = req.method || 'GET';
 
 							// Handle RPC requests for #server blocks
-							if (url.pathname.startsWith('/_$_ripple_rpc_$_/')) {
+							if (is_rpc_request(url.pathname)) {
 								await handleRpcRequest(
 									req,
 									res,
-									url,
 									vite,
-									rippleConfig.server?.trustProxy ?? false,
+									rippleConfig.server.trustProxy,
+									rippleConfig,
 								);
 								return;
 							}
@@ -442,20 +533,14 @@ export function ripple(inlineOptions = {}) {
 
 							try {
 								// Reload config to get fresh routes (for HMR)
-								const freshConfig = await vite.ssrLoadModule(configPath);
-								rippleConfig = freshConfig.default;
-
-								if (!rippleConfig || !rippleConfig.router || !rippleConfig.router.routes) {
-									console.log('[@ripple-ts/vite-plugin] No routes defined in ripple.config.ts');
-									next();
-									return;
+								const previousRoutes = rippleConfig.router.routes;
+								const freshConfig = await loadRippleConfig(root, { vite });
+								if (freshConfig) {
+									rippleConfig = freshConfig;
 								}
 
 								// Check if routes have changed
-								if (
-									JSON.stringify(freshConfig.default.router.routes) !==
-									JSON.stringify(rippleConfig.router.routes)
-								) {
+								if (JSON.stringify(previousRoutes) !== JSON.stringify(rippleConfig.router.routes)) {
 									console.log(
 										`[@ripple-ts/vite-plugin] Detected route changes. Re-loading ${rippleConfig.router.routes.length} routes from ripple.config.ts`,
 									);
@@ -474,8 +559,7 @@ export function ripple(inlineOptions = {}) {
 								const request = nodeRequestToWebRequest(req);
 								const context = createContext(request, freshMatch.params);
 
-								// Get global middlewares
-								const globalMiddlewares = rippleConfig.middlewares || [];
+								const globalMiddlewares = rippleConfig.middlewares;
 
 								let response;
 
@@ -523,6 +607,266 @@ export function ripple(inlineOptions = {}) {
 				};
 			},
 
+			/**
+			 * Handle HMR for files that Vite's default module HMR can't
+			 * properly refresh.
+			 *
+			 * .ripple components self-accept HMR and swap their component
+			 * function. For changes to their OWN code this works perfectly.
+			 * But for changes to DEPENDENCIES (e.g. .md files imported via
+			 * import.meta.glob), the self-accept handler can't refresh
+			 * static imports cached in the browser's ESM module registry.
+			 *
+			 * Strategy:
+			 * - If all changed modules self-accept → they can hot-replace
+			 *   themselves (e.g. .ripple components, CSS). Let Vite handle.
+			 * - Otherwise, check the SSR module graph. If the file is there,
+			 *   invalidate SSR cache and trigger a full page reload.
+			 */
+			hotUpdate({ file, modules, server }) {
+				if (this.environment.name !== 'client') return;
+
+				// If all changed modules self-accept, they can hot-replace
+				// themselves (.ripple components, CSS modules). Let Vite
+				// handle without intervention.
+				if (modules.length > 0 && modules.every((m) => m.isSelfAccepting)) {
+					return;
+				}
+
+				// Check if this file is part of the SSR module graph.
+				const ssr = server.environments.ssr;
+				if (!ssr) return;
+
+				const ssr_modules = ssr.moduleGraph.getModulesByFile(file);
+				if (!ssr_modules || ssr_modules.size === 0) return;
+
+				// Invalidate SSR modules so the server re-reads the file
+				// on next request instead of serving stale cached content.
+				for (const mod of ssr_modules) {
+					ssr.moduleGraph.invalidateModule(mod);
+				}
+
+				// Full reload — the only reliable way to pick up the change
+				// for files that don't self-accept but are consumed by the app.
+				this.environment.hot.send({ type: 'full-reload' });
+				return [];
+			},
+
+			/**
+			 * Inject the hydration script into the HTML template during build.
+			 * In dev mode, this is handled by render-route.js instead.
+			 */
+			transformIndexHtml: {
+				order: 'pre',
+				handler(html) {
+					if (!isBuild || isSSRBuild) return html;
+
+					// Inject the hydration client entry script before </body>
+					const hydrationScript = `<script type="module" src="virtual:ripple-hydrate"></script>`;
+					return html.replace('</body>', `${hydrationScript}\n</body>`);
+				},
+			},
+
+			/**
+			 * After the client build completes, trigger the SSR server build.
+			 * This only runs for the primary (non-SSR) build.
+			 */
+			async closeBundle() {
+				if (!isBuild || isSSRBuild) return;
+
+				// Reuse config loaded in buildStart, or load it now as fallback
+				if (!loadedRippleConfig) {
+					if (!rippleConfigExists(root)) return;
+					loadedRippleConfig = await loadRippleConfig(root);
+				}
+
+				console.log('[@ripple-ts/vite-plugin] Client build done. Starting server build...');
+
+				// Re-resolve with adapter validation for production builds.
+				// loadRippleConfig already resolved the config, but the adapter
+				// is only required for production server builds.
+				loadedRippleConfig = resolveRippleConfig(loadedRippleConfig, { requireAdapter: true });
+
+				const outDir = loadedRippleConfig.build.outDir;
+
+				// ------------------------------------------------------------------
+				// Read Vite's client manifest and build a per-route asset map.
+				// This lets the production server emit <link rel="stylesheet"> and
+				// <link rel="modulepreload"> tags for every CSS/JS file a page
+				// needs (including transitive dependencies).
+				// ------------------------------------------------------------------
+				const clientOutDir = path.join(root, outDir, 'client');
+				const manifestPath = path.join(clientOutDir, '.vite', 'manifest.json');
+
+				/** @type {Record<string, { file: string, css?: string[], imports?: string[], name?: string }>} */
+				let clientManifest = {};
+				if (fs.existsSync(manifestPath)) {
+					clientManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+				} else {
+					console.warn(
+						'[@ripple-ts/vite-plugin] Client manifest not found at',
+						manifestPath,
+						'— asset preloading will be unavailable',
+					);
+				}
+
+				/**
+				 * Recursively collect all CSS files from a manifest entry and its
+				 * imports, avoiding cycles via a visited set.
+				 * @param {string} key - Manifest key (source-relative path)
+				 * @param {Set<string>} [visited] - Already visited keys
+				 * @returns {string[]}
+				 */
+				const collectCss = (key, visited = new Set()) => {
+					if (visited.has(key)) return [];
+					visited.add(key);
+					const entry = clientManifest[key];
+					if (!entry) return [];
+					/** @type {string[]} */
+					const css = [...(entry.css || [])];
+					for (const imp of entry.imports || []) {
+						css.push(...collectCss(imp, visited));
+					}
+					return css;
+				};
+
+				// Build a map of route entry → { js, css } from the manifest
+				/** @type {Record<string, { js: string, css: string[] }>} */
+				const clientAssetMap = {};
+
+				const renderRoutes = loadedRippleConfig.router.routes.filter(
+					(/** @type {Route} */ r) => r.type === 'render',
+				);
+				const uniqueEntries = [
+					...new Set(renderRoutes.map((/** @type {RenderRoute} */ r) => r.entry)),
+				];
+
+				for (const entry of uniqueEntries) {
+					const manifestKey = entry.startsWith('/') ? entry.slice(1) : entry;
+					const manifestEntry = clientManifest[manifestKey];
+					if (manifestEntry) {
+						clientAssetMap[entry] = {
+							js: manifestEntry.file,
+							css: [...new Set(collectCss(manifestKey))],
+						};
+					}
+				}
+
+				// Find the hydrate runtime entry in the manifest
+				let hydrateJsAsset = '';
+				for (const [key, value] of Object.entries(clientManifest)) {
+					if (key.includes('virtual:ripple-hydrate') || value.name === '__ripple_hydrate') {
+						hydrateJsAsset = value.file;
+						break;
+					}
+				}
+
+				if (hydrateJsAsset) {
+					// Store as a special key so the server can modulepreload it
+					clientAssetMap.__hydrate_js = { js: hydrateJsAsset, css: [] };
+				}
+
+				console.log(
+					`[@ripple-ts/vite-plugin] Built client asset map for ${Object.keys(clientAssetMap).length} entries`,
+				);
+
+				// Remove the .vite folder from the client build output.
+				// The manifest was only needed at build time to construct the
+				// clientAssetMap above. Leaving it in dist/client would expose
+				// source file paths publicly via the static file server.
+				const viteMetaDir = path.join(clientOutDir, '.vite');
+				try {
+					fs.rmSync(viteMetaDir, { recursive: true, force: true });
+					console.log('[@ripple-ts/vite-plugin] Removed .vite metadata from client output');
+				} catch {
+					// Non-fatal — warn but continue
+					console.warn('[@ripple-ts/vite-plugin] Could not remove .vite folder from client output');
+				}
+
+				// Generate the virtual server entry
+				const serverEntryCode = generateServerEntry({
+					routes: loadedRippleConfig.router.routes,
+					rippleConfigPath: getRippleConfigPath(root),
+					htmlTemplatePath: './index.html',
+					rpcModulePaths: [...serverBlockModules],
+					clientAssetMap,
+				});
+
+				const VIRTUAL_SERVER_ENTRY_ID = 'virtual:ripple-server-entry';
+				const RESOLVED_VIRTUAL_SERVER_ENTRY_ID = '\0' + VIRTUAL_SERVER_ENTRY_ID;
+
+				/** @type {Plugin} */
+				const virtualEntryPlugin = {
+					name: 'ripple-virtual-server-entry',
+					resolveId(id) {
+						if (id === VIRTUAL_SERVER_ENTRY_ID) return RESOLVED_VIRTUAL_SERVER_ENTRY_ID;
+					},
+					load(id) {
+						if (id === RESOLVED_VIRTUAL_SERVER_ENTRY_ID) return serverEntryCode;
+					},
+				};
+
+				const serverOutDir = path.join(root, outDir, 'server');
+
+				// Do NOT add ripple() here — the user's vite.config.ts (loaded automatically
+				// from `root`) already includes it. Adding another instance causes double
+				// compilation of .ripple files.
+				const { build: viteBuild } = await import('vite');
+				try {
+					await viteBuild({
+						root,
+						appType: 'custom',
+						plugins: [virtualEntryPlugin],
+						build: {
+							outDir: serverOutDir,
+							emptyOutDir: true,
+							ssr: true,
+							target: loadedRippleConfig?.build?.target,
+							minify: loadedRippleConfig?.build?.minify ?? false,
+							rollupOptions: {
+								input: VIRTUAL_SERVER_ENTRY_ID,
+								output: {
+									entryFileNames: ENTRY_FILENAME,
+									format: 'esm',
+								},
+							},
+						},
+						ssr: {
+							external: [
+								'@ripple-ts/adapter',
+								'@ripple-ts/adapter-node',
+								'@ripple-ts/adapter-bun',
+								'@ripple-ts/adapter-vercel',
+							],
+							noExternal: [],
+						},
+					});
+
+					// Copy the HTML template into the server output so the server
+					// entry is self-contained and doesn't depend on dist/client/.
+					// This is critical for platforms like Vercel where dist/client/
+					// is served as static files and index.html would be returned as-is
+					// (with unresolved SSR placeholders) instead of going through SSR.
+					const clientHtml = path.join(clientOutDir, 'index.html');
+					const serverHtml = path.join(serverOutDir, 'index.html');
+					if (fs.existsSync(clientHtml)) {
+						fs.copyFileSync(clientHtml, serverHtml);
+						console.log('[@ripple-ts/vite-plugin] Copied HTML template to server output');
+					}
+
+					console.log('[@ripple-ts/vite-plugin] Server build complete.');
+					console.log(`[@ripple-ts/vite-plugin] Output: ${path.join(root, outDir)}`);
+					console.log(
+						`[@ripple-ts/vite-plugin] Start with: node ${outDir}/server/${ENTRY_FILENAME}`,
+					);
+				} catch (/** @type {any} */ error) {
+					console.error('[@ripple-ts/vite-plugin] Server build failed:', error);
+					throw new Error(
+						`Server build failed: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			},
+
 			async resolveId(id, importer, options) {
 				// Handle virtual hydrate module
 				if (id === 'virtual:ripple-hydrate') {
@@ -571,21 +915,45 @@ export function ripple(inlineOptions = {}) {
 			async load(id, opts) {
 				// Handle virtual hydrate module
 				if (id === '\0virtual:ripple-hydrate') {
-					return `
+					if (isBuild && renderRouteEntries.length > 0) {
+						// Production: generate static import map so Vite bundles page components
+						const importMapLines = renderRouteEntries
+							.map((entry) => `  ${JSON.stringify(entry)}: () => import(${JSON.stringify(entry)}),`)
+							.join('\n');
+
+						// IMPORTANT: Use async IIFE instead of top-level await.
+						// The page modules statically import from the main bundle (which contains
+						// the runtime). If we used top-level await here, it would deadlock:
+						// main bundle awaits page module import → page module awaits main bundle's
+						// TLA to complete → circular wait.
+						return `
 import { hydrate, mount } from 'ripple';
 
-const data = JSON.parse(document.getElementById('__ripple_data').textContent);
-const target = document.getElementById('root');
+const routeModules = {
+${importMapLines}
+};
+
+(async () => {
+  try {
+    const data = JSON.parse(document.getElementById('__ripple_data').textContent);
+    const target = document.getElementById('root');
+    const loadModule = routeModules[data.entry];
 
-try {
-  const module = await import(/* @vite-ignore */ data.entry);
-  const Component =
-    module.default ||
-    Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
+    if (!loadModule) {
+      console.error('[ripple] No client module for route:', data.entry);
+      return;
+    }
+
+    const module = await loadModule();
+    const Component =
+      module.default ||
+      Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
+
+    if (!Component || !target) {
+      console.error('[ripple] Unable to hydrate route: missing component export or #root target.');
+      return;
+    }
 
-  if (!Component || !target) {
-    console.error('[ripple] Unable to hydrate route: missing component export or #root target.');
-  } else {
     try {
       hydrate(Component, {
         target,
@@ -598,10 +966,48 @@ try {
         props: { params: data.params }
       });
     }
+  } catch (error) {
+    console.error('[ripple] Failed to bootstrap client hydration.', error);
   }
-} catch (error) {
-  console.error('[ripple] Failed to bootstrap client hydration.', error);
-}
+})();
+`;
+					}
+
+					// Dev mode: use async IIFE to avoid top-level await deadlock
+					// (same reason as production — page modules import from the main bundle)
+					return `
+import { hydrate, mount } from 'ripple';
+
+(async () => {
+  try {
+    const data = JSON.parse(document.getElementById('__ripple_data').textContent);
+    const target = document.getElementById('root');
+    const module = await import(/* @vite-ignore */ data.entry);
+    const Component =
+      module.default ||
+      Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
+
+    if (!Component || !target) {
+      console.error('[ripple] Unable to hydrate route: missing component export or #root target.');
+      return;
+    }
+
+    try {
+      hydrate(Component, {
+        target,
+        props: { params: data.params }
+      });
+    } catch (error) {
+      console.warn('[ripple] Hydration failed, falling back to mount.', error);
+      mount(Component, {
+        target,
+        props: { params: data.params }
+      });
+    }
+  } catch (error) {
+    console.error('[ripple] Failed to bootstrap client hydration.', error);
+  }
+})();
 `;
 				}
 
@@ -617,11 +1023,19 @@ try {
 					const filename = id.replace(root, '');
 					const ssr = opts?.ssr === true || this.environment.config.consumer === 'server';
 
+					const is_dev = config?.command === 'serve';
+
 					const { js, css } = await compile(code, filename, {
 						mode: ssr ? 'server' : 'client',
-						dev: config?.command === 'serve',
+						dev: is_dev,
+						hmr: is_dev && !ssr,
 					});
 
+					// Track modules with #server blocks for RPC (client build only)
+					if (isBuild && !ssr && js.code.includes('_$_.rpc(')) {
+						serverBlockModules.add(filename);
+					}
+
 					if (css !== '') {
 						const cssId = createVirtualImportId(filename, root, 'style');
 						cssCache.set(cssId, css);
@@ -638,7 +1052,7 @@ try {
 }
 
 // This is mainly to enforce types and provide a better DX with types than anything else
-export function defineConfig(/** @type {RipplePluginOptions} */ options) {
+export function defineConfig(/** @type {RippleConfigOptions} */ options) {
 	return options;
 }
 
@@ -646,39 +1060,6 @@ export function defineConfig(/** @type {RipplePluginOptions} */ options) {
 // Helper functions for dev server
 // ============================================================================
 
-/**
- * Derive the request origin (protocol + host) from a Node.js request.
- * Only honors `X-Forwarded-Proto` and `X-Forwarded-Host` headers when
- * `trustProxy` is explicitly enabled; otherwise the protocol comes from the
- * socket and the host from the `Host` header.
- *
- * @param {import('node:http').IncomingMessage} req
- * @param {boolean} trustProxy
- * @returns {string}
- */
-function deriveOrigin(req, trustProxy) {
-	let protocol = /** @type {import('node:tls').TLSSocket} */ (req.socket).encrypted
-		? 'https'
-		: 'http';
-	let host = req.headers.host || 'localhost';
-
-	if (trustProxy) {
-		const forwardedProto = req.headers['x-forwarded-proto'];
-		const proto = Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto;
-		if (proto) {
-			protocol = proto.split(',')[0].trim();
-		}
-
-		const forwardedHost = req.headers['x-forwarded-host'];
-		const fwdHost = Array.isArray(forwardedHost) ? forwardedHost[0] : forwardedHost;
-		if (fwdHost) {
-			host = fwdHost.split(',')[0].trim();
-		}
-	}
-
-	return `${protocol}://${host}`;
-}
-
 /**
  * Convert a Node.js IncomingMessage to a Web Request
  * @param {import('node:http').IncomingMessage} nodeRequest
@@ -746,62 +1127,50 @@ async function sendWebResponse(nodeResponse, webResponse) {
 }
 
 /**
- * Handle RPC requests for #server blocks
+ * Handle RPC requests for #server blocks in dev mode.
+ *
+ * Delegates to the shared `handle_rpc_request` from `@ripple-ts/adapter/rpc`,
+ * providing a dev-specific `resolveFunction` that uses Vite's `ssrLoadModule`
+ * and `globalThis.rpc_modules` (populated by the compiler during SSR).
+ *
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
- * @param {URL} url
  * @param {import('vite').ViteDevServer} vite
  * @param {boolean} trustProxy
+ * @param {RippleConfigOptions | null} config
  */
-async function handleRpcRequest(req, res, url, vite, trustProxy) {
-	// we don't really need trustProxy in vite but leaving it as a model for production adapters
+async function handleRpcRequest(req, res, vite, trustProxy, config) {
 	try {
-		const hash = url.pathname.slice('/_$_ripple_rpc_$_/'.length);
-
-		// Get request body
-		const body = await getRequestBody(req);
-
-		// Load the RPC module info from globalThis (set during SSR)
-		const rpcModules = /** @type {Map<string, [string, string]>} */ (
-			/** @type {any} */ (globalThis).rpc_modules
-		);
-		if (!rpcModules) {
-			res.statusCode = 500;
-			res.end('RPC modules not initialized');
-			return;
-		}
-
-		const moduleInfo = rpcModules.get(hash);
-		if (!moduleInfo) {
-			res.statusCode = 404;
-			res.end(`RPC function not found: ${hash}`);
-			return;
-		}
-
-		const [filePath, funcName] = moduleInfo;
-
-		// Load the module and execute the function
-		const { executeServerFunction } = await vite.ssrLoadModule('ripple/server');
-		const module = await vite.ssrLoadModule(filePath);
-		const server = module._$_server_$_;
-
-		if (!server || !server[funcName]) {
-			res.statusCode = 404;
-			res.end(`Server function not found: ${funcName}`);
-			return;
-		}
+		// Convert Node request to Web Request for the shared handler
+		const webRequest = nodeRequestToWebRequest(req);
+		const asyncContext = getDevAsyncContext(config);
+
+		const response = await handle_rpc_request(webRequest, {
+			async resolveFunction(hash) {
+				const rpcModules = /** @type {Map<string, [string, string]>} */ (
+					/** @type {any} */ (globalThis).rpc_modules
+				);
+				if (!rpcModules) return null;
 
-		const origin = deriveOrigin(req, trustProxy);
+				const moduleInfo = rpcModules.get(hash);
+				if (!moduleInfo) return null;
 
-		// Execute server function within async context
-		// This allows the patched fetch to access the origin without global state
-		await rpcContext.run({ origin }, async () => {
-			const result = await executeServerFunction(server[funcName], body);
+				const [filePath, funcName] = moduleInfo;
+				const module = await vite.ssrLoadModule(filePath);
+				const server = module._$_server_$_;
 
-			res.statusCode = 200;
-			res.setHeader('Content-Type', 'application/json');
-			res.end(result);
+				if (!server || !server[funcName]) return null;
+				return server[funcName];
+			},
+			async executeServerFunction(fn, body) {
+				const { executeServerFunction } = await vite.ssrLoadModule('ripple/server');
+				return executeServerFunction(fn, body);
+			},
+			asyncContext,
+			trustProxy,
 		});
+
+		await sendWebResponse(res, response);
 	} catch (error) {
 		console.error('[@ripple-ts/vite-plugin] RPC error:', error);
 		res.statusCode = 500;
@@ -810,26 +1179,6 @@ async function handleRpcRequest(req, res, url, vite, trustProxy) {
 	}
 }
 
-/**
- * Get the body of a request as a string
- * @param {import('node:http').IncomingMessage} req
- * @returns {Promise<string>}
- */
-function getRequestBody(req) {
-	return new Promise((resolve, reject) => {
-		let data = '';
-		req.on('data', (chunk) => {
-			data += chunk;
-			if (data.length > 1e6) {
-				req.destroy();
-				reject(new Error('Request body too large'));
-			}
-		});
-		req.on('end', () => resolve(data));
-		req.on('error', reject);
-	});
-}
-
 /**
  * Escape HTML entities
  * @param {string} str