@useavalon/avalon 0.1.11 → 0.1.13

package/src/vite-plugin/nitro-integration.ts

@@ -1,1354 +1,1354 @@
-/**
- * Nitro Integration Module for Avalon Vite Plugin
- *
- * Provides coordination between Avalon's Vite plugin and Nitro:
- * - API routes: Auto-discovered by Nitro from `api/` directory
- * - Page routes: Virtual module for SSR page component discovery
- * - Middleware: Auto-discovered by Nitro from `middleware/` directory
- */
-
-import type { Plugin, ViteDevServer } from 'vite';
-import { nitro as nitroVitePlugin } from 'nitro/vite';
-import { stat as fsStat } from 'node:fs/promises';
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-import type { ResolvedAvalonConfig } from './types.ts';
-import { createNitroConfig, type AvalonNitroConfig, type NitroConfigOutput } from '../nitro/config.ts';
-import type { PageModule } from '../nitro/types.ts';
-import {
-	createNitroBuildPlugin,
-	createIslandManifestPlugin,
-	createSourceMapPlugin,
-	createSourceMapConfig,
-} from '../nitro/index.ts';
-import { discoverScopedMiddleware, executeScopedMiddleware, clearMiddlewareCache } from '../middleware/index.ts';
-import type { MiddlewareRoute } from '../middleware/types.ts';
-import type { H3Event } from 'h3';
-import { generateErrorPage, generateFallback404 } from '../render/error-pages.ts';
-import { collectCssFromModuleGraph, injectSsrCss } from '../render/collect-css.ts';
-import { getUniversalCSSForHead } from '../islands/universal-css-collector.ts';
-import { getUniversalHeadForInjection } from '../islands/universal-head-collector.ts';
-
-/**
- * Resolves the absolute path to a file inside @useavalon/avalon's source tree.
- */
-function resolveAvalonPackagePath(relativePath: string): string {
-	const require = createRequire(import.meta.url);
-	const modEntry = require.resolve('@useavalon/avalon');
-	const pkgRoot = dirname(modEntry);
-	return join(pkgRoot, relativePath);
-}
-
-/**
- * Resolves the absolute path to a file inside an @useavalon/<name> integration package.
- */
-function resolveIntegrationPackagePath(name: string, relativePath: string): string {
-	const require = createRequire(join(process.cwd(), 'package.json'));
-	const modEntry = require.resolve(`@useavalon/${name}`);
-	const pkgRoot = dirname(modEntry);
-	return join(pkgRoot, relativePath);
-}
-
-export const VIRTUAL_MODULE_IDS = {
-	PAGE_ROUTES: 'virtual:avalon/page-routes',
-	ISLAND_MANIFEST: 'virtual:avalon/island-manifest',
-	RUNTIME_CONFIG: 'virtual:avalon/runtime-config',
-	CONFIG: 'virtual:avalon/config',
-} as const;
-
-export const RESOLVED_VIRTUAL_IDS = {
-	PAGE_ROUTES: '\0' + VIRTUAL_MODULE_IDS.PAGE_ROUTES,
-	ISLAND_MANIFEST: '\0' + VIRTUAL_MODULE_IDS.ISLAND_MANIFEST,
-	RUNTIME_CONFIG: '\0' + VIRTUAL_MODULE_IDS.RUNTIME_CONFIG,
-	CONFIG: '\0' + VIRTUAL_MODULE_IDS.CONFIG,
-} as const;
-
-export interface NitroIntegrationResult {
-	nitroOptions: NitroConfigOutput;
-	plugins: Plugin[];
-}
-
-export interface NitroCoordinationPluginOptions {
-	avalonConfig: ResolvedAvalonConfig;
-	nitroConfig: AvalonNitroConfig;
-	verbose?: boolean;
-}
-
-/**
- * Creates the Nitro integration for Avalon — configuration, virtual modules,
- * build plugins, and SSR coordination.
- *
- * Uses the Nitro v3 Vite plugin from `nitro/vite` for server route discovery,
- * SSR rendering pipeline, and Rolldown-optimized bundling.
- */
-export function createNitroIntegration(
-	avalonConfig: ResolvedAvalonConfig,
-	nitroConfig: AvalonNitroConfig = {},
-): NitroIntegrationResult {
-	const nitroOptions = createNitroConfig(nitroConfig, avalonConfig);
-
-	// Nitro v3 Vite plugin — only pass keys that Nitro actually accepts.
-	// Spreading the full nitroOptions leaks Avalon-specific keys (staticAssets,
-	// publicAssets, etc.) which Nitro forwards to Rolldown, causing
-	// "Invalid input options" warnings (e.g. "jsx" key errors).
-	const nitroVitePluginOptions: Record<string, unknown> = {
-		preset: nitroOptions.preset,
-		serverDir: nitroConfig.serverDir ?? nitroOptions.serverDir ?? './server',
-		routeRules: nitroOptions.routeRules,
-		runtimeConfig: nitroOptions.runtimeConfig,
-		renderer: nitroConfig.renderer === false ? false : nitroOptions.renderer,
-		compatibilityDate: nitroOptions.compatibilityDate,
-		// Tell Nitro to scan the project root so it discovers routes/ and middleware/
-		// alongside the serverDir (./server) which contains the catch-all renderer.
-		scanDirs: ['.'],
-	};
-
-	// Only include optional keys if they're defined
-	if (nitroOptions.publicRuntimeConfig) {
-		nitroVitePluginOptions.publicRuntimeConfig = nitroOptions.publicRuntimeConfig;
-	}
-	if (nitroOptions.publicAssets) {
-		nitroVitePluginOptions.publicAssets = nitroOptions.publicAssets;
-	}
-	if (nitroOptions.compressPublicAssets) {
-		nitroVitePluginOptions.compressPublicAssets = nitroOptions.compressPublicAssets;
-	}
-	if (nitroOptions.serverEntry) {
-		nitroVitePluginOptions.serverEntry = nitroOptions.serverEntry;
-	}
-
-	const nitroPlugin = nitroVitePlugin(nitroVitePluginOptions);
-
-	const coordinationPlugin = createNitroCoordinationPlugin({
-		avalonConfig,
-		nitroConfig,
-		verbose: avalonConfig.verbose,
-	});
-
-	const virtualModulesPlugin = createVirtualModulesPlugin({
-		avalonConfig,
-		nitroConfig,
-		verbose: avalonConfig.verbose,
-	});
-
-	const buildPlugin = createNitroBuildPlugin(avalonConfig, nitroConfig);
-
-	const manifestPlugin = createIslandManifestPlugin(avalonConfig, {
-		verbose: avalonConfig.verbose,
-		generatePreloadHints: true,
-	});
-
-	const sourceMapConfig = createSourceMapConfig(nitroConfig.preset ?? 'node_server', avalonConfig.isDev);
-	const sourceMapPlugin = createSourceMapPlugin(sourceMapConfig);
-
-	return {
-		nitroOptions,
-		plugins: [
-			...(Array.isArray(nitroPlugin) ? nitroPlugin : [nitroPlugin]),
-			coordinationPlugin,
-			virtualModulesPlugin,
-			buildPlugin,
-			manifestPlugin,
-			sourceMapPlugin,
-		],
-	};
-}
-
-/**
- * Coordination plugin: stores config/server refs, sets up SSR middleware and HMR,
- * and prewarms core infrastructure modules (fire-and-forget).
- */
-export function createNitroCoordinationPlugin(options: NitroCoordinationPluginOptions): Plugin {
-	const { avalonConfig, verbose } = options;
-
-	return {
-		name: 'avalon:nitro-coordination',
-		enforce: 'pre',
-
-		configResolved(_config) {
-			globalThis.__avalonConfig = avalonConfig;
-		},
-
-		configureServer(server: ViteDevServer) {
-			globalThis.__viteDevServer = server;
-
-			// Scoped middleware — discovered once, cached until invalidated by HMR
-			let scopedMiddlewareRoutes: MiddlewareRoute[] | null = null;
-
-			async function getScopedMiddleware(): Promise<MiddlewareRoute[]> {
-				if (!scopedMiddlewareRoutes) {
-					const viteRoot = server.config.root || process.cwd();
-					scopedMiddlewareRoutes = await discoverScopedMiddleware({
-						baseDir: `${viteRoot}/src`,
-						devMode: false,
-					});
-				}
-				return scopedMiddlewareRoutes;
-			}
-
-			function clearScopedMiddlewareRoutes(): void {
-				scopedMiddlewareRoutes = null;
-			}
-
-			setupHMRCoordination(server, avalonConfig, verbose, clearScopedMiddlewareRoutes);
-
-			// Pre-discover middleware (non-blocking)
-			getScopedMiddleware().catch(err => {
-				console.warn('[middleware] Failed to discover middleware:', err);
-			});
-
-			// Fire-and-forget: prewarm only core infrastructure modules.
-			// Pages, islands, and per-route middleware are loaded on-demand.
-			prewarmCoreModules(server, verbose).catch(err => {
-				console.error('[prewarm] Core modules pre-warm failed:', err);
-			});
-
-			// SSR middleware — runs before Vite's SPA fallback
-			server.middlewares.use(async (req, res, next) => {
-				const originalUrl = req.url || '/';
-				let url = originalUrl;
-
-				if (url.endsWith('.html')) url = url.slice(0, -5) || '/';
-				if (url === '/index') url = '/';
-
-				// Skip static files, HMR, and Vite internals
-				if (
-					url.startsWith('/@') ||
-					url.startsWith('/__') ||
-					url.startsWith('/node_modules/') ||
-					url.startsWith('/src/client/') ||
-					url.startsWith('/packages/') ||
-					(url.includes('.') && !url.endsWith('/'))
-				) {
-					return next();
-				}
-
-				if (url.startsWith('/api/')) {
-					return next();
-				}
-
-				try {
-					const middlewareHandled = await handleScopedMiddleware(server, url, req, res, getScopedMiddleware, verbose);
-					if (middlewareHandled) return;
-
-					// Try streaming SSR first (streams shell before page data resolves)
-					const streamed = await handleStreamingSSRRequest(server, url, avalonConfig, res);
-					if (streamed) return;
-
-					// Fallback to buffered SSR for non-modular pages
-					const html = await handleSSRRequest(server, url, avalonConfig);
-					if (html) {
-						res.statusCode = 200;
-						res.setHeader('Content-Type', 'text/html');
-						res.end(html);
-						return;
-					}
-
-					await handle404(server, url, res, avalonConfig);
-				} catch (error) {
-					console.error('[SSR Error]', error);
-					res.statusCode = 500;
-					res.setHeader('Content-Type', 'text/html');
-					res.end(generateErrorPage(error as Error));
-				}
-			});
-		},
-
-		buildStart() {
-			// no-op in production — coordination happens via other plugins
-		},
-	};
-}
-
-// ─── Dev Server Middleware Helpers ───────────────────────────────────────────
-
-import type { ServerResponse, IncomingMessage } from 'node:http';
-
-async function handleScopedMiddleware(
-	server: ViteDevServer,
-	url: string,
-	req: IncomingMessage,
-	res: ServerResponse,
-	getScopedMiddleware: () => Promise<MiddlewareRoute[]>,
-	verbose?: boolean,
-): Promise<boolean> {
-	const middlewareStart = performance.now();
-	const middlewareRoutes = await getScopedMiddleware();
-	if (middlewareRoutes.length === 0) return false;
-
-	const headers: Record<string, string> = {};
-	for (const [key, value] of Object.entries(req.headers)) {
-		if (typeof value === 'string') headers[key] = value;
-		else if (Array.isArray(value)) headers[key] = value.join(', ');
-	}
-
-	const fullUrl = `http://${req.headers.host || 'localhost'}${url}`;
-	const h3Event = {
-		url: fullUrl,
-		method: req.method || 'GET',
-		path: url,
-		node: { req, res },
-		req: new Request(fullUrl, {
-			method: req.method || 'GET',
-			headers,
-		}),
-		context: {} as Record<string, unknown>,
-	} as unknown as H3Event;
-
-	const middlewareResponse = await executeScopedMiddleware(h3Event, middlewareRoutes, { devMode: false });
-
-	const middlewareTime = performance.now() - middlewareStart;
-	if (middlewareTime > 100) {
-		console.warn(`⚠️ Slow middleware: ${middlewareTime.toFixed(0)}ms for ${url}`);
-	}
-
-	if (middlewareResponse) {
-		res.statusCode = middlewareResponse.status;
-		middlewareResponse.headers.forEach((value, key) => {
-			res.setHeader(key, value);
-		});
-		res.end(await middlewareResponse.text());
-		return true;
-	}
-	return false;
-}
-
-async function handle404(
-	server: ViteDevServer,
-	url: string,
-	res: ServerResponse,
-	config: ResolvedAvalonConfig,
-): Promise<void> {
-	try {
-		const { discoverErrorPages, getErrorPageModule, generateDefaultErrorPage } =
-			await import('../nitro/error-handler.ts');
-		const errorPages = await discoverErrorPages({
-			isDev: config.isDev,
-			pagesDir: config.pagesDir,
-			loadPageModule: async (filePath: string): Promise<PageModule> => {
-				return (await server.ssrLoadModule(filePath)) as PageModule;
-			},
-		});
-		const errorPageModule = getErrorPageModule(404, errorPages);
-
-		if (errorPageModule?.default && typeof errorPageModule.default === 'function') {
-			const { renderToHtml } = await import('../render/ssr.ts');
-			const ErrorPageComponent = errorPageModule.default;
-			const errorHtml = await renderToHtml(
-				{ component: () => ErrorPageComponent({ statusCode: 404, message: `Page not found: ${url}`, url }) },
-				{},
-			);
-			res.statusCode = 404;
-			res.setHeader('Content-Type', 'text/html');
-			res.end(errorHtml);
-			return;
-		}
-
-		const fallbackHtml = generateDefaultErrorPage(404, `Page not found: ${url}`, config.isDev);
-		res.statusCode = 404;
-		res.setHeader('Content-Type', 'text/html');
-		res.end(fallbackHtml);
-	} catch {
-		res.statusCode = 404;
-		res.setHeader('Content-Type', 'text/html');
-		res.end(generateFallback404(url));
-	}
-}
-
-/**
- * Prewarms core infrastructure modules (fire-and-forget).
- * Loads SSR infrastructure and framework renderers so the first page render
- * doesn't pay the full module-load cost. Island components are loaded on-demand
- * to avoid penalizing startup with unused modules.
- */
-async function prewarmCoreModules(server: ViteDevServer, verbose?: boolean): Promise<void> {
-	const prewarmStart = performance.now();
-
-	const frameworkNames = ['react', 'vue', 'solid', 'svelte', 'lit', 'preact'] as const;
-
-	const coreModules = [
-		{ path: resolveAvalonPackagePath('src/render/ssr.ts'), assignTo: 'ssr' as string | null },
-		{ path: resolveAvalonPackagePath('src/core/layout/enhanced-layout-resolver.ts'), assignTo: 'layout' as string | null },
-		{ path: resolveAvalonPackagePath('src/middleware/index.ts'), assignTo: null as string | null },
-		...frameworkNames.map(name => ({
-			path: resolveIntegrationPackagePath(name, 'server/renderer.ts'),
-			assignTo: null as string | null,
-		})),
-	];
-
-	const results = await Promise.allSettled(
-		coreModules.map(async ({ path, assignTo }) => {
-			const mod = await server.ssrLoadModule(path);
-			if (assignTo === 'ssr') cachedSSRModule = mod;
-			if (assignTo === 'layout') cachedLayoutModule = mod;
-		}),
-	);
-
-	const succeeded = results.filter(r => r.status === 'fulfilled').length;
-	const totalTime = performance.now() - prewarmStart;
-
-	if (verbose && succeeded > 0) {
-		console.log(`🔥 SSR ready in ${totalTime.toFixed(0)}ms (${succeeded}/${coreModules.length} core modules)`);
-	}
-}
-
-/**
- * Virtual modules plugin — page routes, island manifest, runtime config.
- */
-export function createVirtualModulesPlugin(options: NitroCoordinationPluginOptions): Plugin {
-	const { avalonConfig, nitroConfig, verbose } = options;
-
-	return {
-		name: 'avalon:nitro-virtual-modules',
-		enforce: 'pre',
-
-		resolveId(id: string) {
-			if (id === VIRTUAL_MODULE_IDS.PAGE_ROUTES) return RESOLVED_VIRTUAL_IDS.PAGE_ROUTES;
-			if (id === VIRTUAL_MODULE_IDS.ISLAND_MANIFEST) return RESOLVED_VIRTUAL_IDS.ISLAND_MANIFEST;
-			if (id === VIRTUAL_MODULE_IDS.RUNTIME_CONFIG) return RESOLVED_VIRTUAL_IDS.RUNTIME_CONFIG;
-			if (id === VIRTUAL_MODULE_IDS.CONFIG) return RESOLVED_VIRTUAL_IDS.CONFIG;
-			return null;
-		},
-
-		async load(id: string) {
-			if (id === RESOLVED_VIRTUAL_IDS.PAGE_ROUTES) return await generatePageRoutesModule(avalonConfig, verbose);
-			if (id === RESOLVED_VIRTUAL_IDS.ISLAND_MANIFEST) return generateIslandManifestModule();
-			if (id === RESOLVED_VIRTUAL_IDS.RUNTIME_CONFIG) return generateRuntimeConfigModule(avalonConfig, nitroConfig);
-			if (id === RESOLVED_VIRTUAL_IDS.CONFIG) return generateConfigModule(avalonConfig, nitroConfig);
-			return null;
-		},
-
-		handleHotUpdate({ file, server }) {
-			if (file.includes(avalonConfig.pagesDir)) {
-				const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_IDS.PAGE_ROUTES);
-				if (mod) server.moduleGraph.invalidateModule(mod);
-			}
-			// Invalidate virtual:avalon/config when config-related files change
-			if (file.includes('vite.config') || file.includes('avalon.config') || file.includes('nitro.config')) {
-				const configMod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_IDS.CONFIG);
-				if (configMod) server.moduleGraph.invalidateModule(configMod);
-			}
-			return undefined;
-		},
-	};
-}
-
-// ─── HMR Coordination ───────────────────────────────────────────────────────
-
-function setupHMRCoordination(
-	server: ViteDevServer,
-	_config: ResolvedAvalonConfig,
-	_verbose?: boolean,
-	clearScopedMiddlewareRoutes?: () => void,
-): void {
-	server.watcher.on('change', file => {
-		if (file.includes('_middleware')) {
-			clearMiddlewareCache();
-			clearScopedMiddlewareRoutes?.();
-		}
-		if (file.includes('/render/') || file.includes('/layout/') || file.includes('/islands/')) {
-			cachedSSRModule = null;
-			cachedLayoutModule = null;
-		}
-		
-		if (file.includes('/layouts/') || file.includes('_layout')) {
-			const resolver = globalThis.__avalonLayoutResolver as { clearCache?: () => void } | undefined;
-			resolver?.clearCache?.();
-		}
-	});
-
-	server.watcher.on('add', file => {
-		if (file.includes('_middleware')) {
-			clearMiddlewareCache();
-			clearScopedMiddlewareRoutes?.();
-		}
-	});
-
-	server.watcher.on('unlink', file => {
-		if (file.includes('_middleware')) {
-			clearMiddlewareCache();
-			clearScopedMiddlewareRoutes?.();
-		}
-	});
-}
-
-// ─── Virtual Module Generators ───────────────────────────────────────────────
-
-async function generatePageRoutesModule(config: ResolvedAvalonConfig, _verbose?: boolean): Promise<string> {
-	try {
-		const { getAllPageDirs } = await import('./module-discovery.ts');
-		const { discoverPageRoutesFromMultipleDirs } = await import('../nitro/route-discovery.ts');
-		
-		// Get all page directories (traditional + modular)
-		const pageDirs = await getAllPageDirs(
-			config.pagesDir,
-			config.modules,
-			process.cwd()
-		);
-		
-		const routes = await discoverPageRoutesFromMultipleDirs(pageDirs, {
-			developmentMode: config.isDev,
-		});
-		
-		const routesJson = JSON.stringify(routes, null, 2);
-		return `export const pageRoutes = ${routesJson};\nexport default pageRoutes;\n`;
-	} catch {
-		return `export const pageRoutes = [];\nexport default pageRoutes;\n`;
-	}
-}
-
-function generateIslandManifestModule(): string {
-	return `export const islandManifest = { islands: {}, clientEntry: "", css: [] };\nexport default islandManifest;\n`;
-}
-
-function generateRuntimeConfigModule(avalonConfig: ResolvedAvalonConfig, nitroConfig: AvalonNitroConfig): string {
-	const runtimeConfig = {
-		avalon: {
-			streaming: nitroConfig.streaming ?? true,
-			pagesDir: avalonConfig.pagesDir,
-			layoutsDir: avalonConfig.layoutsDir,
-			isDev: avalonConfig.isDev,
-		},
-		...nitroConfig.runtimeConfig,
-	};
-	return `export const runtimeConfig = ${JSON.stringify(runtimeConfig, null, 2)};\nexport function useRuntimeConfig() { return runtimeConfig; }\nexport default runtimeConfig;\n`;
-}
-
-export function generateConfigModule(avalonConfig: ResolvedAvalonConfig, nitroConfig: AvalonNitroConfig): string {
-	const config = {
-		streaming: nitroConfig.streaming ?? true,
-		pagesDir: avalonConfig.pagesDir,
-		layoutsDir: avalonConfig.layoutsDir,
-		isDev: avalonConfig.isDev,
-		...nitroConfig.runtimeConfig,
-	};
-	return `const config = ${JSON.stringify(config, null, 2)};\nexport function useAvalonConfig() { return config; }\nexport default config;\n`;
-}
-
-// ─── Public Accessors ────────────────────────────────────────────────────────
-
-export function getViteDevServer(): ViteDevServer | undefined {
-	return globalThis.__viteDevServer;
-}
-
-export function getAvalonConfig(): ResolvedAvalonConfig | undefined {
-	return globalThis.__avalonConfig;
-}
-
-export function isDevelopmentMode(): boolean {
-	return globalThis.__avalonConfig?.isDev ?? true;
-}
-
-// ─── SSR Request Handling ────────────────────────────────────────────────────
-
-const STREAM_MARKER = '<!--AVALON_STREAM_BOUNDARY-->';
-
-let cachedSSRModule: unknown = null;
-
-let cachedLayoutModule: unknown = null;
-
-/**
- * Streaming SSR handler — flushes the layout shell to the browser before
- * the page component's async data fetching resolves.
- *
- * Flow:
- * 1. Load page module + layout modules, collect CSS
- * 2. Render shell layout with a marker placeholder as children
- * 3. Split HTML on the marker → shellBefore / shellAfter
- * 4. res.write(shellBefore) — browser starts parsing <html><head>... immediately
- * 5. Render page content (awaits data fetches)
- * 6. Render wrapper layouts around page content
- * 7. res.write(wrappedContent + shellAfter)
- * 8. res.end()
- *
- * Falls back to null (caller uses buffered path) when:
- * - No modular layouts configured
- * - Page not found
- * - No shell layout detected
- * - Page provides its own complete HTML document
- */
-async function handleStreamingSSRRequest(
-	server: ViteDevServer,
-	url: string,
-	config: ResolvedAvalonConfig,
-	res: ServerResponse,
-): Promise<boolean> {
-	// Streaming only works with modular layouts (need shell + wrapper separation)
-	if (!config.modules) return false;
-
-	const pathname = url.split('?')[0];
-	const pageFile = await findPageFile(pathname, config, server);
-	if (!pageFile) return false;
-
-	try {
-		const pageModule = await server.ssrLoadModule(pageFile);
-		const PageComponent = pageModule.default;
-		if (!PageComponent) return false;
-
-		// Check if page wants to skip layouts entirely (provides own HTML)
-		const layoutConfig = pageModule.layoutConfig as { skipLayouts?: string[] } | undefined;
-
-		// Collect CSS
-		const cssContents = await collectCssFromModuleGraph(server, pageFile);
-		const layoutFiles = await discoverLayoutFiles(pathname, server);
-
-		const layoutModules: Array<{ file: string; module: Record<string, unknown> }> = [];
-		for (const layoutFile of layoutFiles) {
-			const layoutModule = await server.ssrLoadModule(layoutFile);
-			layoutModules.push({ file: layoutFile, module: layoutModule });
-		}
-		for (const layoutFile of layoutFiles) {
-			const layoutCss = await collectCssFromModuleGraph(server, layoutFile);
-			cssContents.push(...layoutCss);
-		}
-
-		if (layoutModules.length === 0) return false;
-
-		const { render: preactRender } = await server.ssrLoadModule('preact-render-to-string');
-		const { h } = await server.ssrLoadModule('preact');
-
-		const skipLayouts = layoutConfig?.skipLayouts || [];
-		const activeLayouts = layoutModules.filter(({ file }) => {
-			const layoutName = file.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
-			return !skipLayouts.includes(layoutName);
-		});
-
-		const frontmatter = pageModule.frontmatter as Record<string, unknown> | undefined;
-		const metadata = pageModule.metadata as Record<string, unknown> | undefined;
-		const mergedFrontmatter = { ...frontmatter, ...metadata, currentPath: pathname };
-		const layoutProps = {
-			children: null as unknown,
-			frontmatter: mergedFrontmatter,
-			params: {},
-			url: pathname,
-		};
-
-		// Categorize layouts into shell vs wrapper
-		const shellLayouts: Array<{ module: Record<string, unknown> }> = [];
-		const wrapperLayouts: Array<{ module: Record<string, unknown> }> = [];
-
-		for (const layout of activeLayouts) {
-			const LayoutComponent = layout.module.default;
-			if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
-			try {
-				const testProps = { ...layoutProps, children: h('div', null, 'test') };
-				const testResult = (LayoutComponent as (props: unknown) => unknown)(testProps);
-				const resolvedTest = testResult instanceof Promise ? await testResult : testResult;
-				const testHtml = preactRender(resolvedTest);
-				if (testHtml.trim().startsWith('<html') || testHtml.includes('<!DOCTYPE')) {
-					shellLayouts.push(layout);
-				} else {
-					wrapperLayouts.push(layout);
-				}
-			} catch {
-				wrapperLayouts.push(layout);
-			}
-		}
-
-		// Need a shell layout to stream
-		if (shellLayouts.length === 0) return false;
-
-		// Render shell layout with stream marker as children
-		const { module: shellModule } = shellLayouts[shellLayouts.length - 1];
-		const ShellComponent = shellModule.default;
-		if (!ShellComponent || typeof ShellComponent !== 'function') return false;
-
-		let shellHtml: string;
-		try {
-			const shellProps = {
-				...layoutProps,
-				children: h('div', { dangerouslySetInnerHTML: { __html: STREAM_MARKER } }),
-			};
-			const shellResult = (ShellComponent as (props: unknown) => unknown)(shellProps);
-			const resolvedShell = shellResult instanceof Promise ? await shellResult : shellResult;
-			shellHtml = preactRender(resolvedShell);
-		} catch {
-			return false;
-		}
-
-		// Split on marker
-		const markerIndex = shellHtml.indexOf(STREAM_MARKER);
-		if (markerIndex === -1) return false;
-
-		let shellBefore = shellHtml.slice(0, markerIndex);
-		const shellAfter = shellHtml.slice(markerIndex + STREAM_MARKER.length);
-
-		// Inject CSS into the shell's <head>
-		let shellBeforeWithCss = shellBefore;
-		if (cssContents.length > 0) {
-			const cssTag = `<style data-avalon-ssr-css>${cssContents.join('\n')}</style>`;
-			if (shellBefore.includes('</head>')) {
-				shellBeforeWithCss = shellBefore.replace('</head>', `${cssTag}\n</head>`);
-			} else {
-				shellBeforeWithCss = shellBefore + cssTag;
-			}
-		}
-
-		// Ensure DOCTYPE
-		if (!shellBeforeWithCss.trim().toLowerCase().startsWith('<!doctype')) {
-			shellBeforeWithCss = '<!DOCTYPE html>\n' + shellBeforeWithCss;
-		}
-
-		// Inject universal CSS and head content
-		const universalCSS = getUniversalCSSForHead(true);
-		if (universalCSS && shellBeforeWithCss.includes('</head>')) {
-			shellBeforeWithCss = shellBeforeWithCss.replace('</head>', `${universalCSS}\n</head>`);
-		}
-		const universalHead = getUniversalHeadForInjection(true);
-		if (universalHead && shellBeforeWithCss.includes('</head>')) {
-			shellBeforeWithCss = shellBeforeWithCss.replace('</head>', `${universalHead}\n</head>`);
-		}
-
-		// ── FLUSH SHELL ──
-		res.statusCode = 200;
-		res.setHeader('Content-Type', 'text/html; charset=utf-8');
-		res.setHeader('Transfer-Encoding', 'chunked');
-		res.setHeader('X-Avalon-Streaming', '1');
-		res.flushHeaders();
-		res.write(shellBeforeWithCss);
-
-		// ── RENDER PAGE CONTENT (this is where data fetching happens) ──
-		let pageContent: string;
-		try {
-			const pageResult = typeof PageComponent === 'function'
-				? (PageComponent as () => unknown)()
-				: PageComponent;
-			const resolvedPage = pageResult instanceof Promise ? await pageResult : pageResult;
-			pageContent = preactRender(resolvedPage);
-		} catch (error) {
-			console.error('[SSR Streaming] Error rendering page component:', error);
-			pageContent = `<div>Error rendering page</div>`;
-		}
-
-		// Check if page returned a complete HTML doc (shouldn't happen with layouts, but safety check)
-		const isCompleteDoc = pageContent.trim().startsWith('<!DOCTYPE html>') ||
-			pageContent.trim().startsWith('<html');
-		if (isCompleteDoc) {
-			// Can't stream this — just send it and close
-			res.end(pageContent);
-			return true;
-		}
-
-		// Apply wrapper layouts around page content
-		let content = pageContent;
-		for (const { module: layoutModule } of wrapperLayouts) {
-			const LayoutComponent = layoutModule.default;
-			if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
-			try {
-				const props = {
-					...layoutProps,
-					children: h('div', { dangerouslySetInnerHTML: { __html: content } }),
-				};
-				const layoutResult = (LayoutComponent as (props: unknown) => unknown)(props);
-				const resolvedLayout = layoutResult instanceof Promise ? await layoutResult : layoutResult;
-				content = preactRender(resolvedLayout);
-			} catch (error) {
-				console.error('[SSR Streaming] Error rendering wrapper layout:', error);
-			}
-		}
-
-		// ── FLUSH PAGE CONTENT + SHELL TAIL ──
-		// Inject client scripts before closing </body>
-		let tail = content + shellAfter;
-		if (!tail.includes('/src/client/main.js') && !tail.includes('/@vite/client')) {
-			const bodyCloseIndex = tail.lastIndexOf('</body>');
-			if (bodyCloseIndex !== -1) {
-				tail = tail.slice(0, bodyCloseIndex) +
-					'\n<script type="module" src="/@vite/client"></script>\n' +
-					'<script type="module" src="/src/client/main.js"></script>\n' +
-					tail.slice(bodyCloseIndex);
-			}
-		}
-
-		res.end(tail);
-		return true;
-	} catch (error) {
-		// If we already started writing, we can't change status code
-		if (res.headersSent) {
-			res.end(`<div>Streaming SSR error: ${(error as Error).message}</div></body></html>`);
-			return true;
-		}
-		return false;
-	}
-}
-
-
-async function handleSSRRequest(
-	server: ViteDevServer,
-	url: string,
-	config: ResolvedAvalonConfig,
-): Promise<string | null> {
-	const pathname = url.split('?')[0];
-	const pageFile = await findPageFile(pathname, config, server);
-
-	if (!pageFile) return null;
-
-	try {
-		const pageModule = await server.ssrLoadModule(pageFile);
-		const PageComponent = pageModule.default;
-
-		if (!PageComponent) {
-			console.warn(`[SSR] Page ${pageFile} has no default export`);
-			return null;
-		}
-
-		// Collect CSS from the module graph after loading the page module.
-		// This captures CSS modules, plain CSS imports, and any transitive CSS deps.
-		const cssContents = await collectCssFromModuleGraph(server, pageFile);
-
-		// Pre-load layout files via ssrLoadModule so their CSS modules enter
-		// Vite's module graph *before* we collect CSS from them.
-		const layoutFiles = await discoverLayoutFiles(pathname, server);
-		
-		// Load all layout modules
-		const layoutModules: Array<{ file: string; module: Record<string, unknown> }> = [];
-		for (const layoutFile of layoutFiles) {
-			const layoutModule = await server.ssrLoadModule(layoutFile);
-			layoutModules.push({ file: layoutFile, module: layoutModule });
-		}
-
-		// Collect CSS from layout files and merge with page CSS
-		for (const layoutFile of layoutFiles) {
-			const layoutCss = await collectCssFromModuleGraph(server, layoutFile);
-			cssContents.push(...layoutCss);
-		}
-
-		let html: string;
-		
-		// If we have modular layouts, use manual layout composition
-		if (config.modules && layoutModules.length > 0) {
-			html = await renderPageWithManualLayouts(
-				PageComponent,
-				pageModule,
-				layoutModules,
-				pathname,
-				config,
-				server
-			);
-		} else {
-			html = await renderPageToHtml(PageComponent, pageModule, pathname, config, server);
-		}
-
-		// Inject collected CSS into the HTML so styles are present on first paint
-		if (cssContents.length > 0) {
-			html = injectSsrCss(html, cssContents);
-		}
-
-		return html;
-	} catch (error) {
-		console.error(`[SSR] Error rendering ${pageFile}:`, error);
-		throw error;
-	}
-}
-
-/**
- * Render a page with manually composed layouts (for modular architecture)
- * 
- * Layout composition order:
- * 1. Page content is rendered first
- * 2. Module-specific layouts (e.g., docs/_layout.tsx) wrap the page content
- * 3. Root/shell layout (shared/_layout.tsx) wraps everything last
- * 
- * This ensures that layouts returning `<div>` wrappers are applied before
- * layouts returning complete `<html>` documents.
- */
-async function renderPageWithManualLayouts(
-	PageComponent: unknown,
-	pageModule: Record<string, unknown>,
-	layoutModules: Array<{ file: string; module: Record<string, unknown> }>,
-	pathname: string,
-	config: ResolvedAvalonConfig,
-	server: ViteDevServer,
-): Promise<string> {
-	const { render: preactRender } = await server.ssrLoadModule('preact-render-to-string');
-	const { h } = await server.ssrLoadModule('preact');
-	
-	// Check if page wants to skip certain layouts
-	const layoutConfig = pageModule.layoutConfig as { skipLayouts?: string[] } | undefined;
-	const skipLayouts = layoutConfig?.skipLayouts || [];
-	
-	// Filter out skipped layouts
-	const activeLayouts = layoutModules.filter(({ file }) => {
-		const layoutName = file.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
-		return !skipLayouts.includes(layoutName);
-	});
-	
-	// Render page content first
-	let pageContent: string;
-	try {
-		const pageResult = typeof PageComponent === 'function' 
-			? (PageComponent as () => unknown)() 
-			: PageComponent;
-		const resolvedPage = pageResult instanceof Promise ? await pageResult : pageResult;
-		pageContent = preactRender(resolvedPage);
-	} catch (error) {
-		console.error('[SSR] Error rendering page component:', error);
-		pageContent = `<div>Error rendering page</div>`;
-	}
-	
-	// Check if page content is a complete HTML document
-	const isCompleteDoc = pageContent.trim().startsWith('<!DOCTYPE html>') || 
-		pageContent.trim().startsWith('<html');
-	
-	if (isCompleteDoc) {
-		// Page provides its own HTML structure, inject client script and return
-		return injectClientScript(pageContent);
-	}
-	
-	// Separate layouts into shell (returns <html>) and wrapper (returns <div>) layouts
-	// We need to render each layout to determine its type, then apply in correct order
-	// Merge frontmatter and metadata - metadata takes precedence for page-specific values
-	const frontmatter = pageModule.frontmatter as Record<string, unknown> | undefined;
-	const metadata = pageModule.metadata as Record<string, unknown> | undefined;
-	const mergedFrontmatter = { ...frontmatter, ...metadata, currentPath: pathname };
-	
-	const layoutProps = {
-		children: null as unknown, // Will be set per-layout
-		frontmatter: mergedFrontmatter,
-		params: {},
-		url: pathname,
-	};
-	
-	// Categorize layouts by rendering them with placeholder content
-	const shellLayouts: Array<{ module: Record<string, unknown> }> = [];
-	const wrapperLayouts: Array<{ module: Record<string, unknown> }> = [];
-	
-	for (const layout of activeLayouts) {
-		const LayoutComponent = layout.module.default;
-		if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
-		
-		try {
-			// Render with placeholder to detect if it returns HTML shell
-			const testProps = {
-				...layoutProps,
-				children: h('div', null, 'test'),
-			};
-			const testResult = (LayoutComponent as (props: unknown) => unknown)(testProps);
-			const resolvedTest = testResult instanceof Promise ? await testResult : testResult;
-			const testHtml = preactRender(resolvedTest);
-			
-			if (testHtml.trim().startsWith('<html') || testHtml.includes('<!DOCTYPE')) {
-				shellLayouts.push(layout);
-			} else {
-				wrapperLayouts.push(layout);
-			}
-		} catch {
-			// If we can't determine, treat as wrapper
-			wrapperLayouts.push(layout);
-		}
-	}
-	
-	// Apply wrapper layouts first (innermost to outermost)
-	// These are module-specific layouts that return <div> wrappers
-	let content = pageContent;
-	
-	for (const { module: layoutModule } of wrapperLayouts) {
-		const LayoutComponent = layoutModule.default;
-		if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
-		
-		try {
-			const props = {
-				...layoutProps,
-				children: h('div', { dangerouslySetInnerHTML: { __html: content } }),
-			};
-			
-			const layoutResult = (LayoutComponent as (props: unknown) => unknown)(props);
-			const resolvedLayout = layoutResult instanceof Promise ? await layoutResult : layoutResult;
-			content = preactRender(resolvedLayout);
-		} catch (error) {
-			console.error('[SSR] Error rendering wrapper layout:', error);
-		}
-	}
-	
-	// Apply shell layout last (the one that provides <html>)
-	// If there are multiple shell layouts, prefer the module-specific one (last in array)
-	// since layouts are discovered in order: shared -> module-specific
-	if (shellLayouts.length > 0) {
-		// Use the last shell layout (module-specific takes precedence over shared)
-		const { module: shellModule } = shellLayouts[shellLayouts.length - 1];
-		const ShellComponent = shellModule.default;
-		
-		if (ShellComponent && typeof ShellComponent === 'function') {
-			try {
-				const props = {
-					...layoutProps,
-					children: h('div', { dangerouslySetInnerHTML: { __html: content } }),
-				};
-				
-				const shellResult = (ShellComponent as (props: unknown) => unknown)(props);
-				const resolvedShell = shellResult instanceof Promise ? await shellResult : shellResult;
-				content = preactRender(resolvedShell);
-			} catch (error) {
-				console.error('[SSR] Error rendering shell layout:', error);
-			}
-		}
-	}
-	
-	// Check if final content is a complete HTML document
-	const isFinalCompleteDoc = content.trim().startsWith('<!DOCTYPE html>') || 
-		content.trim().startsWith('<html');
-	
-	if (isFinalCompleteDoc) {
-		return injectClientScript(content);
-	}
-	
-	// Wrap in basic HTML structure (fallback if no shell layout)
-	const fallbackMetadata = (pageModule.metadata || {}) as { title?: string; description?: string };
-	const title = fallbackMetadata.title || 'Avalon App';
-	const description = fallbackMetadata.description || '';
-	
-	return `<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>${escapeHtml(title)}</title>
-    ${description ? `<meta name="description" content="${escapeHtml(description)}">` : ''}
-    <script type="module" src="/@vite/client"></script>
-  </head>
-  <body>
-    ${content}
-    <script type="module" src="/src/client/main.js"></script>
-  </body>
-</html>`;
-}
-
-/**
- * Inject client script into HTML if not already present.
- * Also ensures DOCTYPE is present for valid HTML5.
- */
-function injectClientScript(html: string): string {
-	let result = html;
-	
-	// Ensure DOCTYPE is present
-	if (!result.trim().toLowerCase().startsWith('<!doctype')) {
-		result = '<!DOCTYPE html>\n' + result;
-	}
-	
-	// Inject universal CSS from island framework renderers (Svelte scoped, Vue scoped, Solid CSS, etc.)
-	if (!result.includes('data-universal-ssr="true"')) {
-		const universalCSS = getUniversalCSSForHead(true);
-		if (universalCSS && result.includes('</head>')) {
-			result = result.replace('</head>', `${universalCSS}\n</head>`);
-		}
-	}
-	
-	// Inject universal head content (hydration scripts from frameworks like Solid)
-	const universalHead = getUniversalHeadForInjection(true);
-	if (universalHead && result.includes('</head>')) {
-		result = result.replace('</head>', `${universalHead}\n</head>`);
-	}
-	
-	// Skip if scripts already present
-	if (result.includes('/src/client/main.js') || result.includes('/@vite/client')) {
-		return result;
-	}
-	
-	// Inject before </body> or at the end
-	const bodyCloseIndex = result.lastIndexOf('</body>');
-	if (bodyCloseIndex !== -1) {
-		return result.slice(0, bodyCloseIndex) + 
-			'\n<script type="module" src="/@vite/client"></script>\n' +
-			'<script type="module" src="/src/client/main.js"></script>\n' +
-			result.slice(bodyCloseIndex);
-	}
-	
-	return result + '\n<script type="module" src="/@vite/client"></script>\n<script type="module" src="/src/client/main.js"></script>';
-}
-
-/**
- * Discover layout files that apply to a given route path.
- *
- * Supports both traditional layouts (src/layouts/) and modular layouts (app/modules/[module]/layouts/).
- * For route "/blog/post", checks shared layouts, module layouts, and traditional layouts.
- */
-async function discoverLayoutFiles(pathname: string, server: ViteDevServer): Promise<string[]> {
-	const viteRoot = server.config.root || process.cwd();
-	const config = globalThis.__avalonConfig;
-	const layoutFileName = '_layout.tsx';
-	const layoutFiles: string[] = [];
-
-	// Build path hierarchy: "/" → [''], "/blog/post" → ['', '/blog', '/blog/post']
-	const segments = pathname.split('/').filter(Boolean);
-	const paths = [''];
-	for (let i = 0; i < segments.length; i++) {
-		paths.push('/' + segments.slice(0, i + 1).join('/'));
-	}
-
-	// Helper to check and add layout file
-	async function tryAddLayout(fullPath: string): Promise<void> {
-		try {
-			const stat = await fsStat(fullPath);
-			if (stat.isFile()) {
-				const relativePath = fullPath.slice(viteRoot.length);
-				if (!layoutFiles.includes(relativePath)) {
-					layoutFiles.push(relativePath);
-				}
-			}
-		} catch {
-			// Layout file doesn't exist — that's fine
-		}
-	}
-
-	// 1. Check shared layouts directory (root layout)
-	if (config?.layoutsDir) {
-		const sharedLayoutsDir = `${viteRoot}/${config.layoutsDir}`;
-		await tryAddLayout(`${sharedLayoutsDir}/${layoutFileName}`);
-	}
-
-	// 2. Check modular layouts (app/modules/*/layouts/)
-	if (config?.modules) {
-		const modulesDir = `${viteRoot}/${config.modules.dir}`;
-		const layoutsDirName = config.modules.layoutsDirName;
-		
-		// Determine which module this route belongs to
-		const firstSegment = segments[0] || '';
-		const rootModules = ['home', 'root', 'main', 'index'];
-		
-		// For root routes, check the home/root/main/index module
-		if (!firstSegment || rootModules.includes(firstSegment.toLowerCase())) {
-			for (const moduleName of rootModules) {
-				await tryAddLayout(`${modulesDir}/${moduleName}/${layoutsDirName}/${layoutFileName}`);
-			}
-		} else {
-			// For other routes, check the module matching the first segment
-			await tryAddLayout(`${modulesDir}/${firstSegment}/${layoutsDirName}/${layoutFileName}`);
-		}
-	}
-
-	// 3. Check traditional layouts directory (src/layouts/)
-	const traditionalLayoutsDir = `${viteRoot}/src/layouts`;
-	for (const pathSegment of paths) {
-		const fullPath = pathSegment === ''
-			? `${traditionalLayoutsDir}/${layoutFileName}`
-			: `${traditionalLayoutsDir}${pathSegment}/${layoutFileName}`;
-		await tryAddLayout(fullPath);
-	}
-
-	return layoutFiles;
-}
-
-async function findPageFile(pathname: string, config: ResolvedAvalonConfig, server: ViteDevServer): Promise<string | null> {
-	let normalizedPath = pathname;
-	if (normalizedPath.endsWith('/') && normalizedPath !== '/') {
-		normalizedPath = normalizedPath.slice(0, -1);
-	}
-	if (normalizedPath === '/') {
-		normalizedPath = '/index';
-	}
-
-	const extensions = ['.tsx', '.ts', '.jsx', '.js', '.mdx', '.md'];
-	const viteRoot = server.config.root || process.cwd();
-	
-	// Helper to check if a file exists
-	async function tryFile(relativePath: string): Promise<string | null> {
-		try {
-			const fullPath = `${viteRoot}/${relativePath}`;
-			const stat = await fsStat(fullPath);
-			if (stat.isFile()) return `/${relativePath}`;
-		} catch {
-			// File doesn't exist
-		}
-		return null;
-	}
-
-	// 1. Check modular page directories first
-	if (config.modules) {
-		const modulesDir = config.modules.dir;
-		const pagesDirName = config.modules.pagesDirName;
-		const segments = pathname.split('/').filter(Boolean);
-		const firstSegment = segments[0] || '';
-		const rootModules = ['home', 'root', 'main', 'index'];
-		
-		// Determine which module and what the relative path within that module is
-		let moduleName: string;
-		let moduleRelativePath: string;
-		
-		if (!firstSegment || rootModules.includes(firstSegment.toLowerCase())) {
-			// Root route - check home module
-			moduleName = 'home';
-			moduleRelativePath = normalizedPath;
-		} else {
-			// Check if first segment matches a module
-			moduleName = firstSegment;
-			// Remove the module prefix from the path
-			const remainingSegments = segments.slice(1);
-			moduleRelativePath = remainingSegments.length > 0 
-				? '/' + remainingSegments.join('/') 
-				: '/index';
-		}
-		
-		// Try to find the page in the module
-		for (const ext of extensions) {
-			const result = await tryFile(`${modulesDir}/${moduleName}/${pagesDirName}${moduleRelativePath}${ext}`);
-			if (result) return result;
-		}
-		if (!moduleRelativePath.endsWith('/index')) {
-			for (const ext of extensions) {
-				const result = await tryFile(`${modulesDir}/${moduleName}/${pagesDirName}${moduleRelativePath}/index${ext}`);
-				if (result) return result;
-			}
-		}
-	}
-
-	// 2. Check traditional pages directory
-	const pagesDir = config.pagesDir;
-	for (const ext of extensions) {
-		const result = await tryFile(`${pagesDir}${normalizedPath}${ext}`);
-		if (result) return result;
-	}
-	if (!normalizedPath.endsWith('/index')) {
-		for (const ext of extensions) {
-			const result = await tryFile(`${pagesDir}${normalizedPath}/index${ext}`);
-			if (result) return result;
-		}
-	}
-
-	return null;
-}
-
-async function renderPageToHtml(
-	PageComponent: unknown,
-	pageModule: Record<string, unknown>,
-	pathname: string,
-	config: ResolvedAvalonConfig,
-	server: ViteDevServer,
-): Promise<string> {
-	const metadata = (pageModule.metadata || {}) as { title?: string; description?: string };
-
-	try {
-		if (!cachedSSRModule) {
-			cachedSSRModule = await server.ssrLoadModule(resolveAvalonPackagePath('src/render/ssr.ts'));
-		}
-		// cachedSSRModule is the dynamically-loaded render/ssr.ts module;
-		// expected exports: renderToHtml, renderToHtmlWithLayouts
-		const ssrModule = cachedSSRModule as Record<string, unknown>;
-
-		if (!cachedLayoutModule) {
-			cachedLayoutModule = await server.ssrLoadModule(resolveAvalonPackagePath('src/core/layout/enhanced-layout-resolver.ts'));
-		}
-		// cachedLayoutModule is the dynamically-loaded enhanced-layout-resolver.ts module;
-		// expected exports: EnhancedLayoutResolver, EnhancedLayoutResolverUtils
-		const layoutModule = cachedLayoutModule as Record<string, unknown>;
-
-		const routeConfig = {
-			component: () => (typeof PageComponent === 'function' ? (PageComponent as () => unknown)() : PageComponent),
-			options: { title: metadata.title || 'Avalon App' },
-			frontmatter: pageModule.frontmatter as Record<string, unknown> | undefined,
-		};
-
-		// Try layout-aware rendering first
-		if (
-			ssrModule.renderToHtmlWithLayouts &&
-			layoutModule.EnhancedLayoutResolver &&
-			layoutModule.EnhancedLayoutResolverUtils
-		) {
-			try {
-				const viteRoot = server.config.root || process.cwd();
-
-				if (!globalThis.__avalonLayoutResolver) {
-					const EnhancedLayoutResolver = layoutModule.EnhancedLayoutResolver as new (
-						opts: Record<string, unknown>,
-					) => unknown;
-					
-					// Use the shared layouts directory as the base
-					// The resolver will also check modular layouts via the layout composer
-					const layoutsDir = config.layoutsDir || 'src/layouts';
-					
-					globalThis.__avalonLayoutResolver = new EnhancedLayoutResolver({
-						baseDirectory: `${viteRoot}/${layoutsDir}`,
-						filePattern: '_layout.tsx',
-						excludeDirectories: ['node_modules', '.git', 'dist', 'build'],
-						enableWatching: true,
-						developmentMode: false,
-						enableCaching: true,
-						cacheTTL: 60 * 1000,
-						maxCacheSize: 100,
-						enableStreaming: true,
-						enableErrorBoundaries: true,
-						enableMetrics: false,
-						enableDebugInfo: false,
-						// Pass modules config for modular layout discovery
-						modulesDir: config.modules ? `${viteRoot}/${config.modules.dir}` : undefined,
-						modulesLayoutsDirName: config.modules?.layoutsDirName,
-					});
-				}
-
-				const fullUrl = `http://localhost${pathname}`;
-				const layoutContext = {
-					params: {},
-					query: {},
-					url: fullUrl,
-					request: { method: 'GET', url: fullUrl, headers: new Headers() },
-				};
-
-				return await (ssrModule.renderToHtmlWithLayouts as Function)(
-					routeConfig,
-					globalThis.__avalonLayoutResolver,
-					layoutContext,
-					pathname,
-					{ title: metadata.title || 'Avalon App' },
-					undefined,
-					{ suppressWarnings: true },
-				);
-			} catch {
-				// Layout rendering failed, fall back to basic rendering
-			}
-		}
-
-		if (ssrModule.renderToHtml) {
-			return await (ssrModule.renderToHtml as Function)(
-				routeConfig,
-				{ title: metadata.title || 'Avalon App' },
-				undefined,
-				{ suppressWarnings: true },
-			);
-		}
-	} catch {
-		// SSR module not available, fall back to basic rendering
-	}
-
-	// Fallback: basic HTML template
-	const title = metadata.title || 'Avalon App';
-	const description = metadata.description || '';
-	let content = '';
-	try {
-		const preactRenderModule = await server.ssrLoadModule('preact-render-to-string');
-		if (preactRenderModule.render && typeof PageComponent === 'function') {
-			content = preactRenderModule.render((PageComponent as () => unknown)());
-		}
-	} catch {
-		content = `<p>Loading page: ${escapeHtml(pathname)}</p>`;
-	}
-
-	return `<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>${escapeHtml(title)}</title>
-    ${description ? `<meta name="description" content="${escapeHtml(description)}">` : ''}
-    <script type="module" src="/@vite/client"></script>
-  </head>
-  <body>
-    <div id="app">${content}</div>
-    <script type="module" src="/src/client/main.js"></script>
-  </body>
-</html>`;
-}
-
-function escapeHtml(str: string): string {
-	return str
-		.replaceAll('&', '&amp;')
-		.replaceAll('<', '&lt;')
-		.replaceAll('>', '&gt;')
-		.replaceAll('"', '&quot;')
-		.replaceAll("'", '&#039;');
-}
-
-// ─── Global Type Declarations ────────────────────────────────────────────────
-
-declare global {
-	// deno-lint-ignore no-var
-	var __avalonLayoutResolver: unknown;
-}
+/**
+ * Nitro Integration Module for Avalon Vite Plugin
+ *
+ * Provides coordination between Avalon's Vite plugin and Nitro:
+ * - API routes: Auto-discovered by Nitro from `api/` directory
+ * - Page routes: Virtual module for SSR page component discovery
+ * - Middleware: Auto-discovered by Nitro from `middleware/` directory
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import { nitro as nitroVitePlugin } from 'nitro/vite';
+import { stat as fsStat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import type { ResolvedAvalonConfig } from './types.ts';
+import { createNitroConfig, type AvalonNitroConfig, type NitroConfigOutput } from '../nitro/config.ts';
+import type { PageModule } from '../nitro/types.ts';
+import {
+	createNitroBuildPlugin,
+	createIslandManifestPlugin,
+	createSourceMapPlugin,
+	createSourceMapConfig,
+} from '../nitro/index.ts';
+import { discoverScopedMiddleware, executeScopedMiddleware, clearMiddlewareCache } from '../middleware/index.ts';
+import type { MiddlewareRoute } from '../middleware/types.ts';
+import type { H3Event } from 'h3';
+import { generateErrorPage, generateFallback404 } from '../render/error-pages.ts';
+import { collectCssFromModuleGraph, injectSsrCss } from '../render/collect-css.ts';
+import { getUniversalCSSForHead } from '../islands/universal-css-collector.ts';
+import { getUniversalHeadForInjection } from '../islands/universal-head-collector.ts';
+
+/**
+ * Resolves the absolute path to a file inside @useavalon/avalon's source tree.
+ */
+function resolveAvalonPackagePath(relativePath: string): string {
+	const require = createRequire(import.meta.url);
+	const modEntry = require.resolve('@useavalon/avalon');
+	const pkgRoot = dirname(modEntry);
+	return join(pkgRoot, relativePath);
+}
+
+/**
+ * Resolves the absolute path to a file inside an @useavalon/<name> integration package.
+ */
+function resolveIntegrationPackagePath(name: string, relativePath: string): string {
+	const require = createRequire(join(process.cwd(), 'package.json'));
+	const modEntry = require.resolve(`@useavalon/${name}`);
+	const pkgRoot = dirname(modEntry);
+	return join(pkgRoot, relativePath);
+}
+
+export const VIRTUAL_MODULE_IDS = {
+	PAGE_ROUTES: 'virtual:avalon/page-routes',
+	ISLAND_MANIFEST: 'virtual:avalon/island-manifest',
+	RUNTIME_CONFIG: 'virtual:avalon/runtime-config',
+	CONFIG: 'virtual:avalon/config',
+} as const;
+
+export const RESOLVED_VIRTUAL_IDS = {
+	PAGE_ROUTES: '\0' + VIRTUAL_MODULE_IDS.PAGE_ROUTES,
+	ISLAND_MANIFEST: '\0' + VIRTUAL_MODULE_IDS.ISLAND_MANIFEST,
+	RUNTIME_CONFIG: '\0' + VIRTUAL_MODULE_IDS.RUNTIME_CONFIG,
+	CONFIG: '\0' + VIRTUAL_MODULE_IDS.CONFIG,
+} as const;
+
+export interface NitroIntegrationResult {
+	nitroOptions: NitroConfigOutput;
+	plugins: Plugin[];
+}
+
+export interface NitroCoordinationPluginOptions {
+	avalonConfig: ResolvedAvalonConfig;
+	nitroConfig: AvalonNitroConfig;
+	verbose?: boolean;
+}
+
+/**
+ * Creates the Nitro integration for Avalon — configuration, virtual modules,
+ * build plugins, and SSR coordination.
+ *
+ * Uses the Nitro v3 Vite plugin from `nitro/vite` for server route discovery,
+ * SSR rendering pipeline, and Rolldown-optimized bundling.
+ */
+export function createNitroIntegration(
+	avalonConfig: ResolvedAvalonConfig,
+	nitroConfig: AvalonNitroConfig = {},
+): NitroIntegrationResult {
+	const nitroOptions = createNitroConfig(nitroConfig, avalonConfig);
+
+	// Nitro v3 Vite plugin — only pass keys that Nitro actually accepts.
+	// Spreading the full nitroOptions leaks Avalon-specific keys (staticAssets,
+	// publicAssets, etc.) which Nitro forwards to Rolldown, causing
+	// "Invalid input options" warnings (e.g. "jsx" key errors).
+	const nitroVitePluginOptions: Record<string, unknown> = {
+		preset: nitroOptions.preset,
+		serverDir: nitroConfig.serverDir ?? nitroOptions.serverDir ?? './server',
+		routeRules: nitroOptions.routeRules,
+		runtimeConfig: nitroOptions.runtimeConfig,
+		renderer: nitroConfig.renderer === false ? false : nitroOptions.renderer,
+		compatibilityDate: nitroOptions.compatibilityDate,
+		// Tell Nitro to scan the project root so it discovers routes/ and middleware/
+		// alongside the serverDir (./server) which contains the catch-all renderer.
+		scanDirs: ['.'],
+	};
+
+	// Only include optional keys if they're defined
+	if (nitroOptions.publicRuntimeConfig) {
+		nitroVitePluginOptions.publicRuntimeConfig = nitroOptions.publicRuntimeConfig;
+	}
+	if (nitroOptions.publicAssets) {
+		nitroVitePluginOptions.publicAssets = nitroOptions.publicAssets;
+	}
+	if (nitroOptions.compressPublicAssets) {
+		nitroVitePluginOptions.compressPublicAssets = nitroOptions.compressPublicAssets;
+	}
+	if (nitroOptions.serverEntry) {
+		nitroVitePluginOptions.serverEntry = nitroOptions.serverEntry;
+	}
+
+	const nitroPlugin = nitroVitePlugin(nitroVitePluginOptions);
+
+	const coordinationPlugin = createNitroCoordinationPlugin({
+		avalonConfig,
+		nitroConfig,
+		verbose: avalonConfig.verbose,
+	});
+
+	const virtualModulesPlugin = createVirtualModulesPlugin({
+		avalonConfig,
+		nitroConfig,
+		verbose: avalonConfig.verbose,
+	});
+
+	const buildPlugin = createNitroBuildPlugin(avalonConfig, nitroConfig);
+
+	const manifestPlugin = createIslandManifestPlugin(avalonConfig, {
+		verbose: avalonConfig.verbose,
+		generatePreloadHints: true,
+	});
+
+	const sourceMapConfig = createSourceMapConfig(nitroConfig.preset ?? 'node_server', avalonConfig.isDev);
+	const sourceMapPlugin = createSourceMapPlugin(sourceMapConfig);
+
+	return {
+		nitroOptions,
+		plugins: [
+			...(Array.isArray(nitroPlugin) ? nitroPlugin : [nitroPlugin]),
+			coordinationPlugin,
+			virtualModulesPlugin,
+			buildPlugin,
+			manifestPlugin,
+			sourceMapPlugin,
+		],
+	};
+}
+
+/**
+ * Coordination plugin: stores config/server refs, sets up SSR middleware and HMR,
+ * and prewarms core infrastructure modules (fire-and-forget).
+ */
+export function createNitroCoordinationPlugin(options: NitroCoordinationPluginOptions): Plugin {
+	const { avalonConfig, verbose } = options;
+
+	return {
+		name: 'avalon:nitro-coordination',
+		enforce: 'pre',
+
+		configResolved(_config) {
+			globalThis.__avalonConfig = avalonConfig;
+		},
+
+		configureServer(server: ViteDevServer) {
+			globalThis.__viteDevServer = server;
+
+			// Scoped middleware — discovered once, cached until invalidated by HMR
+			let scopedMiddlewareRoutes: MiddlewareRoute[] | null = null;
+
+			async function getScopedMiddleware(): Promise<MiddlewareRoute[]> {
+				if (!scopedMiddlewareRoutes) {
+					const viteRoot = server.config.root || process.cwd();
+					scopedMiddlewareRoutes = await discoverScopedMiddleware({
+						baseDir: `${viteRoot}/src`,
+						devMode: false,
+					});
+				}
+				return scopedMiddlewareRoutes;
+			}
+
+			function clearScopedMiddlewareRoutes(): void {
+				scopedMiddlewareRoutes = null;
+			}
+
+			setupHMRCoordination(server, avalonConfig, verbose, clearScopedMiddlewareRoutes);
+
+			// Pre-discover middleware (non-blocking)
+			getScopedMiddleware().catch(err => {
+				console.warn('[middleware] Failed to discover middleware:', err);
+			});
+
+			// Fire-and-forget: prewarm only core infrastructure modules.
+			// Pages, islands, and per-route middleware are loaded on-demand.
+			prewarmCoreModules(server, verbose).catch(err => {
+				console.error('[prewarm] Core modules pre-warm failed:', err);
+			});
+
+			// SSR middleware — runs before Vite's SPA fallback
+			server.middlewares.use(async (req, res, next) => {
+				const originalUrl = req.url || '/';
+				let url = originalUrl;
+
+				if (url.endsWith('.html')) url = url.slice(0, -5) || '/';
+				if (url === '/index') url = '/';
+
+				// Skip static files, HMR, and Vite internals
+				if (
+					url.startsWith('/@') ||
+					url.startsWith('/__') ||
+					url.startsWith('/node_modules/') ||
+					url.startsWith('/src/client/') ||
+					url.startsWith('/packages/') ||
+					(url.includes('.') && !url.endsWith('/'))
+				) {
+					return next();
+				}
+
+				if (url.startsWith('/api/')) {
+					return next();
+				}
+
+				try {
+					const middlewareHandled = await handleScopedMiddleware(server, url, req, res, getScopedMiddleware, verbose);
+					if (middlewareHandled) return;
+
+					// Try streaming SSR first (streams shell before page data resolves)
+					const streamed = await handleStreamingSSRRequest(server, url, avalonConfig, res);
+					if (streamed) return;
+
+					// Fallback to buffered SSR for non-modular pages
+					const html = await handleSSRRequest(server, url, avalonConfig);
+					if (html) {
+						res.statusCode = 200;
+						res.setHeader('Content-Type', 'text/html');
+						res.end(html);
+						return;
+					}
+
+					await handle404(server, url, res, avalonConfig);
+				} catch (error) {
+					console.error('[SSR Error]', error);
+					res.statusCode = 500;
+					res.setHeader('Content-Type', 'text/html');
+					res.end(generateErrorPage(error as Error));
+				}
+			});
+		},
+
+		buildStart() {
+			// no-op in production — coordination happens via other plugins
+		},
+	};
+}
+
+// ─── Dev Server Middleware Helpers ───────────────────────────────────────────
+
+import type { ServerResponse, IncomingMessage } from 'node:http';
+
+async function handleScopedMiddleware(
+	server: ViteDevServer,
+	url: string,
+	req: IncomingMessage,
+	res: ServerResponse,
+	getScopedMiddleware: () => Promise<MiddlewareRoute[]>,
+	verbose?: boolean,
+): Promise<boolean> {
+	const middlewareStart = performance.now();
+	const middlewareRoutes = await getScopedMiddleware();
+	if (middlewareRoutes.length === 0) return false;
+
+	const headers: Record<string, string> = {};
+	for (const [key, value] of Object.entries(req.headers)) {
+		if (typeof value === 'string') headers[key] = value;
+		else if (Array.isArray(value)) headers[key] = value.join(', ');
+	}
+
+	const fullUrl = `http://${req.headers.host || 'localhost'}${url}`;
+	const h3Event = {
+		url: fullUrl,
+		method: req.method || 'GET',
+		path: url,
+		node: { req, res },
+		req: new Request(fullUrl, {
+			method: req.method || 'GET',
+			headers,
+		}),
+		context: {} as Record<string, unknown>,
+	} as unknown as H3Event;
+
+	const middlewareResponse = await executeScopedMiddleware(h3Event, middlewareRoutes, { devMode: false });
+
+	const middlewareTime = performance.now() - middlewareStart;
+	if (middlewareTime > 100) {
+		console.warn(`⚠️ Slow middleware: ${middlewareTime.toFixed(0)}ms for ${url}`);
+	}
+
+	if (middlewareResponse) {
+		res.statusCode = middlewareResponse.status;
+		middlewareResponse.headers.forEach((value, key) => {
+			res.setHeader(key, value);
+		});
+		res.end(await middlewareResponse.text());
+		return true;
+	}
+	return false;
+}
+
+async function handle404(
+	server: ViteDevServer,
+	url: string,
+	res: ServerResponse,
+	config: ResolvedAvalonConfig,
+): Promise<void> {
+	try {
+		const { discoverErrorPages, getErrorPageModule, generateDefaultErrorPage } =
+			await import('../nitro/error-handler.ts');
+		const errorPages = await discoverErrorPages({
+			isDev: config.isDev,
+			pagesDir: config.pagesDir,
+			loadPageModule: async (filePath: string): Promise<PageModule> => {
+				return (await server.ssrLoadModule(filePath)) as PageModule;
+			},
+		});
+		const errorPageModule = getErrorPageModule(404, errorPages);
+
+		if (errorPageModule?.default && typeof errorPageModule.default === 'function') {
+			const { renderToHtml } = await import('../render/ssr.ts');
+			const ErrorPageComponent = errorPageModule.default;
+			const errorHtml = await renderToHtml(
+				{ component: () => ErrorPageComponent({ statusCode: 404, message: `Page not found: ${url}`, url }) },
+				{},
+			);
+			res.statusCode = 404;
+			res.setHeader('Content-Type', 'text/html');
+			res.end(errorHtml);
+			return;
+		}
+
+		const fallbackHtml = generateDefaultErrorPage(404, `Page not found: ${url}`, config.isDev);
+		res.statusCode = 404;
+		res.setHeader('Content-Type', 'text/html');
+		res.end(fallbackHtml);
+	} catch {
+		res.statusCode = 404;
+		res.setHeader('Content-Type', 'text/html');
+		res.end(generateFallback404(url));
+	}
+}
+
+/**
+ * Prewarms core infrastructure modules (fire-and-forget).
+ * Loads SSR infrastructure and framework renderers so the first page render
+ * doesn't pay the full module-load cost. Island components are loaded on-demand
+ * to avoid penalizing startup with unused modules.
+ */
+async function prewarmCoreModules(server: ViteDevServer, verbose?: boolean): Promise<void> {
+	const prewarmStart = performance.now();
+
+	const frameworkNames = ['react', 'vue', 'solid', 'svelte', 'lit', 'preact'] as const;
+
+	const coreModules = [
+		{ path: resolveAvalonPackagePath('src/render/ssr.ts'), assignTo: 'ssr' as string | null },
+		{ path: resolveAvalonPackagePath('src/core/layout/enhanced-layout-resolver.ts'), assignTo: 'layout' as string | null },
+		{ path: resolveAvalonPackagePath('src/middleware/index.ts'), assignTo: null as string | null },
+		...frameworkNames.map(name => ({
+			path: resolveIntegrationPackagePath(name, 'server/renderer.ts'),
+			assignTo: null as string | null,
+		})),
+	];
+
+	const results = await Promise.allSettled(
+		coreModules.map(async ({ path, assignTo }) => {
+			const mod = await server.ssrLoadModule(path);
+			if (assignTo === 'ssr') cachedSSRModule = mod;
+			if (assignTo === 'layout') cachedLayoutModule = mod;
+		}),
+	);
+
+	const succeeded = results.filter(r => r.status === 'fulfilled').length;
+	const totalTime = performance.now() - prewarmStart;
+
+	if (verbose && succeeded > 0) {
+		console.log(`🔥 SSR ready in ${totalTime.toFixed(0)}ms (${succeeded}/${coreModules.length} core modules)`);
+	}
+}
+
+/**
+ * Virtual modules plugin — page routes, island manifest, runtime config.
+ */
+export function createVirtualModulesPlugin(options: NitroCoordinationPluginOptions): Plugin {
+	const { avalonConfig, nitroConfig, verbose } = options;
+
+	return {
+		name: 'avalon:nitro-virtual-modules',
+		enforce: 'pre',
+
+		resolveId(id: string) {
+			if (id === VIRTUAL_MODULE_IDS.PAGE_ROUTES) return RESOLVED_VIRTUAL_IDS.PAGE_ROUTES;
+			if (id === VIRTUAL_MODULE_IDS.ISLAND_MANIFEST) return RESOLVED_VIRTUAL_IDS.ISLAND_MANIFEST;
+			if (id === VIRTUAL_MODULE_IDS.RUNTIME_CONFIG) return RESOLVED_VIRTUAL_IDS.RUNTIME_CONFIG;
+			if (id === VIRTUAL_MODULE_IDS.CONFIG) return RESOLVED_VIRTUAL_IDS.CONFIG;
+			return null;
+		},
+
+		async load(id: string) {
+			if (id === RESOLVED_VIRTUAL_IDS.PAGE_ROUTES) return await generatePageRoutesModule(avalonConfig, verbose);
+			if (id === RESOLVED_VIRTUAL_IDS.ISLAND_MANIFEST) return generateIslandManifestModule();
+			if (id === RESOLVED_VIRTUAL_IDS.RUNTIME_CONFIG) return generateRuntimeConfigModule(avalonConfig, nitroConfig);
+			if (id === RESOLVED_VIRTUAL_IDS.CONFIG) return generateConfigModule(avalonConfig, nitroConfig);
+			return null;
+		},
+
+		handleHotUpdate({ file, server }) {
+			if (file.includes(avalonConfig.pagesDir)) {
+				const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_IDS.PAGE_ROUTES);
+				if (mod) server.moduleGraph.invalidateModule(mod);
+			}
+			// Invalidate virtual:avalon/config when config-related files change
+			if (file.includes('vite.config') || file.includes('avalon.config') || file.includes('nitro.config')) {
+				const configMod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_IDS.CONFIG);
+				if (configMod) server.moduleGraph.invalidateModule(configMod);
+			}
+			return undefined;
+		},
+	};
+}
+
+// ─── HMR Coordination ───────────────────────────────────────────────────────
+
+function setupHMRCoordination(
+	server: ViteDevServer,
+	_config: ResolvedAvalonConfig,
+	_verbose?: boolean,
+	clearScopedMiddlewareRoutes?: () => void,
+): void {
+	server.watcher.on('change', file => {
+		if (file.includes('_middleware')) {
+			clearMiddlewareCache();
+			clearScopedMiddlewareRoutes?.();
+		}
+		if (file.includes('/render/') || file.includes('/layout/') || file.includes('/islands/')) {
+			cachedSSRModule = null;
+			cachedLayoutModule = null;
+		}
+		
+		if (file.includes('/layouts/') || file.includes('_layout')) {
+			const resolver = globalThis.__avalonLayoutResolver as { clearCache?: () => void } | undefined;
+			resolver?.clearCache?.();
+		}
+	});
+
+	server.watcher.on('add', file => {
+		if (file.includes('_middleware')) {
+			clearMiddlewareCache();
+			clearScopedMiddlewareRoutes?.();
+		}
+	});
+
+	server.watcher.on('unlink', file => {
+		if (file.includes('_middleware')) {
+			clearMiddlewareCache();
+			clearScopedMiddlewareRoutes?.();
+		}
+	});
+}
+
+// ─── Virtual Module Generators ───────────────────────────────────────────────
+
+async function generatePageRoutesModule(config: ResolvedAvalonConfig, _verbose?: boolean): Promise<string> {
+	try {
+		const { getAllPageDirs } = await import('./module-discovery.ts');
+		const { discoverPageRoutesFromMultipleDirs } = await import('../nitro/route-discovery.ts');
+		
+		// Get all page directories (traditional + modular)
+		const pageDirs = await getAllPageDirs(
+			config.pagesDir,
+			config.modules,
+			process.cwd()
+		);
+		
+		const routes = await discoverPageRoutesFromMultipleDirs(pageDirs, {
+			developmentMode: config.isDev,
+		});
+		
+		const routesJson = JSON.stringify(routes, null, 2);
+		return `export const pageRoutes = ${routesJson};\nexport default pageRoutes;\n`;
+	} catch {
+		return `export const pageRoutes = [];\nexport default pageRoutes;\n`;
+	}
+}
+
+function generateIslandManifestModule(): string {
+	return `export const islandManifest = { islands: {}, clientEntry: "", css: [] };\nexport default islandManifest;\n`;
+}
+
+function generateRuntimeConfigModule(avalonConfig: ResolvedAvalonConfig, nitroConfig: AvalonNitroConfig): string {
+	const runtimeConfig = {
+		avalon: {
+			streaming: nitroConfig.streaming ?? true,
+			pagesDir: avalonConfig.pagesDir,
+			layoutsDir: avalonConfig.layoutsDir,
+			isDev: avalonConfig.isDev,
+		},
+		...nitroConfig.runtimeConfig,
+	};
+	return `export const runtimeConfig = ${JSON.stringify(runtimeConfig, null, 2)};\nexport function useRuntimeConfig() { return runtimeConfig; }\nexport default runtimeConfig;\n`;
+}
+
+export function generateConfigModule(avalonConfig: ResolvedAvalonConfig, nitroConfig: AvalonNitroConfig): string {
+	const config = {
+		streaming: nitroConfig.streaming ?? true,
+		pagesDir: avalonConfig.pagesDir,
+		layoutsDir: avalonConfig.layoutsDir,
+		isDev: avalonConfig.isDev,
+		...nitroConfig.runtimeConfig,
+	};
+	return `const config = ${JSON.stringify(config, null, 2)};\nexport function useAvalonConfig() { return config; }\nexport default config;\n`;
+}
+
+// ─── Public Accessors ────────────────────────────────────────────────────────
+
+export function getViteDevServer(): ViteDevServer | undefined {
+	return globalThis.__viteDevServer;
+}
+
+export function getAvalonConfig(): ResolvedAvalonConfig | undefined {
+	return globalThis.__avalonConfig;
+}
+
+export function isDevelopmentMode(): boolean {
+	return globalThis.__avalonConfig?.isDev ?? true;
+}
+
+// ─── SSR Request Handling ────────────────────────────────────────────────────
+
+const STREAM_MARKER = '<!--AVALON_STREAM_BOUNDARY-->';
+
+let cachedSSRModule: unknown = null;
+
+let cachedLayoutModule: unknown = null;
+
+/**
+ * Streaming SSR handler — flushes the layout shell to the browser before
+ * the page component's async data fetching resolves.
+ *
+ * Flow:
+ * 1. Load page module + layout modules, collect CSS
+ * 2. Render shell layout with a marker placeholder as children
+ * 3. Split HTML on the marker → shellBefore / shellAfter
+ * 4. res.write(shellBefore) — browser starts parsing <html><head>... immediately
+ * 5. Render page content (awaits data fetches)
+ * 6. Render wrapper layouts around page content
+ * 7. res.write(wrappedContent + shellAfter)
+ * 8. res.end()
+ *
+ * Falls back to null (caller uses buffered path) when:
+ * - No modular layouts configured
+ * - Page not found
+ * - No shell layout detected
+ * - Page provides its own complete HTML document
+ */
+async function handleStreamingSSRRequest(
+	server: ViteDevServer,
+	url: string,
+	config: ResolvedAvalonConfig,
+	res: ServerResponse,
+): Promise<boolean> {
+	// Streaming only works with modular layouts (need shell + wrapper separation)
+	if (!config.modules) return false;
+
+	const pathname = url.split('?')[0];
+	const pageFile = await findPageFile(pathname, config, server);
+	if (!pageFile) return false;
+
+	try {
+		const pageModule = await server.ssrLoadModule(pageFile);
+		const PageComponent = pageModule.default;
+		if (!PageComponent) return false;
+
+		// Check if page wants to skip layouts entirely (provides own HTML)
+		const layoutConfig = pageModule.layoutConfig as { skipLayouts?: string[] } | undefined;
+
+		// Collect CSS
+		const cssContents = await collectCssFromModuleGraph(server, pageFile);
+		const layoutFiles = await discoverLayoutFiles(pathname, server);
+
+		const layoutModules: Array<{ file: string; module: Record<string, unknown> }> = [];
+		for (const layoutFile of layoutFiles) {
+			const layoutModule = await server.ssrLoadModule(layoutFile);
+			layoutModules.push({ file: layoutFile, module: layoutModule });
+		}
+		for (const layoutFile of layoutFiles) {
+			const layoutCss = await collectCssFromModuleGraph(server, layoutFile);
+			cssContents.push(...layoutCss);
+		}
+
+		if (layoutModules.length === 0) return false;
+
+		const { render: preactRender } = await server.ssrLoadModule('preact-render-to-string');
+		const { h } = await server.ssrLoadModule('preact');
+
+		const skipLayouts = layoutConfig?.skipLayouts || [];
+		const activeLayouts = layoutModules.filter(({ file }) => {
+			const layoutName = file.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
+			return !skipLayouts.includes(layoutName);
+		});
+
+		const frontmatter = pageModule.frontmatter as Record<string, unknown> | undefined;
+		const metadata = pageModule.metadata as Record<string, unknown> | undefined;
+		const mergedFrontmatter = { ...frontmatter, ...metadata, currentPath: pathname };
+		const layoutProps = {
+			children: null as unknown,
+			frontmatter: mergedFrontmatter,
+			params: {},
+			url: pathname,
+		};
+
+		// Categorize layouts into shell vs wrapper
+		const shellLayouts: Array<{ module: Record<string, unknown> }> = [];
+		const wrapperLayouts: Array<{ module: Record<string, unknown> }> = [];
+
+		for (const layout of activeLayouts) {
+			const LayoutComponent = layout.module.default;
+			if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
+			try {
+				const testProps = { ...layoutProps, children: h('div', null, 'test') };
+				const testResult = (LayoutComponent as (props: unknown) => unknown)(testProps);
+				const resolvedTest = testResult instanceof Promise ? await testResult : testResult;
+				const testHtml = preactRender(resolvedTest);
+				if (testHtml.trim().startsWith('<html') || testHtml.includes('<!DOCTYPE')) {
+					shellLayouts.push(layout);
+				} else {
+					wrapperLayouts.push(layout);
+				}
+			} catch {
+				wrapperLayouts.push(layout);
+			}
+		}
+
+		// Need a shell layout to stream
+		if (shellLayouts.length === 0) return false;
+
+		// Render shell layout with stream marker as children
+		const { module: shellModule } = shellLayouts[shellLayouts.length - 1];
+		const ShellComponent = shellModule.default;
+		if (!ShellComponent || typeof ShellComponent !== 'function') return false;
+
+		let shellHtml: string;
+		try {
+			const shellProps = {
+				...layoutProps,
+				children: h('div', { dangerouslySetInnerHTML: { __html: STREAM_MARKER } }),
+			};
+			const shellResult = (ShellComponent as (props: unknown) => unknown)(shellProps);
+			const resolvedShell = shellResult instanceof Promise ? await shellResult : shellResult;
+			shellHtml = preactRender(resolvedShell);
+		} catch {
+			return false;
+		}
+
+		// Split on marker
+		const markerIndex = shellHtml.indexOf(STREAM_MARKER);
+		if (markerIndex === -1) return false;
+
+		let shellBefore = shellHtml.slice(0, markerIndex);
+		const shellAfter = shellHtml.slice(markerIndex + STREAM_MARKER.length);
+
+		// Inject CSS into the shell's <head>
+		let shellBeforeWithCss = shellBefore;
+		if (cssContents.length > 0) {
+			const cssTag = `<style data-avalon-ssr-css>${cssContents.join('\n')}</style>`;
+			if (shellBefore.includes('</head>')) {
+				shellBeforeWithCss = shellBefore.replace('</head>', `${cssTag}\n</head>`);
+			} else {
+				shellBeforeWithCss = shellBefore + cssTag;
+			}
+		}
+
+		// Ensure DOCTYPE
+		if (!shellBeforeWithCss.trim().toLowerCase().startsWith('<!doctype')) {
+			shellBeforeWithCss = '<!DOCTYPE html>\n' + shellBeforeWithCss;
+		}
+
+		// Inject universal CSS and head content
+		const universalCSS = getUniversalCSSForHead(true);
+		if (universalCSS && shellBeforeWithCss.includes('</head>')) {
+			shellBeforeWithCss = shellBeforeWithCss.replace('</head>', `${universalCSS}\n</head>`);
+		}
+		const universalHead = getUniversalHeadForInjection(true);
+		if (universalHead && shellBeforeWithCss.includes('</head>')) {
+			shellBeforeWithCss = shellBeforeWithCss.replace('</head>', `${universalHead}\n</head>`);
+		}
+
+		// ── FLUSH SHELL ──
+		res.statusCode = 200;
+		res.setHeader('Content-Type', 'text/html; charset=utf-8');
+		res.setHeader('Transfer-Encoding', 'chunked');
+		res.setHeader('X-Avalon-Streaming', '1');
+		res.flushHeaders();
+		res.write(shellBeforeWithCss);
+
+		// ── RENDER PAGE CONTENT (this is where data fetching happens) ──
+		let pageContent: string;
+		try {
+			const pageResult = typeof PageComponent === 'function'
+				? (PageComponent as () => unknown)()
+				: PageComponent;
+			const resolvedPage = pageResult instanceof Promise ? await pageResult : pageResult;
+			pageContent = preactRender(resolvedPage);
+		} catch (error) {
+			console.error('[SSR Streaming] Error rendering page component:', error);
+			pageContent = `<div>Error rendering page</div>`;
+		}
+
+		// Check if page returned a complete HTML doc (shouldn't happen with layouts, but safety check)
+		const isCompleteDoc = pageContent.trim().startsWith('<!DOCTYPE html>') ||
+			pageContent.trim().startsWith('<html');
+		if (isCompleteDoc) {
+			// Can't stream this — just send it and close
+			res.end(pageContent);
+			return true;
+		}
+
+		// Apply wrapper layouts around page content
+		let content = pageContent;
+		for (const { module: layoutModule } of wrapperLayouts) {
+			const LayoutComponent = layoutModule.default;
+			if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
+			try {
+				const props = {
+					...layoutProps,
+					children: h('div', { dangerouslySetInnerHTML: { __html: content } }),
+				};
+				const layoutResult = (LayoutComponent as (props: unknown) => unknown)(props);
+				const resolvedLayout = layoutResult instanceof Promise ? await layoutResult : layoutResult;
+				content = preactRender(resolvedLayout);
+			} catch (error) {
+				console.error('[SSR Streaming] Error rendering wrapper layout:', error);
+			}
+		}
+
+		// ── FLUSH PAGE CONTENT + SHELL TAIL ──
+		// Inject client scripts before closing </body>
+		let tail = content + shellAfter;
+		if (!tail.includes('/src/client/main.js') && !tail.includes('/@vite/client')) {
+			const bodyCloseIndex = tail.lastIndexOf('</body>');
+			if (bodyCloseIndex !== -1) {
+				tail = tail.slice(0, bodyCloseIndex) +
+					'\n<script type="module" src="/@vite/client"></script>\n' +
+					'<script type="module" src="/src/client/main.js"></script>\n' +
+					tail.slice(bodyCloseIndex);
+			}
+		}
+
+		res.end(tail);
+		return true;
+	} catch (error) {
+		// If we already started writing, we can't change status code
+		if (res.headersSent) {
+			res.end(`<div>Streaming SSR error: ${(error as Error).message}</div></body></html>`);
+			return true;
+		}
+		return false;
+	}
+}
+
+
+async function handleSSRRequest(
+	server: ViteDevServer,
+	url: string,
+	config: ResolvedAvalonConfig,
+): Promise<string | null> {
+	const pathname = url.split('?')[0];
+	const pageFile = await findPageFile(pathname, config, server);
+
+	if (!pageFile) return null;
+
+	try {
+		const pageModule = await server.ssrLoadModule(pageFile);
+		const PageComponent = pageModule.default;
+
+		if (!PageComponent) {
+			console.warn(`[SSR] Page ${pageFile} has no default export`);
+			return null;
+		}
+
+		// Collect CSS from the module graph after loading the page module.
+		// This captures CSS modules, plain CSS imports, and any transitive CSS deps.
+		const cssContents = await collectCssFromModuleGraph(server, pageFile);
+
+		// Pre-load layout files via ssrLoadModule so their CSS modules enter
+		// Vite's module graph *before* we collect CSS from them.
+		const layoutFiles = await discoverLayoutFiles(pathname, server);
+		
+		// Load all layout modules
+		const layoutModules: Array<{ file: string; module: Record<string, unknown> }> = [];
+		for (const layoutFile of layoutFiles) {
+			const layoutModule = await server.ssrLoadModule(layoutFile);
+			layoutModules.push({ file: layoutFile, module: layoutModule });
+		}
+
+		// Collect CSS from layout files and merge with page CSS
+		for (const layoutFile of layoutFiles) {
+			const layoutCss = await collectCssFromModuleGraph(server, layoutFile);
+			cssContents.push(...layoutCss);
+		}
+
+		let html: string;
+		
+		// If we have modular layouts, use manual layout composition
+		if (config.modules && layoutModules.length > 0) {
+			html = await renderPageWithManualLayouts(
+				PageComponent,
+				pageModule,
+				layoutModules,
+				pathname,
+				config,
+				server
+			);
+		} else {
+			html = await renderPageToHtml(PageComponent, pageModule, pathname, config, server);
+		}
+
+		// Inject collected CSS into the HTML so styles are present on first paint
+		if (cssContents.length > 0) {
+			html = injectSsrCss(html, cssContents);
+		}
+
+		return html;
+	} catch (error) {
+		console.error(`[SSR] Error rendering ${pageFile}:`, error);
+		throw error;
+	}
+}
+
+/**
+ * Render a page with manually composed layouts (for modular architecture)
+ * 
+ * Layout composition order:
+ * 1. Page content is rendered first
+ * 2. Module-specific layouts (e.g., docs/_layout.tsx) wrap the page content
+ * 3. Root/shell layout (shared/_layout.tsx) wraps everything last
+ * 
+ * This ensures that layouts returning `<div>` wrappers are applied before
+ * layouts returning complete `<html>` documents.
+ */
+async function renderPageWithManualLayouts(
+	PageComponent: unknown,
+	pageModule: Record<string, unknown>,
+	layoutModules: Array<{ file: string; module: Record<string, unknown> }>,
+	pathname: string,
+	config: ResolvedAvalonConfig,
+	server: ViteDevServer,
+): Promise<string> {
+	const { render: preactRender } = await server.ssrLoadModule('preact-render-to-string');
+	const { h } = await server.ssrLoadModule('preact');
+	
+	// Check if page wants to skip certain layouts
+	const layoutConfig = pageModule.layoutConfig as { skipLayouts?: string[] } | undefined;
+	const skipLayouts = layoutConfig?.skipLayouts || [];
+	
+	// Filter out skipped layouts
+	const activeLayouts = layoutModules.filter(({ file }) => {
+		const layoutName = file.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
+		return !skipLayouts.includes(layoutName);
+	});
+	
+	// Render page content first
+	let pageContent: string;
+	try {
+		const pageResult = typeof PageComponent === 'function' 
+			? (PageComponent as () => unknown)() 
+			: PageComponent;
+		const resolvedPage = pageResult instanceof Promise ? await pageResult : pageResult;
+		pageContent = preactRender(resolvedPage);
+	} catch (error) {
+		console.error('[SSR] Error rendering page component:', error);
+		pageContent = `<div>Error rendering page</div>`;
+	}
+	
+	// Check if page content is a complete HTML document
+	const isCompleteDoc = pageContent.trim().startsWith('<!DOCTYPE html>') || 
+		pageContent.trim().startsWith('<html');
+	
+	if (isCompleteDoc) {
+		// Page provides its own HTML structure, inject client script and return
+		return injectClientScript(pageContent);
+	}
+	
+	// Separate layouts into shell (returns <html>) and wrapper (returns <div>) layouts
+	// We need to render each layout to determine its type, then apply in correct order
+	// Merge frontmatter and metadata - metadata takes precedence for page-specific values
+	const frontmatter = pageModule.frontmatter as Record<string, unknown> | undefined;
+	const metadata = pageModule.metadata as Record<string, unknown> | undefined;
+	const mergedFrontmatter = { ...frontmatter, ...metadata, currentPath: pathname };
+	
+	const layoutProps = {
+		children: null as unknown, // Will be set per-layout
+		frontmatter: mergedFrontmatter,
+		params: {},
+		url: pathname,
+	};
+	
+	// Categorize layouts by rendering them with placeholder content
+	const shellLayouts: Array<{ module: Record<string, unknown> }> = [];
+	const wrapperLayouts: Array<{ module: Record<string, unknown> }> = [];
+	
+	for (const layout of activeLayouts) {
+		const LayoutComponent = layout.module.default;
+		if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
+		
+		try {
+			// Render with placeholder to detect if it returns HTML shell
+			const testProps = {
+				...layoutProps,
+				children: h('div', null, 'test'),
+			};
+			const testResult = (LayoutComponent as (props: unknown) => unknown)(testProps);
+			const resolvedTest = testResult instanceof Promise ? await testResult : testResult;
+			const testHtml = preactRender(resolvedTest);
+			
+			if (testHtml.trim().startsWith('<html') || testHtml.includes('<!DOCTYPE')) {
+				shellLayouts.push(layout);
+			} else {
+				wrapperLayouts.push(layout);
+			}
+		} catch {
+			// If we can't determine, treat as wrapper
+			wrapperLayouts.push(layout);
+		}
+	}
+	
+	// Apply wrapper layouts first (innermost to outermost)
+	// These are module-specific layouts that return <div> wrappers
+	let content = pageContent;
+	
+	for (const { module: layoutModule } of wrapperLayouts) {
+		const LayoutComponent = layoutModule.default;
+		if (!LayoutComponent || typeof LayoutComponent !== 'function') continue;
+		
+		try {
+			const props = {
+				...layoutProps,
+				children: h('div', { dangerouslySetInnerHTML: { __html: content } }),
+			};
+			
+			const layoutResult = (LayoutComponent as (props: unknown) => unknown)(props);
+			const resolvedLayout = layoutResult instanceof Promise ? await layoutResult : layoutResult;
+			content = preactRender(resolvedLayout);
+		} catch (error) {
+			console.error('[SSR] Error rendering wrapper layout:', error);
+		}
+	}
+	
+	// Apply shell layout last (the one that provides <html>)
+	// If there are multiple shell layouts, prefer the module-specific one (last in array)
+	// since layouts are discovered in order: shared -> module-specific
+	if (shellLayouts.length > 0) {
+		// Use the last shell layout (module-specific takes precedence over shared)
+		const { module: shellModule } = shellLayouts[shellLayouts.length - 1];
+		const ShellComponent = shellModule.default;
+		
+		if (ShellComponent && typeof ShellComponent === 'function') {
+			try {
+				const props = {
+					...layoutProps,
+					children: h('div', { dangerouslySetInnerHTML: { __html: content } }),
+				};
+				
+				const shellResult = (ShellComponent as (props: unknown) => unknown)(props);
+				const resolvedShell = shellResult instanceof Promise ? await shellResult : shellResult;
+				content = preactRender(resolvedShell);
+			} catch (error) {
+				console.error('[SSR] Error rendering shell layout:', error);
+			}
+		}
+	}
+	
+	// Check if final content is a complete HTML document
+	const isFinalCompleteDoc = content.trim().startsWith('<!DOCTYPE html>') || 
+		content.trim().startsWith('<html');
+	
+	if (isFinalCompleteDoc) {
+		return injectClientScript(content);
+	}
+	
+	// Wrap in basic HTML structure (fallback if no shell layout)
+	const fallbackMetadata = (pageModule.metadata || {}) as { title?: string; description?: string };
+	const title = fallbackMetadata.title || 'Avalon App';
+	const description = fallbackMetadata.description || '';
+	
+	return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(title)}</title>
+    ${description ? `<meta name="description" content="${escapeHtml(description)}">` : ''}
+    <script type="module" src="/@vite/client"></script>
+  </head>
+  <body>
+    ${content}
+    <script type="module" src="/src/client/main.js"></script>
+  </body>
+</html>`;
+}
+
+/**
+ * Inject client script into HTML if not already present.
+ * Also ensures DOCTYPE is present for valid HTML5.
+ */
+function injectClientScript(html: string): string {
+	let result = html;
+	
+	// Ensure DOCTYPE is present
+	if (!result.trim().toLowerCase().startsWith('<!doctype')) {
+		result = '<!DOCTYPE html>\n' + result;
+	}
+	
+	// Inject universal CSS from island framework renderers (Svelte scoped, Vue scoped, Solid CSS, etc.)
+	if (!result.includes('data-universal-ssr="true"')) {
+		const universalCSS = getUniversalCSSForHead(true);
+		if (universalCSS && result.includes('</head>')) {
+			result = result.replace('</head>', `${universalCSS}\n</head>`);
+		}
+	}
+	
+	// Inject universal head content (hydration scripts from frameworks like Solid)
+	const universalHead = getUniversalHeadForInjection(true);
+	if (universalHead && result.includes('</head>')) {
+		result = result.replace('</head>', `${universalHead}\n</head>`);
+	}
+	
+	// Skip if scripts already present
+	if (result.includes('/src/client/main.js') || result.includes('/@vite/client')) {
+		return result;
+	}
+	
+	// Inject before </body> or at the end
+	const bodyCloseIndex = result.lastIndexOf('</body>');
+	if (bodyCloseIndex !== -1) {
+		return result.slice(0, bodyCloseIndex) + 
+			'\n<script type="module" src="/@vite/client"></script>\n' +
+			'<script type="module" src="/src/client/main.js"></script>\n' +
+			result.slice(bodyCloseIndex);
+	}
+	
+	return result + '\n<script type="module" src="/@vite/client"></script>\n<script type="module" src="/src/client/main.js"></script>';
+}
+
+/**
+ * Discover layout files that apply to a given route path.
+ *
+ * Supports both traditional layouts (src/layouts/) and modular layouts (app/modules/[module]/layouts/).
+ * For route "/blog/post", checks shared layouts, module layouts, and traditional layouts.
+ */
+async function discoverLayoutFiles(pathname: string, server: ViteDevServer): Promise<string[]> {
+	const viteRoot = server.config.root || process.cwd();
+	const config = globalThis.__avalonConfig;
+	const layoutFileName = '_layout.tsx';
+	const layoutFiles: string[] = [];
+
+	// Build path hierarchy: "/" → [''], "/blog/post" → ['', '/blog', '/blog/post']
+	const segments = pathname.split('/').filter(Boolean);
+	const paths = [''];
+	for (let i = 0; i < segments.length; i++) {
+		paths.push('/' + segments.slice(0, i + 1).join('/'));
+	}
+
+	// Helper to check and add layout file
+	async function tryAddLayout(fullPath: string): Promise<void> {
+		try {
+			const stat = await fsStat(fullPath);
+			if (stat.isFile()) {
+				const relativePath = fullPath.slice(viteRoot.length);
+				if (!layoutFiles.includes(relativePath)) {
+					layoutFiles.push(relativePath);
+				}
+			}
+		} catch {
+			// Layout file doesn't exist — that's fine
+		}
+	}
+
+	// 1. Check shared layouts directory (root layout)
+	if (config?.layoutsDir) {
+		const sharedLayoutsDir = `${viteRoot}/${config.layoutsDir}`;
+		await tryAddLayout(`${sharedLayoutsDir}/${layoutFileName}`);
+	}
+
+	// 2. Check modular layouts (app/modules/*/layouts/)
+	if (config?.modules) {
+		const modulesDir = `${viteRoot}/${config.modules.dir}`;
+		const layoutsDirName = config.modules.layoutsDirName;
+		
+		// Determine which module this route belongs to
+		const firstSegment = segments[0] || '';
+		const rootModules = ['home', 'root', 'main', 'index'];
+		
+		// For root routes, check the home/root/main/index module
+		if (!firstSegment || rootModules.includes(firstSegment.toLowerCase())) {
+			for (const moduleName of rootModules) {
+				await tryAddLayout(`${modulesDir}/${moduleName}/${layoutsDirName}/${layoutFileName}`);
+			}
+		} else {
+			// For other routes, check the module matching the first segment
+			await tryAddLayout(`${modulesDir}/${firstSegment}/${layoutsDirName}/${layoutFileName}`);
+		}
+	}
+
+	// 3. Check traditional layouts directory (src/layouts/)
+	const traditionalLayoutsDir = `${viteRoot}/src/layouts`;
+	for (const pathSegment of paths) {
+		const fullPath = pathSegment === ''
+			? `${traditionalLayoutsDir}/${layoutFileName}`
+			: `${traditionalLayoutsDir}${pathSegment}/${layoutFileName}`;
+		await tryAddLayout(fullPath);
+	}
+
+	return layoutFiles;
+}
+
+async function findPageFile(pathname: string, config: ResolvedAvalonConfig, server: ViteDevServer): Promise<string | null> {
+	let normalizedPath = pathname;
+	if (normalizedPath.endsWith('/') && normalizedPath !== '/') {
+		normalizedPath = normalizedPath.slice(0, -1);
+	}
+	if (normalizedPath === '/') {
+		normalizedPath = '/index';
+	}
+
+	const extensions = ['.tsx', '.ts', '.jsx', '.js', '.mdx', '.md'];
+	const viteRoot = server.config.root || process.cwd();
+	
+	// Helper to check if a file exists
+	async function tryFile(relativePath: string): Promise<string | null> {
+		try {
+			const fullPath = `${viteRoot}/${relativePath}`;
+			const stat = await fsStat(fullPath);
+			if (stat.isFile()) return `/${relativePath}`;
+		} catch {
+			// File doesn't exist
+		}
+		return null;
+	}
+
+	// 1. Check modular page directories first
+	if (config.modules) {
+		const modulesDir = config.modules.dir;
+		const pagesDirName = config.modules.pagesDirName;
+		const segments = pathname.split('/').filter(Boolean);
+		const firstSegment = segments[0] || '';
+		const rootModules = ['home', 'root', 'main', 'index'];
+		
+		// Determine which module and what the relative path within that module is
+		let moduleName: string;
+		let moduleRelativePath: string;
+		
+		if (!firstSegment || rootModules.includes(firstSegment.toLowerCase())) {
+			// Root route - check home module
+			moduleName = 'home';
+			moduleRelativePath = normalizedPath;
+		} else {
+			// Check if first segment matches a module
+			moduleName = firstSegment;
+			// Remove the module prefix from the path
+			const remainingSegments = segments.slice(1);
+			moduleRelativePath = remainingSegments.length > 0 
+				? '/' + remainingSegments.join('/') 
+				: '/index';
+		}
+		
+		// Try to find the page in the module
+		for (const ext of extensions) {
+			const result = await tryFile(`${modulesDir}/${moduleName}/${pagesDirName}${moduleRelativePath}${ext}`);
+			if (result) return result;
+		}
+		if (!moduleRelativePath.endsWith('/index')) {
+			for (const ext of extensions) {
+				const result = await tryFile(`${modulesDir}/${moduleName}/${pagesDirName}${moduleRelativePath}/index${ext}`);
+				if (result) return result;
+			}
+		}
+	}
+
+	// 2. Check traditional pages directory
+	const pagesDir = config.pagesDir;
+	for (const ext of extensions) {
+		const result = await tryFile(`${pagesDir}${normalizedPath}${ext}`);
+		if (result) return result;
+	}
+	if (!normalizedPath.endsWith('/index')) {
+		for (const ext of extensions) {
+			const result = await tryFile(`${pagesDir}${normalizedPath}/index${ext}`);
+			if (result) return result;
+		}
+	}
+
+	return null;
+}
+
+async function renderPageToHtml(
+	PageComponent: unknown,
+	pageModule: Record<string, unknown>,
+	pathname: string,
+	config: ResolvedAvalonConfig,
+	server: ViteDevServer,
+): Promise<string> {
+	const metadata = (pageModule.metadata || {}) as { title?: string; description?: string };
+
+	try {
+		if (!cachedSSRModule) {
+			cachedSSRModule = await server.ssrLoadModule(resolveAvalonPackagePath('src/render/ssr.ts'));
+		}
+		// cachedSSRModule is the dynamically-loaded render/ssr.ts module;
+		// expected exports: renderToHtml, renderToHtmlWithLayouts
+		const ssrModule = cachedSSRModule as Record<string, unknown>;
+
+		if (!cachedLayoutModule) {
+			cachedLayoutModule = await server.ssrLoadModule(resolveAvalonPackagePath('src/core/layout/enhanced-layout-resolver.ts'));
+		}
+		// cachedLayoutModule is the dynamically-loaded enhanced-layout-resolver.ts module;
+		// expected exports: EnhancedLayoutResolver, EnhancedLayoutResolverUtils
+		const layoutModule = cachedLayoutModule as Record<string, unknown>;
+
+		const routeConfig = {
+			component: () => (typeof PageComponent === 'function' ? (PageComponent as () => unknown)() : PageComponent),
+			options: { title: metadata.title || 'Avalon App' },
+			frontmatter: pageModule.frontmatter as Record<string, unknown> | undefined,
+		};
+
+		// Try layout-aware rendering first
+		if (
+			ssrModule.renderToHtmlWithLayouts &&
+			layoutModule.EnhancedLayoutResolver &&
+			layoutModule.EnhancedLayoutResolverUtils
+		) {
+			try {
+				const viteRoot = server.config.root || process.cwd();
+
+				if (!globalThis.__avalonLayoutResolver) {
+					const EnhancedLayoutResolver = layoutModule.EnhancedLayoutResolver as new (
+						opts: Record<string, unknown>,
+					) => unknown;
+					
+					// Use the shared layouts directory as the base
+					// The resolver will also check modular layouts via the layout composer
+					const layoutsDir = config.layoutsDir || 'src/layouts';
+					
+					globalThis.__avalonLayoutResolver = new EnhancedLayoutResolver({
+						baseDirectory: `${viteRoot}/${layoutsDir}`,
+						filePattern: '_layout.tsx',
+						excludeDirectories: ['node_modules', '.git', 'dist', 'build'],
+						enableWatching: true,
+						developmentMode: false,
+						enableCaching: true,
+						cacheTTL: 60 * 1000,
+						maxCacheSize: 100,
+						enableStreaming: true,
+						enableErrorBoundaries: true,
+						enableMetrics: false,
+						enableDebugInfo: false,
+						// Pass modules config for modular layout discovery
+						modulesDir: config.modules ? `${viteRoot}/${config.modules.dir}` : undefined,
+						modulesLayoutsDirName: config.modules?.layoutsDirName,
+					});
+				}
+
+				const fullUrl = `http://localhost${pathname}`;
+				const layoutContext = {
+					params: {},
+					query: {},
+					url: fullUrl,
+					request: { method: 'GET', url: fullUrl, headers: new Headers() },
+				};
+
+				return await (ssrModule.renderToHtmlWithLayouts as Function)(
+					routeConfig,
+					globalThis.__avalonLayoutResolver,
+					layoutContext,
+					pathname,
+					{ title: metadata.title || 'Avalon App' },
+					undefined,
+					{ suppressWarnings: true },
+				);
+			} catch {
+				// Layout rendering failed, fall back to basic rendering
+			}
+		}
+
+		if (ssrModule.renderToHtml) {
+			return await (ssrModule.renderToHtml as Function)(
+				routeConfig,
+				{ title: metadata.title || 'Avalon App' },
+				undefined,
+				{ suppressWarnings: true },
+			);
+		}
+	} catch {
+		// SSR module not available, fall back to basic rendering
+	}
+
+	// Fallback: basic HTML template
+	const title = metadata.title || 'Avalon App';
+	const description = metadata.description || '';
+	let content = '';
+	try {
+		const preactRenderModule = await server.ssrLoadModule('preact-render-to-string');
+		if (preactRenderModule.render && typeof PageComponent === 'function') {
+			content = preactRenderModule.render((PageComponent as () => unknown)());
+		}
+	} catch {
+		content = `<p>Loading page: ${escapeHtml(pathname)}</p>`;
+	}
+
+	return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(title)}</title>
+    ${description ? `<meta name="description" content="${escapeHtml(description)}">` : ''}
+    <script type="module" src="/@vite/client"></script>
+  </head>
+  <body>
+    <div id="app">${content}</div>
+    <script type="module" src="/src/client/main.js"></script>
+  </body>
+</html>`;
+}
+
+function escapeHtml(str: string): string {
+	return str
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&#039;');
+}
+
+// ─── Global Type Declarations ────────────────────────────────────────────────
+
+declare global {
+	// deno-lint-ignore no-var
+	var __avalonLayoutResolver: unknown;
+}