@useavalon/avalon 0.1.0

package/src/nitro/types.ts

@@ -0,0 +1,321 @@
+/**
+ * Nitro Types and Interfaces for Avalon
+ *
+ * This module defines the core types used throughout the Nitro integration,
+ * including render context, runtime configuration, and route definitions.
+ *
+ * In Nitro v3, canonical types should be imported from `nitro/types`.
+ * Avalon-specific types that extend or complement Nitro's types are defined here.
+ */
+
+import type { MiddlewareContext } from "../nitro/middleware-adapter.ts";
+import type { ApiMethod } from "../schemas/api.ts";
+
+/**
+ * ServerRequest type reference from Nitro v3 (`nitro/types`).
+ * Re-exported here for convenience within Avalon's Nitro integration.
+ *
+ * Represents the server-side request object in Nitro v3's type system.
+ * When the full `nitro/types` package is available, prefer importing directly.
+ */
+export interface ServerRequest {
+  /** HTTP method */
+  method: string;
+  /** Request URL */
+  url: string;
+  /** Request headers */
+  headers: Record<string, string | string[] | undefined>;
+  /** Request body (if applicable) */
+  body?: unknown;
+}
+
+/**
+ * H3 Event type placeholder
+ * This represents the H3 event object from Nitro's h3 library
+ */
+export interface H3Event {
+  /** HTTP method */
+  method: string;
+  /** Node.js request object */
+  node?: {
+    req: unknown;
+    res?: unknown;
+  };
+  /** Event context for storing data */
+  context: Record<string, unknown>;
+  /** Request path */
+  path: string;
+}
+
+/**
+ * Avalon-specific runtime configuration stored in Nitro's runtimeConfig
+ * This is accessed via useRuntimeConfig().avalon in handlers
+ */
+export interface AvalonRuntimeConfig {
+  /** Enable streaming SSR responses */
+  streaming: boolean;
+  /** Pages directory path relative to project root */
+  pagesDir: string;
+  /** Layouts directory path relative to project root */
+  layoutsDir: string;
+}
+
+/**
+ * Render context provided to the SSR renderer
+ * Contains all information needed to render a page
+ */
+export interface NitroRenderContext {
+  /** Request URL */
+  url: URL;
+  /** Route parameters extracted from dynamic segments */
+  params: Record<string, string>;
+  /** Query parameters from URL search string */
+  query: Record<string, string | string[]>;
+  /** Original HTTP request */
+  request: Request;
+  /** H3 event for advanced use cases */
+  event: H3Event;
+  /** Middleware context if middleware was executed */
+  middlewareContext?: MiddlewareContext;
+  /** Layout context for rendering */
+  layoutContext?: LayoutContext;
+}
+
+/**
+ * Layout context for page rendering
+ */
+export interface LayoutContext {
+  /** Layout component paths in nesting order (outermost first) */
+  layouts: string[];
+  /** Layout data loaded from layout modules */
+  layoutData?: Record<string, unknown>;
+}
+
+/**
+ * Discovered route information
+ */
+export interface DiscoveredRoute {
+  /** Route type: page or API */
+  type: "page" | "api";
+  /** Absolute file path to the route handler */
+  filePath: string;
+  /** Route pattern for matching (e.g., /users/:id) */
+  pattern: string;
+  /** Extracted parameter names from dynamic segments */
+  params: string[];
+  /** HTTP method for API routes with method suffix */
+  method?: ApiMethod;
+}
+
+/**
+ * Nitro route configuration
+ */
+export interface NitroRouteConfig {
+  /** Route pattern (e.g., /users/:id) */
+  pattern: string;
+  /** Route handler type */
+  type: "page" | "api" | "middleware";
+  /** File path to the handler */
+  filePath: string;
+  /** Extracted parameter names */
+  params: string[];
+  /** HTTP method (for API routes) */
+  method?: ApiMethod;
+  /** Layout chain for pages */
+  layouts?: string[];
+}
+
+/**
+ * SSR render options
+ */
+export interface SSRRenderOptions {
+  /** Enable streaming SSR */
+  streaming?: boolean;
+  /** Callback when shell is ready (for streaming) */
+  onShellReady?: () => void;
+  /** Callback when all content is ready */
+  onAllReady?: () => void;
+  /** Callback on render error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * SSR render result
+ */
+export interface SSRRenderResult {
+  /** Rendered HTML string or stream */
+  html: string | ReadableStream<Uint8Array>;
+  /** HTTP status code */
+  statusCode: number;
+  /** Response headers */
+  headers: Record<string, string>;
+}
+
+/**
+ * Island manifest entry for a single island
+ */
+export interface IslandEntry {
+  /** Compiled JavaScript path */
+  src: string;
+  /** Framework identifier (react, vue, svelte, etc.) */
+  framework: string;
+  /** CSS dependencies */
+  css?: string[];
+  /** Preload dependencies */
+  preload?: string[];
+}
+
+/**
+ * Island manifest for production builds
+ */
+export interface IslandManifest {
+  /** Map of island ID to compiled asset information */
+  islands: Record<string, IslandEntry>;
+  /** Client entry script path */
+  clientEntry: string;
+  /** CSS assets to inject */
+  css: string[];
+}
+
+/**
+ * Page module export interface
+ */
+export interface PageModule {
+  /** Default export - the page component */
+  default: unknown;
+  /** Optional page metadata */
+  metadata?: PageMetadata;
+  /** Optional getStaticProps for static generation */
+  getStaticProps?: () => Promise<Record<string, unknown>>;
+  /** Optional getServerSideProps for SSR */
+  getServerSideProps?: (
+    context: NitroRenderContext
+  ) => Promise<Record<string, unknown>>;
+}
+
+/**
+ * Page metadata for SEO and configuration
+ */
+export interface PageMetadata {
+  /** Page title */
+  title?: string;
+  /** Page description */
+  description?: string;
+  /** Open Graph metadata */
+  openGraph?: {
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+  /** Additional head elements */
+  head?: Array<{
+    tag: string;
+    attrs?: Record<string, string>;
+    content?: string;
+  }>;
+}
+
+/**
+ * Error response structure
+ */
+export interface ErrorResponse {
+  /** HTTP status code */
+  statusCode: number;
+  /** Error message */
+  message: string;
+  /** Stack trace (development only) */
+  stack?: string;
+  /** Additional error data */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * HTTP error class for typed error handling
+ */
+export class HttpError extends Error {
+  /** HTTP status code */
+  statusCode: number;
+  /** Additional error data */
+  data?: Record<string, unknown>;
+
+  constructor(
+    statusCode: number,
+    message: string,
+    data?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = "HttpError";
+    this.statusCode = statusCode;
+    this.data = data;
+  }
+}
+
+/**
+ * Create a 404 Not Found error
+ */
+export function createNotFoundError(message = "Not Found"): HttpError {
+  return new HttpError(404, message);
+}
+
+/**
+ * Create a 405 Method Not Allowed error
+ */
+export function createMethodNotAllowedError(
+  allowedMethods: string[]
+): HttpError {
+  return new HttpError(405, "Method Not Allowed", { allowed: allowedMethods });
+}
+
+/**
+ * Create a 500 Internal Server Error
+ */
+export function createInternalError(message = "Internal Server Error"): HttpError {
+  return new HttpError(500, message);
+}
+
+/**
+ * Type guard to check if an error is an HttpError
+ */
+export function isHttpError(error: unknown): error is HttpError {
+  return error instanceof HttpError;
+}
+
+/**
+ * Avalon context stored in H3 event.context
+ */
+export interface AvalonEventContext {
+  /** Middleware context after middleware execution */
+  middlewareContext?: MiddlewareContext;
+  /** Resolved route information */
+  route?: NitroRouteConfig;
+  /** Page props from getServerSideProps */
+  pageProps?: Record<string, unknown>;
+}
+
+/**
+ * Development server options
+ */
+export interface DevServerOptions {
+  /** Port to listen on */
+  port?: number;
+  /** Host to bind to */
+  host?: string;
+  /** Enable HTTPS */
+  https?: boolean;
+  /** Open browser on start */
+  open?: boolean;
+}
+
+/**
+ * Build options for production
+ */
+export interface BuildOptions {
+  /** Output directory */
+  outDir?: string;
+  /** Enable source maps */
+  sourcemap?: boolean;
+  /** Minify output */
+  minify?: boolean;
+  /** Target preset */
+  preset?: string;
+}

package/src/render/collect-css.ts

@@ -0,0 +1,198 @@
+/**
+ * Collect CSS from Vite's module graph for SSR.
+ *
+ * After ssrLoadModule loads a page, Vite's module graph knows about all
+ * imported CSS files (including CSS modules). This utility walks the graph
+ * starting from the page module and collects all CSS content so it can be
+ * injected into the SSR HTML as <style> tags — preventing FOUC.
+ */
+
+import type { ViteDevServer, ModuleNode } from "vite";
+
+/**
+ * Collect all CSS imported (directly or transitively) by a given module URL.
+ *
+ * Walks Vite's module graph breadth-first, collecting the transformed CSS
+ * source for every `.css` dependency (including `.module.css`).
+ *
+ * @param server - The Vite dev server instance
+ * @param moduleUrl - The module URL to start from (e.g. "/src/pages/frameworks.tsx")
+ * @returns Array of CSS strings ready to be injected as <style> tags
+ */
+export async function collectCssFromModuleGraph(
+	server: ViteDevServer,
+	moduleUrl: string,
+): Promise<string[]> {
+	const cssContents: string[] = [];
+	const visited = new Set<string>();
+
+	const entryModule = await server.moduleGraph.getModuleByUrl(moduleUrl);
+	if (!entryModule) return cssContents;
+
+	const queue: ModuleNode[] = [entryModule];
+
+	while (queue.length > 0) {
+		const mod = queue.shift()!;
+		const id = mod.id ?? mod.url;
+
+		if (visited.has(id)) continue;
+		visited.add(id);
+
+		// If this module is a CSS file, collect its transformed content
+		if (isCssModule(id)) {
+			const css = await getCssContent(server, mod);
+			if (css) {
+				cssContents.push(css);
+			}
+		}
+
+		// Walk imported modules
+		for (const imported of mod.importedModules) {
+			const importedId = imported.id ?? imported.url;
+			if (!visited.has(importedId)) {
+				queue.push(imported);
+			}
+		}
+	}
+
+	return cssContents;
+}
+
+/**
+ * Check if a module ID represents a CSS file.
+ */
+function isCssModule(id: string): boolean {
+	// Strip query params for extension check
+	const cleanId = id.split("?")[0];
+	return (
+		cleanId.endsWith(".css") ||
+		cleanId.endsWith(".scss") ||
+		cleanId.endsWith(".sass") ||
+		cleanId.endsWith(".less") ||
+		cleanId.endsWith(".styl") ||
+		cleanId.endsWith(".stylus")
+	);
+}
+
+/**
+ * Get the transformed CSS content for a module.
+ *
+ * Uses Vite's transformRequest to get the processed CSS (with module
+ * class name hashing, PostCSS transforms, etc. already applied).
+ */
+async function getCssContent(
+	server: ViteDevServer,
+	mod: ModuleNode,
+): Promise<string | null> {
+	try {
+		// Use the module's URL for transform (includes query params Vite needs)
+		const url = mod.url;
+		const result = await server.transformRequest(url + "?direct");
+
+		if (result && typeof result.code === "string") {
+			// Vite wraps CSS in a JS module for HMR. For SSR injection we need
+			// the raw CSS. The transformed code contains the CSS as a string
+			// in an `__vite__css` or similar export. Try to extract it.
+			const rawCss = extractCssFromTransformedModule(result.code);
+			return rawCss;
+		}
+
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extract raw CSS from Vite's transformed CSS module JS wrapper.
+ *
+ * Vite transforms CSS files into JS modules that look like:
+ *   const __vite__css = "...actual css..."
+ *   __vite__updateStyle(...)
+ *
+ * We extract the CSS string from this wrapper.
+ */
+function extractCssFromTransformedModule(code: string): string | null {
+	// Pattern 1: __vite__css = "..."
+	const viteVarMatch = new RegExp(/const\s+__vite__css\s*=\s*"((?:[^"\\]|\\.)*)"/).exec(code);
+	if (viteVarMatch) {
+		return unescapeJsString(viteVarMatch[1]);
+	}
+
+	// Pattern 2: __vite_ssr_exports__.default = "..."
+	const ssrExportMatch = new RegExp(/__vite_ssr_exports__\.default\s*=\s*"((?:[^"\\]|\\.)*)"/).exec(code);
+	if (ssrExportMatch) {
+		return unescapeJsString(ssrExportMatch[1]);
+	}
+
+	// Pattern 3: export default "..."
+	const exportDefaultMatch = new RegExp(/export\s+default\s+"((?:[^"\\]|\\.)*)"/).exec(code);
+	if (exportDefaultMatch) {
+		return unescapeJsString(exportDefaultMatch[1]);
+	}
+
+	// Pattern 4: the code itself might be raw CSS (no JS wrapper)
+	if (!code.includes("export ") && !code.includes("__vite")) {
+		return code;
+	}
+
+	return null;
+}
+
+/**
+ * Unescape a JS string literal
+ */
+function unescapeJsString(str: string): string {
+	return str
+		.replaceAll(String.raw`\n`, "\n")
+		.replaceAll(String.raw`\t`, "\t")
+		.replaceAll(String.raw`\r`, "\r")
+		.replaceAll(String.raw`\"`, '"')
+		.replaceAll('\\\\', "\\");
+}
+
+/**
+ * Inject collected CSS into an HTML string before </head>.
+ *
+ * Each CSS string is wrapped in a <style data-avalon-ssr-css> tag.
+ * CSS content is sanitized to prevent style tag breakout (XSS via </style> injection).
+ * If no </head> is found, styles are prepended to the HTML.
+ */
+export function injectSsrCss(html: string, cssContents: string[]): string {
+	if (cssContents.length === 0) return html;
+
+	const styleTags = cssContents
+		.map((css) => `<style data-avalon-ssr-css>${sanitizeCssForStyleTag(css)}</style>`)
+		.join("\n");
+
+	if (html.includes("</head>")) {
+		return html.replace("</head>", `${styleTags}\n</head>`);
+	}
+
+	// Fallback: inject after <head> or at the start
+	if (html.includes("<head>")) {
+		return html.replace("<head>", `<head>\n${styleTags}`);
+	}
+
+	return styleTags + html;
+}
+
+/**
+ * Sanitize CSS content for safe injection inside a <style> tag.
+ *
+ * The only way to break out of a <style> tag is with a closing </style> tag
+ * (case-insensitive, with optional whitespace). We neutralize this by escaping
+ * any occurrence of `</style` in the CSS content.
+ *
+ * This prevents XSS via:
+ *   .foo {} </style><script>alert('xss')</script><style>
+ *
+ * The CSS source comes from Vite's module graph (local project files and
+ * npm dependencies), so this is defense-in-depth against compromised deps.
+ */
+function sanitizeCssForStyleTag(css: string): string {
+	// Replace </style (case-insensitive) with an escaped version that won't
+	// close the tag. Using a backslash escape: <\/style
+	// Browsers ignore the backslash in CSS context, so styles still work.
+	return css.replaceAll(/<\/style/gi, String.raw`<\/style`);
+}

package/src/render/error-pages.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared error page HTML templates for development mode.
+ * Extracted from nitro-integration.ts to keep that file focused on coordination.
+ *
+ * @module render/error-pages
+ */
+
+/**
+ * Escapes HTML special characters
+ */
+function escapeHtml(str: string): string {
+  return str
+    .replaceAll('&', "&")
+    .replaceAll('<', "&lt;")
+    .replaceAll('>', "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll('\'', "&#039;");
+}
+
+/**
+ * Generates a styled 500 error page for development with stack trace.
+ */
+export function generateErrorPage(error: Error): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>SSR Error</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; }
+      .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">
+      <h1>SSR Error</h1>
+      <p class="message">${escapeHtml(error.message)}</p>
+      ${error.stack ? `
+      <div class="stack-title">Stack Trace</div>
+      <pre>${escapeHtml(error.stack)}</pre>
+      ` : ""}
+    </div>
+    <script type="module" src="/@vite/client"></script>
+  </body>
+</html>`;
+}
+
+/**
+ * Generates a minimal fallback 404 page when the error handler itself fails.
+ */
+export function generateFallback404(url: string): string {
+  return `<!DOCTYPE html><html><head><title>404 Not Found</title></head><body><h1>404 - Page Not Found</h1><p>The page ${escapeHtml(url)} was not found.</p></body></html>`;
+}