@useavalon/avalon 0.1.0

package/src/nitro/renderer.ts

@@ -0,0 +1,1458 @@
+/**
+ * Nitro SSR Renderer Handler for Avalon
+ *
+ * This module provides the main SSR renderer for Nitro integration.
+ * It handles page rendering using Avalon's existing SSR pipeline while
+ * integrating with Nitro's h3 event handling system.
+ *
+ * The renderer acts as a catch-all handler for Nitro - it receives requests
+ * that don't match any API routes or static files, and renders the appropriate
+ * page using Avalon's SSR pipeline.
+ *
+ * Key design principle: This renderer relies on Nitro's built-in file-system
+ * routing for route matching. Custom route matching logic has been removed
+ * in favor of Nitro's native capabilities.
+ *
+ * Middleware Integration:
+ * - Global middleware runs first (handled by Nitro's middleware/ directory)
+ * - Route-scoped middleware runs after global middleware, before page rendering
+ * - If global middleware terminates, route-scoped middleware does not run
+ *
+ * Custom Error Pages:
+ * - Supports custom 404 page (src/pages/404.tsx)
+ * - Supports custom 500 page (src/pages/500.tsx)
+ * - Supports generic error page (src/pages/_error.tsx)
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 5.1, 5.3, 9.1, 9.2, 9.3, 9.4, 10.5
+ */
+
+import type {
+	NitroRenderContext,
+	SSRRenderOptions,
+	SSRRenderResult,
+	PageModule,
+	AvalonRuntimeConfig,
+	HttpError,
+} from './types.ts';
+import type { H3Event } from 'h3';
+import { getRequestURL as h3GetRequestURL } from 'h3';
+import { createNotFoundError, isHttpError } from './types.ts';
+import type { MiddlewareRoute } from '../middleware/types.ts';
+import { discoverScopedMiddleware, executeScopedMiddleware } from '../middleware/index.ts';
+import {
+	handleRenderError as handleRenderErrorWithCustomPages,
+	discoverErrorPages,
+	type ErrorHandlerOptions,
+} from './error-handler.ts';
+
+/**
+ * Resolved page route information
+ */
+export interface ResolvedPageRoute {
+	/** File path to the page module */
+	filePath: string;
+	/** Route pattern that matched */
+	pattern: string;
+	/** Extracted route parameters */
+	params: Record<string, string>;
+	/** Layout files to apply (outermost first) */
+	layouts?: string[];
+}
+
+/**
+ * Render handler options
+ *
+ * Simplified for Nitro's catch-all pattern - route resolution is now
+ * handled by Nitro's file-system routing, so custom resolvers are optional
+ * and primarily used for development/testing scenarios.
+ */
+export interface RenderHandlerOptions {
+	/** Avalon runtime configuration */
+	avalonConfig: AvalonRuntimeConfig;
+	/** Whether running in development mode */
+	isDev?: boolean;
+	/** Vite dev server URL for development */
+	viteServerUrl?: string;
+	/**
+	 * Custom page resolver function (optional)
+	 * In production, Nitro handles route resolution via file-system routing.
+	 * This is primarily used for development with Vite's SSR module loading.
+	 */
+	resolvePageRoute?: (pathname: string, pagesDir: string) => Promise<ResolvedPageRoute | null>;
+	/**
+	 * Custom page module loader (optional)
+	 * In production, modules are loaded from the build output.
+	 * In development, Vite's ssrLoadModule is used.
+	 */
+	loadPageModule?: (filePath: string) => Promise<PageModule>;
+	/** Custom layout resolver */
+	resolveLayouts?: (routePath: string, config: AvalonRuntimeConfig) => Promise<string[]>;
+	/**
+	 * Enable custom error pages (404.tsx, 500.tsx, _error.tsx)
+	 * When enabled, the renderer will look for custom error pages in the pages directory
+	 * Requirements: 10.5
+	 */
+	enableCustomErrorPages?: boolean;
+}
+
+/**
+ * Creates a render context from an H3 event
+ *
+ * @param event - The H3 event from Nitro
+ * @param params - Route parameters extracted from the URL
+ * @returns NitroRenderContext for use in rendering
+ */
+export function createRenderContext(event: H3Event, params: Record<string, string> = {}): NitroRenderContext {
+	const url = getRequestURL(event);
+
+	return {
+		url,
+		params,
+		query: Object.fromEntries(url.searchParams),
+		request: toRequest(event),
+		event,
+	};
+}
+
+/**
+ * Gets the request URL from an H3 event
+ */
+export function getRequestURL(event: H3Event): URL {
+	// Use h3's getRequestURL for h3 v2 compatibility
+	const protocol = 'http';
+	const host = 'localhost';
+	return new URL(h3GetRequestURL(event).pathname, `${protocol}://${host}`);
+}
+
+/**
+ * Converts an H3 event to a standard Request object
+ */
+export function toRequest(event: H3Event): Request {
+	const url = getRequestURL(event);
+	return new Request(url, {
+		method: event.req.method,
+		headers: getRequestHeaders(event),
+	});
+}
+
+/**
+ * Gets request headers from an H3 event
+ */
+export function getRequestHeaders(event: H3Event): Headers {
+	const headers = new Headers();
+	// In a real Nitro environment, headers would come from event.node.req.headers
+	// This is a placeholder implementation
+	return headers;
+}
+
+/**
+ * Sets a response header on an H3 event
+ */
+export function setResponseHeader(event: H3Event, name: string, value: string): void {
+	// In a real Nitro environment, this would use h3's setResponseHeader
+	// Store in event context for now
+	if (!event.context.responseHeaders) {
+		event.context.responseHeaders = {};
+	}
+	(event.context.responseHeaders as Record<string, string>)[name] = value;
+}
+
+/**
+ * Creates an error response
+ */
+export function createErrorResponse(error: Error | HttpError, isDev: boolean): Response {
+	const statusCode = isHttpError(error) ? error.statusCode : 500;
+
+	if (isDev) {
+		// Development: include full error details
+		const errorHtml = generateDevErrorPage(error, statusCode);
+		return new Response(errorHtml, {
+			status: statusCode,
+			headers: { 'Content-Type': 'text/html; charset=utf-8' },
+		});
+	}
+
+	// Production: generic error page
+	const errorHtml = generateProdErrorPage(statusCode);
+	return new Response(errorHtml, {
+		status: statusCode,
+		headers: { 'Content-Type': 'text/html; charset=utf-8' },
+	});
+}
+
+/**
+ * Generates a development error page with full details
+ */
+function generateDevErrorPage(error: Error, statusCode: number): string {
+	return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Error ${statusCode}</title>
+    <style>
+      body {
+        font-family: system-ui, -apple-system, sans-serif;
+        margin: 0;
+        padding: 40px;
+        background: #1a1a1a;
+        color: #fff;
+      }
+      .error-container {
+        max-width: 800px;
+        margin: 0 auto;
+        background: #2d2d2d;
+        padding: 40px;
+        border-radius: 8px;
+        border-left: 4px solid #ff6b6b;
+      }
+      h1 {
+        color: #ff6b6b;
+        margin-top: 0;
+        font-size: 24px;
+      }
+      .status-code {
+        font-size: 48px;
+        font-weight: bold;
+        color: #ff6b6b;
+        margin-bottom: 10px;
+      }
+      .message {
+        font-size: 18px;
+        color: #ccc;
+        margin-bottom: 20px;
+      }
+      pre {
+        background: #1a1a1a;
+        padding: 20px;
+        border-radius: 4px;
+        overflow-x: auto;
+        font-size: 14px;
+        line-height: 1.5;
+        color: #e0e0e0;
+      }
+      .stack-title {
+        color: #888;
+        font-size: 12px;
+        text-transform: uppercase;
+        margin-bottom: 10px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="error-container">
+      <div class="status-code">${statusCode}</div>
+      <h1>${getStatusText(statusCode)}</h1>
+      <p class="message">${escapeHtml(error.message)}</p>
+      ${
+				error.stack
+					? `
+      <div class="stack-title">Stack Trace</div>
+      <pre>${escapeHtml(error.stack)}</pre>
+      `
+					: ''
+			}
+    </div>
+  </body>
+</html>`;
+}
+
+/**
+ * Generates a production error page without sensitive details
+ */
+function generateProdErrorPage(statusCode: number): string {
+	return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Error ${statusCode}</title>
+    <style>
+      body {
+        font-family: system-ui, -apple-system, sans-serif;
+        margin: 0;
+        padding: 40px;
+        background: #f5f5f5;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        min-height: 100vh;
+        box-sizing: border-box;
+      }
+      .error-container {
+        text-align: center;
+        max-width: 400px;
+      }
+      .status-code {
+        font-size: 72px;
+        font-weight: bold;
+        color: #333;
+        margin-bottom: 10px;
+      }
+      h1 {
+        color: #666;
+        font-size: 24px;
+        margin: 0 0 20px 0;
+      }
+      p {
+        color: #888;
+        margin: 0;
+      }
+      a {
+        color: #0066cc;
+        text-decoration: none;
+      }
+      a:hover {
+        text-decoration: underline;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="error-container">
+      <div class="status-code">${statusCode}</div>
+      <h1>${getStatusText(statusCode)}</h1>
+      <p><a href="/">Return to home</a></p>
+    </div>
+  </body>
+</html>`;
+}
+
+/**
+ * Gets the status text for an HTTP status code
+ */
+function getStatusText(statusCode: number): string {
+	const statusTexts: Record<number, string> = {
+		400: 'Bad Request',
+		401: 'Unauthorized',
+		403: 'Forbidden',
+		404: 'Page Not Found',
+		405: 'Method Not Allowed',
+		500: 'Internal Server Error',
+		502: 'Bad Gateway',
+		503: 'Service Unavailable',
+	};
+	return statusTexts[statusCode] || 'Error';
+}
+
+/**
+ * Escapes HTML special characters
+ */
+function escapeHtml(str: string): string {
+	return str
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&#039;');
+}
+
+/**
+ * Island hydration marker information
+ */
+export interface IslandMarker {
+	/** Framework identifier (react, vue, svelte, etc.) */
+	framework: string;
+	/** Source path to the island module */
+	src: string;
+	/** Serialized props for the island */
+	props?: string;
+	/** Hydration strategy (load, idle, visible, media) */
+	hydrate?: string;
+}
+
+/**
+ * Extracts island markers from HTML
+ * Requirements: 9.1, 9.2, 9.3
+ *
+ * @param html - The rendered HTML string
+ * @returns Array of island markers found in the HTML
+ */
+export function extractIslandMarkers(html: string): IslandMarker[] {
+	const markers: IslandMarker[] = [];
+
+	// Match island elements with data-framework attribute
+	const islandRegex = /<[^>]*data-framework="([^"]+)"[^>]*>/g;
+	let match;
+
+	while ((match = islandRegex.exec(html)) !== null) {
+		const fullMatch = match[0];
+		const framework = match[1];
+
+		// Extract data-src
+		const srcMatch = /data-src="([^"]+)"/.exec(fullMatch);
+		const src = srcMatch ? srcMatch[1] : '';
+
+		// Extract data-props
+		const propsMatch = /data-props="([^"]*)"/.exec(fullMatch);
+		const props = propsMatch ? propsMatch[1] : undefined;
+
+		// Extract data-hydrate (hydration strategy)
+		const hydrateMatch = /data-hydrate="([^"]+)"/.exec(fullMatch);
+		const hydrate = hydrateMatch ? hydrateMatch[1] : undefined;
+
+		markers.push({
+			framework,
+			src,
+			props,
+			hydrate,
+		});
+	}
+
+	return markers;
+}
+
+/**
+ * Ensures all required hydration markers are present on an island element
+ * Requirements: 9.1, 9.2, 9.3
+ *
+ * @param element - The island element HTML string
+ * @param marker - The island marker data to ensure
+ * @returns The element with all required markers
+ */
+export function ensureHydrationMarkers(element: string, marker: Partial<IslandMarker>): string {
+	let result = element;
+
+	// Ensure data-framework is present
+	if (marker.framework && !result.includes('data-framework=')) {
+		result = result.replace(/>/, ` data-framework="${marker.framework}">`);
+	}
+
+	// Ensure data-src is present
+	if (marker.src && !result.includes('data-src=')) {
+		result = result.replace(/>/, ` data-src="${marker.src}">`);
+	}
+
+	// Ensure data-props is present (even if empty)
+	if (marker.props !== undefined && !result.includes('data-props=')) {
+		result = result.replace(/>/, ` data-props="${marker.props}">`);
+	}
+
+	return result;
+}
+
+/**
+ * Injects the client hydration script into HTML
+ * Requirements: 2.6, 9.4
+ *
+ * This function:
+ * 1. Checks if there are islands that need hydration
+ * 2. Injects the client script before </body> if not already present
+ * 3. Supports both development and production script paths
+ *
+ * @param html - The rendered HTML string
+ * @param isDev - Whether running in development mode
+ * @param options - Additional injection options
+ * @returns HTML with hydration script injected
+ */
+export function injectHydrationScript(
+	html: string,
+	isDev: boolean,
+	options: {
+		/** Custom script path override */
+		scriptPath?: string;
+		/** Additional scripts to inject */
+		additionalScripts?: string[];
+		/** Whether to force injection even without islands */
+		forceInject?: boolean;
+	} = {},
+): string {
+	// Check if there are any islands that need hydration
+	const hasIslands = html.includes('data-framework=') || html.includes('data-src=');
+
+	if (!hasIslands && !options.forceInject) {
+		// No islands found, no need to inject hydration script
+		return html;
+	}
+
+	// Check if the client script is already included
+	const existingScripts = ['/src/client/main.js', '/dist/client.js', 'client/main.js'];
+
+	if (existingScripts.some(script => html.includes(script))) {
+		return html;
+	}
+
+	// Determine the script path based on environment or override
+	const scriptPath = options.scriptPath || (isDev ? '/src/client/main.js' : '/dist/client.js');
+
+	// Build the script tags
+	const scripts: string[] = [];
+
+	// Main hydration script
+	scripts.push(`<script type="module" src="${scriptPath}"></script>`);
+
+	// Additional scripts if provided
+	if (options.additionalScripts) {
+		scripts.push(...options.additionalScripts);
+	}
+
+	const scriptBlock = scripts.join('\n');
+
+	// Inject before closing </body> tag
+	if (html.includes('</body>')) {
+		return html.replace('</body>', `${scriptBlock}\n</body>`);
+	}
+
+	// Fallback: append to the end
+	return html + scriptBlock;
+}
+
+/**
+ * Validates that hydration markers are present in the HTML
+ * Requirements: 2.3, 9.1, 9.2, 9.3
+ *
+ * @param html - The rendered HTML string
+ * @returns Object with validation results
+ */
+export function validateHydrationMarkers(html: string): {
+	hasFrameworkAttr: boolean;
+	hasSrcAttr: boolean;
+	hasPropsAttr: boolean;
+	islandCount: number;
+	islands: IslandMarker[];
+	hasClientScript: boolean;
+	isValid: boolean;
+} {
+	// Extract all island markers
+	const islands = extractIslandMarkers(html);
+
+	// Count islands with each attribute type
+	const frameworkMatches = html.match(/data-framework="[^"]+"/g) || [];
+	const srcMatches = html.match(/data-src="[^"]+"/g) || [];
+	const propsMatches = html.match(/data-props="[^"]*"/g) || [];
+
+	// Check for client script
+	const hasClientScript =
+		html.includes('/src/client/main.js') || html.includes('/dist/client.js') || html.includes('client/main.js');
+
+	// Validation: all islands should have framework and src attributes
+	const allIslandsValid = islands.every(island => island.framework && island.src);
+
+	// Overall validity: if there are islands, they should be valid and have client script
+	const isValid = islands.length === 0 || (allIslandsValid && hasClientScript);
+
+	return {
+		hasFrameworkAttr: frameworkMatches.length > 0,
+		hasSrcAttr: srcMatches.length > 0,
+		hasPropsAttr: propsMatches.length > 0,
+		islandCount: frameworkMatches.length,
+		islands,
+		hasClientScript,
+		isValid,
+	};
+}
+
+/**
+ * Processes HTML to ensure all hydration requirements are met
+ * Requirements: 2.3, 2.6, 9.1, 9.2, 9.3, 9.4
+ *
+ * This is a convenience function that:
+ * 1. Validates existing hydration markers
+ * 2. Injects the client script if needed
+ * 3. Returns the processed HTML
+ *
+ * @param html - The rendered HTML string
+ * @param isDev - Whether running in development mode
+ * @returns Processed HTML with all hydration requirements met
+ */
+export function processHydrationRequirements(
+	html: string,
+	isDev: boolean,
+): {
+	html: string;
+	validation: ReturnType<typeof validateHydrationMarkers>;
+} {
+	// First, inject the hydration script
+	const processedHtml = injectHydrationScript(html, isDev);
+
+	// Then validate the result
+	const validation = validateHydrationMarkers(processedHtml);
+
+	return {
+		html: processedHtml,
+		validation,
+	};
+}
+
+/**
+ * Renders a page to HTML string (non-streaming)
+ * Requirements: 2.1, 2.2
+ *
+ * @param pageModule - The page module to render
+ * @param context - The render context
+ * @param options - Render options
+ * @returns SSR render result
+ */
+export async function renderPage(
+	pageModule: PageModule,
+	context: NitroRenderContext,
+	options: SSRRenderOptions = {},
+): Promise<SSRRenderResult> {
+	try {
+		// Get page props if getServerSideProps is defined
+		let pageProps: Record<string, unknown> = {};
+		if (pageModule.getServerSideProps) {
+			pageProps = await pageModule.getServerSideProps(context);
+		}
+
+		// The actual rendering would integrate with Avalon's existing renderToHtml
+		// For now, we return a placeholder that shows the structure
+		const html = await renderPageComponent(pageModule, pageProps, context, options);
+
+		return {
+			html,
+			statusCode: 200,
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+			},
+		};
+	} catch (error) {
+		console.error('[SSR Error]', error);
+
+		if (options.onError && error instanceof Error) {
+			options.onError(error);
+		}
+
+		throw error;
+	}
+}
+
+/**
+ * Renders a page component to HTML
+ * This is a placeholder that would integrate with Avalon's existing SSR pipeline
+ */
+async function renderPageComponent(
+	pageModule: PageModule,
+	pageProps: Record<string, unknown>,
+	context: NitroRenderContext,
+	_options: SSRRenderOptions,
+): Promise<string> {
+	// This would integrate with the existing renderToHtml function
+	// For now, return a basic structure showing the integration point
+
+	// In the real implementation, this would:
+	// 1. Import and use renderToHtml from '../render/ssr.ts'
+	// 2. Create a RouteConfig from the pageModule
+	// 3. Apply layouts using the layout resolver
+	// 4. Return the fully rendered HTML
+
+	const componentName = (pageModule.default as { name?: string })?.name || 'Page';
+	const metadata = pageModule.metadata || {};
+
+	return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(String(metadata.title || 'Avalon App'))}</title>
+    ${metadata.description ? `<meta name="description" content="${escapeHtml(String(metadata.description))}">` : ''}
+  </head>
+  <body>
+    <div id="app" data-page="${escapeHtml(String(componentName))}" data-props='${escapeHtml(JSON.stringify(pageProps))}'>
+      <!-- Page content rendered by Avalon SSR pipeline -->
+    </div>
+  </body>
+</html>`;
+}
+
+/**
+ * Streaming render state for tracking progress
+ */
+interface StreamingRenderState {
+	shellSent: boolean;
+	contentSent: boolean;
+	closed: boolean;
+	error: Error | null;
+}
+
+/**
+ * Extended streaming options with additional callbacks
+ */
+export interface StreamingSSROptions extends SSRRenderOptions {
+	/** Callback when shell rendering fails before streaming starts */
+	onShellError?: (error: Error) => void;
+	/** Timeout for shell ready in milliseconds */
+	shellReadyTimeout?: number;
+	/** Timeout for all content ready in milliseconds */
+	allReadyTimeout?: number;
+}
+
+/**
+ * Renders a page to a streaming response
+ * Requirements: 2.4
+ *
+ * This function implements streaming SSR with proper shell/content separation:
+ * 1. Shell (DOCTYPE, html, head, body opening) is sent first
+ * 2. onShellReady callback is invoked when shell is ready
+ * 3. Page content is streamed progressively
+ * 4. onAllReady callback is invoked when all content is complete
+ *
+ * @param pageModule - The page module to render
+ * @param context - The render context
+ * @param options - Render options including streaming callbacks
+ * @returns ReadableStream of HTML chunks
+ */
+export async function renderPageStream(
+	pageModule: PageModule,
+	context: NitroRenderContext,
+	options: StreamingSSROptions = {},
+): Promise<ReadableStream<Uint8Array>> {
+	const encoder = new TextEncoder();
+	let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+
+	const state: StreamingRenderState = {
+		shellSent: false,
+		contentSent: false,
+		closed: false,
+		error: null,
+	};
+
+	// Set up timeouts if specified
+	const shellTimeout = options.shellReadyTimeout;
+	const allReadyTimeout = options.allReadyTimeout;
+	let shellTimeoutId: ReturnType<typeof setTimeout> | null = null;
+	let allReadyTimeoutId: ReturnType<typeof setTimeout> | null = null;
+
+	const clearTimeouts = () => {
+		if (shellTimeoutId) {
+			clearTimeout(shellTimeoutId);
+			shellTimeoutId = null;
+		}
+		if (allReadyTimeoutId) {
+			clearTimeout(allReadyTimeoutId);
+			allReadyTimeoutId = null;
+		}
+	};
+
+	function handleStreamError(
+		err: Error,
+		isShellError: boolean,
+		state: StreamingRenderState,
+		ctrl: ReadableStreamDefaultController<Uint8Array> | null,
+		encoder: TextEncoder,
+		clearFn: () => void,
+		opts: StreamingSSROptions,
+	) {
+		state.error = err;
+		clearFn();
+
+		console.error('[Streaming Error]', {
+			message: err.message,
+			stack: err.stack,
+			shellSent: state.shellSent,
+			isShellError,
+			timestamp: new Date().toISOString(),
+		});
+
+		// Call appropriate error callback
+		if (isShellError && opts.onShellError) {
+			opts.onShellError(err);
+		}
+		if (opts.onError) {
+			opts.onError(err);
+		}
+
+		if (!state.closed && ctrl) {
+			if (state.shellSent) {
+				// Inject error boundary into the stream
+				const errorBoundary = generateStreamingErrorBoundary(err);
+				ctrl.enqueue(encoder.encode(errorBoundary));
+
+				// Close the HTML document gracefully
+				const footer = generateStreamingFooter();
+				ctrl.enqueue(encoder.encode(footer));
+			} else {
+				// Send complete error page if shell hasn't been sent
+				const errorHtml = generateDevErrorPage(err, 500);
+				ctrl.enqueue(encoder.encode(errorHtml));
+			}
+
+			state.closed = true;
+			ctrl.close();
+		}
+	}
+
+	async function executeStreamingRender(ctrl: ReadableStreamDefaultController<Uint8Array>) {
+		controller = ctrl;
+
+		// Get page props if getServerSideProps is defined
+		let pageProps: Record<string, unknown> = {};
+		if (pageModule.getServerSideProps) {
+			pageProps = await pageModule.getServerSideProps(context);
+		}
+
+		const metadata = pageModule.metadata || {};
+
+		// Generate the shell (DOCTYPE, html, head, body opening)
+		const shell = generateStreamingShell(metadata, context);
+
+		// Send the shell
+		if (!state.closed) {
+			ctrl.enqueue(encoder.encode(shell));
+			state.shellSent = true;
+
+			// Clear shell timeout
+			if (shellTimeoutId) {
+				clearTimeout(shellTimeoutId);
+				shellTimeoutId = null;
+			}
+
+			// Notify that shell is ready
+			if (options.onShellReady) {
+				options.onShellReady();
+			}
+		}
+
+		// Set up all ready timeout
+		if (allReadyTimeout && allReadyTimeout > 0) {
+			allReadyTimeoutId = setTimeout(() => {
+				if (!state.contentSent && !state.closed) {
+					const timeoutError = new Error(`All ready timeout after ${allReadyTimeout}ms`);
+					handleStreamError(timeoutError, false, state, controller, encoder, clearTimeouts, options);
+				}
+			}, allReadyTimeout);
+		}
+
+		// Send the page content
+		if (!state.closed) {
+			const content = generateStreamingContent(pageModule, pageProps);
+			ctrl.enqueue(encoder.encode(content));
+			state.contentSent = true;
+		}
+
+		// Send the footer (closing body and html tags)
+		if (!state.closed) {
+			const footer = generateStreamingFooter();
+			ctrl.enqueue(encoder.encode(footer));
+		}
+
+		// Clear all ready timeout
+		clearTimeouts();
+
+		// Notify that all content is ready
+		if (options.onAllReady && !state.closed) {
+			options.onAllReady();
+		}
+
+		if (!state.closed) {
+			state.closed = true;
+			ctrl.close();
+		}
+	}
+
+	const stream = new ReadableStream<Uint8Array>({
+		async start(ctrl) {
+			controller = ctrl;
+
+			// Set up shell timeout
+			if (shellTimeout && shellTimeout > 0) {
+				shellTimeoutId = setTimeout(() => {
+					if (!state.shellSent && !state.closed) {
+						const timeoutError = new Error(`Shell ready timeout after ${shellTimeout}ms`);
+						handleStreamError(timeoutError, true, state, controller, encoder, clearTimeouts, options);
+					}
+				}, shellTimeout);
+			}
+
+			try {
+				await executeStreamingRender(ctrl);
+			} catch (error) {
+				handleStreamError(
+					error instanceof Error ? error : new Error(String(error)),
+					!state.shellSent,
+					state,
+					controller,
+					encoder,
+					clearTimeouts,
+					options,
+				);
+			}
+		},
+
+		cancel() {
+			clearTimeouts();
+			if (!state.closed && controller) {
+				state.closed = true;
+				try {
+					controller.close();
+				} catch {
+					// Already closed
+				}
+			}
+		},
+	});
+
+	return stream;
+}
+
+/**
+ * Generates the streaming shell (DOCTYPE, html, head, body opening)
+ */
+function generateStreamingShell(
+	metadata: { title?: string; description?: string },
+	_context: NitroRenderContext,
+): string {
+	return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeHtml(String(metadata.title || 'Avalon App'))}</title>
+    ${metadata.description ? `<meta name="description" content="${escapeHtml(String(metadata.description))}">` : ''}
+  </head>
+  <body>
+`;
+}
+
+/**
+ * Generates the streaming content
+ */
+function generateStreamingContent(pageModule: PageModule, pageProps: Record<string, unknown>): string {
+	const componentName = (pageModule.default as { name?: string })?.name || 'Page';
+	return `    <div id="app" data-page="${escapeHtml(String(componentName))}" data-props='${escapeHtml(JSON.stringify(pageProps))}'>
+      <!-- Page content rendered by Avalon SSR pipeline -->
+    </div>
+`;
+}
+
+/**
+ * Generates the streaming footer (closing body and html tags)
+ */
+function generateStreamingFooter(): string {
+	return `  </body>
+</html>`;
+}
+
+/**
+ * Generates an error boundary for mid-stream errors
+ */
+function generateStreamingErrorBoundary(error: Error): string {
+	const isDev = process.env.NODE_ENV !== 'production';
+
+	const stackHtml = error.stack
+		? `<pre style="
+            background: #f5f5f5;
+            padding: 10px;
+            border-radius: 4px;
+            overflow-x: auto;
+            font-size: 12px;
+            margin-top: 10px;
+          ">${escapeHtml(error.stack)}</pre>`
+		: '';
+
+	return `
+    <div class="streaming-error-boundary" data-error-boundary="true" style="
+      background: #fff3cd;
+      border: 2px solid #ffc107;
+      border-radius: 8px;
+      padding: 20px;
+      margin: 20px 0;
+      font-family: system-ui, -apple-system, sans-serif;
+    ">
+      <div style="display: flex; align-items: center; gap: 10px; margin-bottom: 10px;">
+        <span style="font-size: 24px;">⚠️</span>
+        <h3 style="margin: 0; color: #856404;">Streaming Error</h3>
+      </div>
+      <p style="margin: 10px 0; color: #856404;">
+        An error occurred while streaming this page.
+      </p>
+      ${
+				isDev
+					? `
+      <details style="margin-top: 15px;">
+        <summary style="cursor: pointer; color: #856404; font-weight: bold;">
+          Error Details (Development Mode)
+        </summary>
+        <div style="margin-top: 10px;">
+          <p><strong>Error:</strong> ${escapeHtml(error.message)}</p>
+          ${stackHtml}
+        </div>
+      </details>
+      `
+					: ''
+			}
+    </div>
+`;
+}
+
+/**
+ * Creates a streaming response with proper headers
+ * Requirements: 2.4
+ *
+ * @param stream - The ReadableStream to wrap
+ * @param options - Additional response options
+ * @returns Response object with streaming body
+ */
+export function createStreamingResponse(
+	stream: ReadableStream<Uint8Array>,
+	options: {
+		status?: number;
+		headers?: Record<string, string>;
+	} = {},
+): Response {
+	const headers = new Headers({
+		'Content-Type': 'text/html; charset=utf-8',
+		'Transfer-Encoding': 'chunked',
+		...options.headers,
+	});
+
+	return new Response(stream, {
+		status: options.status || 200,
+		headers,
+	});
+}
+
+/**
+ * Creates a scoped middleware getter that discovers and caches middleware routes.
+ * Shared between createNitroRenderer and createNitroCatchAllRenderer.
+ */
+function createScopedMiddlewareGetter(
+	routesRef: { value: MiddlewareRoute[] | null },
+	srcDir: string,
+	isDev: boolean,
+): () => Promise<MiddlewareRoute[]> {
+	return async () => {
+		routesRef.value ??= await discoverScopedMiddleware({
+			baseDir: srcDir,
+			devMode: isDev,
+		});
+		return routesRef.value;
+	};
+}
+
+/**
+ * Creates an error handler with custom error page support.
+ * Shared between createNitroRenderer and createNitroCatchAllRenderer.
+ */
+function createErrorHandler(
+	enableCustomErrorPages: boolean,
+	errorHandlerOptions: ErrorHandlerOptions,
+	isDev: boolean,
+): (error: Error | HttpError, event: H3Event) => Promise<Response> {
+	return async (error, event) => {
+		if (enableCustomErrorPages) {
+			return handleRenderErrorWithCustomPages(error, event, errorHandlerOptions);
+		}
+		return createErrorResponse(error, isDev);
+	};
+}
+
+/**
+ * Creates the main Nitro renderer handler
+ *
+ * This is the catch-all handler for Nitro that renders pages not matched
+ * by API routes or static files. It integrates with Nitro's routing system:
+ *
+ * 1. Nitro's file-system routing handles API routes (api/ directory)
+ * 2. Nitro's static asset handling serves files from public/
+ * 3. This renderer catches all remaining requests for SSR page rendering
+ *
+ * Middleware execution order:
+ * 1. Global middleware (from middleware/ directory) - handled by Nitro
+ * 2. Route-scoped middleware (from _middleware.ts files) - handled here
+ * 3. Page rendering
+ *
+ * If global middleware terminates the chain, this handler is not called.
+ * If route-scoped middleware terminates, page rendering is skipped.
+ *
+ * The renderer relies on Nitro's event context for route information when
+ * available, falling back to pathname-based resolution for development.
+ *
+ * Requirements: 2.1, 2.2, 2.4, 5.1, 5.3, 10.5
+ *
+ * @param options - Render handler options
+ * @returns Handler function for Nitro
+ */
+export function createNitroRenderer(options: RenderHandlerOptions) {
+	const { avalonConfig, isDev = false, enableCustomErrorPages = true } = options;
+
+	// Middleware routes cache - discovered once at startup
+	let scopedMiddlewareRoutes: MiddlewareRoute[] | null = null;
+
+	// Error handler options for custom error pages
+	const errorHandlerOptions: ErrorHandlerOptions = {
+		isDev,
+		avalonConfig,
+		loadPageModule: options.loadPageModule,
+		pagesDir: avalonConfig.pagesDir,
+	};
+
+	// Pre-discover error pages if custom error pages are enabled
+	if (enableCustomErrorPages) {
+		discoverErrorPages(errorHandlerOptions).catch(err => {
+			console.warn('[renderer] Failed to discover error pages:', err);
+		});
+	}
+
+	/**
+	 * Gets scoped middleware routes, discovering them on first call
+	 * Routes are cached for performance in production
+	 */
+	const middlewareRef = { value: scopedMiddlewareRoutes };
+	const getScopedMiddleware = createScopedMiddlewareGetter(middlewareRef, avalonConfig.srcDir || 'src', isDev);
+
+	/**
+	 * Handles errors with custom error page support
+	 */
+	const handleError = createErrorHandler(enableCustomErrorPages, errorHandlerOptions, isDev);
+
+	return async function nitroRendererHandler(event: H3Event): Promise<Response> {
+		const url = getRequestURL(event);
+		const pathname = url.pathname;
+
+		try {
+			// Execute route-scoped middleware before page rendering
+			// Global middleware has already run (handled by Nitro's middleware/ directory)
+			// Requirements: 5.1, 5.3
+			const middlewareRoutes = await getScopedMiddleware();
+			const middlewareResponse = await executeScopedMiddleware(event, middlewareRoutes, {
+				devMode: isDev,
+			});
+
+			// If middleware returned a response, use it and skip page rendering
+			if (middlewareResponse) {
+				if (isDev) {
+					console.log(`[renderer] Middleware terminated request for ${pathname}`);
+				}
+				return middlewareResponse;
+			}
+
+			// Check if Nitro has already resolved route information in the event context
+			// This happens when Nitro's file-system routing has matched a route
+			const nitroRouteContext = event.context.route as ResolvedPageRoute | undefined;
+
+			let route: ResolvedPageRoute | null = null;
+
+			if (nitroRouteContext) {
+				// Use Nitro's resolved route information
+				route = nitroRouteContext;
+			} else {
+				// Fall back to custom resolution (primarily for development)
+				// In production with Nitro, this path is rarely taken as Nitro
+				// handles route resolution before reaching the catch-all renderer
+				route = options.resolvePageRoute
+					? await options.resolvePageRoute(pathname, avalonConfig.pagesDir)
+					: await defaultResolvePageRoute(pathname, avalonConfig.pagesDir);
+			}
+
+			if (!route) {
+				// No page found, return 404 with custom error page support
+				const error = createNotFoundError(`Page not found: ${pathname}`);
+				return handleError(error, event);
+			}
+
+			// Load the page module
+			const pageModule = options.loadPageModule
+				? await options.loadPageModule(route.filePath)
+				: await defaultLoadPageModule(route.filePath);
+
+			// Create render context with route params from Nitro or custom resolution
+			// Nitro provides params via event.context.params when using its routing
+			const routeParams = (event.context.params as Record<string, string>) || route.params;
+			const renderContext = createRenderContext(event, routeParams);
+
+			// Resolve layouts if available
+			if (options.resolveLayouts) {
+				const layouts = await options.resolveLayouts(pathname, avalonConfig);
+				renderContext.layoutContext = { layouts };
+			}
+
+			// Render the page
+			if (avalonConfig.streaming) {
+				// Streaming SSR
+				const stream = await renderPageStream(pageModule, renderContext, {
+					onShellReady: () => {
+						setResponseHeader(event, 'Content-Type', 'text/html; charset=utf-8');
+					},
+				});
+
+				return new Response(stream, {
+					headers: { 'Content-Type': 'text/html; charset=utf-8' },
+				});
+			} else {
+				// Non-streaming SSR
+				const result = await renderPage(pageModule, renderContext);
+
+				// Inject hydration script
+				const html = injectHydrationScript(result.html as string, isDev);
+
+				return new Response(html, {
+					status: result.statusCode,
+					headers: result.headers,
+				});
+			}
+		} catch (error) {
+			console.error('[Nitro Renderer Error]', error);
+
+			const err = error instanceof Error ? error : new Error(String(error));
+			return handleError(err, event);
+		}
+	};
+}
+
+/**
+ * Default page route resolver
+ *
+ * This is a fallback resolver used primarily in development when Nitro's
+ * file-system routing hasn't resolved the route. In production with Nitro,
+ * route resolution is handled by Nitro's native routing system.
+ *
+ * The resolver converts URL pathnames to potential file paths in the pages
+ * directory. It's intentionally simple as the heavy lifting of route matching
+ * is delegated to Nitro's routing system.
+ *
+ * @param pathname - URL pathname to resolve
+ * @param _pagesDir - Pages directory (unused, kept for interface compatibility)
+ * @returns Resolved page route or null if not found
+ */
+async function defaultResolvePageRoute(pathname: string, _pagesDir: string): Promise<ResolvedPageRoute | null> {
+	// Handle root path
+	if (pathname === '/' || pathname === '') {
+		return {
+			filePath: 'src/pages/index.tsx',
+			pattern: '/',
+			params: {},
+		};
+	}
+
+	// Convert pathname to potential file path
+	// This is a simple conversion - Nitro's routing handles complex patterns
+	const cleanPath = pathname.replace(/^\//, '').replace(/\/$/, '');
+	const filePath = `src/pages/${cleanPath}.tsx`;
+
+	return {
+		filePath,
+		pattern: pathname,
+		params: {},
+	};
+}
+
+/**
+ * Default page module loader
+ *
+ * This is a placeholder implementation that returns a minimal page module.
+ * In actual usage:
+ * - Development: Vite's ssrLoadModule is used via the loadPageModule option
+ * - Production: Modules are imported from the build output
+ *
+ * The actual module loading is handled by the integration layer (nitro-integration.ts)
+ * which provides the appropriate loader based on the environment.
+ *
+ * @param _filePath - File path to load (unused in placeholder)
+ * @returns Minimal page module
+ */
+async function defaultLoadPageModule(_filePath: string): Promise<PageModule> {
+	// This is a placeholder - actual loading is done by:
+	// - Vite's ssrLoadModule in development
+	// - Direct imports from build output in production
+
+	return {
+		default: () => null,
+		metadata: {
+			title: 'Avalon Page',
+		},
+	};
+}
+
+/**
+ * Options for the Nitro catch-all renderer
+ */
+export interface NitroCatchAllOptions {
+	/** Avalon runtime configuration */
+	avalonConfig: AvalonRuntimeConfig;
+	/** Whether running in development mode */
+	isDev?: boolean;
+	/**
+	 * Page module loader function
+	 * In development, this should use Vite's ssrLoadModule
+	 * In production, this imports from the build output
+	 */
+	loadPageModule: (filePath: string) => Promise<PageModule>;
+	/** Optional layout resolver */
+	resolveLayouts?: (routePath: string, config: AvalonRuntimeConfig) => Promise<string[]>;
+	/**
+	 * Enable custom error pages (404.tsx, 500.tsx, _error.tsx)
+	 * When enabled, the renderer will look for custom error pages in the pages directory
+	 * Requirements: 10.5
+	 */
+	enableCustomErrorPages?: boolean;
+}
+
+/**
+ * Creates a Nitro catch-all renderer handler
+ *
+ * This is the recommended way to create a renderer for Nitro's catch-all pattern.
+ * It's designed to work with Nitro's file-system routing where:
+ *
+ * 1. API routes are handled by files in the api/ directory
+ * 2. Static assets are served from public/
+ * 3. This catch-all handles all remaining requests for SSR
+ *
+ * Middleware execution order:
+ * 1. Global middleware (from middleware/ directory) - handled by Nitro
+ * 2. Route-scoped middleware (from _middleware.ts files) - handled here
+ * 3. Page rendering
+ *
+ * The handler expects Nitro to provide route information via event.context:
+ * - event.context.params: Route parameters from dynamic segments
+ * - event.context.route: Optional resolved route information
+ *
+ * Usage in Nitro routes/[...slug].ts:
+ * ```ts
+ * import { createNitroCatchAllRenderer } from '@useavalon/nitro/renderer';
+ *
+ * export default createNitroCatchAllRenderer({
+ *   avalonConfig: useRuntimeConfig().avalon,
+ *   isDev: import.meta.dev,
+ *   loadPageModule: async (filePath) => {
+ *     return await import(filePath);
+ *   }
+ * });
+ * ```
+ *
+ * Requirements: 2.1, 2.2, 2.6, 5.1, 5.3, 10.5
+ *
+ * @param options - Catch-all renderer options
+ * @returns Nitro event handler function
+ */
+export function createNitroCatchAllRenderer(options: NitroCatchAllOptions) {
+	const { avalonConfig, isDev = false, loadPageModule, resolveLayouts, enableCustomErrorPages = true } = options;
+
+	// Middleware routes cache - discovered once at startup
+	let scopedMiddlewareRoutes: MiddlewareRoute[] | null = null;
+
+	// Error handler options for custom error pages
+	const errorHandlerOptions: ErrorHandlerOptions = {
+		isDev,
+		avalonConfig,
+		loadPageModule,
+		pagesDir: avalonConfig.pagesDir,
+	};
+
+	// Pre-discover error pages if custom error pages are enabled
+	if (enableCustomErrorPages) {
+		discoverErrorPages(errorHandlerOptions).catch(err => {
+			console.warn('[renderer] Failed to discover error pages:', err);
+		});
+	}
+
+	/**
+	 * Gets scoped middleware routes, discovering them on first call
+	 * Routes are cached for performance in production
+	 */
+	const middlewareRef = { value: scopedMiddlewareRoutes };
+	const getScopedMiddleware = createScopedMiddlewareGetter(middlewareRef, avalonConfig.srcDir || 'src', isDev);
+
+	/**
+	 * Handles errors with custom error page support
+	 */
+	const handleError = createErrorHandler(enableCustomErrorPages, errorHandlerOptions, isDev);
+
+	return async function nitroCatchAllHandler(event: H3Event): Promise<Response> {
+		const url = getRequestURL(event);
+		const pathname = url.pathname;
+
+		try {
+			// Execute route-scoped middleware before page rendering
+			// Global middleware has already run (handled by Nitro's middleware/ directory)
+			// Requirements: 5.1, 5.3
+			const middlewareRoutes = await getScopedMiddleware();
+			const middlewareResponse = await executeScopedMiddleware(event, middlewareRoutes, {
+				devMode: isDev,
+			});
+
+			// If middleware returned a response, use it and skip page rendering
+			if (middlewareResponse) {
+				if (isDev) {
+					console.log(`[renderer] Middleware terminated request for ${pathname}`);
+				}
+				return middlewareResponse;
+			}
+
+			// Get route params from Nitro's routing (e.g., from [...slug].ts)
+			const params = (event.context.params as Record<string, string>) || {};
+
+			// Reconstruct the page file path from the pathname
+			// Nitro's catch-all provides the slug, we map it to the pages directory
+			const slug = params.slug || pathname.replace(/^\//, '') || 'index';
+			const filePath = `${avalonConfig.pagesDir}/${slug}.tsx`;
+
+			// Try to load the page module
+			let pageModule: PageModule;
+			try {
+				pageModule = await loadPageModule(filePath);
+			} catch (loadError) {
+				// Direct path failed — try index file in directory
+				try {
+					const indexPath = `${avalonConfig.pagesDir}/${slug}/index.tsx`;
+					pageModule = await loadPageModule(indexPath);
+				} catch (indexLoadError) {
+					// Neither direct path nor index path found
+					if (isDev) {
+						console.debug(`[renderer] Page not found: ${filePath}`, loadError);
+						console.debug(
+							`[renderer] Index fallback not found: ${avalonConfig.pagesDir}/${slug}/index.tsx`,
+							indexLoadError,
+						);
+					}
+					const error = createNotFoundError(`Page not found: ${pathname}`);
+					return handleError(error, event);
+				}
+			}
+
+			// Create render context
+			const renderContext = createRenderContext(event, params);
+
+			// Resolve layouts if available
+			if (resolveLayouts) {
+				const layouts = await resolveLayouts(pathname, avalonConfig);
+				renderContext.layoutContext = { layouts };
+			}
+
+			// Render the page
+			if (avalonConfig.streaming) {
+				// Streaming SSR
+				const stream = await renderPageStream(pageModule, renderContext, {
+					onShellReady: () => {
+						setResponseHeader(event, 'Content-Type', 'text/html; charset=utf-8');
+					},
+				});
+
+				return new Response(stream, {
+					headers: { 'Content-Type': 'text/html; charset=utf-8' },
+				});
+			} else {
+				// Non-streaming SSR
+				const result = await renderPage(pageModule, renderContext);
+
+				// Inject hydration script - ensures client-side hydration works
+				const html = injectHydrationScript(result.html as string, isDev);
+
+				return new Response(html, {
+					status: result.statusCode,
+					headers: result.headers,
+				});
+			}
+		} catch (error) {
+			console.error('[Nitro Catch-All Renderer Error]', error);
+
+			const err = error instanceof Error ? error : new Error(String(error));
+			return handleError(err, event);
+		}
+	};
+}
+
+/**
+ * Re-export middleware cache clearing for hot reload support
+ *
+ * Call this function when middleware files change during development
+ * to ensure the latest version is loaded on the next request.
+ *
+ * @example
+ * ```ts
+ * // In your HMR handler
+ * if (file.endsWith('_middleware.ts')) {
+ *   clearRendererMiddlewareCache();
+ * }
+ * ```
+ */
+export { clearMiddlewareCache as clearRendererMiddlewareCache } from '../middleware/index.ts';