alepha 0.15.1 → 0.15.3

package/dist/react/router/index.js

@@ -0,0 +1,4722 @@
+import { $atom, $env, $hook, $inject, $module, $use, Alepha, AlephaError, Json, KIND, Primitive, createPrimitive, isFileLike, t } from "alepha";
+import { AlephaDateTime, DateTimeProvider } from "alepha/datetime";
+import { AlephaContext, AlephaReact, ClientOnly, ErrorBoundary, useAlepha, useEvents, useInject, useStore } from "alepha/react";
+import { AlephaServer, ServerProvider, ServerRouterProvider } from "alepha/server";
+import { AlephaServerCache } from "alepha/server/cache";
+import { AlephaServerLinks, LinkProvider, ServerLinksProvider } from "alepha/server/links";
+import { $logger } from "alepha/logger";
+import { StrictMode, createContext, createElement, memo, use, useEffect, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { join } from "node:path";
+import { BrowserHeadProvider, ServerHeadProvider } from "alepha/react/head";
+import { ServerStaticProvider } from "alepha/server/static";
+import { createReadStream } from "node:fs";
+import { access, copyFile, cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { PassThrough, Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { exec, spawn } from "node:child_process";
+import { renderToReadableStream, renderToString } from "react-dom/server";
+import { RouterProvider } from "alepha/router";
+
+//#region ../../src/react/router/constants/PAGE_PRELOAD_KEY.ts
+/**
+* Symbol key for SSR module preloading path.
+* Using Symbol.for() allows the Vite plugin to inject this at build time.
+* @internal
+*/
+const PAGE_PRELOAD_KEY = Symbol.for("alepha.page.preload");
+
+//#endregion
+//#region ../../src/react/router/services/ReactPageService.ts
+/**
+* $page methods interface.
+*/
+var ReactPageService = class {
+	fetch(pathname, options = {}) {
+		throw new AlephaError("Fetch is not available for this environment.");
+	}
+	render(name, options = {}) {
+		throw new AlephaError("Render is not available for this environment.");
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/primitives/$page.ts
+/**
+* Main primitive for defining a React route in the application.
+*
+* The $page primitive is the core building block for creating type-safe, SSR-enabled React routes.
+* It provides a declarative way to define pages with powerful features:
+*
+* **Routing & Navigation**
+* - URL pattern matching with parameters (e.g., `/users/:id`)
+* - Nested routing with parent-child relationships
+* - Type-safe URL parameter and query string validation
+*
+* **Data Loading**
+* - Server-side data fetching with the `loader` function
+* - Automatic serialization and hydration for SSR
+* - Access to request context, URL params, and parent data
+*
+* **Component Loading**
+* - Direct component rendering or lazy loading for code splitting
+* - Client-only rendering when browser APIs are needed
+* - Automatic fallback handling during hydration
+*
+* **Performance Optimization**
+* - Static generation for pre-rendered pages at build time
+* - Server-side caching with configurable TTL and providers
+* - Code splitting through lazy component loading
+*
+* **Error Handling**
+* - Custom error handlers with support for redirects
+* - Hierarchical error handling (child → parent)
+* - HTTP status code handling (404, 401, etc.)
+*
+* **Page Animations**
+* - CSS-based enter/exit animations
+* - Dynamic animations based on page state
+* - Custom timing and easing functions
+*
+* **Lifecycle Management**
+* - Server response hooks for headers and status codes
+* - Page leave handlers for cleanup (browser only)
+* - Permission-based access control
+*
+* @example Simple page with data fetching
+* ```typescript
+* const userProfile = $page({
+*   path: "/users/:id",
+*   schema: {
+*     params: t.object({ id: t.integer() }),
+*     query: t.object({ tab: t.optional(t.text()) })
+*   },
+*   loader: async ({ params }) => {
+*     const user = await userApi.getUser(params.id);
+*     return { user };
+*   },
+*   lazy: () => import("./UserProfile.tsx")
+* });
+* ```
+*
+* @example Nested routing with error handling
+* ```typescript
+* const projectSection = $page({
+*   path: "/projects/:id",
+*   children: () => [projectBoard, projectSettings],
+*   loader: async ({ params }) => {
+*     const project = await projectApi.get(params.id);
+*     return { project };
+*   },
+*   errorHandler: (error) => {
+*     if (HttpError.is(error, 404)) {
+*       return <ProjectNotFound />;
+*     }
+*   }
+* });
+* ```
+*
+* @example Static generation with caching
+* ```typescript
+* const blogPost = $page({
+*   path: "/blog/:slug",
+*   static: {
+*     entries: posts.map(p => ({ params: { slug: p.slug } }))
+*   },
+*   loader: async ({ params }) => {
+*     const post = await loadPost(params.slug);
+*     return { post };
+*   }
+* });
+* ```
+*/
+const $page = (options) => {
+	return createPrimitive(PagePrimitive, options);
+};
+var PagePrimitive = class extends Primitive {
+	reactPageService = $inject(ReactPageService);
+	onInit() {
+		if (this.options.static) this.options.cache ??= { store: {
+			provider: "memory",
+			ttl: [1, "week"]
+		} };
+	}
+	get name() {
+		return this.options.name ?? this.config.propertyKey;
+	}
+	/**
+	* For testing or build purposes.
+	*
+	* This will render the page (HTML layout included or not) and return the HTML + context.
+	* Only valid for server-side rendering, it will throw an error if called on the client-side.
+	*/
+	async render(options) {
+		return this.reactPageService.render(this.name, options);
+	}
+	async fetch(options) {
+		return this.reactPageService.fetch(this.options.path || "", options);
+	}
+};
+$page[KIND] = PagePrimitive;
+
+//#endregion
+//#region ../../src/react/router/components/ErrorViewer.tsx
+const isBrowser = typeof window !== "undefined";
+/**
+* Error viewer component - Terminal/brutalist aesthetic
+*/
+const ErrorViewer = ({ error, alepha }) => {
+	const [expanded, setExpanded] = useState(false);
+	const [showNodeModules, setShowNodeModules] = useState(false);
+	const [visible, setVisible] = useState(false);
+	const containerRef = useRef(null);
+	const isProduction = alepha.isProduction();
+	useEffect(() => {
+		const timer = setTimeout(() => setVisible(true), 10);
+		return () => clearTimeout(timer);
+	}, []);
+	useEffect(() => {
+		if (!isBrowser) return;
+		const handler = (e) => {
+			if (e.key === "c" && !e.metaKey && !e.ctrlKey) copyToClipboard(error.stack || error.message);
+		};
+		window.addEventListener("keydown", handler);
+		return () => window.removeEventListener("keydown", handler);
+	}, [error]);
+	if (isProduction) return /* @__PURE__ */ jsx(ErrorViewerProduction, {});
+	const frames = parseStackTrace(error.stack);
+	const appFrames = frames.filter((f) => !f.isNodeModules);
+	const nodeModulesFrames = frames.filter((f) => f.isNodeModules);
+	const visibleAppFrames = expanded ? appFrames : appFrames.slice(0, 5);
+	const hiddenAppCount = appFrames.length - 5;
+	const timestamp = (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", {
+		hour12: false,
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		ref: containerRef,
+		style: {
+			...styles.overlay,
+			opacity: visible ? 1 : 0
+		},
+		role: "alertdialog",
+		"aria-modal": "true",
+		"aria-labelledby": "error-viewer-title",
+		children: [/* @__PURE__ */ jsx("div", {
+			style: styles.scanlines,
+			"aria-hidden": "true"
+		}), /* @__PURE__ */ jsxs("div", {
+			style: {
+				...styles.container,
+				transform: visible ? "translateY(0)" : "translateY(-20px)",
+				opacity: visible ? 1 : 0
+			},
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					style: styles.terminalBar,
+					children: [
+						/* @__PURE__ */ jsxs("div", {
+							style: styles.terminalDots,
+							children: [
+								/* @__PURE__ */ jsx("span", { style: {
+									...styles.dot,
+									backgroundColor: "#ff5f57"
+								} }),
+								/* @__PURE__ */ jsx("span", { style: {
+									...styles.dot,
+									backgroundColor: "#febc2e"
+								} }),
+								/* @__PURE__ */ jsx("span", { style: {
+									...styles.dot,
+									backgroundColor: "#28c840"
+								} })
+							]
+						}),
+						/* @__PURE__ */ jsx("div", {
+							style: styles.terminalTitle,
+							children: /* @__PURE__ */ jsxs("span", {
+								style: styles.terminalTitleText,
+								children: ["error — ", timestamp]
+							})
+						}),
+						/* @__PURE__ */ jsxs("div", {
+							style: styles.terminalActions,
+							children: [/* @__PURE__ */ jsx("kbd", {
+								style: styles.kbd,
+								children: "C"
+							}), /* @__PURE__ */ jsx("span", {
+								style: styles.kbdLabel,
+								children: "copy"
+							})]
+						})
+					]
+				}),
+				/* @__PURE__ */ jsx(Header, { error }),
+				/* @__PURE__ */ jsxs("div", {
+					style: styles.stackSection,
+					children: [/* @__PURE__ */ jsxs("div", {
+						style: styles.stackHeader,
+						children: [/* @__PURE__ */ jsx("span", {
+							style: styles.stackHeaderText,
+							children: "STACK TRACE"
+						}), /* @__PURE__ */ jsxs("span", {
+							style: styles.stackCount,
+							children: [
+								appFrames.length,
+								" frames",
+								nodeModulesFrames.length > 0 && ` · ${nodeModulesFrames.length} in node_modules`
+							]
+						})]
+					}), /* @__PURE__ */ jsxs("div", {
+						style: styles.frameList,
+						children: [
+							visibleAppFrames.map((frame, i) => /* @__PURE__ */ jsx(StackFrameRow, {
+								frame,
+								index: i
+							}, `${frame.raw}-${i}`)),
+							hiddenAppCount > 0 && !expanded && /* @__PURE__ */ jsx(ExpandButton, {
+								onClick: () => setExpanded(true),
+								label: `Show ${hiddenAppCount} more frames`
+							}),
+							expanded && hiddenAppCount > 0 && /* @__PURE__ */ jsx(ExpandButton, {
+								onClick: () => setExpanded(false),
+								label: "Collapse"
+							}),
+							nodeModulesFrames.length > 0 && /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("button", {
+								type: "button",
+								onClick: () => setShowNodeModules(!showNodeModules),
+								style: styles.nodeModulesToggle,
+								children: [
+									/* @__PURE__ */ jsx("span", {
+										style: styles.nodeModulesIcon,
+										children: showNodeModules ? "▼" : "▶"
+									}),
+									/* @__PURE__ */ jsx("span", {
+										style: styles.nodeModulesLabel,
+										children: "node_modules"
+									}),
+									/* @__PURE__ */ jsx("span", {
+										style: styles.nodeModulesCount,
+										children: nodeModulesFrames.length
+									})
+								]
+							}), showNodeModules && /* @__PURE__ */ jsx("div", {
+								style: styles.nodeModulesFrames,
+								children: nodeModulesFrames.map((frame, i) => /* @__PURE__ */ jsx(StackFrameRow, {
+									frame,
+									index: appFrames.length + i,
+									dimmed: true
+								}, `nm-${frame.raw}-${i}`))
+							})] })
+						]
+					})]
+				}),
+				/* @__PURE__ */ jsx("div", {
+					style: styles.footer,
+					children: /* @__PURE__ */ jsxs("span", {
+						style: styles.footerText,
+						children: [
+							"Press ",
+							/* @__PURE__ */ jsx("kbd", {
+								style: styles.kbdInline,
+								children: "C"
+							}),
+							" to copy stack trace"
+						]
+					})
+				})
+			]
+		})]
+	});
+};
+var ErrorViewer_default = ErrorViewer;
+function parseStackTrace(stack) {
+	if (!stack) return [];
+	const lines = stack.split("\n").slice(1);
+	const frames = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("at ")) continue;
+		const frame = parseStackLine(trimmed);
+		if (frame) frames.push(frame);
+	}
+	return frames;
+}
+function parseStackLine(line) {
+	const isNodeModules = line.includes("node_modules") || line.includes("node:");
+	const withFn = line.match(/^at\s+(.+?)\s+\((.+):(\d+):(\d+)\)$/);
+	if (withFn) return {
+		fn: withFn[1],
+		file: withFn[2],
+		line: withFn[3],
+		col: withFn[4],
+		raw: line,
+		isNodeModules
+	};
+	const withoutFn = line.match(/^at\s+(.+):(\d+):(\d+)$/);
+	if (withoutFn) return {
+		fn: "<anonymous>",
+		file: withoutFn[1],
+		line: withoutFn[2],
+		col: withoutFn[3],
+		raw: line,
+		isNodeModules
+	};
+	return {
+		fn: "",
+		file: line.replace(/^at\s+/, ""),
+		line: "",
+		col: "",
+		raw: line,
+		isNodeModules
+	};
+}
+function copyToClipboard(text) {
+	if (!isBrowser || !navigator.clipboard) return Promise.resolve(false);
+	return navigator.clipboard.writeText(text).then(() => true).catch(() => false);
+}
+/**
+* Header with error badge and message
+*/
+function Header({ error }) {
+	const [copied, setCopied] = useState(false);
+	const [hovered, setHovered] = useState(false);
+	useEffect(() => {
+		if (!copied) return;
+		const timer = setTimeout(() => setCopied(false), 2e3);
+		return () => clearTimeout(timer);
+	}, [copied]);
+	const handleCopy = async () => {
+		if (await copyToClipboard(error.stack || error.message)) setCopied(true);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		style: styles.header,
+		children: [/* @__PURE__ */ jsxs("div", {
+			style: styles.headerRow,
+			children: [/* @__PURE__ */ jsxs("div", {
+				style: styles.errorIndicator,
+				children: [/* @__PURE__ */ jsx("div", { style: styles.errorGlow }), /* @__PURE__ */ jsx("div", {
+					style: styles.errorBadge,
+					children: error.name
+				})]
+			}), /* @__PURE__ */ jsx("button", {
+				type: "button",
+				onClick: handleCopy,
+				onMouseEnter: () => setHovered(true),
+				onMouseLeave: () => setHovered(false),
+				style: {
+					...styles.copyBtn,
+					...hovered ? styles.copyBtnHover : {}
+				},
+				children: copied ? "✓ Copied" : "Copy"
+			})]
+		}), /* @__PURE__ */ jsx("h1", {
+			id: "error-viewer-title",
+			style: styles.message,
+			children: error.message
+		})]
+	});
+}
+/**
+* Single stack frame row
+*/
+function StackFrameRow({ frame, index, dimmed = false }) {
+	const [hovered, setHovered] = useState(false);
+	const isFirst = index === 0 && !dimmed;
+	const fileName = frame.file.split("/").pop() || frame.file;
+	const dirPath = frame.file.substring(0, frame.file.length - fileName.length);
+	const vsCodeLink = frame.file && frame.line ? `vscode://file${frame.file}:${frame.line}:${frame.col || 1}` : null;
+	const content = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", {
+		style: {
+			...styles.frameIndex,
+			color: isFirst ? "#ff6b6b" : dimmed ? "#555" : "#666"
+		},
+		children: String(index + 1).padStart(2, "0")
+	}), /* @__PURE__ */ jsxs("div", {
+		style: styles.frameContent,
+		children: [frame.fn && /* @__PURE__ */ jsx("div", {
+			style: {
+				...styles.fnName,
+				color: dimmed ? "#888" : "#f0f0f0"
+			},
+			children: formatFunctionName(frame.fn)
+		}), /* @__PURE__ */ jsxs("div", {
+			style: styles.filePath,
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					style: {
+						...styles.dirPath,
+						opacity: dimmed ? .6 : .8
+					},
+					children: dirPath
+				}),
+				/* @__PURE__ */ jsx("span", {
+					style: {
+						...styles.fileName,
+						color: dimmed ? "#5a9aba" : "#7cc4eb"
+					},
+					children: fileName
+				}),
+				frame.line && /* @__PURE__ */ jsxs("span", {
+					style: {
+						...styles.lineCol,
+						color: dimmed ? "#9a8a40" : "#e5b83a"
+					},
+					children: [
+						":",
+						frame.line,
+						frame.col && `:${frame.col}`
+					]
+				})
+			]
+		})]
+	})] });
+	const rowStyles = {
+		...styles.frame,
+		...isFirst ? styles.frameFirst : {},
+		backgroundColor: hovered ? "rgba(255,255,255,0.03)" : "transparent"
+	};
+	if (vsCodeLink && isBrowser) return /* @__PURE__ */ jsx("a", {
+		href: vsCodeLink,
+		style: {
+			...rowStyles,
+			textDecoration: "none"
+		},
+		onMouseEnter: () => setHovered(true),
+		onMouseLeave: () => setHovered(false),
+		children: content
+	});
+	return /* @__PURE__ */ jsx("div", {
+		style: rowStyles,
+		children: content
+	});
+}
+/**
+* Format function name with syntax highlighting
+*/
+function formatFunctionName(fn) {
+	const asyncMatch = fn.match(/^(async\s+)?(.+)$/);
+	if (asyncMatch?.[1]) return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+		style: { color: "#c678dd" },
+		children: "async "
+	}), /* @__PURE__ */ jsx("span", { children: asyncMatch[2] })] });
+	const methodMatch = fn.match(/^(.+)\.([^.]+)$/);
+	if (methodMatch) return /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsx("span", {
+			style: { color: "#e5c07b" },
+			children: methodMatch[1]
+		}),
+		/* @__PURE__ */ jsx("span", {
+			style: { color: "#666" },
+			children: "."
+		}),
+		/* @__PURE__ */ jsx("span", { children: methodMatch[2] })
+	] });
+	return fn;
+}
+/**
+* Expand/collapse button
+*/
+function ExpandButton({ onClick, label }) {
+	const [hovered, setHovered] = useState(false);
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		onClick,
+		onMouseEnter: () => setHovered(true),
+		onMouseLeave: () => setHovered(false),
+		style: {
+			...styles.expandBtn,
+			backgroundColor: hovered ? "rgba(255,255,255,0.05)" : "transparent",
+			color: hovered ? "#aaa" : "#777"
+		},
+		children: label
+	});
+}
+/**
+* Production error view - minimal, user-friendly
+*/
+function ErrorViewerProduction() {
+	const [hovered, setHovered] = useState(false);
+	const handleReload = () => {
+		if (isBrowser) window.location.reload();
+	};
+	return /* @__PURE__ */ jsx("div", {
+		style: styles.overlay,
+		role: "alertdialog",
+		"aria-modal": "true",
+		children: /* @__PURE__ */ jsxs("div", {
+			style: styles.prodContainer,
+			children: [
+				/* @__PURE__ */ jsx("div", {
+					style: styles.prodIcon,
+					children: /* @__PURE__ */ jsxs("svg", {
+						width: "32",
+						height: "32",
+						viewBox: "0 0 24 24",
+						fill: "none",
+						stroke: "currentColor",
+						strokeWidth: "2",
+						children: [
+							/* @__PURE__ */ jsx("circle", {
+								cx: "12",
+								cy: "12",
+								r: "10"
+							}),
+							/* @__PURE__ */ jsx("line", {
+								x1: "12",
+								y1: "8",
+								x2: "12",
+								y2: "12"
+							}),
+							/* @__PURE__ */ jsx("line", {
+								x1: "12",
+								y1: "16",
+								x2: "12.01",
+								y2: "16"
+							})
+						]
+					})
+				}),
+				/* @__PURE__ */ jsx("h1", {
+					style: styles.prodTitle,
+					children: "Something went wrong"
+				}),
+				/* @__PURE__ */ jsx("p", {
+					style: styles.prodMessage,
+					children: "We encountered an unexpected error. Please try again."
+				}),
+				/* @__PURE__ */ jsx("button", {
+					type: "button",
+					onClick: handleReload,
+					onMouseEnter: () => setHovered(true),
+					onMouseLeave: () => setHovered(false),
+					style: {
+						...styles.prodButton,
+						backgroundColor: hovered ? "#333" : "#222",
+						borderColor: hovered ? "#555" : "#444"
+					},
+					children: "Reload page"
+				})
+			]
+		})
+	});
+}
+const MONO_FONT = "ui-monospace, \"JetBrains Mono\", \"Fira Code\", SFMono-Regular, Menlo, Monaco, Consolas, monospace";
+const styles = {
+	overlay: {
+		position: "fixed",
+		inset: 0,
+		backgroundColor: "rgba(0, 0, 0, 0.92)",
+		display: "flex",
+		alignItems: "flex-start",
+		justifyContent: "center",
+		padding: "40px 20px",
+		overflow: "auto",
+		fontFamily: MONO_FONT,
+		fontSize: "13px",
+		zIndex: 99999,
+		transition: "opacity 0.2s ease-out"
+	},
+	scanlines: {
+		position: "fixed",
+		inset: 0,
+		background: "repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)",
+		pointerEvents: "none",
+		zIndex: 1e5
+	},
+	container: {
+		width: "100%",
+		maxWidth: "900px",
+		backgroundColor: "#0d0d0d",
+		borderRadius: "8px",
+		overflow: "hidden",
+		boxShadow: "0 0 0 1px #333, 0 25px 80px -12px rgba(0, 0, 0, 0.8)",
+		transition: "transform 0.3s ease-out, opacity 0.3s ease-out"
+	},
+	terminalBar: {
+		display: "flex",
+		alignItems: "center",
+		padding: "12px 16px",
+		backgroundColor: "#1a1a1a",
+		borderBottom: "1px solid #333"
+	},
+	terminalDots: {
+		display: "flex",
+		gap: "8px"
+	},
+	dot: {
+		width: "12px",
+		height: "12px",
+		borderRadius: "50%"
+	},
+	terminalTitle: {
+		flex: 1,
+		textAlign: "center"
+	},
+	terminalTitleText: {
+		color: "#777",
+		fontSize: "12px",
+		letterSpacing: "0.5px"
+	},
+	terminalActions: {
+		display: "flex",
+		alignItems: "center",
+		gap: "6px"
+	},
+	kbd: {
+		display: "inline-block",
+		padding: "2px 6px",
+		backgroundColor: "#2a2a2a",
+		borderRadius: "4px",
+		fontSize: "11px",
+		color: "#aaa",
+		border: "1px solid #444"
+	},
+	kbdInline: {
+		display: "inline-block",
+		padding: "1px 5px",
+		backgroundColor: "#222",
+		borderRadius: "3px",
+		fontSize: "11px",
+		color: "#888",
+		border: "1px solid #444",
+		marginLeft: "4px",
+		marginRight: "4px"
+	},
+	kbdLabel: {
+		color: "#777",
+		fontSize: "11px"
+	},
+	header: {
+		padding: "24px",
+		borderBottom: "1px solid #333"
+	},
+	headerRow: {
+		display: "flex",
+		alignItems: "center",
+		justifyContent: "space-between",
+		marginBottom: "16px"
+	},
+	errorIndicator: {
+		position: "relative",
+		display: "inline-flex"
+	},
+	errorGlow: {
+		position: "absolute",
+		inset: "-4px",
+		background: "radial-gradient(ellipse at center, rgba(255,80,80,0.3) 0%, transparent 70%)",
+		borderRadius: "12px",
+		filter: "blur(8px)"
+	},
+	errorBadge: {
+		position: "relative",
+		display: "inline-block",
+		padding: "6px 14px",
+		backgroundColor: "#3d1a1a",
+		color: "#ff7b7b",
+		fontSize: "12px",
+		fontWeight: 600,
+		borderRadius: "6px",
+		border: "1px solid #5a2828",
+		letterSpacing: "0.5px"
+	},
+	copyBtn: {
+		padding: "8px 14px",
+		backgroundColor: "transparent",
+		color: "#888",
+		fontSize: "12px",
+		fontWeight: 500,
+		borderWidth: "1px",
+		borderStyle: "solid",
+		borderColor: "#444",
+		borderRadius: "6px",
+		cursor: "pointer",
+		transition: "all 0.15s",
+		fontFamily: MONO_FONT
+	},
+	copyBtnHover: {
+		backgroundColor: "#252525",
+		color: "#bbb",
+		borderColor: "#555"
+	},
+	message: {
+		margin: 0,
+		fontSize: "18px",
+		fontWeight: 400,
+		color: "#e8e8e8",
+		lineHeight: 1.6,
+		wordBreak: "break-word",
+		fontFamily: MONO_FONT
+	},
+	stackSection: { borderTop: "1px solid #2a2a2a" },
+	stackHeader: {
+		display: "flex",
+		alignItems: "center",
+		justifyContent: "space-between",
+		padding: "14px 24px",
+		borderBottom: "1px solid #2a2a2a"
+	},
+	stackHeaderText: {
+		fontSize: "10px",
+		fontWeight: 600,
+		color: "#666",
+		letterSpacing: "1.5px"
+	},
+	stackCount: {
+		fontSize: "11px",
+		color: "#555"
+	},
+	frameList: {
+		display: "flex",
+		flexDirection: "column"
+	},
+	frame: {
+		display: "flex",
+		alignItems: "flex-start",
+		padding: "12px 24px",
+		borderBottom: "1px solid #222",
+		transition: "background-color 0.1s",
+		cursor: "pointer"
+	},
+	frameFirst: {
+		backgroundColor: "rgba(255, 80, 80, 0.08)",
+		borderLeft: "2px solid #ff6b6b"
+	},
+	frameIndex: {
+		width: "28px",
+		flexShrink: 0,
+		fontSize: "11px",
+		fontWeight: 500,
+		fontFamily: MONO_FONT
+	},
+	frameContent: {
+		flex: 1,
+		minWidth: 0
+	},
+	fnName: {
+		fontSize: "13px",
+		fontWeight: 500,
+		marginBottom: "4px",
+		fontFamily: MONO_FONT
+	},
+	filePath: {
+		fontSize: "12px",
+		color: "#888",
+		fontFamily: MONO_FONT,
+		wordBreak: "break-all"
+	},
+	dirPath: { color: "#666" },
+	fileName: { color: "#7cc4eb" },
+	lineCol: { color: "#e5b83a" },
+	expandBtn: {
+		width: "100%",
+		padding: "14px 24px",
+		backgroundColor: "transparent",
+		color: "#777",
+		fontSize: "12px",
+		fontWeight: 500,
+		border: "none",
+		borderTop: "1px solid #2a2a2a",
+		cursor: "pointer",
+		textAlign: "left",
+		transition: "all 0.15s",
+		fontFamily: MONO_FONT
+	},
+	nodeModulesToggle: {
+		display: "flex",
+		alignItems: "center",
+		gap: "10px",
+		width: "100%",
+		padding: "12px 24px",
+		backgroundColor: "#0a0a0a",
+		color: "#666",
+		fontSize: "11px",
+		fontWeight: 500,
+		border: "none",
+		borderTop: "1px solid #2a2a2a",
+		cursor: "pointer",
+		textAlign: "left",
+		fontFamily: MONO_FONT
+	},
+	nodeModulesIcon: {
+		fontSize: "8px",
+		color: "#555"
+	},
+	nodeModulesLabel: {
+		flex: 1,
+		letterSpacing: "0.5px"
+	},
+	nodeModulesCount: { color: "#555" },
+	nodeModulesFrames: { backgroundColor: "#080808" },
+	footer: {
+		padding: "14px 24px",
+		borderTop: "1px solid #2a2a2a",
+		backgroundColor: "#0a0a0a"
+	},
+	footerText: {
+		fontSize: "11px",
+		color: "#555"
+	},
+	prodContainer: {
+		textAlign: "center",
+		padding: "60px 40px",
+		backgroundColor: "#0d0d0d",
+		borderRadius: "8px",
+		maxWidth: "400px",
+		border: "1px solid #333"
+	},
+	prodIcon: {
+		width: "64px",
+		height: "64px",
+		margin: "0 auto 24px",
+		color: "#666",
+		display: "flex",
+		alignItems: "center",
+		justifyContent: "center"
+	},
+	prodTitle: {
+		margin: "0 0 12px",
+		fontSize: "18px",
+		fontWeight: 500,
+		color: "#f0f0f0",
+		fontFamily: MONO_FONT
+	},
+	prodMessage: {
+		margin: "0 0 28px",
+		fontSize: "13px",
+		color: "#888",
+		lineHeight: 1.6,
+		fontFamily: MONO_FONT
+	},
+	prodButton: {
+		padding: "12px 24px",
+		backgroundColor: "#222",
+		color: "#bbb",
+		fontSize: "13px",
+		fontWeight: 500,
+		borderWidth: "1px",
+		borderStyle: "solid",
+		borderColor: "#444",
+		borderRadius: "6px",
+		cursor: "pointer",
+		transition: "all 0.15s",
+		fontFamily: MONO_FONT
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/contexts/RouterLayerContext.ts
+const RouterLayerContext = createContext(void 0);
+
+//#endregion
+//#region ../../src/react/router/errors/Redirection.ts
+/**
+* Used for Redirection during the page loading.
+*
+* Depends on the context, it can be thrown or just returned.
+*
+* @example
+* ```ts
+* import { Redirection } from "alepha/react";
+*
+* const MyPage = $page({
+*   loader: async () => {
+*    if (needRedirect) {
+*      throw new Redirection("/new-path");
+*    }
+*   },
+* });
+* ```
+*/
+var Redirection = class extends AlephaError {
+	redirect;
+	constructor(redirect) {
+		super("Redirection");
+		this.redirect = redirect;
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/hooks/useRouterState.ts
+const useRouterState = () => {
+	const [state] = useStore("alepha.react.router.state");
+	if (!state) throw new AlephaError("Missing react router state");
+	return state;
+};
+
+//#endregion
+//#region ../../src/react/router/components/NestedView.tsx
+/**
+* A component that renders the current view of the nested router layer.
+*
+* To be simple, it renders the `element` of the current child page of a parent page.
+*
+* @example
+* ```tsx
+* import { NestedView } from "alepha/react";
+*
+* class App {
+*   parent = $page({
+*     component: () => <NestedView />,
+*   });
+*
+*   child = $page({
+*     parent: this.root,
+*     component: () => <div>Child Page</div>,
+*   });
+* }
+* ```
+*/
+const NestedView = (props) => {
+	const routerLayer = use(RouterLayerContext);
+	const index = routerLayer?.index ?? 0;
+	const onError = routerLayer?.onError;
+	const state = useRouterState();
+	const alepha = useAlepha();
+	const [view, setView] = useState(state.layers[index]?.element);
+	const [animation, setAnimation] = useState("");
+	const animationExitDuration = useRef(0);
+	const animationExitNow = useRef(0);
+	useEvents({
+		"react:transition:begin": async ({ previous, state }) => {
+			const layer = previous.layers[index];
+			if (!layer) return;
+			if (`${state.url.pathname}/`.startsWith(`${layer.path}/`)) return;
+			const animationExit = parseAnimation(layer.route?.animation, state, "exit");
+			if (animationExit) {
+				const duration = animationExit.duration || 200;
+				animationExitNow.current = Date.now();
+				animationExitDuration.current = duration;
+				setAnimation(animationExit.animation);
+			} else {
+				animationExitNow.current = 0;
+				animationExitDuration.current = 0;
+				setAnimation("");
+			}
+		},
+		"react:transition:end": async ({ state }) => {
+			const layer = state.layers[index];
+			if (animationExitNow.current) {
+				const duration = animationExitDuration.current;
+				const diff = Date.now() - animationExitNow.current;
+				if (diff < duration) await new Promise((resolve) => setTimeout(resolve, duration - diff));
+			}
+			if (!layer?.cache) {
+				setView(layer?.element);
+				const animationEnter = parseAnimation(layer?.route?.animation, state, "enter");
+				if (animationEnter) setAnimation(animationEnter.animation);
+				else setAnimation("");
+			}
+		}
+	}, []);
+	let element = view ?? props.children ?? null;
+	if (animation) element = /* @__PURE__ */ jsx("div", {
+		style: {
+			display: "flex",
+			flex: 1,
+			height: "100%",
+			width: "100%",
+			position: "relative",
+			overflow: "hidden"
+		},
+		children: /* @__PURE__ */ jsx("div", {
+			style: {
+				height: "100%",
+				width: "100%",
+				display: "flex",
+				animation
+			},
+			children: element
+		})
+	});
+	if (props.errorBoundary === false) return /* @__PURE__ */ jsx(Fragment, { children: element });
+	if (props.errorBoundary) return /* @__PURE__ */ jsx(ErrorBoundary, {
+		fallback: props.errorBoundary,
+		children: element
+	});
+	const fallback = (error) => {
+		const result = onError?.(error, state) ?? /* @__PURE__ */ jsx(ErrorViewer_default, {
+			error,
+			alepha
+		});
+		if (result instanceof Redirection) return "Redirection inside ErrorBoundary is not allowed.";
+		return result;
+	};
+	return /* @__PURE__ */ jsx(ErrorBoundary, {
+		fallback,
+		children: element
+	});
+};
+var NestedView_default = memo(NestedView);
+function parseAnimation(animationLike, state, type = "enter") {
+	if (!animationLike) return;
+	const DEFAULT_DURATION = 300;
+	const animation = typeof animationLike === "function" ? animationLike(state) : animationLike;
+	if (typeof animation === "string") {
+		if (type === "exit") return;
+		return {
+			duration: DEFAULT_DURATION,
+			animation: `${DEFAULT_DURATION}ms ${animation}`
+		};
+	}
+	if (typeof animation === "object") {
+		const anim = animation[type];
+		const duration = typeof anim === "object" ? anim.duration ?? DEFAULT_DURATION : DEFAULT_DURATION;
+		const name = typeof anim === "object" ? anim.name : anim;
+		if (type === "exit") return {
+			duration,
+			animation: `${duration}ms ${typeof anim === "object" ? anim.timing ?? "" : ""} ${name}`
+		};
+		return {
+			duration,
+			animation: `${duration}ms ${typeof anim === "object" ? anim.timing ?? "" : ""} ${name}`
+		};
+	}
+}
+
+//#endregion
+//#region ../../src/react/router/components/NotFound.tsx
+/**
+* Default 404 Not Found page component.
+*/
+const NotFound = (props) => /* @__PURE__ */ jsxs("div", {
+	style: {
+		width: "100%",
+		minHeight: "90vh",
+		boxSizing: "border-box",
+		display: "flex",
+		flexDirection: "column",
+		justifyContent: "center",
+		alignItems: "center",
+		textAlign: "center",
+		fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
+		padding: "2rem",
+		...props.style
+	},
+	children: [/* @__PURE__ */ jsx("div", {
+		style: {
+			fontSize: "6rem",
+			fontWeight: 200,
+			lineHeight: 1
+		},
+		children: "404"
+	}), /* @__PURE__ */ jsx("div", {
+		style: {
+			fontSize: "0.875rem",
+			marginTop: "1rem",
+			opacity: .6
+		},
+		children: "Page not found"
+	})]
+});
+var NotFound_default = NotFound;
+
+//#endregion
+//#region ../../src/react/router/providers/ReactPageProvider.ts
+const envSchema$1 = t.object({ REACT_STRICT_MODE: t.boolean({ default: true }) });
+/**
+* Handle page routes for React applications. (Browser and Server)
+*/
+var ReactPageProvider = class {
+	log = $logger();
+	env = $env(envSchema$1);
+	alepha = $inject(Alepha);
+	pages = [];
+	getPages() {
+		return this.pages;
+	}
+	getConcretePages() {
+		const pages = [];
+		for (const page of this.pages) {
+			if (page.children && page.children.length > 0) continue;
+			const fullPath = this.pathname(page.name);
+			if (fullPath.includes(":") || fullPath.includes("*")) {
+				if (typeof page.static === "object") {
+					const entries = page.static.entries;
+					if (entries && entries.length > 0) for (const entry of entries) {
+						const params = entry.params;
+						const path = this.compile(page.path ?? "", params);
+						if (!path.includes(":") && !path.includes("*")) pages.push({
+							...page,
+							name: params[Object.keys(params)[0]],
+							staticName: page.name,
+							path,
+							...entry
+						});
+					}
+				}
+				continue;
+			}
+			pages.push(page);
+		}
+		return pages;
+	}
+	page(name) {
+		for (const page of this.pages) if (page.name === name) return page;
+		throw new AlephaError(`Page '${name}' not found`);
+	}
+	pathname(name, options = {}) {
+		const page = this.page(name);
+		if (!page) throw new AlephaError(`Page ${name} not found`);
+		let url = page.path ?? "";
+		let parent = page.parent;
+		while (parent) {
+			url = `${parent.path ?? ""}/${url}`;
+			parent = parent.parent;
+		}
+		url = this.compile(url, options.params ?? {});
+		if (options.query) {
+			const query = new URLSearchParams(options.query);
+			if (query.toString()) url += `?${query.toString()}`;
+		}
+		return url.replace(/\/\/+/g, "/") || "/";
+	}
+	url(name, options = {}) {
+		return new URL(this.pathname(name, options), options.host ?? `http://localhost`);
+	}
+	root(state) {
+		const root = createElement(AlephaContext.Provider, { value: this.alepha }, createElement(NestedView_default, {}, state.layers[0]?.element));
+		if (this.env.REACT_STRICT_MODE) return createElement(StrictMode, {}, root);
+		return root;
+	}
+	convertStringObjectToObject = (schema, value) => {
+		if (t.schema.isObject(schema) && typeof value === "object") {
+			for (const key in schema.properties) if (t.schema.isObject(schema.properties[key]) && typeof value[key] === "string") try {
+				value[key] = this.alepha.codec.decode(schema.properties[key], decodeURIComponent(value[key]));
+			} catch (e) {}
+		}
+		return value;
+	};
+	/**
+	* Create a new RouterState based on a given route and request.
+	* This method resolves the layers for the route, applying any query and params schemas defined in the route.
+	* It also handles errors and redirects.
+	*/
+	async createLayers(route, state, previous = []) {
+		let context = {};
+		const stack = [{ route }];
+		let parent = route.parent;
+		while (parent) {
+			stack.unshift({ route: parent });
+			parent = parent.parent;
+		}
+		let forceRefresh = false;
+		for (let i = 0; i < stack.length; i++) {
+			const it = stack[i];
+			const route = it.route;
+			const config = {};
+			try {
+				this.convertStringObjectToObject(route.schema?.query, state.query);
+				config.query = route.schema?.query ? this.alepha.codec.decode(route.schema.query, state.query) : {};
+			} catch (e) {
+				it.error = e;
+				break;
+			}
+			try {
+				config.params = route.schema?.params ? this.alepha.codec.decode(route.schema.params, state.params) : {};
+			} catch (e) {
+				it.error = e;
+				break;
+			}
+			it.config = { ...config };
+			if (previous?.[i] && !forceRefresh && previous[i].name === route.name) {
+				const url = (str) => str ? str.replace(/\/\/+/g, "/") : "/";
+				if (JSON.stringify({
+					part: url(previous[i].part),
+					params: previous[i].config?.params ?? {}
+				}) === JSON.stringify({
+					part: url(route.path),
+					params: config.params ?? {}
+				})) {
+					it.props = previous[i].props;
+					it.error = previous[i].error;
+					it.cache = true;
+					context = {
+						...context,
+						...it.props
+					};
+					continue;
+				}
+				forceRefresh = true;
+			}
+			if (!route.loader) continue;
+			try {
+				const args = Object.create(state);
+				Object.assign(args, config, context);
+				const props = await route.loader?.(args) ?? {};
+				it.props = { ...props };
+				context = {
+					...context,
+					...props
+				};
+			} catch (e) {
+				if (e instanceof Redirection) return { redirect: e.redirect };
+				this.log.error("Page loader has failed", e);
+				it.error = e;
+				break;
+			}
+		}
+		let acc = "";
+		for (let i = 0; i < stack.length; i++) {
+			const it = stack[i];
+			const props = it.props ?? {};
+			const params = { ...it.config?.params };
+			for (const key of Object.keys(params)) params[key] = String(params[key]);
+			acc += "/";
+			acc += it.route.path ? this.compile(it.route.path, params) : "";
+			const path = acc.replace(/\/+/, "/");
+			const localErrorHandler = this.getErrorHandler(it.route);
+			if (localErrorHandler) {
+				const onErrorParent = state.onError;
+				state.onError = (error, context) => {
+					const result = localErrorHandler(error, context);
+					if (result === void 0) return onErrorParent(error, context);
+					return result;
+				};
+			}
+			if (!it.error) try {
+				const element = await this.createElement(it.route, {
+					...it.route.props ? it.route.props() : {},
+					...props,
+					...context
+				});
+				state.layers.push({
+					name: it.route.name,
+					props,
+					part: it.route.path,
+					config: it.config,
+					element: this.renderView(i + 1, path, element, it.route),
+					index: i + 1,
+					path,
+					route: it.route,
+					cache: it.cache
+				});
+			} catch (e) {
+				it.error = e;
+			}
+			if (it.error) try {
+				let element = await state.onError(it.error, state);
+				if (element === void 0) throw it.error;
+				if (element instanceof Redirection) return { redirect: element.redirect };
+				if (element === null) element = this.renderError(it.error);
+				state.layers.push({
+					props,
+					error: it.error,
+					name: it.route.name,
+					part: it.route.path,
+					config: it.config,
+					element: this.renderView(i + 1, path, element, it.route),
+					index: i + 1,
+					path,
+					route: it.route
+				});
+				break;
+			} catch (e) {
+				if (e instanceof Redirection) return { redirect: e.redirect };
+				throw e;
+			}
+		}
+		return { state };
+	}
+	getErrorHandler(route) {
+		if (route.errorHandler) return route.errorHandler;
+		let parent = route.parent;
+		while (parent) {
+			if (parent.errorHandler) return parent.errorHandler;
+			parent = parent.parent;
+		}
+	}
+	async createElement(page, props) {
+		if (page.lazy && page.component) this.log.warn(`Page ${page.name} has both lazy and component options, lazy will be used`);
+		if (page.lazy) return createElement((await page.lazy()).default, props);
+		if (page.component) return createElement(page.component, props);
+	}
+	renderError(error) {
+		return createElement(ErrorViewer_default, {
+			error,
+			alepha: this.alepha
+		});
+	}
+	renderEmptyView() {
+		return createElement(NestedView_default, {});
+	}
+	href(page, params = {}) {
+		const found = this.pages.find((it) => it.name === page.options.name);
+		if (!found) throw new AlephaError(`Page ${page.options.name} not found`);
+		let url = found.path ?? "";
+		let parent = found.parent;
+		while (parent) {
+			url = `${parent.path ?? ""}/${url}`;
+			parent = parent.parent;
+		}
+		url = this.compile(url, params);
+		return url.replace(/\/\/+/g, "/") || "/";
+	}
+	compile(path, params = {}) {
+		for (const [key, value] of Object.entries(params)) path = path.replace(`:${key}`, value);
+		return path;
+	}
+	renderView(index, path, view, page) {
+		view ??= this.renderEmptyView();
+		const element = page.client ? createElement(ClientOnly, typeof page.client === "object" ? page.client : {}, view) : view;
+		return createElement(RouterLayerContext.Provider, { value: {
+			index,
+			path,
+			onError: this.getErrorHandler(page) ?? ((error) => this.renderError(error))
+		} }, element);
+	}
+	configure = $hook({
+		on: "configure",
+		handler: () => {
+			let hasNotFoundHandler = false;
+			const pages = this.alepha.primitives($page);
+			const hasParent = (it) => {
+				if (it.options.parent) return true;
+				for (const page of pages) if ((page.options.children ? Array.isArray(page.options.children) ? page.options.children : page.options.children() : []).includes(it)) return true;
+			};
+			for (const page of pages) {
+				if (page.options.path === "/*") hasNotFoundHandler = true;
+				if (hasParent(page)) continue;
+				this.add(this.map(pages, page));
+			}
+			if (!hasNotFoundHandler && pages.length > 0) this.add({
+				path: "/*",
+				name: "notFound",
+				cache: true,
+				component: NotFound_default,
+				onServerResponse: ({ reply }) => {
+					reply.status = 404;
+				}
+			});
+		}
+	});
+	map(pages, target) {
+		const children = target.options.children ? Array.isArray(target.options.children) ? target.options.children : target.options.children() : [];
+		const getChildrenFromParent = (it) => {
+			const children = [];
+			for (const page of pages) if (page.options.parent === it) children.push(page);
+			return children;
+		};
+		children.push(...getChildrenFromParent(target));
+		return {
+			...target.options,
+			name: target.name,
+			parent: void 0,
+			children: children.map((it) => this.map(pages, it))
+		};
+	}
+	add(entry) {
+		if (this.alepha.isReady()) throw new AlephaError("Router is already initialized");
+		entry.name ??= this.nextId();
+		const page = entry;
+		page.match = this.createMatch(page);
+		this.pages.push(page);
+		if (page.children) for (const child of page.children) {
+			child.parent = page;
+			this.add(child);
+		}
+	}
+	createMatch(page) {
+		let url = page.path ?? "/";
+		let target = page.parent;
+		while (target) {
+			url = `${target.path ?? ""}/${url}`;
+			target = target.parent;
+		}
+		let path = url.replace(/\/\/+/g, "/");
+		if (path.endsWith("/") && path !== "/") path = path.slice(0, -1);
+		return path;
+	}
+	_next = 0;
+	nextId() {
+		this._next += 1;
+		return `P${this._next}`;
+	}
+};
+const isPageRoute = (it) => {
+	return it && typeof it === "object" && typeof it.path === "string" && typeof it.page === "object";
+};
+
+//#endregion
+//#region ../../src/react/router/atoms/ssrManifestAtom.ts
+/**
+* Schema for the SSR manifest atom.
+*/
+const ssrManifestAtomSchema = t.object({
+	base: t.optional(t.string()),
+	preload: t.optional(t.record(t.string(), t.string())),
+	client: t.optional(t.record(t.string(), t.object({
+		file: t.string(),
+		isEntry: t.optional(t.boolean()),
+		imports: t.optional(t.array(t.string())),
+		css: t.optional(t.array(t.string()))
+	})))
+});
+/**
+* SSR Manifest atom containing all manifest data for SSR module preloading.
+*
+* This atom is populated at build time by embedding manifest data into the
+* generated index.js. This approach is optimal for serverless deployments
+* as it eliminates filesystem reads at runtime.
+*
+* The manifest includes:
+* - preload: Maps short hash keys to source paths (from viteAlephaSsrPreload)
+* - client: Maps source files to their output info (file, imports, css)
+*/
+const ssrManifestAtom = $atom({
+	name: "alepha.react.ssr.manifest",
+	description: "SSR manifest for module preloading",
+	schema: ssrManifestAtomSchema,
+	default: {}
+});
+
+//#endregion
+//#region ../../src/react/router/providers/SSRManifestProvider.ts
+/**
+* Provider for SSR manifest data used for module preloading.
+*
+* The manifest is populated at build time by embedding data into the
+* generated index.js via the ssrManifestAtom. This eliminates filesystem
+* reads at runtime, making it optimal for serverless deployments.
+*
+* Manifest files are generated during `vite build`:
+* - manifest.json (client manifest)
+* - preload-manifest.json (from viteAlephaSsrPreload plugin)
+*/
+var SSRManifestProvider = class {
+	alepha = $inject(Alepha);
+	/**
+	* Get the manifest from the store at runtime.
+	* This ensures the manifest is available even when set after module load.
+	*/
+	get manifest() {
+		return this.alepha.store.get(ssrManifestAtom) ?? {};
+	}
+	/**
+	* Get the base path for assets (from Vite's base config).
+	* Returns empty string if base is "/" (default), otherwise returns the base path.
+	*/
+	get base() {
+		return this.manifest.base ?? "";
+	}
+	/**
+	* Get the preload manifest.
+	*/
+	get preloadManifest() {
+		return this.manifest.preload;
+	}
+	/**
+	* Get the client manifest.
+	*/
+	get clientManifest() {
+		return this.manifest.client;
+	}
+	/**
+	* Resolve a preload key to its source path.
+	*
+	* The key is a short hash injected by viteAlephaSsrPreload plugin,
+	* which maps to the full source path in the preload manifest.
+	*
+	* @param key - Short hash key (e.g., "a1b2c3d4")
+	* @returns Source path (e.g., "src/pages/UserDetail.tsx") or undefined
+	*/
+	resolvePreloadKey(key) {
+		return this.preloadManifest?.[key];
+	}
+	/**
+	* Get all chunks required for a source file, including transitive dependencies.
+	*
+	* Uses the client manifest to recursively resolve all imported chunks.
+	*
+	* @param sourcePath - Source file path (e.g., "src/pages/Home.tsx")
+	* @returns Array of chunk URLs to preload, or empty array if not found
+	*/
+	getChunks(sourcePath) {
+		if (!this.clientManifest) return [];
+		if (!this.findManifestEntry(sourcePath)) return [];
+		const chunks = /* @__PURE__ */ new Set();
+		const visited = /* @__PURE__ */ new Set();
+		this.collectChunksRecursive(sourcePath, chunks, visited);
+		return Array.from(chunks);
+	}
+	/**
+	* Find manifest entry for a source path, trying different extensions.
+	*/
+	findManifestEntry(sourcePath) {
+		if (!this.clientManifest) return void 0;
+		if (this.clientManifest[sourcePath]) return this.clientManifest[sourcePath];
+		const basePath = sourcePath.replace(/\.[^.]+$/, "");
+		for (const ext of [
+			".tsx",
+			".ts",
+			".jsx",
+			".js"
+		]) {
+			const pathWithExt = basePath + ext;
+			if (this.clientManifest[pathWithExt]) return this.clientManifest[pathWithExt];
+		}
+	}
+	/**
+	* Recursively collect all chunk URLs for a manifest entry.
+	*/
+	collectChunksRecursive(key, chunks, visited) {
+		if (visited.has(key)) return;
+		visited.add(key);
+		if (!this.clientManifest) return;
+		const entry = this.clientManifest[key];
+		if (!entry) return;
+		const base = this.base;
+		if (entry.file) chunks.add(`${base}/${entry.file}`);
+		if (entry.css) for (const css of entry.css) chunks.add(`${base}/${css}`);
+		if (entry.imports) for (const imp of entry.imports) {
+			if (imp === "index.html" || imp.endsWith(".html")) continue;
+			this.collectChunksRecursive(imp, chunks, visited);
+		}
+	}
+	/**
+	* Collect modulepreload links for a route and its parent chain.
+	*/
+	collectPreloadLinks(route) {
+		if (!this.isAvailable()) return [];
+		const preloadPaths = [];
+		let current = route;
+		while (current) {
+			const preloadKey = current[PAGE_PRELOAD_KEY];
+			if (preloadKey) {
+				const sourcePath = this.resolvePreloadKey(preloadKey);
+				if (sourcePath) preloadPaths.push(sourcePath);
+			}
+			current = current.parent;
+		}
+		if (preloadPaths.length === 0) return [];
+		return this.getChunksForMultiple(preloadPaths).map((href) => {
+			if (href.endsWith(".css")) return {
+				rel: "preload",
+				href,
+				as: "style",
+				crossorigin: ""
+			};
+			return {
+				rel: "modulepreload",
+				href
+			};
+		});
+	}
+	/**
+	* Get all chunks for multiple source files.
+	*
+	* @param sourcePaths - Array of source file paths
+	* @returns Deduplicated array of chunk URLs
+	*/
+	getChunksForMultiple(sourcePaths) {
+		const allChunks = /* @__PURE__ */ new Set();
+		for (const path of sourcePaths) {
+			const chunks = this.getChunks(path);
+			for (const chunk of chunks) allChunks.add(chunk);
+		}
+		return Array.from(allChunks);
+	}
+	/**
+	* Check if manifest is loaded and available.
+	*/
+	isAvailable() {
+		return this.clientManifest !== void 0;
+	}
+	/**
+	* Cached entry assets - computed once at first access.
+	*/
+	cachedEntryAssets = null;
+	/**
+	* Get the entry point assets (main entry.js and associated CSS files).
+	*
+	* These assets are always required for all pages and can be preloaded
+	* before page-specific loaders run.
+	*
+	* @returns Entry assets with js and css paths, or null if manifest unavailable
+	*/
+	getEntryAssets() {
+		if (this.cachedEntryAssets) return this.cachedEntryAssets;
+		if (!this.clientManifest) return null;
+		const base = this.base;
+		for (const [key, entry] of Object.entries(this.clientManifest)) if (entry.isEntry) {
+			this.cachedEntryAssets = {
+				js: `${base}/${entry.file}`,
+				css: entry.css?.map((css) => `${base}/${css}`) ?? []
+			};
+			return this.cachedEntryAssets;
+		}
+		return null;
+	}
+	/**
+	* Build preload link tags for entry assets.
+	*
+	* @returns Array of link objects ready to be rendered
+	*/
+	getEntryPreloadLinks() {
+		const assets = this.getEntryAssets();
+		if (!assets) return [];
+		const links = [];
+		for (const css of assets.css) links.push({
+			rel: "stylesheet",
+			href: css,
+			crossorigin: ""
+		});
+		if (assets.js) links.push({
+			rel: "modulepreload",
+			href: assets.js
+		});
+		return links;
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/providers/ReactPreloadProvider.ts
+/**
+* Adds HTTP Link headers for preloading entry assets.
+*
+* Benefits:
+* - Early Hints (103): Servers can send preload hints before the full response
+* - CDN optimization: Many CDNs use Link headers to optimize asset delivery
+* - Browser prefetching: Browsers can start fetching resources earlier
+*
+* The Link header is computed once at first request and cached for reuse.
+*/
+var ReactPreloadProvider = class {
+	alepha = $inject(Alepha);
+	ssrManifest = $inject(SSRManifestProvider);
+	/**
+	* Cached Link header value - computed once, reused for all requests.
+	*/
+	cachedLinkHeader;
+	/**
+	* Build the Link header string from entry assets.
+	*
+	* Format: <url>; rel=preload; as=type, <url>; rel=modulepreload
+	*
+	* @returns Link header string or null if no assets
+	*/
+	buildLinkHeader() {
+		const assets = this.ssrManifest.getEntryAssets();
+		if (!assets) return null;
+		const links = [];
+		for (const css of assets.css) links.push(`<${css}>; rel=preload; as=style`);
+		if (assets.js) links.push(`<${assets.js}>; rel=modulepreload`);
+		return links.length > 0 ? links.join(", ") : null;
+	}
+	/**
+	* Get the cached Link header, computing it on first access.
+	*/
+	getLinkHeader() {
+		if (this.cachedLinkHeader === void 0) this.cachedLinkHeader = this.buildLinkHeader();
+		return this.cachedLinkHeader;
+	}
+	/**
+	* Add Link header to HTML responses for asset preloading.
+	*/
+	onResponse = $hook({
+		on: "server:onResponse",
+		priority: "first",
+		handler: ({ response }) => {
+			const contentType = response.headers["content-type"];
+			if (!contentType || !contentType.includes("text/html")) return;
+			const linkHeader = this.getLinkHeader();
+			if (!linkHeader) return;
+			if (response.headers.link) response.headers.link = `${response.headers.link}, ${linkHeader}`;
+			else response.headers.link = linkHeader;
+		}
+	});
+};
+
+//#endregion
+//#region ../../src/system/providers/FileSystemProvider.ts
+/**
+* FileSystem interface providing utilities for working with files.
+*/
+var FileSystemProvider = class {};
+
+//#endregion
+//#region ../../src/system/providers/MemoryFileSystemProvider.ts
+/**
+* In-memory implementation of FileSystemProvider for testing.
+*
+* This provider stores all files and directories in memory, making it ideal for
+* unit tests that need to verify file operations without touching the real file system.
+*
+* @example
+* ```typescript
+* // In tests, substitute the real FileSystemProvider with MemoryFileSystemProvider
+* const alepha = Alepha.create().with({
+*   provide: FileSystemProvider,
+*   use: MemoryFileSystemProvider,
+* });
+*
+* // Run code that uses FileSystemProvider
+* const service = alepha.inject(MyService);
+* await service.saveFile("test.txt", "Hello World");
+*
+* // Verify the file was written
+* const memoryFs = alepha.inject(MemoryFileSystemProvider);
+* expect(memoryFs.files.get("test.txt")?.toString()).toBe("Hello World");
+* ```
+*/
+var MemoryFileSystemProvider = class {
+	json = $inject(Json);
+	/**
+	* In-memory storage for files (path -> content)
+	*/
+	files = /* @__PURE__ */ new Map();
+	/**
+	* In-memory storage for directories
+	*/
+	directories = /* @__PURE__ */ new Set();
+	/**
+	* Track mkdir calls for test assertions
+	*/
+	mkdirCalls = [];
+	/**
+	* Track writeFile calls for test assertions
+	*/
+	writeFileCalls = [];
+	/**
+	* Track readFile calls for test assertions
+	*/
+	readFileCalls = [];
+	/**
+	* Track rm calls for test assertions
+	*/
+	rmCalls = [];
+	/**
+	* Track join calls for test assertions
+	*/
+	joinCalls = [];
+	/**
+	* Error to throw on mkdir (for testing error handling)
+	*/
+	mkdirError = null;
+	/**
+	* Error to throw on writeFile (for testing error handling)
+	*/
+	writeFileError = null;
+	/**
+	* Error to throw on readFile (for testing error handling)
+	*/
+	readFileError = null;
+	constructor(options = {}) {
+		this.mkdirError = options.mkdirError ?? null;
+		this.writeFileError = options.writeFileError ?? null;
+		this.readFileError = options.readFileError ?? null;
+	}
+	/**
+	* Join path segments using forward slashes.
+	* Uses Node's path.join for proper normalization (handles .. and .)
+	*/
+	join(...paths) {
+		this.joinCalls.push(paths);
+		return join(...paths);
+	}
+	/**
+	* Create a FileLike object from various sources.
+	*/
+	createFile(options) {
+		if ("path" in options) {
+			const filePath = options.path;
+			const buffer = this.files.get(filePath);
+			if (buffer === void 0) throw new Error(`ENOENT: no such file or directory, open '${filePath}'`);
+			return {
+				name: options.name ?? filePath.split("/").pop() ?? "file",
+				type: options.type ?? "application/octet-stream",
+				size: buffer.byteLength,
+				lastModified: Date.now(),
+				stream: () => {
+					throw new Error("Stream not implemented in MemoryFileSystemProvider");
+				},
+				arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+				text: async () => buffer.toString("utf-8")
+			};
+		}
+		if ("buffer" in options) {
+			const buffer = options.buffer;
+			return {
+				name: options.name ?? "file",
+				type: options.type ?? "application/octet-stream",
+				size: buffer.byteLength,
+				lastModified: Date.now(),
+				stream: () => {
+					throw new Error("Stream not implemented in MemoryFileSystemProvider");
+				},
+				arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+				text: async () => buffer.toString("utf-8")
+			};
+		}
+		if ("text" in options) {
+			const buffer = Buffer.from(options.text, "utf-8");
+			return {
+				name: options.name ?? "file.txt",
+				type: options.type ?? "text/plain",
+				size: buffer.byteLength,
+				lastModified: Date.now(),
+				stream: () => {
+					throw new Error("Stream not implemented in MemoryFileSystemProvider");
+				},
+				arrayBuffer: async () => buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+				text: async () => options.text
+			};
+		}
+		throw new Error("MemoryFileSystemProvider.createFile: unsupported options. Only buffer and text are supported.");
+	}
+	/**
+	* Remove a file or directory from memory.
+	*/
+	async rm(path, options) {
+		this.rmCalls.push({
+			path,
+			options
+		});
+		if (!(this.files.has(path) || this.directories.has(path)) && !options?.force) throw new Error(`ENOENT: no such file or directory, rm '${path}'`);
+		if (this.directories.has(path)) if (options?.recursive) {
+			this.directories.delete(path);
+			for (const filePath of this.files.keys()) if (filePath.startsWith(`${path}/`)) this.files.delete(filePath);
+			for (const dirPath of this.directories) if (dirPath.startsWith(`${path}/`)) this.directories.delete(dirPath);
+		} else throw new Error(`EISDIR: illegal operation on a directory, rm '${path}'`);
+		else this.files.delete(path);
+	}
+	/**
+	* Copy a file or directory in memory.
+	*/
+	async cp(src, dest, options) {
+		if (this.directories.has(src)) {
+			if (!options?.recursive) throw new Error(`Cannot copy directory without recursive option: ${src}`);
+			this.directories.add(dest);
+			for (const [filePath, content] of this.files) if (filePath.startsWith(`${src}/`)) {
+				const newPath = filePath.replace(src, dest);
+				this.files.set(newPath, Buffer.from(content));
+			}
+		} else if (this.files.has(src)) {
+			const content = this.files.get(src);
+			this.files.set(dest, Buffer.from(content));
+		} else throw new Error(`ENOENT: no such file or directory, cp '${src}'`);
+	}
+	/**
+	* Move/rename a file or directory in memory.
+	*/
+	async mv(src, dest) {
+		if (this.directories.has(src)) {
+			this.directories.delete(src);
+			this.directories.add(dest);
+			for (const [filePath, content] of this.files) if (filePath.startsWith(`${src}/`)) {
+				const newPath = filePath.replace(src, dest);
+				this.files.delete(filePath);
+				this.files.set(newPath, content);
+			}
+		} else if (this.files.has(src)) {
+			const content = this.files.get(src);
+			this.files.delete(src);
+			this.files.set(dest, content);
+		} else throw new Error(`ENOENT: no such file or directory, mv '${src}'`);
+	}
+	/**
+	* Create a directory in memory.
+	*/
+	async mkdir(path, options) {
+		this.mkdirCalls.push({
+			path,
+			options
+		});
+		if (this.mkdirError) throw this.mkdirError;
+		if (this.directories.has(path) && !options?.recursive) throw new Error(`EEXIST: file already exists, mkdir '${path}'`);
+		this.directories.add(path);
+		if (options?.recursive) {
+			const parts = path.split("/").filter(Boolean);
+			let current = "";
+			for (const part of parts) {
+				current = current ? `${current}/${part}` : part;
+				this.directories.add(current);
+			}
+		}
+	}
+	/**
+	* List files in a directory.
+	*/
+	async ls(path, options) {
+		const normalizedPath = path.replace(/\/$/, "");
+		const entries = /* @__PURE__ */ new Set();
+		for (const filePath of this.files.keys()) if (filePath.startsWith(`${normalizedPath}/`)) {
+			const relativePath = filePath.slice(normalizedPath.length + 1);
+			const parts = relativePath.split("/");
+			if (options?.recursive) entries.add(relativePath);
+			else entries.add(parts[0]);
+		}
+		for (const dirPath of this.directories) if (dirPath.startsWith(`${normalizedPath}/`) && dirPath !== normalizedPath) {
+			const relativePath = dirPath.slice(normalizedPath.length + 1);
+			const parts = relativePath.split("/");
+			if (options?.recursive) entries.add(relativePath);
+			else if (parts.length === 1) entries.add(parts[0]);
+		}
+		let result = Array.from(entries);
+		if (!options?.hidden) result = result.filter((entry) => !entry.startsWith("."));
+		return result.sort();
+	}
+	/**
+	* Check if a file or directory exists in memory.
+	*/
+	async exists(path) {
+		return this.files.has(path) || this.directories.has(path);
+	}
+	/**
+	* Read a file from memory.
+	*/
+	async readFile(path) {
+		this.readFileCalls.push(path);
+		if (this.readFileError) throw this.readFileError;
+		const content = this.files.get(path);
+		if (!content) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+		return content;
+	}
+	/**
+	* Read a file from memory as text.
+	*/
+	async readTextFile(path) {
+		return (await this.readFile(path)).toString("utf-8");
+	}
+	/**
+	* Read a file from memory as JSON.
+	*/
+	async readJsonFile(path) {
+		const text = await this.readTextFile(path);
+		return this.json.parse(text);
+	}
+	/**
+	* Write a file to memory.
+	*/
+	async writeFile(path, data) {
+		const dataStr = typeof data === "string" ? data : data instanceof Buffer || data instanceof Uint8Array ? data.toString("utf-8") : await data.text();
+		this.writeFileCalls.push({
+			path,
+			data: dataStr
+		});
+		if (this.writeFileError) throw this.writeFileError;
+		const buffer = typeof data === "string" ? Buffer.from(data, "utf-8") : data instanceof Buffer ? data : data instanceof Uint8Array ? Buffer.from(data) : Buffer.from(await data.text(), "utf-8");
+		this.files.set(path, buffer);
+	}
+	/**
+	* Reset all in-memory state (useful between tests).
+	*/
+	reset() {
+		this.files.clear();
+		this.directories.clear();
+		this.mkdirCalls = [];
+		this.writeFileCalls = [];
+		this.readFileCalls = [];
+		this.rmCalls = [];
+		this.joinCalls = [];
+		this.mkdirError = null;
+		this.writeFileError = null;
+		this.readFileError = null;
+	}
+	/**
+	* Check if a file was written during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasWritten("/project/tsconfig.json")).toBe(true);
+	* ```
+	*/
+	wasWritten(path) {
+		return this.writeFileCalls.some((call) => call.path === path);
+	}
+	/**
+	* Check if a file was written with content matching a pattern.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasWrittenMatching("/project/tsconfig.json", /extends/)).toBe(true);
+	* ```
+	*/
+	wasWrittenMatching(path, pattern) {
+		const call = this.writeFileCalls.find((c) => c.path === path);
+		return call ? pattern.test(call.data) : false;
+	}
+	/**
+	* Check if a file was read during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasRead("/project/package.json")).toBe(true);
+	* ```
+	*/
+	wasRead(path) {
+		return this.readFileCalls.includes(path);
+	}
+	/**
+	* Check if a file was deleted during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(fs.wasDeleted("/project/old-file.txt")).toBe(true);
+	* ```
+	*/
+	wasDeleted(path) {
+		return this.rmCalls.some((call) => call.path === path);
+	}
+	/**
+	* Get the content of a file as a string (convenience method for testing).
+	*/
+	getFileContent(path) {
+		return this.files.get(path)?.toString("utf-8");
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/MemoryShellProvider.ts
+/**
+* In-memory implementation of ShellProvider for testing.
+*
+* Records all commands that would be executed without actually running them.
+* Can be configured to return specific outputs or throw errors for testing.
+*
+* @example
+* ```typescript
+* // In tests, substitute the real ShellProvider with MemoryShellProvider
+* const alepha = Alepha.create().with({
+*   provide: ShellProvider,
+*   use: MemoryShellProvider,
+* });
+*
+* // Configure mock behavior
+* const shell = alepha.inject(MemoryShellProvider);
+* shell.configure({
+*   outputs: { "echo hello": "hello\n" },
+*   errors: { "failing-cmd": "Command failed" },
+* });
+*
+* // Or use the fluent API
+* shell.outputs.set("another-cmd", "output");
+* shell.errors.set("another-error", "Error message");
+*
+* // Run code that uses ShellProvider
+* const service = alepha.inject(MyService);
+* await service.doSomething();
+*
+* // Verify commands were called
+* expect(shell.calls).toHaveLength(2);
+* expect(shell.calls[0].command).toBe("yarn install");
+* ```
+*/
+var MemoryShellProvider = class {
+	/**
+	* All recorded shell calls.
+	*/
+	calls = [];
+	/**
+	* Simulated outputs for specific commands.
+	*/
+	outputs = /* @__PURE__ */ new Map();
+	/**
+	* Commands that should throw an error.
+	*/
+	errors = /* @__PURE__ */ new Map();
+	/**
+	* Commands considered installed in the system PATH.
+	*/
+	installedCommands = /* @__PURE__ */ new Set();
+	/**
+	* Configure the mock with predefined outputs, errors, and installed commands.
+	*/
+	configure(options) {
+		if (options.outputs) for (const [cmd, output] of Object.entries(options.outputs)) this.outputs.set(cmd, output);
+		if (options.errors) for (const [cmd, error] of Object.entries(options.errors)) this.errors.set(cmd, error);
+		if (options.installedCommands) for (const cmd of options.installedCommands) this.installedCommands.add(cmd);
+		return this;
+	}
+	/**
+	* Record command and return simulated output.
+	*/
+	async run(command, options = {}) {
+		this.calls.push({
+			command,
+			options
+		});
+		const errorMsg = this.errors.get(command);
+		if (errorMsg) throw new Error(errorMsg);
+		return this.outputs.get(command) ?? "";
+	}
+	/**
+	* Check if a specific command was called.
+	*/
+	wasCalled(command) {
+		return this.calls.some((call) => call.command === command);
+	}
+	/**
+	* Check if a command matching a pattern was called.
+	*/
+	wasCalledMatching(pattern) {
+		return this.calls.some((call) => pattern.test(call.command));
+	}
+	/**
+	* Get all calls matching a pattern.
+	*/
+	getCallsMatching(pattern) {
+		return this.calls.filter((call) => pattern.test(call.command));
+	}
+	/**
+	* Check if a command is installed.
+	*/
+	async isInstalled(command) {
+		return this.installedCommands.has(command);
+	}
+	/**
+	* Reset all recorded state.
+	*/
+	reset() {
+		this.calls = [];
+		this.outputs.clear();
+		this.errors.clear();
+		this.installedCommands.clear();
+	}
+};
+
+//#endregion
+//#region ../../src/system/services/FileDetector.ts
+/**
+* Service for detecting file types and getting content types.
+*
+* @example
+* ```typescript
+* const detector = alepha.inject(FileDetector);
+*
+* // Get content type from filename
+* const mimeType = detector.getContentType("image.png"); // "image/png"
+*
+* // Detect file type by magic bytes
+* const stream = createReadStream('image.png');
+* const result = await detector.detectFileType(stream, 'image.png');
+* console.log(result.mimeType); // 'image/png'
+* console.log(result.verified); // true if magic bytes match
+* ```
+*/
+var FileDetector = class FileDetector {
+	/**
+	* Magic byte signatures for common file formats.
+	* Each signature is represented as an array of bytes or null (wildcard).
+	*/
+	static MAGIC_BYTES = {
+		png: [{
+			signature: [
+				137,
+				80,
+				78,
+				71,
+				13,
+				10,
+				26,
+				10
+			],
+			mimeType: "image/png"
+		}],
+		jpg: [
+			{
+				signature: [
+					255,
+					216,
+					255,
+					224
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					225
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					226
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					227
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					232
+				],
+				mimeType: "image/jpeg"
+			}
+		],
+		jpeg: [
+			{
+				signature: [
+					255,
+					216,
+					255,
+					224
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					225
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					226
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					227
+				],
+				mimeType: "image/jpeg"
+			},
+			{
+				signature: [
+					255,
+					216,
+					255,
+					232
+				],
+				mimeType: "image/jpeg"
+			}
+		],
+		gif: [{
+			signature: [
+				71,
+				73,
+				70,
+				56,
+				55,
+				97
+			],
+			mimeType: "image/gif"
+		}, {
+			signature: [
+				71,
+				73,
+				70,
+				56,
+				57,
+				97
+			],
+			mimeType: "image/gif"
+		}],
+		webp: [{
+			signature: [
+				82,
+				73,
+				70,
+				70,
+				null,
+				null,
+				null,
+				null,
+				87,
+				69,
+				66,
+				80
+			],
+			mimeType: "image/webp"
+		}],
+		bmp: [{
+			signature: [66, 77],
+			mimeType: "image/bmp"
+		}],
+		ico: [{
+			signature: [
+				0,
+				0,
+				1,
+				0
+			],
+			mimeType: "image/x-icon"
+		}],
+		tiff: [{
+			signature: [
+				73,
+				73,
+				42,
+				0
+			],
+			mimeType: "image/tiff"
+		}, {
+			signature: [
+				77,
+				77,
+				0,
+				42
+			],
+			mimeType: "image/tiff"
+		}],
+		tif: [{
+			signature: [
+				73,
+				73,
+				42,
+				0
+			],
+			mimeType: "image/tiff"
+		}, {
+			signature: [
+				77,
+				77,
+				0,
+				42
+			],
+			mimeType: "image/tiff"
+		}],
+		pdf: [{
+			signature: [
+				37,
+				80,
+				68,
+				70,
+				45
+			],
+			mimeType: "application/pdf"
+		}],
+		zip: [
+			{
+				signature: [
+					80,
+					75,
+					3,
+					4
+				],
+				mimeType: "application/zip"
+			},
+			{
+				signature: [
+					80,
+					75,
+					5,
+					6
+				],
+				mimeType: "application/zip"
+			},
+			{
+				signature: [
+					80,
+					75,
+					7,
+					8
+				],
+				mimeType: "application/zip"
+			}
+		],
+		rar: [{
+			signature: [
+				82,
+				97,
+				114,
+				33,
+				26,
+				7
+			],
+			mimeType: "application/vnd.rar"
+		}],
+		"7z": [{
+			signature: [
+				55,
+				122,
+				188,
+				175,
+				39,
+				28
+			],
+			mimeType: "application/x-7z-compressed"
+		}],
+		tar: [{
+			signature: [
+				117,
+				115,
+				116,
+				97,
+				114
+			],
+			mimeType: "application/x-tar"
+		}],
+		gz: [{
+			signature: [31, 139],
+			mimeType: "application/gzip"
+		}],
+		tgz: [{
+			signature: [31, 139],
+			mimeType: "application/gzip"
+		}],
+		mp3: [
+			{
+				signature: [255, 251],
+				mimeType: "audio/mpeg"
+			},
+			{
+				signature: [255, 243],
+				mimeType: "audio/mpeg"
+			},
+			{
+				signature: [255, 242],
+				mimeType: "audio/mpeg"
+			},
+			{
+				signature: [
+					73,
+					68,
+					51
+				],
+				mimeType: "audio/mpeg"
+			}
+		],
+		wav: [{
+			signature: [
+				82,
+				73,
+				70,
+				70,
+				null,
+				null,
+				null,
+				null,
+				87,
+				65,
+				86,
+				69
+			],
+			mimeType: "audio/wav"
+		}],
+		ogg: [{
+			signature: [
+				79,
+				103,
+				103,
+				83
+			],
+			mimeType: "audio/ogg"
+		}],
+		flac: [{
+			signature: [
+				102,
+				76,
+				97,
+				67
+			],
+			mimeType: "audio/flac"
+		}],
+		mp4: [
+			{
+				signature: [
+					null,
+					null,
+					null,
+					null,
+					102,
+					116,
+					121,
+					112
+				],
+				mimeType: "video/mp4"
+			},
+			{
+				signature: [
+					null,
+					null,
+					null,
+					null,
+					102,
+					116,
+					121,
+					112,
+					105,
+					115,
+					111,
+					109
+				],
+				mimeType: "video/mp4"
+			},
+			{
+				signature: [
+					null,
+					null,
+					null,
+					null,
+					102,
+					116,
+					121,
+					112,
+					109,
+					112,
+					52,
+					50
+				],
+				mimeType: "video/mp4"
+			}
+		],
+		webm: [{
+			signature: [
+				26,
+				69,
+				223,
+				163
+			],
+			mimeType: "video/webm"
+		}],
+		avi: [{
+			signature: [
+				82,
+				73,
+				70,
+				70,
+				null,
+				null,
+				null,
+				null,
+				65,
+				86,
+				73,
+				32
+			],
+			mimeType: "video/x-msvideo"
+		}],
+		mov: [{
+			signature: [
+				null,
+				null,
+				null,
+				null,
+				102,
+				116,
+				121,
+				112,
+				113,
+				116,
+				32,
+				32
+			],
+			mimeType: "video/quicktime"
+		}],
+		mkv: [{
+			signature: [
+				26,
+				69,
+				223,
+				163
+			],
+			mimeType: "video/x-matroska"
+		}],
+		docx: [{
+			signature: [
+				80,
+				75,
+				3,
+				4
+			],
+			mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+		}],
+		xlsx: [{
+			signature: [
+				80,
+				75,
+				3,
+				4
+			],
+			mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+		}],
+		pptx: [{
+			signature: [
+				80,
+				75,
+				3,
+				4
+			],
+			mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+		}],
+		doc: [{
+			signature: [
+				208,
+				207,
+				17,
+				224,
+				161,
+				177,
+				26,
+				225
+			],
+			mimeType: "application/msword"
+		}],
+		xls: [{
+			signature: [
+				208,
+				207,
+				17,
+				224,
+				161,
+				177,
+				26,
+				225
+			],
+			mimeType: "application/vnd.ms-excel"
+		}],
+		ppt: [{
+			signature: [
+				208,
+				207,
+				17,
+				224,
+				161,
+				177,
+				26,
+				225
+			],
+			mimeType: "application/vnd.ms-powerpoint"
+		}]
+	};
+	/**
+	* All possible format signatures for checking against actual file content
+	*/
+	static ALL_SIGNATURES = Object.entries(FileDetector.MAGIC_BYTES).flatMap(([ext, signatures]) => signatures.map((sig) => ({
+		ext,
+		...sig
+	})));
+	/**
+	* MIME type map for file extensions.
+	*
+	* Can be used to get the content type of file based on its extension.
+	* Feel free to add more mime types in your project!
+	*/
+	static mimeMap = {
+		json: "application/json",
+		txt: "text/plain",
+		html: "text/html",
+		htm: "text/html",
+		xml: "application/xml",
+		csv: "text/csv",
+		pdf: "application/pdf",
+		md: "text/markdown",
+		markdown: "text/markdown",
+		rtf: "application/rtf",
+		css: "text/css",
+		js: "application/javascript",
+		mjs: "application/javascript",
+		ts: "application/typescript",
+		jsx: "text/jsx",
+		tsx: "text/tsx",
+		zip: "application/zip",
+		rar: "application/vnd.rar",
+		"7z": "application/x-7z-compressed",
+		tar: "application/x-tar",
+		gz: "application/gzip",
+		tgz: "application/gzip",
+		png: "image/png",
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		gif: "image/gif",
+		webp: "image/webp",
+		svg: "image/svg+xml",
+		bmp: "image/bmp",
+		ico: "image/x-icon",
+		tiff: "image/tiff",
+		tif: "image/tiff",
+		mp3: "audio/mpeg",
+		wav: "audio/wav",
+		ogg: "audio/ogg",
+		m4a: "audio/mp4",
+		aac: "audio/aac",
+		flac: "audio/flac",
+		mp4: "video/mp4",
+		webm: "video/webm",
+		avi: "video/x-msvideo",
+		mov: "video/quicktime",
+		wmv: "video/x-ms-wmv",
+		flv: "video/x-flv",
+		mkv: "video/x-matroska",
+		doc: "application/msword",
+		docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+		xls: "application/vnd.ms-excel",
+		xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		ppt: "application/vnd.ms-powerpoint",
+		pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+		woff: "font/woff",
+		woff2: "font/woff2",
+		ttf: "font/ttf",
+		otf: "font/otf",
+		eot: "application/vnd.ms-fontobject"
+	};
+	/**
+	* Reverse MIME type map for looking up extensions from MIME types.
+	* Prefers shorter, more common extensions when multiple exist.
+	*/
+	static reverseMimeMap = (() => {
+		const reverse = {};
+		for (const [ext, mimeType] of Object.entries(FileDetector.mimeMap)) if (!reverse[mimeType]) reverse[mimeType] = ext;
+		return reverse;
+	})();
+	/**
+	* Returns the file extension for a given MIME type.
+	*
+	* @param mimeType - The MIME type to look up
+	* @returns The file extension (without dot), or "bin" if not found
+	*
+	* @example
+	* ```typescript
+	* const detector = alepha.inject(FileDetector);
+	* const ext = detector.getExtensionFromMimeType("image/png"); // "png"
+	* const ext2 = detector.getExtensionFromMimeType("application/octet-stream"); // "bin"
+	* ```
+	*/
+	getExtensionFromMimeType(mimeType) {
+		return FileDetector.reverseMimeMap[mimeType] || "bin";
+	}
+	/**
+	* Returns the content type of file based on its filename.
+	*
+	* @param filename - The filename to check
+	* @returns The MIME type
+	*
+	* @example
+	* ```typescript
+	* const detector = alepha.inject(FileDetector);
+	* const mimeType = detector.getContentType("image.png"); // "image/png"
+	* ```
+	*/
+	getContentType(filename) {
+		const ext = filename.toLowerCase().split(".").pop() || "";
+		return FileDetector.mimeMap[ext] || "application/octet-stream";
+	}
+	/**
+	* Detects the file type by checking magic bytes against the stream content.
+	*
+	* @param stream - The readable stream to check
+	* @param filename - The filename (used to get the extension)
+	* @returns File type information including MIME type, extension, and verification status
+	*
+	* @example
+	* ```typescript
+	* const detector = alepha.inject(FileDetector);
+	* const stream = createReadStream('image.png');
+	* const result = await detector.detectFileType(stream, 'image.png');
+	* console.log(result.mimeType); // 'image/png'
+	* console.log(result.verified); // true if magic bytes match
+	* ```
+	*/
+	async detectFileType(stream, filename) {
+		const expectedMimeType = this.getContentType(filename);
+		const lastDotIndex = filename.lastIndexOf(".");
+		const ext = lastDotIndex > 0 ? filename.substring(lastDotIndex + 1).toLowerCase() : "";
+		const { buffer, stream: newStream } = await this.peekBytes(stream, 16);
+		const expectedSignatures = FileDetector.MAGIC_BYTES[ext];
+		if (expectedSignatures) {
+			for (const { signature, mimeType } of expectedSignatures) if (this.matchesSignature(buffer, signature)) return {
+				mimeType,
+				extension: ext,
+				verified: true,
+				stream: newStream
+			};
+		}
+		for (const { ext: detectedExt, signature, mimeType } of FileDetector.ALL_SIGNATURES) if (detectedExt !== ext && this.matchesSignature(buffer, signature)) return {
+			mimeType,
+			extension: detectedExt,
+			verified: true,
+			stream: newStream
+		};
+		return {
+			mimeType: expectedMimeType,
+			extension: ext,
+			verified: false,
+			stream: newStream
+		};
+	}
+	/**
+	* Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.
+	* This approach reads the entire stream upfront to avoid complex async handling issues.
+	*
+	* @protected
+	*/
+	async peekBytes(stream, numBytes) {
+		const chunks = [];
+		for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		const allData = Buffer.concat(chunks);
+		return {
+			buffer: allData.subarray(0, numBytes),
+			stream: Readable.from(allData)
+		};
+	}
+	/**
+	* Checks if a buffer matches a magic byte signature.
+	*
+	* @protected
+	*/
+	matchesSignature(buffer, signature) {
+		if (buffer.length < signature.length) return false;
+		for (let i = 0; i < signature.length; i++) if (signature[i] !== null && buffer[i] !== signature[i]) return false;
+		return true;
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/NodeFileSystemProvider.ts
+/**
+* Node.js implementation of FileSystem interface.
+*
+* @example
+* ```typescript
+* const fs = alepha.inject(NodeFileSystemProvider);
+*
+* // Create from URL
+* const file1 = fs.createFile({ url: "file:///path/to/file.png" });
+*
+* // Create from Buffer
+* const file2 = fs.createFile({ buffer: Buffer.from("hello"), name: "hello.txt" });
+*
+* // Create from text
+* const file3 = fs.createFile({ text: "Hello, world!", name: "greeting.txt" });
+*
+* // File operations
+* await fs.mkdir("/tmp/mydir", { recursive: true });
+* await fs.cp("/src/file.txt", "/dest/file.txt");
+* await fs.mv("/old/path.txt", "/new/path.txt");
+* const files = await fs.ls("/tmp");
+* await fs.rm("/tmp/file.txt");
+* ```
+*/
+var NodeFileSystemProvider = class {
+	detector = $inject(FileDetector);
+	json = $inject(Json);
+	join(...paths) {
+		return join(...paths);
+	}
+	/**
+	* Creates a FileLike object from various sources.
+	*
+	* @param options - Options for creating the file
+	* @returns A FileLike object
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // From URL
+	* const file1 = fs.createFile({ url: "https://example.com/image.png" });
+	*
+	* // From Buffer
+	* const file2 = fs.createFile({
+	*   buffer: Buffer.from("hello"),
+	*   name: "hello.txt",
+	*   type: "text/plain"
+	* });
+	*
+	* // From text
+	* const file3 = fs.createFile({ text: "Hello!", name: "greeting.txt" });
+	*
+	* // From stream with detection
+	* const stream = createReadStream("/path/to/file.png");
+	* const file4 = fs.createFile({ stream, name: "image.png" });
+	* ```
+	*/
+	createFile(options) {
+		if ("path" in options) {
+			const path = options.path;
+			const filename = path.split("/").pop() || "file";
+			return this.createFileFromUrl(`file://${path}`, {
+				type: options.type,
+				name: options.name || filename
+			});
+		}
+		if ("url" in options) return this.createFileFromUrl(options.url, {
+			type: options.type,
+			name: options.name
+		});
+		if ("response" in options) {
+			if (!options.response.body) throw new AlephaError("Response has no body stream");
+			const res = options.response;
+			const sizeHeader = res.headers.get("content-length");
+			const size = sizeHeader ? parseInt(sizeHeader, 10) : void 0;
+			let name = options.name;
+			const contentDisposition = res.headers.get("content-disposition");
+			if (contentDisposition && !name) {
+				const match = contentDisposition.match(/filename="?([^"]+)"?/);
+				if (match) name = match[1];
+			}
+			const type = options.type || res.headers.get("content-type") || void 0;
+			return this.createFileFromStream(options.response.body, {
+				type,
+				name,
+				size
+			});
+		}
+		if ("file" in options) return this.createFileFromWebFile(options.file, {
+			type: options.type,
+			name: options.name,
+			size: options.size
+		});
+		if ("buffer" in options) return this.createFileFromBuffer(options.buffer, {
+			type: options.type,
+			name: options.name
+		});
+		if ("arrayBuffer" in options) return this.createFileFromBuffer(Buffer.from(options.arrayBuffer), {
+			type: options.type,
+			name: options.name
+		});
+		if ("text" in options) return this.createFileFromBuffer(Buffer.from(options.text, "utf-8"), {
+			type: options.type || "text/plain",
+			name: options.name || "file.txt"
+		});
+		if ("stream" in options) return this.createFileFromStream(options.stream, {
+			type: options.type,
+			name: options.name,
+			size: options.size
+		});
+		throw new AlephaError("Invalid createFile options: no valid source provided");
+	}
+	/**
+	* Removes a file or directory.
+	*
+	* @param path - The path to remove
+	* @param options - Remove options
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Remove a file
+	* await fs.rm("/tmp/file.txt");
+	*
+	* // Remove a directory recursively
+	* await fs.rm("/tmp/mydir", { recursive: true });
+	*
+	* // Remove with force (no error if doesn't exist)
+	* await fs.rm("/tmp/maybe-exists.txt", { force: true });
+	* ```
+	*/
+	async rm(path, options) {
+		await rm(path, options);
+	}
+	/**
+	* Copies a file or directory.
+	*
+	* @param src - Source path
+	* @param dest - Destination path
+	* @param options - Copy options
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Copy a file
+	* await fs.cp("/src/file.txt", "/dest/file.txt");
+	*
+	* // Copy a directory recursively
+	* await fs.cp("/src/dir", "/dest/dir", { recursive: true });
+	*
+	* // Copy with force (overwrite existing)
+	* await fs.cp("/src/file.txt", "/dest/file.txt", { force: true });
+	* ```
+	*/
+	async cp(src, dest, options) {
+		if ((await stat(src)).isDirectory()) {
+			if (!options?.recursive) throw new Error(`Cannot copy directory without recursive option: ${src}`);
+			await cp(src, dest, {
+				recursive: true,
+				force: options?.force ?? false
+			});
+		} else await copyFile(src, dest);
+	}
+	/**
+	* Moves/renames a file or directory.
+	*
+	* @param src - Source path
+	* @param dest - Destination path
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Move/rename a file
+	* await fs.mv("/old/path.txt", "/new/path.txt");
+	*
+	* // Move a directory
+	* await fs.mv("/old/dir", "/new/dir");
+	* ```
+	*/
+	async mv(src, dest) {
+		await rename(src, dest);
+	}
+	/**
+	* Creates a directory.
+	*
+	* @param path - The directory path to create
+	* @param options - Mkdir options
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Create a directory
+	* await fs.mkdir("/tmp/mydir");
+	*
+	* // Create nested directories
+	* await fs.mkdir("/tmp/path/to/dir", { recursive: true });
+	*
+	* // Create with specific permissions
+	* await fs.mkdir("/tmp/mydir", { mode: 0o755 });
+	* ```
+	*/
+	async mkdir(path, options = {}) {
+		const p = mkdir(path, {
+			recursive: options.recursive ?? true,
+			mode: options.mode
+		});
+		if (options.force === false) await p;
+		else await p.catch(() => {});
+	}
+	/**
+	* Lists files in a directory.
+	*
+	* @param path - The directory path to list
+	* @param options - List options
+	* @returns Array of filenames
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // List files in a directory
+	* const files = await fs.ls("/tmp");
+	* console.log(files); // ["file1.txt", "file2.txt", "subdir"]
+	*
+	* // List with hidden files
+	* const allFiles = await fs.ls("/tmp", { hidden: true });
+	*
+	* // List recursively
+	* const allFilesRecursive = await fs.ls("/tmp", { recursive: true });
+	* ```
+	*/
+	async ls(path, options) {
+		const entries = await readdir(path);
+		const filteredEntries = options?.hidden ? entries : entries.filter((e) => !e.startsWith("."));
+		if (options?.recursive) {
+			const allFiles = [];
+			for (const entry of filteredEntries) {
+				const fullPath = join(path, entry);
+				if ((await stat(fullPath)).isDirectory()) {
+					allFiles.push(entry);
+					const subFiles = await this.ls(fullPath, options);
+					allFiles.push(...subFiles.map((f) => join(entry, f)));
+				} else allFiles.push(entry);
+			}
+			return allFiles;
+		}
+		return filteredEntries;
+	}
+	/**
+	* Checks if a file or directory exists.
+	*
+	* @param path - The path to check
+	* @returns True if the path exists, false otherwise
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* if (await fs.exists("/tmp/file.txt")) {
+	*   console.log("File exists");
+	* }
+	* ```
+	*/
+	async exists(path) {
+		try {
+			await access(path);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Reads the content of a file.
+	*
+	* @param path - The file path to read
+	* @returns The file content as a Buffer
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* const buffer = await fs.readFile("/tmp/file.txt");
+	* console.log(buffer.toString("utf-8"));
+	* ```
+	*/
+	async readFile(path) {
+		return await readFile(path);
+	}
+	/**
+	* Writes data to a file.
+	*
+	* @param path - The file path to write to
+	* @param data - The data to write (Buffer or string)
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	*
+	* // Write string
+	* await fs.writeFile("/tmp/file.txt", "Hello, world!");
+	*
+	* // Write Buffer
+	* await fs.writeFile("/tmp/file.bin", Buffer.from([0x01, 0x02, 0x03]));
+	* ```
+	*/
+	async writeFile(path, data) {
+		if (isFileLike(data)) {
+			await writeFile(path, Readable.from(data.stream()));
+			return;
+		}
+		await writeFile(path, data);
+	}
+	/**
+	* Reads the content of a file as a string.
+	*
+	* @param path - The file path to read
+	* @returns The file content as a string
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	* const content = await fs.readTextFile("/tmp/file.txt");
+	* ```
+	*/
+	async readTextFile(path) {
+		return (await this.readFile(path)).toString("utf-8");
+	}
+	/**
+	* Reads the content of a file as JSON.
+	*
+	* @param path - The file path to read
+	* @returns The parsed JSON content
+	*
+	* @example
+	* ```typescript
+	* const fs = alepha.inject(NodeFileSystemProvider);
+	* const config = await fs.readJsonFile<{ name: string }>("/tmp/config.json");
+	* ```
+	*/
+	async readJsonFile(path) {
+		const text = await this.readTextFile(path);
+		return this.json.parse(text);
+	}
+	/**
+	* Creates a FileLike object from a Web File.
+	*
+	* @protected
+	*/
+	createFileFromWebFile(source, options = {}) {
+		const name = options.name ?? source.name;
+		return {
+			name,
+			type: options.type ?? (source.type || this.detector.getContentType(name)),
+			size: options.size ?? source.size ?? 0,
+			lastModified: source.lastModified || Date.now(),
+			stream: () => source.stream(),
+			arrayBuffer: async () => {
+				return await source.arrayBuffer();
+			},
+			text: async () => {
+				return await source.text();
+			}
+		};
+	}
+	/**
+	* Creates a FileLike object from a Buffer.
+	*
+	* @protected
+	*/
+	createFileFromBuffer(source, options = {}) {
+		const name = options.name ?? "file";
+		return {
+			name,
+			type: options.type ?? this.detector.getContentType(options.name ?? name),
+			size: source.byteLength,
+			lastModified: Date.now(),
+			stream: () => Readable.from(source),
+			arrayBuffer: async () => {
+				return this.bufferToArrayBuffer(source);
+			},
+			text: async () => {
+				return source.toString("utf-8");
+			}
+		};
+	}
+	/**
+	* Creates a FileLike object from a stream.
+	*
+	* @protected
+	*/
+	createFileFromStream(source, options = {}) {
+		let buffer = null;
+		return {
+			name: options.name ?? "file",
+			type: options.type ?? this.detector.getContentType(options.name ?? "file"),
+			size: options.size ?? 0,
+			lastModified: Date.now(),
+			stream: () => source,
+			_buffer: null,
+			arrayBuffer: async () => {
+				buffer ??= await this.streamToBuffer(source);
+				return this.bufferToArrayBuffer(buffer);
+			},
+			text: async () => {
+				buffer ??= await this.streamToBuffer(source);
+				return buffer.toString("utf-8");
+			}
+		};
+	}
+	/**
+	* Creates a FileLike object from a URL.
+	*
+	* @protected
+	*/
+	createFileFromUrl(url, options = {}) {
+		const parsedUrl = new URL(url);
+		const filename = options.name || parsedUrl.pathname.split("/").pop() || "file";
+		let buffer = null;
+		return {
+			name: filename,
+			type: options.type ?? this.detector.getContentType(filename),
+			size: 0,
+			lastModified: Date.now(),
+			stream: () => this.createStreamFromUrl(url),
+			arrayBuffer: async () => {
+				buffer ??= await this.loadFromUrl(url);
+				return this.bufferToArrayBuffer(buffer);
+			},
+			text: async () => {
+				buffer ??= await this.loadFromUrl(url);
+				return buffer.toString("utf-8");
+			},
+			filepath: url
+		};
+	}
+	/**
+	* Gets a streaming response from a URL.
+	*
+	* @protected
+	*/
+	getStreamingResponse(url) {
+		const stream = new PassThrough();
+		fetch(url).then((res) => Readable.fromWeb(res.body).pipe(stream)).catch((err) => stream.destroy(err));
+		return stream;
+	}
+	/**
+	* Loads data from a URL.
+	*
+	* @protected
+	*/
+	async loadFromUrl(url) {
+		const parsedUrl = new URL(url);
+		if (parsedUrl.protocol === "file:") return await readFile(fileURLToPath(url));
+		else if (parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:") {
+			const response = await fetch(url);
+			if (!response.ok) throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+			const arrayBuffer = await response.arrayBuffer();
+			return Buffer.from(arrayBuffer);
+		} else throw new Error(`Unsupported protocol: ${parsedUrl.protocol}`);
+	}
+	/**
+	* Creates a stream from a URL.
+	*
+	* @protected
+	*/
+	createStreamFromUrl(url) {
+		const parsedUrl = new URL(url);
+		if (parsedUrl.protocol === "file:") return createReadStream(fileURLToPath(url));
+		else if (parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:") return this.getStreamingResponse(url);
+		else throw new AlephaError(`Unsupported protocol: ${parsedUrl.protocol}`);
+	}
+	/**
+	* Converts a stream-like object to a Buffer.
+	*
+	* @protected
+	*/
+	async streamToBuffer(streamLike) {
+		const stream = streamLike instanceof Readable ? streamLike : Readable.fromWeb(streamLike);
+		return new Promise((resolve, reject) => {
+			const buffer = [];
+			stream.on("data", (chunk) => buffer.push(Buffer.from(chunk)));
+			stream.on("end", () => resolve(Buffer.concat(buffer)));
+			stream.on("error", (err) => reject(new AlephaError("Error converting stream", { cause: err })));
+		});
+	}
+	/**
+	* Converts a Node.js Buffer to an ArrayBuffer.
+	*
+	* @protected
+	*/
+	bufferToArrayBuffer(buffer) {
+		return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/NodeShellProvider.ts
+/**
+* Node.js implementation of ShellProvider.
+*
+* Executes shell commands using Node.js child_process module.
+* Supports binary resolution from node_modules/.bin for local packages.
+*/
+var NodeShellProvider = class {
+	log = $logger();
+	fs = $inject(FileSystemProvider);
+	/**
+	* Run a shell command or binary.
+	*/
+	async run(command, options = {}) {
+		const { resolve = false, capture = false, root, env } = options;
+		const cwd = root ?? process.cwd();
+		this.log.debug(`Shell: ${command}`, {
+			cwd,
+			resolve,
+			capture
+		});
+		let executable;
+		let args;
+		if (resolve) {
+			const [bin, ...rest] = command.split(" ");
+			executable = await this.resolveExecutable(bin, cwd);
+			args = rest;
+		} else [executable, ...args] = command.split(" ");
+		if (capture) return this.execCapture(command, {
+			cwd,
+			env
+		});
+		return this.execInherit(executable, args, {
+			cwd,
+			env
+		});
+	}
+	/**
+	* Execute command with inherited stdio (streams to terminal).
+	*/
+	async execInherit(executable, args, options) {
+		const proc = spawn(executable, args, {
+			stdio: "inherit",
+			cwd: options.cwd,
+			env: {
+				...process.env,
+				...options.env
+			}
+		});
+		return new Promise((resolve, reject) => {
+			proc.on("exit", (code) => {
+				if (code === 0 || code === null) resolve("");
+				else reject(new AlephaError(`Command exited with code ${code}`));
+			});
+			proc.on("error", reject);
+		});
+	}
+	/**
+	* Execute command and capture stdout.
+	*/
+	execCapture(command, options) {
+		return new Promise((resolve, reject) => {
+			exec(command, {
+				cwd: options.cwd,
+				env: {
+					...process.env,
+					LOG_FORMAT: "pretty",
+					...options.env
+				}
+			}, (err, stdout) => {
+				if (err) {
+					err.stdout = stdout;
+					reject(err);
+				} else resolve(stdout);
+			});
+		});
+	}
+	/**
+	* Resolve executable path from node_modules/.bin.
+	*
+	* Search order:
+	* 1. Local: node_modules/.bin/
+	* 2. Pnpm nested: node_modules/alepha/node_modules/.bin/
+	* 3. Monorepo: Walk up to 3 parent directories
+	*/
+	async resolveExecutable(name, root) {
+		const suffix = process.platform === "win32" ? ".cmd" : "";
+		let execPath = await this.findExecutable(root, `node_modules/.bin/${name}${suffix}`);
+		if (!execPath) execPath = await this.findExecutable(root, `node_modules/alepha/node_modules/.bin/${name}${suffix}`);
+		if (!execPath) {
+			let parentDir = this.fs.join(root, "..");
+			for (let i = 0; i < 3; i++) {
+				execPath = await this.findExecutable(parentDir, `node_modules/.bin/${name}${suffix}`);
+				if (execPath) break;
+				parentDir = this.fs.join(parentDir, "..");
+			}
+		}
+		if (!execPath) throw new AlephaError(`Could not find executable for '${name}'. Make sure the package is installed.`);
+		return execPath;
+	}
+	/**
+	* Check if executable exists at path.
+	*/
+	async findExecutable(root, relativePath) {
+		const fullPath = this.fs.join(root, relativePath);
+		if (await this.fs.exists(fullPath)) return fullPath;
+	}
+	/**
+	* Check if a command is installed and available in the system PATH.
+	*/
+	isInstalled(command) {
+		return new Promise((resolve) => {
+			exec(process.platform === "win32" ? `where ${command}` : `command -v ${command}`, (error) => resolve(!error));
+		});
+	}
+};
+
+//#endregion
+//#region ../../src/system/providers/ShellProvider.ts
+/**
+* Abstract provider for executing shell commands and binaries.
+*
+* Implementations:
+* - `NodeShellProvider` - Real shell execution using Node.js child_process
+* - `MemoryShellProvider` - In-memory mock for testing
+*
+* @example
+* ```typescript
+* class MyService {
+*   protected readonly shell = $inject(ShellProvider);
+*
+*   async build() {
+*     // Run shell command directly
+*     await this.shell.run("yarn install");
+*
+*     // Run local binary with resolution
+*     await this.shell.run("vite build", { resolve: true });
+*
+*     // Capture output
+*     const output = await this.shell.run("echo hello", { capture: true });
+*   }
+* }
+* ```
+*/
+var ShellProvider = class {};
+
+//#endregion
+//#region ../../src/system/index.ts
+/**
+* | type | quality | stability |
+* |------|---------|-----------|
+* | tooling | standard | stable |
+*
+* System-level abstractions for portable code across runtimes.
+*
+* **Features:**
+* - File system operations (read, write, exists, etc.)
+* - Shell command execution
+* - File type detection and MIME utilities
+* - Memory implementations for testing
+*
+* @module alepha.system
+*/
+const AlephaSystem = $module({
+	name: "alepha.system",
+	primitives: [],
+	services: [
+		FileDetector,
+		FileSystemProvider,
+		MemoryFileSystemProvider,
+		NodeFileSystemProvider,
+		ShellProvider,
+		MemoryShellProvider,
+		NodeShellProvider
+	],
+	register: (alepha) => alepha.with({
+		optional: true,
+		provide: FileSystemProvider,
+		use: NodeFileSystemProvider
+	}).with({
+		optional: true,
+		provide: ShellProvider,
+		use: alepha.isTest() ? MemoryShellProvider : NodeShellProvider
+	})
+});
+
+//#endregion
+//#region ../../src/react/router/providers/ReactServerTemplateProvider.ts
+/**
+* Handles HTML streaming for SSR.
+*
+* Uses hardcoded HTML structure - all customization via $head primitive.
+* Pre-encodes static parts as Uint8Array for zero-copy streaming.
+*/
+var ReactServerTemplateProvider = class {
+	log = $logger();
+	alepha = $inject(Alepha);
+	/**
+	* Shared TextEncoder - reused across all requests.
+	*/
+	encoder = new TextEncoder();
+	/**
+	* Pre-encoded static HTML parts for zero-copy streaming.
+	*/
+	SLOTS = {
+		DOCTYPE: this.encoder.encode("<!DOCTYPE html>\n"),
+		HTML_OPEN: this.encoder.encode("<html"),
+		HTML_CLOSE: this.encoder.encode(">\n"),
+		HEAD_OPEN: this.encoder.encode("<head>"),
+		HEAD_CLOSE: this.encoder.encode("</head>\n"),
+		BODY_OPEN: this.encoder.encode("<body"),
+		BODY_CLOSE: this.encoder.encode(">\n"),
+		ROOT_OPEN: this.encoder.encode("<div id=\"root\">"),
+		ROOT_CLOSE: this.encoder.encode("</div>\n"),
+		BODY_HTML_CLOSE: this.encoder.encode("</body>\n</html>"),
+		HYDRATION_PREFIX: this.encoder.encode("<script>window.__ssr="),
+		HYDRATION_SUFFIX: this.encoder.encode("<\/script>")
+	};
+	/**
+	* Early head content (charset, viewport, entry assets).
+	* Set once during configuration, reused for all requests.
+	*/
+	earlyHeadContent = "";
+	/**
+	* Root element ID for React mounting.
+	*/
+	rootId = "root";
+	/**
+	* Regex for extracting root div content from HTML.
+	*/
+	rootDivRegex = new RegExp(`<div[^>]*\\s+id=["']${this.rootId}["'][^>]*>([\\s\\S]*?)<\\/div>`, "i");
+	/**
+	* Extract content inside the root div from HTML.
+	*/
+	extractRootContent(html) {
+		return html.match(this.rootDivRegex)?.[1];
+	}
+	/**
+	* Set early head content (charset, viewport, entry assets).
+	* Called once during server configuration.
+	*/
+	setEarlyHeadContent(entryAssets, globalHead) {
+		const charset = globalHead?.charset ?? "UTF-8";
+		const viewport = globalHead?.viewport ?? "width=device-width, initial-scale=1";
+		this.earlyHeadContent = `<meta charset="${this.escapeHtml(charset)}">\n<meta name="viewport" content="${this.escapeHtml(viewport)}">\n` + entryAssets;
+	}
+	/**
+	* Render attributes record to HTML string.
+	*/
+	renderAttributes(attrs) {
+		if (!attrs) return "";
+		const entries = Object.entries(attrs);
+		if (entries.length === 0) return "";
+		return entries.map(([key, value]) => ` ${key}="${this.escapeHtml(value)}"`).join("");
+	}
+	/**
+	* Render head content (title, meta, link, script tags).
+	*/
+	renderHeadContent(head) {
+		if (!head) return "";
+		let content = "";
+		if (head.title) content += `<title>${this.escapeHtml(head.title)}</title>\n`;
+		if (head.meta) {
+			for (const meta of head.meta) if (meta.property) content += `<meta property="${this.escapeHtml(meta.property)}" content="${this.escapeHtml(meta.content)}">\n`;
+			else if (meta.name) content += `<meta name="${this.escapeHtml(meta.name)}" content="${this.escapeHtml(meta.content)}">\n`;
+		}
+		if (head.link) for (const link of head.link) {
+			content += `<link rel="${this.escapeHtml(link.rel)}" href="${this.escapeHtml(link.href)}"`;
+			if (link.type) content += ` type="${this.escapeHtml(link.type)}"`;
+			if (link.as) content += ` as="${this.escapeHtml(link.as)}"`;
+			if (link.crossorigin != null) content += " crossorigin=\"\"";
+			content += ">\n";
+		}
+		if (head.script) for (const script of head.script) if (typeof script === "string") content += `<script>${script}<\/script>\n`;
+		else {
+			const { content: scriptContent, ...rest } = script;
+			const attrs = Object.entries(rest).filter(([, v]) => v !== false && v !== void 0).map(([k, v]) => v === true ? k : `${k}="${this.escapeHtml(String(v))}"`).join(" ");
+			content += scriptContent ? `<script ${attrs}>${scriptContent}<\/script>\n` : `<script ${attrs}><\/script>\n`;
+		}
+		return content;
+	}
+	/**
+	* Escape HTML special characters.
+	*/
+	escapeHtml(str) {
+		return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+	}
+	/**
+	* Safely serialize data to JSON for embedding in HTML.
+	*/
+	safeJsonSerialize(data) {
+		return JSON.stringify(data).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+	}
+	/**
+	* Build hydration data from router state.
+	*/
+	buildHydrationData(state) {
+		const { request, context, ...store } = this.alepha.context.als?.getStore() ?? {};
+		const hydrationData = { layers: state.layers.map((layer) => ({
+			part: layer.part,
+			name: layer.name,
+			config: layer.config,
+			props: layer.props,
+			error: layer.error ? {
+				...layer.error,
+				name: layer.error.name,
+				message: layer.error.message,
+				stack: !this.alepha.isProduction() ? layer.error.stack : void 0
+			} : void 0
+		})) };
+		for (const [key, value] of Object.entries(store)) if (key.charAt(0) !== "_" && key !== "alepha.react.router.state" && key !== "registry") hydrationData[key] = value;
+		return hydrationData;
+	}
+	/**
+	* Pipe React stream to controller with backpressure handling.
+	* Returns true if stream completed successfully, false if error occurred.
+	*/
+	async pipeReactStream(controller, reactStream, state) {
+		const reader = reactStream.getReader();
+		try {
+			while (true) {
+				if (controller.desiredSize !== null && controller.desiredSize <= 0) await new Promise((resolve) => queueMicrotask(resolve));
+				const { done, value } = await reader.read();
+				if (done) break;
+				controller.enqueue(value);
+			}
+			return true;
+		} catch (error) {
+			this.log.error("React stream error", error);
+			controller.enqueue(this.encoder.encode(this.renderErrorToString(error instanceof Error ? error : new Error(String(error)), state)));
+			return false;
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	/**
+	* Stream complete HTML document (head already closed).
+	* Used by both createHtmlStream and late phase of createEarlyHtmlStream.
+	*/
+	async streamBodyAndClose(controller, reactStream, state, hydration) {
+		const { encoder, SLOTS: slots } = this;
+		controller.enqueue(slots.BODY_OPEN);
+		controller.enqueue(encoder.encode(this.renderAttributes(state.head?.bodyAttributes)));
+		controller.enqueue(slots.BODY_CLOSE);
+		controller.enqueue(slots.ROOT_OPEN);
+		await this.pipeReactStream(controller, reactStream, state);
+		controller.enqueue(slots.ROOT_CLOSE);
+		if (hydration) {
+			controller.enqueue(slots.HYDRATION_PREFIX);
+			controller.enqueue(encoder.encode(this.safeJsonSerialize(this.buildHydrationData(state))));
+			controller.enqueue(slots.HYDRATION_SUFFIX);
+		}
+		controller.enqueue(slots.BODY_HTML_CLOSE);
+	}
+	/**
+	* Create HTML stream with early head optimization.
+	*
+	* Flow:
+	* 1. Send DOCTYPE, <html>, <head> open, entry preloads (IMMEDIATE)
+	* 2. Run async work (page loaders)
+	* 3. Send rest of head, body, React content, hydration
+	*/
+	createEarlyHtmlStream(globalHead, asyncWork, options = {}) {
+		const { hydration = true, onError } = options;
+		const { encoder, SLOTS: slots } = this;
+		let headClosed = false;
+		let bodyStarted = false;
+		let routerState;
+		return new ReadableStream({ start: async (controller) => {
+			try {
+				controller.enqueue(slots.DOCTYPE);
+				controller.enqueue(slots.HTML_OPEN);
+				controller.enqueue(encoder.encode(this.renderAttributes(globalHead?.htmlAttributes)));
+				controller.enqueue(slots.HTML_CLOSE);
+				controller.enqueue(slots.HEAD_OPEN);
+				if (this.earlyHeadContent) controller.enqueue(encoder.encode(this.earlyHeadContent));
+				const result = await asyncWork();
+				if (!result || "redirect" in result) {
+					if (result && "redirect" in result) {
+						this.log.debug("Loader redirect, using meta refresh", { redirect: result.redirect });
+						controller.enqueue(encoder.encode(`<meta http-equiv="refresh" content="0; url=${this.escapeHtml(result.redirect)}">\n`));
+					}
+					controller.enqueue(slots.HEAD_CLOSE);
+					controller.enqueue(encoder.encode("<body></body></html>"));
+					controller.close();
+					return;
+				}
+				const { state, reactStream } = result;
+				routerState = state;
+				controller.enqueue(encoder.encode(this.renderHeadContent(state.head)));
+				controller.enqueue(slots.HEAD_CLOSE);
+				headClosed = true;
+				bodyStarted = true;
+				await this.streamBodyAndClose(controller, reactStream, state, hydration);
+				controller.close();
+			} catch (error) {
+				onError?.(error);
+				try {
+					this.injectErrorHtml(controller, error, routerState, {
+						headClosed,
+						bodyStarted
+					});
+					controller.close();
+				} catch {
+					controller.error(error);
+				}
+			}
+		} });
+	}
+	/**
+	* Create HTML stream (non-early version, for testing/prerender).
+	*/
+	createHtmlStream(reactStream, state, options = {}) {
+		const { hydration = true, onError } = options;
+		const { encoder, SLOTS: slots } = this;
+		return new ReadableStream({ start: async (controller) => {
+			try {
+				controller.enqueue(slots.DOCTYPE);
+				controller.enqueue(slots.HTML_OPEN);
+				controller.enqueue(encoder.encode(this.renderAttributes(state.head?.htmlAttributes)));
+				controller.enqueue(slots.HTML_CLOSE);
+				controller.enqueue(slots.HEAD_OPEN);
+				if (this.earlyHeadContent) controller.enqueue(encoder.encode(this.earlyHeadContent));
+				controller.enqueue(encoder.encode(this.renderHeadContent(state.head)));
+				controller.enqueue(slots.HEAD_CLOSE);
+				await this.streamBodyAndClose(controller, reactStream, state, hydration);
+				controller.close();
+			} catch (error) {
+				onError?.(error);
+				controller.error(error);
+			}
+		} });
+	}
+	/**
+	* Inject error HTML when streaming fails.
+	*/
+	injectErrorHtml(controller, error, routerState, streamState) {
+		const { encoder, SLOTS: slots } = this;
+		if (!streamState.headClosed) {
+			controller.enqueue(encoder.encode(this.renderHeadContent(routerState?.head)));
+			controller.enqueue(slots.HEAD_CLOSE);
+		}
+		if (!streamState.bodyStarted) {
+			controller.enqueue(slots.BODY_OPEN);
+			controller.enqueue(encoder.encode(this.renderAttributes(routerState?.head?.bodyAttributes)));
+			controller.enqueue(slots.BODY_CLOSE);
+			controller.enqueue(slots.ROOT_OPEN);
+		}
+		controller.enqueue(encoder.encode(this.renderErrorToString(error instanceof Error ? error : new Error(String(error)), routerState)));
+		controller.enqueue(slots.ROOT_CLOSE);
+		controller.enqueue(slots.BODY_HTML_CLOSE);
+	}
+	/**
+	* Render error to HTML string.
+	*/
+	renderErrorToString(error, routerState) {
+		this.log.error("SSR rendering error", error);
+		let errorElement;
+		if (routerState?.onError) try {
+			const result = routerState.onError(error, routerState);
+			if (result instanceof Redirection) this.log.warn("Error handler returned Redirection but headers sent", { redirect: result.redirect });
+			else if (result != null) errorElement = result;
+		} catch (handlerError) {
+			this.log.error("Error handler threw", handlerError);
+		}
+		if (!errorElement) errorElement = createElement(ErrorViewer_default, {
+			error,
+			alepha: this.alepha
+		});
+		const wrappedElement = createElement(AlephaContext.Provider, { value: this.alepha }, errorElement);
+		try {
+			return renderToString(wrappedElement);
+		} catch (renderError) {
+			this.log.error("Failed to render error component", renderError);
+			return error.message;
+		}
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/providers/ReactServerProvider.ts
+/**
+* React server provider responsible for SSR and static file serving.
+*
+* Coordinates between:
+* - ReactPageProvider: Page routing and layer resolution
+* - ReactServerTemplateProvider: HTML template parsing and streaming
+* - ServerHeadProvider: Head content management
+* - SSRManifestProvider: Module preload link collection
+*
+* Uses `react-dom/server` under the hood.
+*/
+var ReactServerProvider = class {
+	/**
+	* SSR response headers - pre-allocated to avoid object creation per request.
+	*/
+	SSR_HEADERS = {
+		"content-type": "text/html",
+		"cache-control": "no-store, no-cache, must-revalidate, proxy-revalidate",
+		pragma: "no-cache",
+		expires: "0"
+	};
+	fs = $inject(FileSystemProvider);
+	log = $logger();
+	alepha = $inject(Alepha);
+	env = $env(envSchema);
+	pageApi = $inject(ReactPageProvider);
+	templateProvider = $inject(ReactServerTemplateProvider);
+	serverHeadProvider = $inject(ServerHeadProvider);
+	serverStaticProvider = $inject(ServerStaticProvider);
+	serverRouterProvider = $inject(ServerRouterProvider);
+	ssrManifestProvider = $inject(SSRManifestProvider);
+	/**
+	* Cached check for ServerLinksProvider - avoids has() lookup per request.
+	*/
+	hasServerLinksProvider = false;
+	options = $use(reactServerOptions);
+	/**
+	* Configure the React server provider.
+	*/
+	onConfigure = $hook({
+		on: "configure",
+		handler: async () => {
+			const ssrEnabled = this.alepha.primitives($page).length > 0 && this.env.REACT_SSR_ENABLED !== false;
+			this.alepha.store.set("alepha.react.server.ssr", ssrEnabled);
+			let root = "";
+			if (!this.alepha.isServerless() && !this.alepha.isViteDev()) {
+				root = await this.getPublicDirectory();
+				if (!root) this.log.warn("Missing static files, static file server will be disabled");
+				else {
+					this.log.debug(`Using static files from: ${root}`);
+					await this.configureStaticServer(root);
+				}
+			}
+			if (ssrEnabled) {
+				this.registerPages();
+				this.log.info("SSR OK");
+				return;
+			}
+			this.log.info("SSR is disabled");
+		}
+	});
+	/**
+	* Register all pages as server routes.
+	*/
+	registerPages() {
+		this.setupEarlyHeadContent();
+		this.hasServerLinksProvider = this.alepha.has(ServerLinksProvider);
+		for (const page of this.pageApi.getPages()) if (page.component || page.lazy) {
+			this.log.debug(`+ ${page.match} -> ${page.name}`);
+			this.serverRouterProvider.createRoute({
+				...page,
+				schema: void 0,
+				method: "GET",
+				path: page.match,
+				handler: this.createHandler(page)
+			});
+		}
+	}
+	/**
+	* Set up early head content with entry assets.
+	*
+	* This content is sent immediately when streaming starts, before page loaders run,
+	* allowing the browser to start downloading entry.js and CSS files early.
+	*/
+	setupEarlyHeadContent() {
+		const assets = this.ssrManifestProvider.getEntryAssets();
+		const globalHead = this.serverHeadProvider.resolveGlobalHead();
+		const parts = [];
+		if (assets) {
+			for (const css of assets.css) parts.push(`<link rel="stylesheet" href="${css}" crossorigin="">`);
+			if (assets.js) parts.push(`<script type="module" crossorigin="" src="${assets.js}"><\/script>`);
+		}
+		this.templateProvider.setEarlyHeadContent(parts.length > 0 ? `${parts.join("\n")}\n` : "", globalHead);
+		this.log.debug("Early head content set", {
+			css: assets?.css.length ?? 0,
+			js: assets?.js ? 1 : 0
+		});
+	}
+	/**
+	* Get the public directory path where static files are located.
+	*/
+	async getPublicDirectory() {
+		const maybe = [join(process.cwd(), `dist/${this.options.publicDir}`), join(process.cwd(), this.options.publicDir)];
+		for (const it of maybe) if (await this.fs.exists(it)) return it;
+		return "";
+	}
+	/**
+	* Configure the static file server to serve files from the given root directory.
+	*/
+	async configureStaticServer(root) {
+		await this.serverStaticProvider.createStaticServer({
+			root,
+			cacheControl: {
+				maxAge: 3600,
+				immutable: true
+			},
+			...this.options.staticServer
+		});
+	}
+	/**
+	* Create the request handler for a page route.
+	*/
+	createHandler(route) {
+		return async (serverRequest) => {
+			const { url, reply, query, params } = serverRequest;
+			this.log.trace("Rendering page", { name: route.name });
+			const state = {
+				url,
+				params,
+				query,
+				name: route.name,
+				onError: () => null,
+				layers: [],
+				meta: {},
+				head: {}
+			};
+			if (this.hasServerLinksProvider) this.alepha.store.set("alepha.server.request.apiLinks", await this.alepha.inject(ServerLinksProvider).getUserApiLinks({
+				user: serverRequest.user,
+				authorization: serverRequest.headers.authorization
+			}));
+			let target = route;
+			while (target) {
+				if (route.can && !route.can()) {
+					this.log.warn(`Access to page '${route.name}' is forbidden by can() check`);
+					reply.status = 403;
+					reply.headers["content-type"] = "text/plain";
+					return "Forbidden";
+				}
+				target = target.parent;
+			}
+			await this.alepha.events.emit("react:server:render:begin", {
+				request: serverRequest,
+				state
+			});
+			Object.assign(reply.headers, this.SSR_HEADERS);
+			const globalHead = this.serverHeadProvider.resolveGlobalHead();
+			const htmlStream = this.templateProvider.createEarlyHtmlStream(globalHead, async () => {
+				const result = await this.renderPage(route, state);
+				if (result.redirect) return { redirect: result.redirect };
+				return {
+					state,
+					reactStream: result.reactStream
+				};
+			}, {
+				hydration: true,
+				onError: (error) => {
+					if (error instanceof Redirection) this.log.debug("Streaming resulted in redirection", { redirect: error.redirect });
+				}
+			});
+			this.log.trace("Page streaming started (early head optimization)");
+			route.onServerResponse?.(serverRequest);
+			reply.body = htmlStream;
+		};
+	}
+	/**
+	* Core page rendering logic shared between SSR handler and static prerendering.
+	*
+	* Handles:
+	* - Layer resolution (loaders)
+	* - Redirect detection
+	* - Head content filling
+	* - Preload link collection
+	* - React stream rendering
+	*
+	* @param route - The page route to render
+	* @param state - The router state
+	* @returns Render result with redirect or React stream
+	*/
+	async renderPage(route, state) {
+		const { redirect } = await this.pageApi.createLayers(route, state);
+		if (redirect) {
+			this.log.debug("Resolver resulted in redirection", { redirect });
+			return { redirect };
+		}
+		this.serverHeadProvider.fillHead(state);
+		const preloadLinks = this.ssrManifestProvider.collectPreloadLinks(route);
+		if (preloadLinks.length > 0) {
+			state.head ??= {};
+			state.head.link = [...state.head.link ?? [], ...preloadLinks];
+		}
+		const element = this.pageApi.root(state);
+		this.alepha.store.set("alepha.react.router.state", state);
+		return { reactStream: await renderToReadableStream(element, { onError: (error) => {
+			if (error instanceof Redirection) this.log.warn("Redirect during streaming ignored", { redirect: error.redirect });
+		} }) };
+	}
+	/**
+	* For testing purposes, renders a page to HTML string.
+	* Uses the same streaming code path as production, then collects to string.
+	*
+	* @param name - Page name to render
+	* @param options - Render options (params, query, html, hydration)
+	*/
+	async render(name, options = {}) {
+		const page = this.pageApi.page(name);
+		const url = new URL(this.pageApi.url(name, options));
+		const state = {
+			url,
+			params: options.params ?? {},
+			query: options.query ?? {},
+			onError: () => null,
+			layers: [],
+			meta: {},
+			head: {}
+		};
+		this.log.trace("Rendering", { url });
+		await this.alepha.events.emit("react:server:render:begin", { state });
+		const result = await this.renderPage(page, state);
+		if (result.redirect) return {
+			state,
+			html: "",
+			redirect: result.redirect
+		};
+		const reactStream = result.reactStream;
+		if (!options.html) return {
+			state,
+			html: await this.streamToString(reactStream)
+		};
+		const htmlStream = this.templateProvider.createHtmlStream(reactStream, state, { hydration: options.hydration ?? true });
+		const html = await this.streamToString(htmlStream);
+		await this.alepha.events.emit("react:server:render:end", {
+			state,
+			html
+		});
+		return {
+			state,
+			html
+		};
+	}
+	/**
+	* Collect a ReadableStream into a string.
+	*/
+	async streamToString(stream) {
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		const chunks = [];
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				chunks.push(decoder.decode(value, { stream: true }));
+			}
+			chunks.push(decoder.decode());
+		} finally {
+			reader.releaseLock();
+		}
+		return chunks.join("");
+	}
+};
+const envSchema = t.object({ REACT_SSR_ENABLED: t.optional(t.boolean()) });
+/**
+* React server provider configuration atom
+*/
+const reactServerOptions = $atom({
+	name: "alepha.react.server.options",
+	schema: t.object({
+		publicDir: t.string(),
+		staticServer: t.object({
+			disabled: t.boolean(),
+			path: t.string({ description: "URL path where static files will be served." })
+		})
+	}),
+	default: {
+		publicDir: "public",
+		staticServer: {
+			disabled: false,
+			path: "/"
+		}
+	}
+});
+
+//#endregion
+//#region ../../src/react/router/services/ReactPageServerService.ts
+/**
+* $page methods for server-side.
+*/
+var ReactPageServerService = class extends ReactPageService {
+	reactServerProvider = $inject(ReactServerProvider);
+	templateProvider = $inject(ReactServerTemplateProvider);
+	serverProvider = $inject(ServerProvider);
+	async render(name, options = {}) {
+		return this.reactServerProvider.render(name, options);
+	}
+	async fetch(pathname, options = {}) {
+		const response = await fetch(`${this.serverProvider.hostname}/${pathname}`);
+		const html = await response.text();
+		if (options?.html) return {
+			html,
+			response
+		};
+		const rootContent = this.templateProvider.extractRootContent(html);
+		if (rootContent !== void 0) return {
+			html: rootContent,
+			response
+		};
+		throw new AlephaError("Invalid HTML response");
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/providers/ReactBrowserRouterProvider.ts
+/**
+* Implementation of AlephaRouter for React in browser environment.
+*/
+var ReactBrowserRouterProvider = class extends RouterProvider {
+	log = $logger();
+	alepha = $inject(Alepha);
+	pageApi = $inject(ReactPageProvider);
+	browserHeadProvider = $inject(BrowserHeadProvider);
+	add(entry) {
+		this.pageApi.add(entry);
+	}
+	configure = $hook({
+		on: "configure",
+		handler: async () => {
+			for (const page of this.pageApi.getPages()) if (page.component || page.lazy) this.push({
+				path: page.match,
+				page
+			});
+		}
+	});
+	async transition(url, previous = [], meta = {}) {
+		const { pathname, search } = url;
+		const state = {
+			url,
+			query: {},
+			params: {},
+			layers: [],
+			onError: () => null,
+			meta
+		};
+		await this.alepha.events.emit("react:action:begin", { type: "transition" });
+		await this.alepha.events.emit("react:transition:begin", {
+			previous: this.alepha.store.get("alepha.react.router.state"),
+			state
+		});
+		try {
+			const { route, params } = this.match(pathname);
+			const query = {};
+			if (search) for (const [key, value] of new URLSearchParams(search).entries()) query[key] = String(value);
+			state.name = route?.page.name;
+			state.query = query;
+			state.params = params ?? {};
+			if (isPageRoute(route)) {
+				const { redirect } = await this.pageApi.createLayers(route.page, state, previous);
+				if (redirect) return redirect;
+			}
+			if (state.layers.length === 0) state.layers.push({
+				name: "not-found",
+				element: createElement(NotFound_default),
+				index: 0,
+				path: "/"
+			});
+			await this.alepha.events.emit("react:action:success", { type: "transition" });
+			await this.alepha.events.emit("react:transition:success", { state });
+		} catch (e) {
+			this.log.error("Transition has failed", e);
+			state.layers = [{
+				name: "error",
+				element: this.pageApi.renderError(e),
+				index: 0,
+				path: "/"
+			}];
+			await this.alepha.events.emit("react:action:error", {
+				type: "transition",
+				error: e
+			});
+			await this.alepha.events.emit("react:transition:error", {
+				error: e,
+				state
+			});
+		}
+		if (previous) for (let i = 0; i < previous.length; i++) {
+			const layer = previous[i];
+			if (state.layers[i]?.name !== layer.name) this.pageApi.page(layer.name)?.onLeave?.();
+		}
+		for (let i = 0; i < state.layers.length; i++) {
+			const layer = state.layers[i];
+			if (previous?.[i]?.name !== layer.name) this.pageApi.page(layer.name)?.onEnter?.();
+		}
+		this.alepha.store.set("alepha.react.router.state", state);
+		await this.alepha.events.emit("react:action:end", { type: "transition" });
+		await this.alepha.events.emit("react:transition:end", { state });
+		this.browserHeadProvider.fillAndRenderHead(state);
+	}
+	root(state) {
+		return this.pageApi.root(state);
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/providers/ReactBrowserProvider.ts
+/**
+* React browser renderer configuration atom
+*/
+const reactBrowserOptions = $atom({
+	name: "alepha.react.browser.options",
+	schema: t.object({ scrollRestoration: t.enum(["top", "manual"]) }),
+	default: { scrollRestoration: "top" }
+});
+var ReactBrowserProvider = class {
+	log = $logger();
+	client = $inject(LinkProvider);
+	alepha = $inject(Alepha);
+	router = $inject(ReactBrowserRouterProvider);
+	dateTimeProvider = $inject(DateTimeProvider);
+	browserHeadProvider = $inject(BrowserHeadProvider);
+	options = $use(reactBrowserOptions);
+	get rootId() {
+		return "root";
+	}
+	getRootElement() {
+		const root = this.document.getElementById(this.rootId);
+		if (root) return root;
+		const div = this.document.createElement("div");
+		div.id = this.rootId;
+		this.document.body.prepend(div);
+		return div;
+	}
+	transitioning;
+	get state() {
+		return this.alepha.store.get("alepha.react.router.state");
+	}
+	/**
+	* Accessor for Document DOM API.
+	*/
+	get document() {
+		return window.document;
+	}
+	/**
+	* Accessor for History DOM API.
+	*/
+	get history() {
+		return window.history;
+	}
+	/**
+	* Accessor for Location DOM API.
+	*/
+	get location() {
+		return window.location;
+	}
+	get base() {
+		const base = import.meta.env?.BASE_URL;
+		if (!base || base === "/") return "";
+		return base;
+	}
+	get url() {
+		const url = this.location.pathname + this.location.search;
+		if (this.base) return url.replace(this.base, "");
+		return url;
+	}
+	pushState(path, replace) {
+		const url = this.base + path;
+		if (replace) this.history.replaceState({}, "", url);
+		else this.history.pushState({}, "", url);
+	}
+	async invalidate(props) {
+		const previous = [];
+		this.log.trace("Invalidating layers");
+		if (props) {
+			const [key] = Object.keys(props);
+			const value = props[key];
+			for (const layer of this.state.layers) {
+				if (layer.props?.[key]) {
+					previous.push({
+						...layer,
+						props: {
+							...layer.props,
+							[key]: value
+						}
+					});
+					break;
+				}
+				previous.push(layer);
+			}
+		}
+		await this.render({ previous });
+	}
+	async push(url, options = {}) {
+		this.log.trace(`Going to ${url}`, {
+			url,
+			options
+		});
+		await this.render({
+			url,
+			previous: options.force ? [] : this.state.layers,
+			meta: options.meta
+		});
+		if (this.state.url.pathname + this.state.url.search !== url) {
+			this.pushState(this.state.url.pathname + this.state.url.search);
+			return;
+		}
+		this.pushState(url, options.replace);
+	}
+	async render(options = {}) {
+		const previous = options.previous ?? this.state.layers;
+		const url = options.url ?? this.url;
+		const start = this.dateTimeProvider.now();
+		this.transitioning = {
+			to: url,
+			from: this.state?.url.pathname
+		};
+		this.log.debug("Transitioning...", { to: url });
+		const redirect = await this.router.transition(new URL(`http://localhost${url}`), previous, options.meta);
+		if (redirect) {
+			this.log.info("Redirecting to", { redirect });
+			if (redirect.startsWith("http")) window.location.href = redirect;
+			else return await this.render({ url: redirect });
+		}
+		const ms = this.dateTimeProvider.now().diff(start);
+		this.log.info(`Transition OK [${ms}ms]`, this.transitioning);
+		this.transitioning = void 0;
+	}
+	/**
+	* Get embedded layers from the server.
+	*/
+	getHydrationState() {
+		try {
+			if ("__ssr" in window && typeof window.__ssr === "object") return window.__ssr;
+		} catch (error) {
+			console.error(error);
+		}
+	}
+	onTransitionEnd = $hook({
+		on: "react:transition:end",
+		handler: () => {
+			if (this.options.scrollRestoration === "top" && typeof window !== "undefined" && !this.alepha.isTest()) {
+				this.log.trace("Restoring scroll position to top");
+				window.scrollTo(0, 0);
+			}
+		}
+	});
+	ready = $hook({
+		on: "ready",
+		handler: async () => {
+			const hydration = this.getHydrationState();
+			const previous = hydration?.layers ?? [];
+			if (hydration) {
+				for (const [key, value] of Object.entries(hydration)) if (key !== "layers") this.alepha.set(key, value);
+			}
+			await this.render({ previous });
+			const element = this.router.root(this.state);
+			await this.alepha.events.emit("react:browser:render", {
+				element,
+				root: this.getRootElement(),
+				hydration,
+				state: this.state
+			});
+			this.browserHeadProvider.fillAndRenderHead(this.state);
+			window.addEventListener("popstate", () => {
+				if (this.base + this.state.url.pathname === this.location.pathname) return;
+				this.log.debug("Popstate event triggered - rendering new state", { url: this.location.pathname + this.location.search });
+				this.render();
+			});
+		}
+	});
+};
+
+//#endregion
+//#region ../../src/react/router/services/ReactRouter.ts
+/**
+* Friendly browser router API.
+*
+* Can be safely used server-side, but most methods will be no-op.
+*/
+var ReactRouter = class {
+	alepha = $inject(Alepha);
+	pageApi = $inject(ReactPageProvider);
+	get state() {
+		return this.alepha.store.get("alepha.react.router.state");
+	}
+	get pages() {
+		return this.pageApi.getPages();
+	}
+	get concretePages() {
+		return this.pageApi.getConcretePages();
+	}
+	get browser() {
+		if (this.alepha.isBrowser()) return this.alepha.inject(ReactBrowserProvider);
+	}
+	isActive(href, options = {}) {
+		const current = this.state.url.pathname;
+		let isActive = current === href || current === `${href}/` || `${current}/` === href;
+		if (options.startWith && !isActive) isActive = current.startsWith(href);
+		return isActive;
+	}
+	node(name, config = {}) {
+		const page = this.pageApi.page(name);
+		if (!page.lazy && !page.component) return {
+			...page,
+			label: page.label ?? page.name,
+			children: void 0
+		};
+		return {
+			...page,
+			label: page.label ?? page.name,
+			href: this.path(name, config),
+			children: void 0
+		};
+	}
+	path(name, config = {}) {
+		return this.pageApi.pathname(name, {
+			params: {
+				...this.state?.params,
+				...config.params
+			},
+			query: config.query
+		});
+	}
+	/**
+	* Reload the current page.
+	* This is equivalent to calling `go()` with the current pathname and search.
+	*/
+	async reload() {
+		if (!this.browser) return;
+		await this.push(this.location.pathname + this.location.search, {
+			replace: true,
+			force: true
+		});
+	}
+	getURL() {
+		if (!this.browser) return this.state.url;
+		return new URL(this.location.href);
+	}
+	get location() {
+		if (!this.browser) throw new Error("Browser is required");
+		return this.browser.location;
+	}
+	get current() {
+		return this.state;
+	}
+	get pathname() {
+		return this.state.url.pathname;
+	}
+	get query() {
+		const query = {};
+		for (const [key, value] of new URLSearchParams(this.state.url.search).entries()) query[key] = String(value);
+		return query;
+	}
+	async back() {
+		this.browser?.history.back();
+	}
+	async forward() {
+		this.browser?.history.forward();
+	}
+	async invalidate(props) {
+		await this.browser?.invalidate(props);
+	}
+	async push(path, options) {
+		for (const page of this.pages) if (page.name === path) {
+			await this.browser?.push(this.path(path, options), options);
+			return;
+		}
+		await this.browser?.push(path, options);
+	}
+	anchor(path, options = {}) {
+		let href = path;
+		for (const page of this.pages) if (page.name === path) {
+			href = this.path(path, options);
+			break;
+		}
+		return {
+			href: this.base(href),
+			onClick: (ev) => {
+				ev.stopPropagation();
+				ev.preventDefault();
+				this.push(href, options).catch(console.error);
+			}
+		};
+	}
+	base(path) {
+		const base = import.meta.env?.BASE_URL;
+		if (!base || base === "/") return path;
+		return base + path;
+	}
+	/**
+	* Set query params.
+	*
+	* @param record
+	* @param options
+	*/
+	setQueryParams(record, options = {}) {
+		const func = typeof record === "function" ? record : () => record;
+		const search = new URLSearchParams(func(this.query)).toString();
+		const state = search ? `${this.pathname}?${search}` : this.pathname;
+		if (options.push) window.history.pushState({}, "", state);
+		else window.history.replaceState({}, "", state);
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/hooks/useRouter.ts
+/**
+* Use this hook to access the React Router instance.
+*
+* You can add a type parameter to specify the type of your application.
+* This will allow you to use the router in a typesafe way.
+*
+* @example
+* class App {
+*   home = $page();
+* }
+*
+* const router = useRouter<App>();
+* router.push("home"); // typesafe
+*/
+const useRouter = () => {
+	return useInject(ReactRouter);
+};
+
+//#endregion
+//#region ../../src/react/router/components/Link.tsx
+/**
+* Link component for client-side navigation.
+*
+* It's a simple wrapper around an anchor (`<a>`) element using the `useRouter` hook.
+*/
+const Link = (props) => {
+	const router = useRouter();
+	return createElement("a", {
+		...props,
+		...router.anchor(props.href)
+	}, props.children);
+};
+var Link_default = Link;
+
+//#endregion
+//#region ../../src/react/router/hooks/useActive.ts
+/**
+* Hook to determine if a given route is active and to provide anchor props for navigation.
+* This hook refreshes on router state changes.
+*/
+const useActive = (args) => {
+	useRouterState();
+	const router = useRouter();
+	const [isPending, setPending] = useState(false);
+	const options = typeof args === "string" ? { href: args } : {
+		...args,
+		href: args.href
+	};
+	const href = options.href;
+	const isActive = router.isActive(href, options);
+	return {
+		isPending,
+		isActive,
+		anchorProps: {
+			href: router.base(href),
+			onClick: async (ev) => {
+				ev?.stopPropagation();
+				ev?.preventDefault();
+				if (isActive) return;
+				if (isPending) return;
+				setPending(true);
+				try {
+					await router.push(href);
+				} finally {
+					setPending(false);
+				}
+			}
+		}
+	};
+};
+
+//#endregion
+//#region ../../src/react/router/hooks/useQueryParams.ts
+/**
+* Hook to manage query parameters in the URL using a defined schema.
+*/
+const useQueryParams = (schema, options = {}) => {
+	const alepha = useAlepha();
+	const key = options.key ?? "q";
+	const router = useRouter();
+	const querystring = router.query[key];
+	const [queryParams = {}, setQueryParams] = useState(decode(alepha, schema, router.query[key]));
+	useEffect(() => {
+		setQueryParams(decode(alepha, schema, querystring));
+	}, [querystring]);
+	return [queryParams, (queryParams) => {
+		setQueryParams(queryParams);
+		router.setQueryParams((data) => {
+			return {
+				...data,
+				[key]: encode(alepha, schema, queryParams)
+			};
+		});
+	}];
+};
+const encode = (alepha, schema, data) => {
+	return btoa(JSON.stringify(alepha.codec.decode(schema, data)));
+};
+const decode = (alepha, schema, data) => {
+	try {
+		return alepha.codec.decode(schema, JSON.parse(atob(decodeURIComponent(data))));
+	} catch {
+		return;
+	}
+};
+
+//#endregion
+//#region ../../src/react/router/index.ts
+/**
+* Provides declarative routing with the `$page` primitive for building type-safe React routes.
+*
+* This module enables:
+* - URL pattern matching with parameters (e.g., `/users/:id`)
+* - Nested routing with parent-child relationships
+* - Type-safe URL parameter and query string validation
+* - Server-side data fetching with the `loader` function
+* - Lazy loading and code splitting
+* - Page animations and error handling
+*
+* @see {@link $page}
+* @module alepha.react.router
+*/
+const AlephaReactRouter = $module({
+	name: "alepha.react.router",
+	primitives: [$page],
+	services: [
+		ReactPageProvider,
+		ReactPageService,
+		ReactPreloadProvider,
+		ReactRouter,
+		ReactServerProvider,
+		ReactServerTemplateProvider,
+		SSRManifestProvider,
+		ReactPageServerService
+	],
+	register: (alepha) => alepha.with(AlephaReact).with(AlephaDateTime).with(AlephaServer).with(AlephaServerCache).with(AlephaServerLinks).with({
+		provide: ReactPageService,
+		use: ReactPageServerService
+	}).with(SSRManifestProvider).with(ReactServerTemplateProvider).with(ReactPreloadProvider).with(ReactServerProvider).with(ReactPageProvider).with(ReactRouter)
+});
+
+//#endregion
+export { $page, AlephaReactRouter, ErrorViewer_default as ErrorViewer, Link_default as Link, NestedView_default as NestedView, NotFound_default as NotFound, PAGE_PRELOAD_KEY, PagePrimitive, ReactBrowserProvider, ReactPageProvider, ReactPageService, ReactPreloadProvider, ReactRouter, ReactServerProvider, ReactServerTemplateProvider, Redirection, RouterLayerContext, SSRManifestProvider, isPageRoute, reactBrowserOptions, reactServerOptions, useActive, useQueryParams, useRouter, useRouterState };
+//# sourceMappingURL=index.js.map