@alepha/react 0.14.2 → 0.14.4

package/dist/router/index.js

@@ -3,14 +3,15 @@ import { $atom, $env, $hook, $inject, $module, $use, Alepha, AlephaError, KIND,
 import { AlephaDateTime, DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { AlephaServerLinks, LinkProvider, ServerLinksProvider } from "alepha/server/links";
+import { BrowserHeadProvider, ServerHeadProvider } from "@alepha/react/head";
 import { RouterProvider } from "alepha/router";
 import { StrictMode, createContext, createElement, memo, use, useEffect, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { AlephaServer, ServerProvider, ServerRouterProvider, ServerTimingProvider } from "alepha/server";
-import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { FileSystemProvider } from "alepha/file";
 import { ServerStaticProvider } from "alepha/server/static";
-import { renderToString } from "react-dom/server";
+import { renderToReadableStream } from "react-dom/server";
 import { AlephaServerCache } from "alepha/server/cache";
 
 //#region ../../src/router/services/ReactPageService.ts
@@ -26,6 +27,15 @@ var ReactPageService = class {
 	}
 };
 
+//#endregion
+//#region ../../src/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/router/primitives/$page.ts
 /**
@@ -40,7 +50,7 @@ var ReactPageService = class {
 * - Type-safe URL parameter and query string validation
 *
 * **Data Loading**
-* - Server-side data fetching with the `resolve` function
+* - Server-side data fetching with the `loader` function
 * - Automatic serialization and hydration for SSR
 * - Access to request context, URL params, and parent data
 *
@@ -77,7 +87,7 @@ var ReactPageService = class {
 *     params: t.object({ id: t.integer() }),
 *     query: t.object({ tab: t.optional(t.text()) })
 *   },
-*   resolve: async ({ params }) => {
+*   loader: async ({ params }) => {
 *     const user = await userApi.getUser(params.id);
 *     return { user };
 *   },
@@ -90,7 +100,7 @@ var ReactPageService = class {
 * const projectSection = $page({
 *   path: "/projects/:id",
 *   children: () => [projectBoard, projectSettings],
-*   resolve: async ({ params }) => {
+*   loader: async ({ params }) => {
 *     const project = await projectApi.get(params.id);
 *     return { project };
 *   },
@@ -109,7 +119,7 @@ var ReactPageService = class {
 *   static: {
 *     entries: posts.map(p => ({ params: { slug: p.slug } }))
 *   },
-*   resolve: async ({ params }) => {
+*   loader: async ({ params }) => {
 *     const post = await loadPost(params.slug);
 *     return { post };
 *   }
@@ -590,7 +600,7 @@ const RouterLayerContext = createContext(void 0);
 * import { Redirection } from "@alepha/react";
 *
 * const MyPage = $page({
-*   resolve: async () => {
+*   loader: async () => {
 *    if (needRedirect) {
 *      throw new Redirection("/new-path");
 *    }
@@ -746,13 +756,13 @@ function parseAnimation(animationLike, state, type = "enter") {
 
 //#endregion
 //#region ../../src/router/providers/ReactPageProvider.ts
-const envSchema$2 = t.object({ REACT_STRICT_MODE: t.boolean({ default: true }) });
+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$2);
+	env = $env(envSchema$1);
 	alepha = $inject(Alepha);
 	pages = [];
 	getPages() {
@@ -872,11 +882,11 @@ var ReactPageProvider = class {
 				}
 				forceRefresh = true;
 			}
-			if (!route$1.resolve) continue;
+			if (!route$1.loader) continue;
 			try {
 				const args = Object.create(state);
 				Object.assign(args, config, context);
-				const props = await route$1.resolve?.(args) ?? {};
+				const props = await route$1.loader?.(args) ?? {};
 				it.props = { ...props };
 				context = {
 					...context,
@@ -884,7 +894,7 @@ var ReactPageProvider = class {
 				};
 			} catch (e) {
 				if (e instanceof Redirection) return { redirect: e.redirect };
-				this.log.error("Page resolver has failed", e);
+				this.log.error("Page loader has failed", e);
 				it.error = e;
 				break;
 			}
@@ -1079,6 +1089,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 	log = $logger();
 	alepha = $inject(Alepha);
 	pageApi = $inject(ReactPageProvider);
+	browserHeadProvider = $inject(BrowserHeadProvider);
 	add(entry) {
 		this.pageApi.add(entry);
 	}
@@ -1149,6 +1160,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 		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);
@@ -1157,7 +1169,6 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 
 //#endregion
 //#region ../../src/router/providers/ReactBrowserProvider.ts
-const envSchema$1 = t.object({ REACT_ROOT_ID: t.text({ default: "root" }) });
 /**
 * React browser renderer configuration atom
 */
@@ -1167,18 +1178,21 @@ const reactBrowserOptions = $atom({
 	default: { scrollRestoration: "top" }
 });
 var ReactBrowserProvider = class {
-	env = $env(envSchema$1);
 	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.env.REACT_ROOT_ID);
+		const root = this.document.getElementById(this.rootId);
 		if (root) return root;
 		const div = this.document.createElement("div");
-		div.id = this.env.REACT_ROOT_ID;
+		div.id = this.rootId;
 		this.document.body.prepend(div);
 		return div;
 	}
@@ -1311,6 +1325,7 @@ var ReactBrowserProvider = class {
 				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 });
@@ -1453,46 +1468,750 @@ var ReactRouter = class {
 };
 
 //#endregion
-//#region ../../src/router/providers/ReactServerProvider.ts
-const envSchema = t.object({
-	REACT_SSR_ENABLED: t.optional(t.boolean()),
-	REACT_ROOT_ID: t.text({ default: "root" })
-});
+//#region ../../src/router/providers/ReactServerTemplateProvider.ts
 /**
-* React server provider configuration atom
+* Handles HTML template parsing, preprocessing, and streaming for SSR.
+*
+* Responsibilities:
+* - Parse template once at startup into logical slots
+* - Pre-encode static parts as Uint8Array for zero-copy streaming
+* - Render dynamic parts (attributes, head content) efficiently
+* - Build hydration data for client-side rehydration
+*
+* This provider is injected into ReactServerProvider to handle all
+* template-related operations, keeping ReactServerProvider focused
+* on request handling and React rendering coordination.
 */
-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: "/"
+var ReactServerTemplateProvider = class {
+	log = $logger();
+	alepha = $inject(Alepha);
+	/**
+	* Shared TextEncoder instance - reused across all requests.
+	*/
+	encoder = new TextEncoder();
+	/**
+	* Pre-encoded common strings for streaming.
+	*/
+	ENCODED = {
+		HYDRATION_PREFIX: this.encoder.encode("<script>window.__ssr="),
+		HYDRATION_SUFFIX: this.encoder.encode("<\/script>"),
+		EMPTY: this.encoder.encode("")
+	};
+	/**
+	* Cached template slots - parsed once, reused for all requests.
+	*/
+	slots = null;
+	/**
+	* Root element ID for React mounting.
+	*/
+	get rootId() {
+		return "root";
+	}
+	/**
+	* Regex pattern for matching the root div and extracting its content.
+	*/
+	get rootDivRegex() {
+		return new RegExp(`<div([^>]*)\\s+id=["']${this.rootId}["']([^>]*)>([\\s\\S]*?)<\\/div>`, "i");
+	}
+	/**
+	* Extract the content inside the root div from HTML.
+	*
+	* @param html - Full HTML string
+	* @returns The content inside the root div, or undefined if not found
+	*/
+	extractRootContent(html) {
+		return html.match(this.rootDivRegex)?.[3];
+	}
+	/**
+	* Check if template has been parsed and slots are available.
+	*/
+	isReady() {
+		return this.slots !== null;
+	}
+	/**
+	* Get the parsed template slots.
+	* Throws if template hasn't been parsed yet.
+	*/
+	getSlots() {
+		if (!this.slots) throw new AlephaError("Template not parsed. Call parseTemplate() during configuration.");
+		return this.slots;
+	}
+	/**
+	* Parse an HTML template into logical slots for efficient streaming.
+	*
+	* This should be called once during server startup/configuration.
+	* The parsed slots are cached and reused for all requests.
+	*
+	* @param template - The HTML template string (typically index.html)
+	*/
+	parseTemplate(template) {
+		this.log.debug("Parsing template into slots");
+		const rootId = this.rootId;
+		const doctypeMatch = template.match(/<!DOCTYPE[^>]*>/i);
+		const doctype = doctypeMatch?.[0] ?? "<!DOCTYPE html>";
+		let remaining = doctypeMatch ? template.slice(doctypeMatch.index + doctypeMatch[0].length) : template;
+		const htmlMatch = remaining.match(/<html([^>]*)>/i);
+		const htmlAttrsStr = htmlMatch?.[1]?.trim() ?? "";
+		const htmlOriginalAttrs = this.parseAttributes(htmlAttrsStr);
+		remaining = htmlMatch ? remaining.slice(htmlMatch.index + htmlMatch[0].length) : remaining;
+		const headMatch = remaining.match(/<head([^>]*)>([\s\S]*?)<\/head>/i);
+		const headOriginalContent = headMatch?.[2]?.trim() ?? "";
+		remaining = headMatch ? remaining.slice(headMatch.index + headMatch[0].length) : remaining;
+		const bodyMatch = remaining.match(/<body([^>]*)>/i);
+		const bodyAttrsStr = bodyMatch?.[1]?.trim() ?? "";
+		const bodyOriginalAttrs = this.parseAttributes(bodyAttrsStr);
+		const bodyStartIndex = bodyMatch ? bodyMatch.index + bodyMatch[0].length : 0;
+		remaining = remaining.slice(bodyStartIndex);
+		const rootDivRegex = new RegExp(`<div([^>]*)\\s+id=["']${rootId}["']([^>]*)>([\\s\\S]*?)<\\/div>`, "i");
+		const rootMatch = remaining.match(rootDivRegex);
+		let beforeRoot = "";
+		let afterRoot = "";
+		let rootAttrs = "";
+		if (rootMatch) {
+			beforeRoot = remaining.slice(0, rootMatch.index).trim();
+			const rootEndIndex = rootMatch.index + rootMatch[0].length;
+			const bodyCloseIndex = remaining.indexOf("</body>");
+			afterRoot = bodyCloseIndex > rootEndIndex ? remaining.slice(rootEndIndex, bodyCloseIndex).trim() : "";
+			rootAttrs = `${rootMatch[1] ?? ""}${rootMatch[2] ?? ""}`.trim();
+		} else {
+			const bodyCloseIndex = remaining.indexOf("</body>");
+			if (bodyCloseIndex > 0) beforeRoot = remaining.slice(0, bodyCloseIndex).trim();
 		}
+		const rootOpenTag = rootAttrs ? `<div ${rootAttrs} id="${rootId}">` : `<div id="${rootId}">`;
+		this.slots = {
+			doctype: this.encoder.encode(doctype + "\n"),
+			htmlOpen: this.encoder.encode("<html"),
+			htmlClose: this.encoder.encode(">\n"),
+			headOpen: this.encoder.encode("<head>"),
+			headClose: this.encoder.encode("</head>\n"),
+			bodyOpen: this.encoder.encode("<body"),
+			bodyClose: this.encoder.encode(">\n"),
+			rootOpen: this.encoder.encode(rootOpenTag),
+			rootClose: this.encoder.encode("</div>\n"),
+			scriptClose: this.encoder.encode("</body>\n</html>"),
+			htmlOriginalAttrs,
+			bodyOriginalAttrs,
+			headOriginalContent,
+			beforeRoot,
+			afterRoot
+		};
+		this.log.debug("Template parsed successfully", {
+			hasHtmlAttrs: Object.keys(htmlOriginalAttrs).length > 0,
+			hasBodyAttrs: Object.keys(bodyOriginalAttrs).length > 0,
+			hasHeadContent: headOriginalContent.length > 0,
+			hasBeforeRoot: beforeRoot.length > 0,
+			hasAfterRoot: afterRoot.length > 0
+		});
+		return this.slots;
 	}
+	/**
+	* Parse HTML attributes string into a record.
+	*
+	* Handles: key="value", key='value', key=value, and boolean key
+	*/
+	parseAttributes(attrStr) {
+		const attrs = {};
+		if (!attrStr) return attrs;
+		const attrRegex = /([^\s=]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+		let match;
+		while (match = attrRegex.exec(attrStr)) {
+			const key = match[1];
+			attrs[key] = match[2] ?? match[3] ?? match[4] ?? "";
+		}
+		return attrs;
+	}
+	/**
+	* Render attributes record to HTML string.
+	*
+	* @param attrs - Attributes to render
+	* @returns HTML attribute string like ` lang="en" class="dark"`
+	*/
+	renderAttributes(attrs) {
+		const entries = Object.entries(attrs);
+		if (entries.length === 0) return "";
+		return entries.map(([key, value]) => ` ${key}="${this.escapeHtml(value)}"`).join("");
+	}
+	/**
+	* Render merged HTML attributes (original + dynamic).
+	*/
+	renderMergedHtmlAttrs(dynamicAttrs) {
+		const merged = {
+			...this.getSlots().htmlOriginalAttrs,
+			...dynamicAttrs
+		};
+		return this.renderAttributes(merged);
+	}
+	/**
+	* Render merged body attributes (original + dynamic).
+	*/
+	renderMergedBodyAttrs(dynamicAttrs) {
+		const merged = {
+			...this.getSlots().bodyOriginalAttrs,
+			...dynamicAttrs
+		};
+		return this.renderAttributes(merged);
+	}
+	/**
+	* Render head content (title, meta, link, script tags).
+	*
+	* @param head - Head data to render
+	* @param includeOriginal - Whether to include original head content
+	* @returns HTML string with head content
+	*/
+	renderHeadContent(head, includeOriginal = true) {
+		const slots = this.getSlots();
+		let content = "";
+		if (includeOriginal && slots.headOriginalContent) content += slots.headOriginalContent;
+		if (!head) return content;
+		if (head.title) if (content.includes("<title>")) content = content.replace(/<title>.*?<\/title>/i, `<title>${this.escapeHtml(head.title)}</title>`);
+		else content += `<title>${this.escapeHtml(head.title)}</title>\n`;
+		if (head.meta) for (const meta of head.meta) content += this.renderMetaTag(meta);
+		if (head.link) for (const link of head.link) content += this.renderLinkTag(link);
+		if (head.script) for (const script of head.script) content += this.renderScriptTag(script);
+		return content;
+	}
+	/**
+	* Render a meta tag.
+	*/
+	renderMetaTag(meta) {
+		if (meta.property) return `<meta property="${this.escapeHtml(meta.property)}" content="${this.escapeHtml(meta.content)}">\n`;
+		if (meta.name) return `<meta name="${this.escapeHtml(meta.name)}" content="${this.escapeHtml(meta.content)}">\n`;
+		return "";
+	}
+	/**
+	* Render a link tag.
+	*/
+	renderLinkTag(link) {
+		let tag = `<link rel="${this.escapeHtml(link.rel)}" href="${this.escapeHtml(link.href)}"`;
+		if (link.as) tag += ` as="${this.escapeHtml(link.as)}"`;
+		if (link.crossorigin != null) tag += " crossorigin=\"\"";
+		tag += ">\n";
+		return tag;
+	}
+	/**
+	* Render a script tag.
+	*/
+	renderScriptTag(script) {
+		return `<script ${Object.entries(script).filter(([, value]) => value !== false).map(([key, value]) => {
+			if (value === true) return key;
+			return `${key}="${this.escapeHtml(String(value))}"`;
+		}).join(" ")}><\/script>\n`;
+	}
+	/**
+	* 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.
+	* Escapes characters that could break out of script tags.
+	*/
+	safeJsonSerialize(data) {
+		return JSON.stringify(data).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+	}
+	/**
+	* Build hydration data from router state.
+	*
+	* This creates the data structure that will be serialized to window.__ssr
+	* for client-side rehydration.
+	*/
+	buildHydrationData(state) {
+		const { request, context, ...store } = this.alepha.context.als?.getStore() ?? {};
+		return {
+			...store,
+			"alepha.react.router.state": void 0,
+			layers: state.layers.map((layer) => ({
+				...layer,
+				error: layer.error ? {
+					...layer.error,
+					name: layer.error.name,
+					message: layer.error.message,
+					stack: !this.alepha.isProduction() ? layer.error.stack : void 0
+				} : void 0,
+				index: void 0,
+				path: void 0,
+				element: void 0,
+				route: void 0
+			}))
+		};
+	}
+	/**
+	* Encode a string to Uint8Array using the shared encoder.
+	*/
+	encode(str) {
+		return this.encoder.encode(str);
+	}
+	/**
+	* Get the pre-encoded hydration script prefix.
+	*/
+	get hydrationPrefix() {
+		return this.ENCODED.HYDRATION_PREFIX;
+	}
+	/**
+	* Get the pre-encoded hydration script suffix.
+	*/
+	get hydrationSuffix() {
+		return this.ENCODED.HYDRATION_SUFFIX;
+	}
+	/**
+	* Create a ReadableStream that streams the HTML template with React content.
+	*
+	* This is the main entry point for SSR streaming. It:
+	* 1. Sends <head> immediately (browser starts downloading assets)
+	* 2. Streams React content as it renders
+	* 3. Appends hydration script and closing tags
+	*
+	* @param reactStream - ReadableStream from renderToReadableStream
+	* @param state - Router state with head data
+	* @param options - Streaming options
+	*/
+	createHtmlStream(reactStream, state, options = {}) {
+		const { hydration = true, onError } = options;
+		const slots = this.getSlots();
+		const head = state.head;
+		const encoder = this.encoder;
+		return new ReadableStream({ start: async (controller) => {
+			try {
+				controller.enqueue(slots.doctype);
+				controller.enqueue(slots.htmlOpen);
+				controller.enqueue(encoder.encode(this.renderMergedHtmlAttrs(head?.htmlAttributes)));
+				controller.enqueue(slots.htmlClose);
+				controller.enqueue(slots.headOpen);
+				if (this.earlyHeadContent) controller.enqueue(encoder.encode(this.earlyHeadContent));
+				controller.enqueue(encoder.encode(this.renderHeadContent(head)));
+				controller.enqueue(slots.headClose);
+				controller.enqueue(slots.bodyOpen);
+				controller.enqueue(encoder.encode(this.renderMergedBodyAttrs(head?.bodyAttributes)));
+				controller.enqueue(slots.bodyClose);
+				if (slots.beforeRoot) controller.enqueue(encoder.encode(slots.beforeRoot));
+				controller.enqueue(slots.rootOpen);
+				const reader = reactStream.getReader();
+				try {
+					while (true) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						controller.enqueue(value);
+					}
+				} finally {
+					reader.releaseLock();
+				}
+				controller.enqueue(slots.rootClose);
+				if (slots.afterRoot) controller.enqueue(encoder.encode(slots.afterRoot));
+				if (hydration) {
+					const hydrationData = this.buildHydrationData(state);
+					controller.enqueue(this.ENCODED.HYDRATION_PREFIX);
+					controller.enqueue(encoder.encode(this.safeJsonSerialize(hydrationData)));
+					controller.enqueue(this.ENCODED.HYDRATION_SUFFIX);
+				}
+				controller.enqueue(slots.scriptClose);
+				controller.close();
+			} catch (error) {
+				onError?.(error);
+				controller.error(error);
+			}
+		} });
+	}
+	/**
+	* Early head content for preloading.
+	*
+	* Contains entry assets (JS + CSS) that are always required and can be
+	* sent before page loaders run.
+	*/
+	earlyHeadContent = "";
+	/**
+	* Set the early head content (entry script + CSS).
+	*
+	* Also strips these assets from the original head content to avoid duplicates,
+	* since we're moving them to the early phase.
+	*
+	* @param content - HTML string with entry assets
+	* @param entryAssets - Entry asset paths to strip from original head
+	*/
+	setEarlyHeadContent(content, entryAssets) {
+		this.earlyHeadContent = content;
+		if (entryAssets && this.slots) {
+			let headContent = this.slots.headOriginalContent;
+			if (entryAssets.js) {
+				const scriptPattern = new RegExp(`<script[^>]*\\ssrc=["']${this.escapeRegExp(entryAssets.js)}["'][^>]*>\\s*<\/script>\\s*`, "gi");
+				headContent = headContent.replace(scriptPattern, "");
+			}
+			for (const css of entryAssets.css) {
+				const linkPattern = new RegExp(`<link[^>]*\\shref=["']${this.escapeRegExp(css)}["'][^>]*>\\s*`, "gi");
+				headContent = headContent.replace(linkPattern, "");
+			}
+			this.slots.headOriginalContent = headContent.trim();
+		}
+	}
+	/**
+	* Escape special regex characters in a string.
+	*/
+	escapeRegExp(str) {
+		return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}
+	/**
+	* Create an optimized HTML stream with early head streaming.
+	*
+	* This version sends critical assets (entry.js, CSS) BEFORE page loaders run,
+	* allowing the browser to start downloading them immediately.
+	*
+	* Flow:
+	* 1. Send DOCTYPE, <html>, <head> open, entry preloads (IMMEDIATE)
+	* 2. Run async work (createLayers, etc.)
+	* 3. Send rest of head, body, React content, hydration
+	*
+	* @param globalHead - Global head with htmlAttributes (from $head primitives)
+	* @param asyncWork - Async function to run between early head and rest of stream
+	* @param options - Streaming options
+	*/
+	createEarlyHtmlStream(globalHead, asyncWork, options = {}) {
+		const { hydration = true, onError, onRedirect } = options;
+		const slots = this.getSlots();
+		const encoder = this.encoder;
+		return new ReadableStream({ start: async (controller) => {
+			try {
+				controller.enqueue(slots.doctype);
+				controller.enqueue(slots.htmlOpen);
+				controller.enqueue(encoder.encode(this.renderMergedHtmlAttrs(globalHead?.htmlAttributes)));
+				controller.enqueue(slots.htmlClose);
+				controller.enqueue(slots.headOpen);
+				if (this.earlyHeadContent) controller.enqueue(encoder.encode(this.earlyHeadContent));
+				const result = await asyncWork();
+				if (!result) {
+					controller.enqueue(slots.headClose);
+					controller.enqueue(encoder.encode("<body></body></html>"));
+					controller.close();
+					return;
+				}
+				const { state, reactStream } = result;
+				const head = state.head;
+				controller.enqueue(encoder.encode(this.renderHeadContent(head)));
+				controller.enqueue(slots.headClose);
+				controller.enqueue(slots.bodyOpen);
+				controller.enqueue(encoder.encode(this.renderMergedBodyAttrs(head?.bodyAttributes)));
+				controller.enqueue(slots.bodyClose);
+				if (slots.beforeRoot) controller.enqueue(encoder.encode(slots.beforeRoot));
+				controller.enqueue(slots.rootOpen);
+				const reader = reactStream.getReader();
+				try {
+					while (true) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						controller.enqueue(value);
+					}
+				} finally {
+					reader.releaseLock();
+				}
+				controller.enqueue(slots.rootClose);
+				if (slots.afterRoot) controller.enqueue(encoder.encode(slots.afterRoot));
+				if (hydration) {
+					const hydrationData = this.buildHydrationData(state);
+					controller.enqueue(this.ENCODED.HYDRATION_PREFIX);
+					controller.enqueue(encoder.encode(this.safeJsonSerialize(hydrationData)));
+					controller.enqueue(this.ENCODED.HYDRATION_SUFFIX);
+				}
+				controller.enqueue(slots.scriptClose);
+				controller.close();
+			} catch (error) {
+				onError?.(error);
+				controller.error(error);
+			}
+		} });
+	}
+};
+
+//#endregion
+//#region ../../src/router/atoms/ssrManifestAtom.ts
+/**
+* Schema for the SSR manifest atom.
+*/
+const ssrManifestAtomSchema = t.object({
+	preload: t.optional(t.record(t.string(), t.string())),
+	ssr: t.optional(t.record(t.string(), t.array(t.string()))),
+	client: t.optional(t.record(t.string(), t.object({
+		file: t.string(),
+		src: t.optional(t.string()),
+		isEntry: t.optional(t.boolean()),
+		isDynamicEntry: t.optional(t.boolean()),
+		imports: t.optional(t.array(t.string())),
+		dynamicImports: t.optional(t.array(t.string())),
+		css: t.optional(t.array(t.string())),
+		assets: 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)
+* - ssr: Maps source files to their required chunks
+* - client: Maps source files to their output info including imports/css
+*/
+const ssrManifestAtom = $atom({
+	name: "alepha.react.ssr.manifest",
+	description: "SSR manifest for module preloading",
+	schema: ssrManifestAtomSchema,
+	default: {}
 });
+
+//#endregion
+//#region ../../src/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)
+* - ssr-manifest.json (SSR 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 preload manifest.
+	*/
+	get preloadManifest() {
+		return this.manifest.preload;
+	}
+	/**
+	* Get the SSR manifest.
+	*/
+	get ssrManifest() {
+		return this.manifest.ssr;
+	}
+	/**
+	* 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,
+	* not just the direct chunks from the SSR manifest.
+	*
+	* @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 this.getChunksFromSSRManifest(sourcePath);
+		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;
+		if (entry.file) chunks.add("/" + entry.file);
+		if (entry.css) for (const css of entry.css) chunks.add("/" + css);
+		if (entry.imports) for (const imp of entry.imports) {
+			if (imp === "index.html" || imp.endsWith(".html")) continue;
+			this.collectChunksRecursive(imp, chunks, visited);
+		}
+	}
+	/**
+	* Fallback to SSR manifest for chunk lookup.
+	*/
+	getChunksFromSSRManifest(sourcePath) {
+		if (!this.ssrManifest) return [];
+		if (this.ssrManifest[sourcePath]) return this.ssrManifest[sourcePath];
+		const basePath = sourcePath.replace(/\.[^.]+$/, "");
+		for (const ext of [
+			".tsx",
+			".ts",
+			".jsx",
+			".js"
+		]) {
+			const pathWithExt = basePath + ext;
+			if (this.ssrManifest[pathWithExt]) return this.ssrManifest[pathWithExt];
+		}
+		return [];
+	}
+	/**
+	* 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 manifests are loaded and available.
+	*/
+	isAvailable() {
+		return this.clientManifest !== void 0 || this.ssrManifest !== 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;
+		for (const [key, entry] of Object.entries(this.clientManifest)) if (entry.isEntry) {
+			this.cachedEntryAssets = {
+				js: "/" + entry.file,
+				css: entry.css?.map((css) => "/" + 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/router/providers/ReactServerProvider.ts
 /**
 * React server provider responsible for SSR and static file serving.
 *
-* Use `react-dom/server` under the hood.
+* 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);
 	serverTimingProvider = $inject(ServerTimingProvider);
-	ROOT_DIV_REGEX = new RegExp(`<div([^>]*)\\s+id=["']${this.env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`, "is");
-	preprocessedTemplate = null;
+	ssrManifestProvider = $inject(SSRManifestProvider);
+	/**
+	* Cached check for ServerLinksProvider - avoids has() lookup per request.
+	*/
+	hasServerLinksProvider = false;
 	options = $use(reactServerOptions);
 	/**
 	* Configure the React server provider.
@@ -1502,13 +2221,14 @@ var ReactServerProvider = class {
 		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);
+			if (ssrEnabled) this.log.info("SSR streaming enabled");
 			if (this.alepha.isViteDev()) {
 				await this.configureVite(ssrEnabled);
 				return;
 			}
 			let root = "";
 			if (!this.alepha.isServerless()) {
-				root = this.getPublicDirectory();
+				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}`);
@@ -1536,12 +2256,20 @@ var ReactServerProvider = class {
 			});
 		}
 	});
+	/**
+	* Get the current HTML template.
+	*/
 	get template() {
-		return this.alepha.store.get("alepha.react.server.template") ?? "<!DOCTYPE html><html lang='en'><head></head><body></body></html>";
+		return this.alepha.store.get("alepha.react.server.template") ?? "<!DOCTYPE html><html lang='en'><head></head><body><div id='root'></div></body></html>";
 	}
+	/**
+	* Register all pages as server routes.
+	*/
 	async registerPages(templateLoader) {
 		const template = await templateLoader();
-		if (template) this.preprocessedTemplate = this.preprocessTemplate(template);
+		if (template) this.templateProvider.parseTemplate(template);
+		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({
@@ -1554,11 +2282,37 @@ var ReactServerProvider = class {
 		}
 	}
 	/**
+	* 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.
+	*
+	* Uses <script type="module"> instead of <link rel="modulepreload"> for JS
+	* because the script needs to execute anyway - this way the browser starts
+	* downloading, parsing, AND will execute as soon as ready.
+	*
+	* Also strips these assets from the original template head to avoid duplicates.
+	*/
+	setupEarlyHeadContent() {
+		const assets = this.ssrManifestProvider.getEntryAssets();
+		if (!assets) return;
+		const parts = [];
+		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>`);
+		if (parts.length > 0) {
+			this.templateProvider.setEarlyHeadContent(parts.join("\n") + "\n", assets);
+			this.log.debug("Early head content set", {
+				css: assets.css.length,
+				js: assets.js ? 1 : 0
+			});
+		}
+	}
+	/**
 	* Get the public directory path where static files are located.
 	*/
-	getPublicDirectory() {
+	async getPublicDirectory() {
 		const maybe = [join(process.cwd(), `dist/${this.options.publicDir}`), join(process.cwd(), this.options.publicDir)];
-		for (const it of maybe) if (existsSync(it)) return it;
+		for (const it of maybe) if (await this.fs.exists(it)) return it;
 		return "";
 	}
 	/**
@@ -1575,72 +2329,38 @@ var ReactServerProvider = class {
 		});
 	}
 	/**
-	* Configure Vite for SSR.
+	* Configure Vite for SSR in development mode.
 	*/
 	async configureVite(ssrEnabled) {
 		if (!ssrEnabled) return;
-		this.log.info("SSR (dev) OK");
-		const url = `http://${process.env.SERVER_HOST}:${process.env.SERVER_PORT}`;
+		const url = `http://localhost:${this.alepha.env.SERVER_PORT ?? "5173"}`;
+		this.log.info("SSR (dev) OK", { url });
 		await this.registerPages(() => fetch(`${url}/index.html`).then((it) => it.text()).catch(() => void 0));
 	}
 	/**
-	* For testing purposes, creates a render function that can be used.
+	* Create the request handler for a page route.
 	*/
-	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: {}
-		};
-		this.log.trace("Rendering", { url });
-		await this.alepha.events.emit("react:server:render:begin", { state });
-		const { redirect } = await this.pageApi.createLayers(page, state);
-		if (redirect) return {
-			state,
-			html: "",
-			redirect
-		};
-		if (!options.html) {
-			this.alepha.store.set("alepha.react.router.state", state);
-			return {
-				state,
-				html: renderToString(this.pageApi.root(state))
-			};
-		}
-		const template = this.template ?? "";
-		const html = this.renderToHtml(template, state, options.hydration);
-		if (html instanceof Redirection) return {
-			state,
-			html: "",
-			redirect
-		};
-		const result = {
-			state,
-			html
-		};
-		await this.alepha.events.emit("react:server:render:end", result);
-		return result;
-	}
 	createHandler(route, templateLoader) {
 		return async (serverRequest) => {
 			const { url, reply, query, params } = serverRequest;
-			const template = await templateLoader();
-			if (!template) throw new AlephaError("Missing template for SSR rendering");
+			if (!this.templateProvider.isReady()) {
+				const template = await templateLoader();
+				if (!template) throw new AlephaError("Missing template for SSR rendering");
+				this.templateProvider.parseTemplate(template);
+				this.setupEarlyHeadContent();
+			}
 			this.log.trace("Rendering page", { name: route.name });
 			const state = {
 				url,
 				params,
 				query,
+				name: route.name,
 				onError: () => null,
-				layers: []
+				layers: [],
+				meta: {},
+				head: {}
 			};
-			state.name = route.name;
-			if (this.alepha.has(ServerLinksProvider)) this.alepha.store.set("alepha.server.request.apiLinks", await this.alepha.inject(ServerLinksProvider).getUserApiLinks({
+			if (this.hasServerLinksProvider) this.alepha.store.set("alepha.server.request.apiLinks", await this.alepha.inject(ServerLinksProvider).getUserApiLinks({
 				user: serverRequest.user,
 				authorization: serverRequest.headers.authorization
 			}));
@@ -1658,114 +2378,156 @@ var ReactServerProvider = class {
 				request: serverRequest,
 				state
 			});
-			this.serverTimingProvider.beginTiming("createLayers");
-			const { redirect } = await this.pageApi.createLayers(route, state);
-			this.serverTimingProvider.endTiming("createLayers");
-			if (redirect) {
-				this.log.debug("Resolver resulted in redirection", { redirect });
-				return reply.redirect(redirect);
-			}
-			reply.headers["content-type"] = "text/html";
-			reply.headers["cache-control"] = "no-store, no-cache, must-revalidate, proxy-revalidate";
-			reply.headers.pragma = "no-cache";
-			reply.headers.expires = "0";
-			const html = this.renderToHtml(template, state);
-			if (html instanceof Redirection) {
-				reply.redirect(typeof html.redirect === "string" ? html.redirect : this.pageApi.href(html.redirect));
-				this.log.debug("Rendering resulted in redirection", { redirect: html.redirect });
-				return;
-			}
-			this.log.trace("Page rendered to HTML successfully");
-			const event = {
-				request: serverRequest,
-				state,
-				html
-			};
-			await this.alepha.events.emit("react:server:render:end", event);
+			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) {
+					reply.redirect(result.redirect);
+					return null;
+				}
+				return {
+					state,
+					reactStream: result.reactStream
+				};
+			}, {
+				hydration: true,
+				onError: (error) => {
+					if (error instanceof Redirection) this.log.debug("Streaming resulted in redirection", { redirect: error.redirect });
+					else this.log.error("HTML stream error", error);
+				}
+			});
+			this.log.trace("Page streaming started (early head optimization)");
 			route.onServerResponse?.(serverRequest);
-			this.log.trace("Page rendered", { name: route.name });
-			return event.html;
+			reply.body = htmlStream;
 		};
 	}
-	renderToHtml(template, state, hydration = true) {
-		const element = this.pageApi.root(state);
-		this.alepha.store.set("alepha.react.router.state", state);
-		this.serverTimingProvider.beginTiming("renderToString");
-		let app = "";
-		try {
-			app = renderToString(element);
-		} catch (error) {
-			this.log.error("renderToString has failed, fallback to error handler", error);
-			const element$1 = state.onError(error, state);
-			if (element$1 instanceof Redirection) return element$1;
-			app = renderToString(element$1);
-			this.log.debug("Error handled successfully with fallback");
-		}
-		this.serverTimingProvider.endTiming("renderToString");
-		const response = { html: template };
-		if (hydration) {
-			const { request, context, ...store } = this.alepha.context.als?.getStore() ?? {};
-			const hydrationData = {
-				...store,
-				"alepha.react.router.state": void 0,
-				layers: state.layers.map((it) => ({
-					...it,
-					error: it.error ? {
-						...it.error,
-						name: it.error.name,
-						message: it.error.message,
-						stack: !this.alepha.isProduction() ? it.error.stack : void 0
-					} : void 0,
-					index: void 0,
-					path: void 0,
-					element: void 0,
-					route: void 0
-				}))
-			};
-			const script = `<script>window.__ssr=${JSON.stringify(hydrationData)}<\/script>`;
-			this.fillTemplate(response, app, script);
+	/**
+	* 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) {
+		this.serverTimingProvider.beginTiming("createLayers");
+		const { redirect } = await this.pageApi.createLayers(route, state);
+		this.serverTimingProvider.endTiming("createLayers");
+		if (redirect) {
+			this.log.debug("Resolver resulted in redirection", { redirect });
+			return { redirect };
 		}
-		return response.html;
-	}
-	preprocessTemplate(template) {
-		const bodyCloseIndex = template.match(/<\/body>/i)?.index ?? template.length;
-		const beforeScript = template.substring(0, bodyCloseIndex);
-		const afterScript = template.substring(bodyCloseIndex);
-		const rootDivMatch = beforeScript.match(this.ROOT_DIV_REGEX);
-		if (rootDivMatch) {
-			const beforeDiv = beforeScript.substring(0, rootDivMatch.index);
-			const afterDivStart = rootDivMatch.index + rootDivMatch[0].length;
-			const afterDiv = beforeScript.substring(afterDivStart);
-			return {
-				beforeApp: `${beforeDiv}<div${rootDivMatch[1]} id="${this.env.REACT_ROOT_ID}"${rootDivMatch[2]}>`,
-				afterApp: `</div>${afterDiv}`,
-				beforeScript: "",
-				afterScript
-			};
+		this.serverHeadProvider.fillHead(state);
+		const preloadLinks = this.ssrManifestProvider.collectPreloadLinks(route);
+		if (preloadLinks.length > 0) {
+			state.head ??= {};
+			state.head.link = [...state.head.link ?? [], ...preloadLinks];
 		}
-		const bodyMatch = beforeScript.match(/<body([^>]*)>/i);
-		if (bodyMatch) {
-			const beforeBody = beforeScript.substring(0, bodyMatch.index + bodyMatch[0].length);
-			const afterBody = beforeScript.substring(bodyMatch.index + bodyMatch[0].length);
-			return {
-				beforeApp: `${beforeBody}<div id="${this.env.REACT_ROOT_ID}">`,
-				afterApp: `</div>${afterBody}`,
-				beforeScript: "",
-				afterScript
-			};
+		this.serverTimingProvider.beginTiming("renderToStream");
+		const element = this.pageApi.root(state);
+		this.alepha.store.set("alepha.react.router.state", state);
+		const reactStream = await renderToReadableStream(element, { onError: (error) => {
+			if (error instanceof Redirection) this.log.warn("Redirect during streaming ignored", { redirect: error.redirect });
+			else this.log.error("Streaming render error", error);
+		} });
+		this.serverTimingProvider.endTiming("renderToStream");
+		return { reactStream };
+	}
+	/**
+	* 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 });
+		if (!this.templateProvider.isReady()) {
+			this.templateProvider.parseTemplate(this.template);
+			this.setupEarlyHeadContent();
 		}
+		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 {
-			beforeApp: `<div id="${this.env.REACT_ROOT_ID}">`,
-			afterApp: `</div>`,
-			beforeScript,
-			afterScript
+			state,
+			html
 		};
 	}
-	fillTemplate(response, app, script) {
-		if (!this.preprocessedTemplate) this.preprocessedTemplate = this.preprocessTemplate(response.html);
-		response.html = this.preprocessedTemplate.beforeApp + app + this.preprocessedTemplate.afterApp + script + this.preprocessedTemplate.afterScript;
+	/**
+	* 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/router/services/ReactPageServerService.ts
@@ -1774,6 +2536,7 @@ var ReactServerProvider = class {
 */
 var ReactPageServerService = class extends ReactPageService {
 	reactServerProvider = $inject(ReactServerProvider);
+	templateProvider = $inject(ReactServerTemplateProvider);
 	serverProvider = $inject(ServerProvider);
 	async render(name, options = {}) {
 		return this.reactServerProvider.render(name, options);
@@ -1785,9 +2548,9 @@ var ReactPageServerService = class extends ReactPageService {
 			html,
 			response
 		};
-		const match = html.match(this.reactServerProvider.ROOT_DIV_REGEX);
-		if (match) return {
-			html: match[3],
+		const rootContent = this.templateProvider.extractRootContent(html);
+		if (rootContent !== void 0) return {
+			html: rootContent,
 			response
 		};
 		throw new AlephaError("Invalid HTML response");
@@ -1911,7 +2674,7 @@ const decode = (alepha, schema, data) => {
 * - 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 `resolve` function
+* - Server-side data fetching with the `loader` function
 * - Lazy loading and code splitting
 * - Page animations and error handling
 *
@@ -1926,14 +2689,16 @@ const AlephaReactRouter = $module({
 		ReactPageService,
 		ReactRouter,
 		ReactServerProvider,
+		ReactServerTemplateProvider,
+		SSRManifestProvider,
 		ReactPageServerService
 	],
 	register: (alepha) => alepha.with(AlephaReact).with(AlephaDateTime).with(AlephaServer).with(AlephaServerCache).with(AlephaServerLinks).with({
 		provide: ReactPageService,
 		use: ReactPageServerService
-	}).with(ReactServerProvider).with(ReactPageProvider).with(ReactRouter)
+	}).with(SSRManifestProvider).with(ReactServerTemplateProvider).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, PagePrimitive, ReactBrowserProvider, ReactPageProvider, ReactPageService, ReactRouter, ReactServerProvider, Redirection, RouterLayerContext, isPageRoute, reactBrowserOptions, reactServerOptions, useActive, useQueryParams, useRouter, useRouterState };
+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, ReactRouter, ReactServerProvider, ReactServerTemplateProvider, Redirection, RouterLayerContext, SSRManifestProvider, isPageRoute, reactBrowserOptions, reactServerOptions, useActive, useQueryParams, useRouter, useRouterState };
 //# sourceMappingURL=index.js.map