@useavalon/avalon 0.1.11 → 0.1.13

package/src/nitro/error-handler.ts

@@ -1,636 +1,636 @@
-/**
- * Nitro Error Handler for Avalon
- *
- * This module provides error handling utilities for the Nitro integration,
- * including support for custom error pages (404, 500, _error).
- *
- * Custom error pages are discovered from the pages directory:
- * - src/pages/404.tsx → Custom 404 page
- * - src/pages/500.tsx → Custom 500 page
- * - src/pages/_error.tsx → Generic error page (fallback)
- *
- * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
- */
-
-import type { PageModule, NitroRenderContext, AvalonRuntimeConfig } from "./types.ts";
-import type { H3Event } from "h3";
-import { HttpError, isHttpError, createNotFoundError, createInternalError } from "./types.ts";
-import { createRenderContext, getRequestURL } from "./renderer.ts";
-
-/**
- * Error page props passed to custom error page components
- */
-export interface ErrorPageProps {
-  /** HTTP status code */
-  statusCode: number;
-  /** Error message */
-  message: string;
-  /** Error object (development only) */
-  error?: Error;
-  /** Stack trace (development only) */
-  stack?: string;
-  /** Request URL that caused the error */
-  url?: string;
-}
-
-/**
- * Options for error handling
- */
-export interface ErrorHandlerOptions {
-  /** Whether running in development mode */
-  isDev?: boolean;
-  /** Avalon runtime configuration */
-  avalonConfig?: AvalonRuntimeConfig;
-  /** Custom page module loader */
-  loadPageModule?: (filePath: string) => Promise<PageModule>;
-  /** Pages directory path */
-  pagesDir?: string;
-}
-
-/**
- * Cache for discovered error pages
- */
-interface ErrorPageCache {
-  /** Custom 404 page module */
-  notFound?: PageModule | null;
-  /** Custom 500 page module */
-  serverError?: PageModule | null;
-  /** Generic error page module */
-  genericError?: PageModule | null;
-  /** Whether cache has been initialized */
-  initialized: boolean;
-}
-
-// Module-level cache for error pages
-let errorPageCache: ErrorPageCache = {
-  initialized: false,
-};
-
-/**
- * Clears the error page cache
- * Call this during development when error pages change
- */
-export function clearErrorPageCache(): void {
-  errorPageCache = {
-    initialized: false,
-  };
-}
-
-/**
- * Discovers and caches custom error pages from the pages directory
- *
- * @param options - Error handler options
- * @returns Object containing discovered error page modules
- */
-export async function discoverErrorPages(
-  options: ErrorHandlerOptions
-): Promise<ErrorPageCache> {
-  if (errorPageCache.initialized && !options.isDev) {
-    return errorPageCache;
-  }
-
-  const { loadPageModule, pagesDir = "src/pages" } = options;
-
-  if (!loadPageModule) {
-    errorPageCache.initialized = true;
-    return errorPageCache;
-  }
-
-  // Try to load custom 404 page
-  try {
-    errorPageCache.notFound = await loadPageModule(`${pagesDir}/404.tsx`);
-  } catch {
-    // Try .jsx extension
-    try {
-      errorPageCache.notFound = await loadPageModule(`${pagesDir}/404.jsx`);
-    } catch {
-      errorPageCache.notFound = null;
-    }
-  }
-
-  // Try to load custom 500 page
-  try {
-    errorPageCache.serverError = await loadPageModule(`${pagesDir}/500.tsx`);
-  } catch {
-    // Try .jsx extension
-    try {
-      errorPageCache.serverError = await loadPageModule(`${pagesDir}/500.jsx`);
-    } catch {
-      errorPageCache.serverError = null;
-    }
-  }
-
-  // Try to load generic error page
-  try {
-    errorPageCache.genericError = await loadPageModule(`${pagesDir}/_error.tsx`);
-  } catch {
-    // Try .jsx extension
-    try {
-      errorPageCache.genericError = await loadPageModule(`${pagesDir}/_error.jsx`);
-    } catch {
-      errorPageCache.genericError = null;
-    }
-  }
-
-  errorPageCache.initialized = true;
-  return errorPageCache;
-}
-
-/**
- * Gets the appropriate error page module for a status code
- *
- * @param statusCode - HTTP status code
- * @param cache - Error page cache
- * @returns Error page module or null if no custom page exists
- */
-export function getErrorPageModule(
-  statusCode: number,
-  cache: ErrorPageCache
-): PageModule | null {
-  // Check for specific status code pages first
-  if (statusCode === 404 && cache.notFound) {
-    return cache.notFound;
-  }
-
-  if (statusCode === 500 && cache.serverError) {
-    return cache.serverError;
-  }
-
-  // Fall back to generic error page
-  if (cache.genericError) {
-    return cache.genericError;
-  }
-
-  return null;
-}
-
-/**
- * Creates error page props from an error
- *
- * @param error - The error that occurred
- * @param url - Request URL
- * @param isDev - Whether running in development mode
- * @returns Error page props
- */
-export function createErrorPageProps(
-  error: Error | HttpError,
-  url?: string,
-  isDev?: boolean
-): ErrorPageProps {
-  const statusCode = isHttpError(error) ? error.statusCode : 500;
-
-  const props: ErrorPageProps = {
-    statusCode,
-    message: error.message,
-    url,
-  };
-
-  // Include error details only in development
-  if (isDev) {
-    props.error = error;
-    props.stack = error.stack;
-  }
-
-  return props;
-}
-
-/**
- * Renders a custom error page to HTML
- *
- * @param pageModule - The error page module
- * @param props - Error page props
- * @param context - Render context
- * @param isDev - Whether running in development mode
- * @returns Rendered HTML string
- */
-export async function renderErrorPage(
-  pageModule: PageModule,
-  props: ErrorPageProps,
-  context: NitroRenderContext,
-  isDev: boolean
-): Promise<string> {
-  // The page module's default export should be a component function
-  const Component = pageModule.default as (props: ErrorPageProps) => unknown;
-
-  if (typeof Component !== "function") {
-    // Fall back to default error page if component is invalid
-    return generateDefaultErrorPage(props.statusCode, props.message, isDev, props.stack);
-  }
-
-  try {
-    // Render the component
-    // In a real implementation, this would use the SSR pipeline
-    // For now, we generate a basic HTML structure
-    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 || `Error ${props.statusCode}`))}</title>
-    ${metadata.description ? `<meta name="description" content="${escapeHtml(String(metadata.description))}">` : ""}
-    <style>
-      body {
-        font-family: system-ui, -apple-system, sans-serif;
-        margin: 0;
-        padding: 40px;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        min-height: 100vh;
-        box-sizing: border-box;
-        background: #f5f5f5;
-      }
-      .error-page {
-        text-align: center;
-        max-width: 600px;
-      }
-      h1 {
-        font-size: 48px;
-        margin: 0 0 20px 0;
-        color: #333;
-      }
-      p {
-        color: #666;
-        margin: 0 0 20px 0;
-      }
-      a {
-        color: #0066cc;
-        text-decoration: none;
-      }
-      a:hover {
-        text-decoration: underline;
-      }
-      details {
-        margin-top: 20px;
-        text-align: left;
-      }
-      pre {
-        background: #1a1a1a;
-        color: #e0e0e0;
-        padding: 15px;
-        border-radius: 4px;
-        overflow-x: auto;
-        font-size: 12px;
-      }
-    </style>
-  </head>
-  <body>
-    <div id="app" data-error-page="true" data-status-code="${props.statusCode}" data-props='${escapeHtml(JSON.stringify(props))}'>
-      <!-- Custom error page content rendered by Avalon SSR pipeline -->
-      <div class="error-page">
-        <h1>${props.statusCode}</h1>
-        <p>${escapeHtml(props.message)}</p>
-        ${isDev && props.stack ? `
-        <details>
-          <summary>Error details</summary>
-          <pre>${escapeHtml(props.stack)}</pre>
-        </details>
-        ` : ""}
-        <a href="/">Go back home</a>
-      </div>
-    </div>
-  </body>
-</html>`;
-  } catch (renderError) {
-    console.error("[Error Page Render Error]", renderError);
-    // Fall back to default error page
-    return generateDefaultErrorPage(props.statusCode, props.message, isDev, props.stack);
-  }
-}
-
-/**
- * Generates a default error page when no custom page is available
- *
- * @param statusCode - HTTP status code
- * @param message - Error message
- * @param isDev - Whether running in development mode
- * @param stack - Stack trace (development only)
- * @returns HTML string
- */
-export function generateDefaultErrorPage(
-  statusCode: number,
-  message: string,
-  isDev: boolean,
-  stack?: string
-): string {
-  if (isDev) {
-    return generateDevErrorPage(statusCode, message, stack);
-  }
-  return generateProdErrorPage(statusCode, message);
-}
-
-/**
- * Generates a development error page with full details
- */
-function generateDevErrorPage(
-  statusCode: number,
-  message: string,
-  stack?: string
-): 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;
-      }
-      a {
-        color: #6b9fff;
-        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 class="message">${escapeHtml(message)}</p>
-      ${stack ? `
-      <div class="stack-title">Stack Trace</div>
-      <pre>${escapeHtml(stack)}</pre>
-      ` : ""}
-      <p><a href="/">← Return to home</a></p>
-    </div>
-  </body>
-</html>`;
-}
-
-/**
- * Generates a production error page without sensitive details
- */
-function generateProdErrorPage(statusCode: number, message: string): string {
-  // Use generic message for 500 errors in production
-  const displayMessage = statusCode >= 500 
-    ? "An unexpected error occurred. Please try again later."
-    : message;
-
-  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 0 20px 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>${escapeHtml(displayMessage)}</p>
-      <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",
-    408: "Request Timeout",
-    410: "Gone",
-    429: "Too Many Requests",
-    500: "Internal Server Error",
-    502: "Bad Gateway",
-    503: "Service Unavailable",
-    504: "Gateway Timeout",
-  };
-  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;");
-}
-
-/**
- * Handles a render error and returns an appropriate response
- *
- * This function:
- * 1. Discovers custom error pages if available
- * 2. Renders the appropriate error page (custom or default)
- * 3. Returns a Response with the correct status code
- *
- * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
- *
- * @param error - The error that occurred
- * @param event - H3 event
- * @param options - Error handler options
- * @returns Response with error page
- */
-export async function handleRenderError(
-  error: Error | HttpError,
-  event: H3Event,
-  options: ErrorHandlerOptions
-): Promise<Response> {
-  const { isDev = false } = options;
-  const statusCode = isHttpError(error) ? error.statusCode : 500;
-  const url = getRequestURL(event);
-
-  console.error(`[Render Error] ${statusCode} - ${error.message}`, {
-    url: url.pathname,
-    stack: isDev ? error.stack : undefined,
-  });
-
-  // Try to discover and use custom error pages
-  const errorPages = await discoverErrorPages(options);
-  const errorPageModule = getErrorPageModule(statusCode, errorPages);
-
-  let html: string;
-
-  if (errorPageModule) {
-    // Render custom error page
-    const props = createErrorPageProps(error, url.pathname, isDev);
-    const context = createRenderContext(event, {});
-    html = await renderErrorPage(errorPageModule, props, context, isDev);
-  } else {
-    // Use default error page
-    html = generateDefaultErrorPage(
-      statusCode,
-      error.message,
-      isDev,
-      isDev ? error.stack : undefined
-    );
-  }
-
-  return new Response(html, {
-    status: statusCode,
-    headers: { "Content-Type": "text/html; charset=utf-8" },
-  });
-}
-
-/**
- * Handles an API error and returns an appropriate JSON response
- *
- * Requirements: 10.1, 10.2, 10.4
- *
- * @param error - The error that occurred
- * @param options - Error handler options
- * @returns Response with JSON error
- */
-export function handleApiError(
-  error: Error | HttpError,
-  options: ErrorHandlerOptions
-): Response {
-  const { isDev = false } = options;
-  const statusCode = isHttpError(error) ? error.statusCode : 500;
-
-  console.error(`[API Error] ${statusCode} - ${error.message}`, {
-    stack: isDev ? error.stack : undefined,
-  });
-
-  const body = isDev
-    ? {
-        error: error.message,
-        statusCode,
-        stack: error.stack,
-      }
-    : {
-        error: statusCode >= 500 ? "Internal Server Error" : error.message,
-        statusCode,
-      };
-
-  return new Response(JSON.stringify(body), {
-    status: statusCode,
-    headers: { "Content-Type": "application/json" },
-  });
-}
-
-/**
- * Creates a 404 Not Found response
- *
- * @param pathname - The requested path
- * @param event - H3 event
- * @param options - Error handler options
- * @returns Response with 404 error page
- */
-export async function handleNotFound(
-  pathname: string,
-  event: H3Event,
-  options: ErrorHandlerOptions
-): Promise<Response> {
-  const error = createNotFoundError(`Page not found: ${pathname}`);
-  return handleRenderError(error, event, options);
-}
-
-/**
- * Creates a 500 Internal Server Error response
- *
- * @param error - The original error
- * @param event - H3 event
- * @param options - Error handler options
- * @returns Response with 500 error page
- */
-export async function handleInternalError(
-  error: Error,
-  event: H3Event,
-  options: ErrorHandlerOptions
-): Promise<Response> {
-  const httpError = createInternalError(error.message);
-  // Preserve the original stack trace
-  httpError.stack = error.stack;
-  return handleRenderError(httpError, event, options);
-}
-
+/**
+ * Nitro Error Handler for Avalon
+ *
+ * This module provides error handling utilities for the Nitro integration,
+ * including support for custom error pages (404, 500, _error).
+ *
+ * Custom error pages are discovered from the pages directory:
+ * - src/pages/404.tsx → Custom 404 page
+ * - src/pages/500.tsx → Custom 500 page
+ * - src/pages/_error.tsx → Generic error page (fallback)
+ *
+ * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+
+import type { PageModule, NitroRenderContext, AvalonRuntimeConfig } from "./types.ts";
+import type { H3Event } from "h3";
+import { HttpError, isHttpError, createNotFoundError, createInternalError } from "./types.ts";
+import { createRenderContext, getRequestURL } from "./renderer.ts";
+
+/**
+ * Error page props passed to custom error page components
+ */
+export interface ErrorPageProps {
+  /** HTTP status code */
+  statusCode: number;
+  /** Error message */
+  message: string;
+  /** Error object (development only) */
+  error?: Error;
+  /** Stack trace (development only) */
+  stack?: string;
+  /** Request URL that caused the error */
+  url?: string;
+}
+
+/**
+ * Options for error handling
+ */
+export interface ErrorHandlerOptions {
+  /** Whether running in development mode */
+  isDev?: boolean;
+  /** Avalon runtime configuration */
+  avalonConfig?: AvalonRuntimeConfig;
+  /** Custom page module loader */
+  loadPageModule?: (filePath: string) => Promise<PageModule>;
+  /** Pages directory path */
+  pagesDir?: string;
+}
+
+/**
+ * Cache for discovered error pages
+ */
+interface ErrorPageCache {
+  /** Custom 404 page module */
+  notFound?: PageModule | null;
+  /** Custom 500 page module */
+  serverError?: PageModule | null;
+  /** Generic error page module */
+  genericError?: PageModule | null;
+  /** Whether cache has been initialized */
+  initialized: boolean;
+}
+
+// Module-level cache for error pages
+let errorPageCache: ErrorPageCache = {
+  initialized: false,
+};
+
+/**
+ * Clears the error page cache
+ * Call this during development when error pages change
+ */
+export function clearErrorPageCache(): void {
+  errorPageCache = {
+    initialized: false,
+  };
+}
+
+/**
+ * Discovers and caches custom error pages from the pages directory
+ *
+ * @param options - Error handler options
+ * @returns Object containing discovered error page modules
+ */
+export async function discoverErrorPages(
+  options: ErrorHandlerOptions
+): Promise<ErrorPageCache> {
+  if (errorPageCache.initialized && !options.isDev) {
+    return errorPageCache;
+  }
+
+  const { loadPageModule, pagesDir = "src/pages" } = options;
+
+  if (!loadPageModule) {
+    errorPageCache.initialized = true;
+    return errorPageCache;
+  }
+
+  // Try to load custom 404 page
+  try {
+    errorPageCache.notFound = await loadPageModule(`${pagesDir}/404.tsx`);
+  } catch {
+    // Try .jsx extension
+    try {
+      errorPageCache.notFound = await loadPageModule(`${pagesDir}/404.jsx`);
+    } catch {
+      errorPageCache.notFound = null;
+    }
+  }
+
+  // Try to load custom 500 page
+  try {
+    errorPageCache.serverError = await loadPageModule(`${pagesDir}/500.tsx`);
+  } catch {
+    // Try .jsx extension
+    try {
+      errorPageCache.serverError = await loadPageModule(`${pagesDir}/500.jsx`);
+    } catch {
+      errorPageCache.serverError = null;
+    }
+  }
+
+  // Try to load generic error page
+  try {
+    errorPageCache.genericError = await loadPageModule(`${pagesDir}/_error.tsx`);
+  } catch {
+    // Try .jsx extension
+    try {
+      errorPageCache.genericError = await loadPageModule(`${pagesDir}/_error.jsx`);
+    } catch {
+      errorPageCache.genericError = null;
+    }
+  }
+
+  errorPageCache.initialized = true;
+  return errorPageCache;
+}
+
+/**
+ * Gets the appropriate error page module for a status code
+ *
+ * @param statusCode - HTTP status code
+ * @param cache - Error page cache
+ * @returns Error page module or null if no custom page exists
+ */
+export function getErrorPageModule(
+  statusCode: number,
+  cache: ErrorPageCache
+): PageModule | null {
+  // Check for specific status code pages first
+  if (statusCode === 404 && cache.notFound) {
+    return cache.notFound;
+  }
+
+  if (statusCode === 500 && cache.serverError) {
+    return cache.serverError;
+  }
+
+  // Fall back to generic error page
+  if (cache.genericError) {
+    return cache.genericError;
+  }
+
+  return null;
+}
+
+/**
+ * Creates error page props from an error
+ *
+ * @param error - The error that occurred
+ * @param url - Request URL
+ * @param isDev - Whether running in development mode
+ * @returns Error page props
+ */
+export function createErrorPageProps(
+  error: Error | HttpError,
+  url?: string,
+  isDev?: boolean
+): ErrorPageProps {
+  const statusCode = isHttpError(error) ? error.statusCode : 500;
+
+  const props: ErrorPageProps = {
+    statusCode,
+    message: error.message,
+    url,
+  };
+
+  // Include error details only in development
+  if (isDev) {
+    props.error = error;
+    props.stack = error.stack;
+  }
+
+  return props;
+}
+
+/**
+ * Renders a custom error page to HTML
+ *
+ * @param pageModule - The error page module
+ * @param props - Error page props
+ * @param context - Render context
+ * @param isDev - Whether running in development mode
+ * @returns Rendered HTML string
+ */
+export async function renderErrorPage(
+  pageModule: PageModule,
+  props: ErrorPageProps,
+  context: NitroRenderContext,
+  isDev: boolean
+): Promise<string> {
+  // The page module's default export should be a component function
+  const Component = pageModule.default as (props: ErrorPageProps) => unknown;
+
+  if (typeof Component !== "function") {
+    // Fall back to default error page if component is invalid
+    return generateDefaultErrorPage(props.statusCode, props.message, isDev, props.stack);
+  }
+
+  try {
+    // Render the component
+    // In a real implementation, this would use the SSR pipeline
+    // For now, we generate a basic HTML structure
+    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 || `Error ${props.statusCode}`))}</title>
+    ${metadata.description ? `<meta name="description" content="${escapeHtml(String(metadata.description))}">` : ""}
+    <style>
+      body {
+        font-family: system-ui, -apple-system, sans-serif;
+        margin: 0;
+        padding: 40px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        min-height: 100vh;
+        box-sizing: border-box;
+        background: #f5f5f5;
+      }
+      .error-page {
+        text-align: center;
+        max-width: 600px;
+      }
+      h1 {
+        font-size: 48px;
+        margin: 0 0 20px 0;
+        color: #333;
+      }
+      p {
+        color: #666;
+        margin: 0 0 20px 0;
+      }
+      a {
+        color: #0066cc;
+        text-decoration: none;
+      }
+      a:hover {
+        text-decoration: underline;
+      }
+      details {
+        margin-top: 20px;
+        text-align: left;
+      }
+      pre {
+        background: #1a1a1a;
+        color: #e0e0e0;
+        padding: 15px;
+        border-radius: 4px;
+        overflow-x: auto;
+        font-size: 12px;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app" data-error-page="true" data-status-code="${props.statusCode}" data-props='${escapeHtml(JSON.stringify(props))}'>
+      <!-- Custom error page content rendered by Avalon SSR pipeline -->
+      <div class="error-page">
+        <h1>${props.statusCode}</h1>
+        <p>${escapeHtml(props.message)}</p>
+        ${isDev && props.stack ? `
+        <details>
+          <summary>Error details</summary>
+          <pre>${escapeHtml(props.stack)}</pre>
+        </details>
+        ` : ""}
+        <a href="/">Go back home</a>
+      </div>
+    </div>
+  </body>
+</html>`;
+  } catch (renderError) {
+    console.error("[Error Page Render Error]", renderError);
+    // Fall back to default error page
+    return generateDefaultErrorPage(props.statusCode, props.message, isDev, props.stack);
+  }
+}
+
+/**
+ * Generates a default error page when no custom page is available
+ *
+ * @param statusCode - HTTP status code
+ * @param message - Error message
+ * @param isDev - Whether running in development mode
+ * @param stack - Stack trace (development only)
+ * @returns HTML string
+ */
+export function generateDefaultErrorPage(
+  statusCode: number,
+  message: string,
+  isDev: boolean,
+  stack?: string
+): string {
+  if (isDev) {
+    return generateDevErrorPage(statusCode, message, stack);
+  }
+  return generateProdErrorPage(statusCode, message);
+}
+
+/**
+ * Generates a development error page with full details
+ */
+function generateDevErrorPage(
+  statusCode: number,
+  message: string,
+  stack?: string
+): 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;
+      }
+      a {
+        color: #6b9fff;
+        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 class="message">${escapeHtml(message)}</p>
+      ${stack ? `
+      <div class="stack-title">Stack Trace</div>
+      <pre>${escapeHtml(stack)}</pre>
+      ` : ""}
+      <p><a href="/">← Return to home</a></p>
+    </div>
+  </body>
+</html>`;
+}
+
+/**
+ * Generates a production error page without sensitive details
+ */
+function generateProdErrorPage(statusCode: number, message: string): string {
+  // Use generic message for 500 errors in production
+  const displayMessage = statusCode >= 500 
+    ? "An unexpected error occurred. Please try again later."
+    : message;
+
+  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 0 20px 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>${escapeHtml(displayMessage)}</p>
+      <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",
+    408: "Request Timeout",
+    410: "Gone",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+  };
+  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;");
+}
+
+/**
+ * Handles a render error and returns an appropriate response
+ *
+ * This function:
+ * 1. Discovers custom error pages if available
+ * 2. Renders the appropriate error page (custom or default)
+ * 3. Returns a Response with the correct status code
+ *
+ * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
+ *
+ * @param error - The error that occurred
+ * @param event - H3 event
+ * @param options - Error handler options
+ * @returns Response with error page
+ */
+export async function handleRenderError(
+  error: Error | HttpError,
+  event: H3Event,
+  options: ErrorHandlerOptions
+): Promise<Response> {
+  const { isDev = false } = options;
+  const statusCode = isHttpError(error) ? error.statusCode : 500;
+  const url = getRequestURL(event);
+
+  console.error(`[Render Error] ${statusCode} - ${error.message}`, {
+    url: url.pathname,
+    stack: isDev ? error.stack : undefined,
+  });
+
+  // Try to discover and use custom error pages
+  const errorPages = await discoverErrorPages(options);
+  const errorPageModule = getErrorPageModule(statusCode, errorPages);
+
+  let html: string;
+
+  if (errorPageModule) {
+    // Render custom error page
+    const props = createErrorPageProps(error, url.pathname, isDev);
+    const context = createRenderContext(event, {});
+    html = await renderErrorPage(errorPageModule, props, context, isDev);
+  } else {
+    // Use default error page
+    html = generateDefaultErrorPage(
+      statusCode,
+      error.message,
+      isDev,
+      isDev ? error.stack : undefined
+    );
+  }
+
+  return new Response(html, {
+    status: statusCode,
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  });
+}
+
+/**
+ * Handles an API error and returns an appropriate JSON response
+ *
+ * Requirements: 10.1, 10.2, 10.4
+ *
+ * @param error - The error that occurred
+ * @param options - Error handler options
+ * @returns Response with JSON error
+ */
+export function handleApiError(
+  error: Error | HttpError,
+  options: ErrorHandlerOptions
+): Response {
+  const { isDev = false } = options;
+  const statusCode = isHttpError(error) ? error.statusCode : 500;
+
+  console.error(`[API Error] ${statusCode} - ${error.message}`, {
+    stack: isDev ? error.stack : undefined,
+  });
+
+  const body = isDev
+    ? {
+        error: error.message,
+        statusCode,
+        stack: error.stack,
+      }
+    : {
+        error: statusCode >= 500 ? "Internal Server Error" : error.message,
+        statusCode,
+      };
+
+  return new Response(JSON.stringify(body), {
+    status: statusCode,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/**
+ * Creates a 404 Not Found response
+ *
+ * @param pathname - The requested path
+ * @param event - H3 event
+ * @param options - Error handler options
+ * @returns Response with 404 error page
+ */
+export async function handleNotFound(
+  pathname: string,
+  event: H3Event,
+  options: ErrorHandlerOptions
+): Promise<Response> {
+  const error = createNotFoundError(`Page not found: ${pathname}`);
+  return handleRenderError(error, event, options);
+}
+
+/**
+ * Creates a 500 Internal Server Error response
+ *
+ * @param error - The original error
+ * @param event - H3 event
+ * @param options - Error handler options
+ * @returns Response with 500 error page
+ */
+export async function handleInternalError(
+  error: Error,
+  event: H3Event,
+  options: ErrorHandlerOptions
+): Promise<Response> {
+  const httpError = createInternalError(error.message);
+  // Preserve the original stack trace
+  httpError.stack = error.stack;
+  return handleRenderError(httpError, event, options);
+}
+