@alepha/react 0.14.3 → 0.15.0

package/dist/router/index.d.ts

@@ -1,21 +1,20 @@
 import { ClientOnlyProps } from "@alepha/react";
-import * as alepha12 from "alepha";
+import * as alepha1 from "alepha";
 import { Alepha, AlephaError, Async, KIND, Primitive, Static, TObject, TSchema } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import * as alepha_logger0 from "alepha/logger";
 import { LinkProvider } from "alepha/server/links";
+import { BrowserHeadProvider, Head, ServerHeadProvider, SimpleHead } from "@alepha/react/head";
 import { Route, RouterProvider } from "alepha/router";
 import * as react0 from "react";
 import { AnchorHTMLAttributes, CSSProperties, FC, ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
-import * as alepha_server0 from "alepha/server";
 import { ServerHandler, ServerRequest, ServerRouterProvider, ServerTimingProvider } from "alepha/server";
+import { FileSystemProvider } from "alepha/file";
 import { ServerStaticProvider } from "alepha/server/static";
-import * as alepha_server_cache0 from "alepha/server/cache";
 import { ServerRouteCache } from "alepha/server/cache";
 
 //#region ../../src/router/errors/Redirection.d.ts
-
 /**
  * Used for Redirection during the page loading.
  *
@@ -26,7 +25,7 @@ import { ServerRouteCache } from "alepha/server/cache";
  * import { Redirection } from "@alepha/react";
  *
  * const MyPage = $page({
- *   resolve: async () => {
+ *   loader: async () => {
  *    if (needRedirect) {
  *      throw new Redirection("/new-path");
  *    }
@@ -40,11 +39,11 @@ declare class Redirection extends AlephaError {
 }
 //#endregion
 //#region ../../src/router/providers/ReactPageProvider.d.ts
-declare const envSchema$2: alepha12.TObject<{
-  REACT_STRICT_MODE: alepha12.TBoolean;
+declare const envSchema$1: alepha1.TObject<{
+  REACT_STRICT_MODE: alepha1.TBoolean;
 }>;
 declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema$2>> {}
+  interface Env extends Partial<Static<typeof envSchema$1>> {}
 }
 /**
  * Handle page routes for React applications. (Browser and Server)
@@ -70,10 +69,10 @@ declare class ReactPageProvider {
   root(state: ReactRouterState): ReactNode;
   protected convertStringObjectToObject: (schema?: TSchema, value?: any) => any;
   /**
-   * 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.
-   */
+       * 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.
+       */
   createLayers(route: PageRoute, state: ReactRouterState, previous?: PreviousLayerData[]): Promise<CreateLayersResult>;
   protected getErrorHandler(route: PageRoute): ErrorHandler | undefined;
   protected createElement(page: PageRoute, props: Record<string, any>): Promise<ReactNode>;
@@ -86,7 +85,7 @@ declare class ReactPageProvider {
   }, params?: Record<string, any>): string;
   compile(path: string, params?: Record<string, string>): string;
   protected renderView(index: number, path: string, view: ReactNode | undefined, page: PageRoute): ReactNode;
-  protected readonly configure: alepha12.HookPrimitive<"configure">;
+  protected readonly configure: alepha1.HookPrimitive<"configure">;
   protected map(pages: Array<PagePrimitive>, target: PagePrimitive): PageRouteEntry;
   add(entry: PageRouteEntry): void;
   protected createMatch(page: PageRoute): string;
@@ -99,9 +98,9 @@ interface PageRouteEntry extends Omit<PagePrimitiveOptions, "children" | "parent
 }
 interface ConcretePageRoute extends PageRoute {
   /**
-   * When exported, static routes can be split into multiple pages with different params.
-   * We replace 'name' by the new name for each static entry, and old 'name' becomes 'staticName'.
-   */
+       * When exported, static routes can be split into multiple pages with different params.
+       * We replace 'name' by the new name for each static entry, and old 'name' becomes 'staticName'.
+       */
   staticName?: string;
   params?: Record<string, string>;
 }
@@ -134,29 +133,34 @@ interface AnchorProps {
 }
 interface ReactRouterState {
   /**
-   * Stack of layers for the current page.
-   */
+       * Stack of layers for the current page.
+       */
   layers: Array<Layer>;
   /**
-   * URL of the current page.
-   */
+       * URL of the current page.
+       */
   url: URL;
   /**
-   * Error handler for the current page.
-   */
+       * Error handler for the current page.
+       */
   onError: ErrorHandler;
   /**
-   * Params extracted from the URL for the current page.
-   */
+       * Params extracted from the URL for the current page.
+       */
   params: Record<string, any>;
   /**
-   * Query parameters extracted from the URL for the current page.
-   */
+       * Query parameters extracted from the URL for the current page.
+       */
   query: Record<string, string>;
   /**
-   * Optional meta information associated with the current page.
-   */
+       * Optional meta information associated with the current page.
+       */
   meta: Record<string, any>;
+  /**
+       * Head configuration for the current page (title, meta tags, etc.).
+       * Populated by HeadProvider during SSR.
+       */
+  head: Head;
   name?: string;
 }
 interface RouterStackItem {
@@ -186,6 +190,14 @@ declare abstract class ReactPageService {
   render(name: string, options?: PagePrimitiveRenderOptions): Promise<PagePrimitiveRenderResult>;
 }
 //#endregion
+//#region ../../src/router/constants/PAGE_PRELOAD_KEY.d.ts
+/**
+ * Symbol key for SSR module preloading path.
+ * Using Symbol.for() allows the Vite plugin to inject this at build time.
+ * @internal
+ */
+declare const PAGE_PRELOAD_KEY: unique symbol;
+//#endregion
 //#region ../../src/router/primitives/$page.d.ts
 /**
  * Main primitive for defining a React route in the application.
@@ -199,7 +211,7 @@ declare abstract class ReactPageService {
  * - 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
  *
@@ -236,7 +248,7 @@ declare abstract class ReactPageService {
  *     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 };
  *   },
@@ -249,7 +261,7 @@ declare abstract class ReactPageService {
  * const projectSection = $page({
  *   path: "/projects/:id",
  *   children: () => [projectBoard, projectSettings],
- *   resolve: async ({ params }) => {
+ *   loader: async ({ params }) => {
  *     const project = await projectApi.get(params.id);
  *     return { project };
  *   },
@@ -268,7 +280,7 @@ declare abstract class ReactPageService {
  *   static: {
  *     entries: posts.map(p => ({ params: { slug: p.slug } }))
  *   },
- *   resolve: async ({ params }) => {
+ *   loader: async ({ params }) => {
  *     const post = await loadPost(params.slug);
  *     return { post };
  *   }
@@ -281,184 +293,215 @@ declare const $page: {
 };
 interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> {
   /**
-   * Identifier name for the page. Must be unique.
-   *
-   * @default Primitive key
-   */
+       * Identifier name for the page. Must be unique.
+       *
+       * @default Primitive key
+       */
   name?: string;
   /**
-   * Add a pathname to the page.
-   *
-   * Pathname can contain parameters, like `/post/:slug`.
-   *
-   * @default ""
-   */
+       * Add a pathname to the page.
+       *
+       * Pathname can contain parameters, like `/post/:slug`.
+       *
+       * @default ""
+       */
   path?: string;
   /**
-   * Add an input schema to define:
-   * - `params`: parameters from the pathname.
-   * - `query`: query parameters from the URL.
-   */
+       * Add an input schema to define:
+       * - `params`: parameters from the pathname.
+       * - `query`: query parameters from the URL.
+       */
   schema?: TConfig;
   /**
-   * Load data before rendering the page.
-   *
-   * This function receives
-   * - the request context (params, query, etc.)
-   * - the parent props (if page has a parent)
-   *
-   * > In SSR, the returned data will be serialized and sent to the client, then reused during the client-side hydration.
-   *
-   * Resolve can be stopped by throwing an error, which will be handled by the `errorHandler` function.
-   * It's common to throw a `NotFoundError` to display a 404 page.
-   *
-   * RedirectError can be thrown to redirect the user to another page.
-   */
-  resolve?: (context: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
-  /**
-   * Default props to pass to the component when rendering the page.
-   *
-   * Resolved props from the `resolve` function will override these default props.
-   */
+       * Load data before rendering the page.
+       *
+       * This function receives
+       * - the request context (params, query, etc.)
+       * - the parent props (if page has a parent)
+       *
+       * > In SSR, the returned data will be serialized and sent to the client, then reused during the client-side hydration.
+       *
+       * Loader can be stopped by throwing an error, which will be handled by the `errorHandler` function.
+       * It's common to throw a `NotFoundError` to display a 404 page.
+       *
+       * RedirectError can be thrown to redirect the user to another page.
+       */
+  loader?: (context: PageLoader<TConfig, TPropsParent>) => Async<TProps>;
+  /**
+       * Default props to pass to the component when rendering the page.
+       *
+       * Resolved props from the `resolve` function will override these default props.
+       */
   props?: () => Partial<TProps>;
   /**
-   * The component to render when the page is loaded.
-   *
-   * If `lazy` is defined, this will be ignored.
-   * Prefer using `lazy` to improve the initial loading time.
-   */
+       * The component to render when the page is loaded.
+       *
+       * If `lazy` is defined, this will be ignored.
+       * Prefer using `lazy` to improve the initial loading time.
+       */
   component?: FC<TProps & TPropsParent>;
   /**
-   * Lazy load the component when the page is loaded.
-   *
-   * It's recommended to use this for components to improve the initial loading time
-   * and enable code-splitting.
-   */
+       * Lazy load the component when the page is loaded.
+       *
+       * It's recommended to use this for components to improve the initial loading time
+       * and enable code-splitting.
+       */
   lazy?: () => Promise<{
     default: FC<TProps & TPropsParent>;
   }>;
   /**
-   * Attach child pages to create nested routes.
-   * This will make the page a parent route.
-   */
+       * Attach child pages to create nested routes.
+       * This will make the page a parent route.
+       */
   children?: Array<PagePrimitive> | (() => Array<PagePrimitive>);
   /**
-   * Define a parent page for nested routing.
-   */
+       * Define a parent page for nested routing.
+       */
   parent?: PagePrimitive<PageConfigSchema, TPropsParent, any>;
   /**
-   * Function to determine if the page can be accessed.
-   *
-   * If it returns false, the page will not be accessible and a 403 Forbidden error will be returned.
-   * This function can be used to implement permission-based access control.
-   */
+       * Function to determine if the page can be accessed.
+       *
+       * If it returns false, the page will not be accessible and a 403 Forbidden error will be returned.
+       * This function can be used to implement permission-based access control.
+       */
   can?: () => boolean;
   /**
-   * Catch any error from the `resolve` function or during `rendering`.
-   *
-   * Expected to return one of the following:
-   * - a ReactNode to render an error page
-   * - a Redirection to redirect the user
-   * - undefined to let the error propagate
-   *
-   * If not defined, the error will be thrown and handled by the server or client error handler.
-   * If a leaf $page does not define an error handler, the error can be caught by parent pages.
-   *
-   * @example Catch a 404 from API and render a custom not found component:
-   * ```ts
-   * resolve: async ({ params, query }) => {
-   *    api.fetch("/api/resource", { params, query });
-   * },
-   * errorHandler: (error, context) => {
-   *   if (HttpError.is(error, 404)) {
-   *     return <ResourceNotFound />;
-   *   }
-   * }
-   * ```
-   *
-   * @example Catch an 401 error and redirect the user to the login page:
-   * ```ts
-   * resolve: async ({ params, query }) => {
-   *   // but the user is not authenticated
-   *   api.fetch("/api/resource", { params, query });
-   * },
-   * errorHandler: (error, context) => {
-   *   if (HttpError.is(error, 401)) {
-   *     // throwing a Redirection is also valid!
-   *     return new Redirection("/login");
-   *   }
-   * }
-   * ```
-   */
+       * Catch any error from the `loader` function or during `rendering`.
+       *
+       * Expected to return one of the following:
+       * - a ReactNode to render an error page
+       * - a Redirection to redirect the user
+       * - undefined to let the error propagate
+       *
+       * If not defined, the error will be thrown and handled by the server or client error handler.
+       * If a leaf $page does not define an error handler, the error can be caught by parent pages.
+       *
+       * @example Catch a 404 from API and render a custom not found component:
+       * ```ts
+       * loader: async ({ params, query }) => {
+       *    api.fetch("/api/resource", { params, query });
+       * },
+       * errorHandler: (error, context) => {
+       *   if (HttpError.is(error, 404)) {
+       *     return <ResourceNotFound />;
+       *   }
+       * }
+       * ```
+       *
+       * @example Catch an 401 error and redirect the user to the login page:
+       * ```ts
+       * loader: async ({ params, query }) => {
+       *   // but the user is not authenticated
+       *   api.fetch("/api/resource", { params, query });
+       * },
+       * errorHandler: (error, context) => {
+       *   if (HttpError.is(error, 401)) {
+       *     // throwing a Redirection is also valid!
+       *     return new Redirection("/login");
+       *   }
+       * }
+       * ```
+       */
   errorHandler?: ErrorHandler;
   /**
-   * If true, the page will be considered as a static page, immutable and cacheable.
-   * Replace boolean by an object to define static entries. (e.g. list of params/query)
-   *
-   * Browser-side: it only works with `alepha/vite`, which can pre-render the page at build time.
-   *
-   * Server-side: It will act as timeless cached page. You can use `cache` to configure the cache behavior.
-   */
+       * If true, the page will be considered as a static page, immutable and cacheable.
+       * Replace boolean by an object to define static entries. (e.g. list of params/query)
+       *
+       * Browser-side: it only works with `alepha/vite`, which can pre-render the page at build time.
+       *
+       * Server-side: It will act as timeless cached page. You can use `cache` to configure the cache behavior.
+       */
   static?: boolean | {
     entries?: Array<Partial<PageRequestConfig<TConfig>>>;
   };
   cache?: ServerRouteCache;
   /**
-   * If true, force the page to be rendered only on the client-side (browser).
-   * It uses the `<ClientOnly/>` component to render the page.
-   */
+       * If true, force the page to be rendered only on the client-side (browser).
+       * It uses the `<ClientOnly/>` component to render the page.
+       */
   client?: boolean | ClientOnlyProps;
   /**
-   * Called before the server response is sent to the client. (server only)
-   */
+       * Called before the server response is sent to the client. (server only)
+       */
   onServerResponse?: (request: ServerRequest) => unknown;
   /**
-   * Called when user leaves the page. (browser only)
-   */
+       * Called when user leaves the page. (browser only)
+       */
   onLeave?: () => void;
   /**
-   * @experimental
-   *
-   * Add a css animation when the page is loaded or unloaded.
-   * It uses CSS animations, so you need to define the keyframes in your CSS.
-   *
-   * @example Simple animation name
-   * ```ts
-   * animation: "fadeIn"
-   * ```
-   *
-   * CSS example:
-   * ```css
-   * @keyframes fadeIn {
-   *  from { opacity: 0; }
-   *  to { opacity: 1; }
-   * }
-   * ```
-   *
-   * @example Detailed animation
-   * ```ts
-   * animation: {
-   *   enter: { name: "fadeIn", duration: 300 },
-   *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
-   * }
-   * ```
-   *
-   * @example Only exit animation
-   * ```ts
-   * animation: {
-   *   exit: "fadeOut"
-   * }
-   * ```
-   *
-   * @example With custom timing function
-   * ```ts
-   * animation: {
-   *   enter: { name: "fadeIn", duration: 300, timing: "cubic-bezier(0.4, 0, 0.2, 1)" },
-   *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
-   * }
-   * ```
-   */
+       * @experimental
+       *
+       * Add a css animation when the page is loaded or unloaded.
+       * It uses CSS animations, so you need to define the keyframes in your CSS.
+       *
+       * @example Simple animation name
+       * ```ts
+       * animation: "fadeIn"
+       * ```
+       *
+       * CSS example:
+       * ```css
+       * @keyframes fadeIn {
+       *  from { opacity: 0; }
+       *  to { opacity: 1; }
+       * }
+       * ```
+       *
+       * @example Detailed animation
+       * ```ts
+       * animation: {
+       *   enter: { name: "fadeIn", duration: 300 },
+       *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
+       * }
+       * ```
+       *
+       * @example Only exit animation
+       * ```ts
+       * animation: {
+       *   exit: "fadeOut"
+       * }
+       * ```
+       *
+       * @example With custom timing function
+       * ```ts
+       * animation: {
+       *   enter: { name: "fadeIn", duration: 300, timing: "cubic-bezier(0.4, 0, 0.2, 1)" },
+       *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
+       * }
+       * ```
+       */
   animation?: PageAnimation;
+  /**
+       * Head configuration for the page (title, meta tags, etc.).
+       *
+       * Can be a static object or a function that receives resolved props.
+       *
+       * @example Static head
+       * ```ts
+       * head: {
+       *   title: "My Page",
+       *   description: "Page description",
+       * }
+       * ```
+       *
+       * @example Dynamic head based on props
+       * ```ts
+       * head: (props) => ({
+       *   title: props.user.name,
+       *   description: `Profile of ${props.user.name}`,
+       * })
+       * ```
+       */
+  head?: Head | ((props: TProps, previous?: Head) => Head);
+  /**
+       * Source path for SSR module preloading.
+       *
+       * This is automatically injected by the viteAlephaPreload plugin.
+       * It maps to the source file path used in Vite's SSR manifest.
+       *
+       * @internal
+       */
+  [PAGE_PRELOAD_KEY]?: string;
 }
 type ErrorHandler = (error: Error, state: ReactRouterState) => ReactNode | Redirection | undefined;
 declare class PagePrimitive<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> extends Primitive<PagePrimitiveOptions<TConfig, TProps, TPropsParent>> {
@@ -466,11 +509,11 @@ declare class PagePrimitive<TConfig extends PageConfigSchema = PageConfigSchema,
   protected onInit(): void;
   get name(): string;
   /**
-   * 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.
-   */
+       * 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.
+       */
   render(options?: PagePrimitiveRenderOptions): Promise<PagePrimitiveRenderResult>;
   fetch(options?: PagePrimitiveRenderOptions): Promise<{
     html: string;
@@ -489,11 +532,11 @@ interface PagePrimitiveRenderOptions {
   params?: Record<string, string>;
   query?: Record<string, string>;
   /**
-   * If true, the HTML layout will be included in the response.
-   * If false, only the page content will be returned.
-   *
-   * @default true
-   */
+       * If true, the HTML layout will be included in the response.
+       * If false, only the page content will be returned.
+       *
+       * @default true
+       */
   html?: boolean;
   hydration?: boolean;
 }
@@ -506,7 +549,7 @@ interface PageRequestConfig<TConfig extends PageConfigSchema = PageConfigSchema>
   params: TConfig["params"] extends TSchema ? Static<TConfig["params"]> : Record<string, string>;
   query: TConfig["query"] extends TSchema ? Static<TConfig["query"]> : Record<string, string>;
 }
-type PageResolve<TConfig extends PageConfigSchema = PageConfigSchema, TPropsParent extends object = TPropsParentDefault> = PageRequestConfig<TConfig> & TPropsParent & Omit<ReactRouterState, "layers" | "onError">;
+type PageLoader<TConfig extends PageConfigSchema = PageConfigSchema, TPropsParent extends object = TPropsParentDefault> = PageRequestConfig<TConfig> & TPropsParent & Omit<ReactRouterState, "layers" | "onError">;
 type PageAnimation = PageAnimationObject | ((state: ReactRouterState) => PageAnimationObject | undefined);
 type PageAnimationObject = CssAnimationName | {
   enter?: CssAnimation | CssAnimationName;
@@ -530,67 +573,13 @@ declare class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
   protected readonly log: alepha_logger0.Logger;
   protected readonly alepha: Alepha;
   protected readonly pageApi: ReactPageProvider;
+  protected readonly browserHeadProvider: BrowserHeadProvider;
   add(entry: PageRouteEntry): void;
-  protected readonly configure: alepha12.HookPrimitive<"configure">;
+  protected readonly configure: alepha1.HookPrimitive<"configure">;
   transition(url: URL, previous?: PreviousLayerData[], meta?: {}): Promise<string | void>;
   root(state: ReactRouterState): ReactNode;
 }
 //#endregion
-//#region ../../src/core/components/ClientOnly.d.ts
-interface ClientOnlyProps$1 {
-  fallback?: ReactNode;
-  disabled?: boolean;
-}
-//#endregion
-//#region ../../src/core/index.d.ts
-declare module "alepha" {
-  interface Hooks {
-    /**
-     * Fires when a user action is starting.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:begin": {
-      type: string;
-      id?: string;
-    };
-    /**
-     * Fires when a user action has succeeded.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:success": {
-      type: string;
-      id?: string;
-    };
-    /**
-     * Fires when a user action has failed.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:error": {
-      type: string;
-      id?: string;
-      error: Error;
-    };
-    /**
-     * Fires when a user action has completed, regardless of success or failure.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:end": {
-      type: string;
-      id?: string;
-    };
-  }
-}
-/**
- * Provides full-stack React development with declarative routing, server-side rendering, and client-side hydration.
- *
- * The React module enables building modern React applications using the `$page` primitive on class properties.
- * It delivers seamless server-side rendering, automatic code splitting, and client-side navigation with full
- * type safety and schema validation for route parameters and data.
- *
- * @see {@link $page}
- * @module alepha.react
- */
-//#endregion
 //#region ../../src/router/services/ReactRouter.d.ts
 interface RouterGoOptions {
   replace?: boolean;
@@ -598,8 +587,8 @@ interface RouterGoOptions {
   query?: Record<string, string>;
   meta?: Record<string, any>;
   /**
-   * Recreate the whole page, ignoring the current state.
-   */
+       * Recreate the whole page, ignoring the current state.
+       */
   force?: boolean;
 }
 /**
@@ -607,7 +596,7 @@ interface RouterGoOptions {
  *
  * Can be safely used server-side, but most methods will be no-op.
  */
-declare class ReactRouter<T$1 extends object> {
+declare class ReactRouter<T extends object> {
   protected readonly alepha: Alepha;
   protected readonly pageApi: ReactPageProvider;
   get state(): ReactRouterState;
@@ -617,69 +606,18 @@ declare class ReactRouter<T$1 extends object> {
   isActive(href: string, options?: {
     startWith?: boolean;
   }): boolean;
-  node(name: keyof VirtualRouter<T$1> | string, config?: {
+  node(name: keyof VirtualRouter<T> | string, config?: {
     params?: Record<string, any>;
     query?: Record<string, any>;
-  }): {
-    label: any;
-    children: undefined;
-    type: "page";
-    name: string;
-    parent?: PageRoute;
-    match: string;
-    path?: string | undefined;
-    schema?: PageConfigSchema | undefined;
-    resolve?: ((context: PageResolve<PageConfigSchema, TPropsParentDefault>) => any) | undefined;
-    props?: (() => Partial<any>) | undefined;
-    component?: react0.FC<any> | undefined;
-    lazy?: (() => Promise<{
-      default: react0.FC<any>;
-    }>) | undefined;
-    can?: (() => boolean) | undefined;
-    errorHandler?: ErrorHandler | undefined;
-    static?: boolean | {
-      entries?: Partial<PageRequestConfig<PageConfigSchema>>[] | undefined;
-    } | undefined;
-    cache?: alepha_server_cache0.ServerRouteCache | undefined;
-    client?: (boolean | ClientOnlyProps$1) | undefined;
-    onServerResponse?: ((request: alepha_server0.ServerRequest) => unknown) | undefined;
-    onLeave?: (() => void) | undefined;
-    animation?: PageAnimation | undefined;
-  } | {
-    label: any;
-    href: string;
-    children: undefined;
-    type: "page";
-    name: string;
-    parent?: PageRoute;
-    match: string;
-    path?: string | undefined;
-    schema?: PageConfigSchema | undefined;
-    resolve?: ((context: PageResolve<PageConfigSchema, TPropsParentDefault>) => any) | undefined;
-    props?: (() => Partial<any>) | undefined;
-    component?: react0.FC<any> | undefined;
-    lazy?: (() => Promise<{
-      default: react0.FC<any>;
-    }>) | undefined;
-    can?: (() => boolean) | undefined;
-    errorHandler?: ErrorHandler | undefined;
-    static?: boolean | {
-      entries?: Partial<PageRequestConfig<PageConfigSchema>>[] | undefined;
-    } | undefined;
-    cache?: alepha_server_cache0.ServerRouteCache | undefined;
-    client?: (boolean | ClientOnlyProps$1) | undefined;
-    onServerResponse?: ((request: alepha_server0.ServerRequest) => unknown) | undefined;
-    onLeave?: (() => void) | undefined;
-    animation?: PageAnimation | undefined;
-  };
-  path(name: keyof VirtualRouter<T$1> | string, config?: {
+  }): any;
+  path(name: keyof VirtualRouter<T> | string, config?: {
     params?: Record<string, any>;
     query?: Record<string, any>;
   }): string;
   /**
-   * Reload the current page.
-   * This is equivalent to calling `go()` with the current pathname and search.
-   */
+       * Reload the current page.
+       * This is equivalent to calling `go()` with the current pathname and search.
+       */
   reload(): Promise<void>;
   getURL(): URL;
   get location(): Location;
@@ -690,37 +628,31 @@ declare class ReactRouter<T$1 extends object> {
   forward(): Promise<void>;
   invalidate(props?: Record<string, any>): Promise<void>;
   go(path: string, options?: RouterGoOptions): Promise<void>;
-  go(path: keyof VirtualRouter<T$1>, options?: RouterGoOptions): Promise<void>;
+  go(path: keyof VirtualRouter<T>, options?: RouterGoOptions): Promise<void>;
   anchor(path: string, options?: RouterGoOptions): AnchorProps;
-  anchor(path: keyof VirtualRouter<T$1>, options?: RouterGoOptions): AnchorProps;
+  anchor(path: keyof VirtualRouter<T>, options?: RouterGoOptions): AnchorProps;
   base(path: string): string;
   /**
-   * Set query params.
-   *
-   * @param record
-   * @param options
-   */
+       * Set query params.
+       *
+       * @param record
+       * @param options
+       */
   setQueryParams(record: Record<string, any> | ((queryParams: Record<string, any>) => Record<string, any>), options?: {
     /**
-     * If true, this will add a new entry to the history stack.
-     */
+             * If true, this will add a new entry to the history stack.
+             */
     push?: boolean;
   }): void;
 }
-type VirtualRouter<T$1> = { [K in keyof T$1 as T$1[K] extends PagePrimitive ? K : never]: T$1[K] };
+type VirtualRouter<T> = { [K in keyof T as T[K] extends PagePrimitive ? K : never]: T[K] };
 //#endregion
 //#region ../../src/router/providers/ReactBrowserProvider.d.ts
-declare const envSchema$1: alepha12.TObject<{
-  REACT_ROOT_ID: alepha12.TString;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema$1>> {}
-}
 /**
  * React browser renderer configuration atom
  */
-declare const reactBrowserOptions: alepha12.Atom<alepha12.TObject<{
-  scrollRestoration: alepha12.TUnsafe<"top" | "manual">;
+declare const reactBrowserOptions: alepha1.Atom<alepha1.TObject<{
+  scrollRestoration: alepha1.TUnsafe<"top" | "manual">;
 }>, "alepha.react.browser.options">;
 type ReactBrowserRendererOptions = Static<typeof reactBrowserOptions.schema>;
 declare module "alepha" {
@@ -729,17 +661,16 @@ declare module "alepha" {
   }
 }
 declare class ReactBrowserProvider {
-  protected readonly env: {
-    REACT_ROOT_ID: string;
-  };
   protected readonly log: alepha_logger0.Logger;
   protected readonly client: LinkProvider;
   protected readonly alepha: Alepha;
   protected readonly router: ReactBrowserRouterProvider;
   protected readonly dateTimeProvider: DateTimeProvider;
+  protected readonly browserHeadProvider: BrowserHeadProvider;
   protected readonly options: Readonly<{
     scrollRestoration: "top" | "manual";
   }>;
+  get rootId(): string;
   protected getRootElement(): HTMLElement;
   transitioning?: {
     to: string;
@@ -747,16 +678,16 @@ declare class ReactBrowserProvider {
   };
   get state(): ReactRouterState;
   /**
-   * Accessor for Document DOM API.
-   */
+       * Accessor for Document DOM API.
+       */
   get document(): Document;
   /**
-   * Accessor for History DOM API.
-   */
+       * Accessor for History DOM API.
+       */
   get history(): History;
   /**
-   * Accessor for Location DOM API.
-   */
+       * Accessor for Location DOM API.
+       */
   get location(): Location;
   get base(): string;
   get url(): string;
@@ -765,11 +696,11 @@ declare class ReactBrowserProvider {
   go(url: string, options?: RouterGoOptions): Promise<void>;
   protected render(options?: RouterRenderOptions): Promise<void>;
   /**
-   * Get embedded layers from the server.
-   */
+       * Get embedded layers from the server.
+       */
   protected getHydrationState(): ReactHydrationState | undefined;
-  protected readonly onTransitionEnd: alepha12.HookPrimitive<"react:transition:end">;
-  readonly ready: alepha12.HookPrimitive<"ready">;
+  protected readonly onTransitionEnd: alepha1.HookPrimitive<"react:transition:end">;
+  readonly ready: alepha1.HookPrimitive<"ready">;
 }
 type ReactHydrationState = {
   layers?: Array<PreviousLayerData>;
@@ -1138,7 +1069,7 @@ interface UseActiveHook {
 /**
  * Hook to manage query parameters in the URL using a defined schema.
  */
-declare const useQueryParams: <T$1 extends TObject>(schema: T$1, options?: UseQueryParamsHookOptions) => [Partial<Static<T$1>>, (data: Static<T$1>) => void];
+declare const useQueryParams: <T extends TObject>(schema: T, options?: UseQueryParamsHookOptions) => [Partial<Static<T>>, (data: Static<T>) => void];
 interface UseQueryParamsHookOptions {
   format?: "base64" | "querystring";
   key?: string;
@@ -1160,57 +1091,484 @@ interface UseQueryParamsHookOptions {
  * const router = useRouter<App>();
  * router.go("home"); // typesafe
  */
-declare const useRouter: <T$1 extends object = any>() => ReactRouter<T$1>;
+declare const useRouter: <T extends object = any>() => ReactRouter<T>;
 //#endregion
 //#region ../../src/router/hooks/useRouterState.d.ts
 declare const useRouterState: () => ReactRouterState;
 //#endregion
-//#region ../../src/router/providers/ReactServerProvider.d.ts
-declare const envSchema: alepha12.TObject<{
-  REACT_SSR_ENABLED: alepha12.TOptional<alepha12.TBoolean>;
-  REACT_ROOT_ID: alepha12.TString;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-  interface State {
-    "alepha.react.server.ssr"?: boolean;
-    "alepha.react.server.template"?: string;
-  }
+//#region ../../src/router/providers/ReactServerTemplateProvider.d.ts
+/**
+ * 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.
+ */
+declare class ReactServerTemplateProvider {
+  protected readonly log: alepha_logger0.Logger;
+  protected readonly alepha: Alepha;
+  /**
+       * Shared TextEncoder instance - reused across all requests.
+       */
+  protected readonly encoder: TextEncoder;
+  /**
+       * Pre-encoded common strings for streaming.
+       */
+  protected readonly ENCODED: {
+    readonly HYDRATION_PREFIX: Uint8Array<ArrayBuffer>;
+    readonly HYDRATION_SUFFIX: Uint8Array<ArrayBuffer>;
+    readonly EMPTY: Uint8Array<ArrayBuffer>;
+  };
+  /**
+       * Cached template slots - parsed once, reused for all requests.
+       */
+  protected slots: TemplateSlots | null;
+  /**
+       * Root element ID for React mounting.
+       */
+  get rootId(): string;
+  /**
+       * Regex pattern for matching the root div and extracting its content.
+       */
+  get rootDivRegex(): RegExp;
+  /**
+       * 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: string): string | undefined;
+  /**
+       * Check if template has been parsed and slots are available.
+       */
+  isReady(): boolean;
+  /**
+       * Get the parsed template slots.
+       * Throws if template hasn't been parsed yet.
+       */
+  getSlots(): TemplateSlots;
+  /**
+       * 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: string): TemplateSlots;
+  /**
+       * Parse HTML attributes string into a record.
+       *
+       * Handles: key="value", key='value', key=value, and boolean key
+       */
+  protected parseAttributes(attrStr: string): Record<string, string>;
+  /**
+       * Render attributes record to HTML string.
+       *
+       * @param attrs - Attributes to render
+       * @returns HTML attribute string like ` lang="en" class="dark"`
+       */
+  renderAttributes(attrs: Record<string, string>): string;
+  /**
+       * Render merged HTML attributes (original + dynamic).
+       */
+  renderMergedHtmlAttrs(dynamicAttrs?: Record<string, string>): string;
+  /**
+       * Render merged body attributes (original + dynamic).
+       */
+  renderMergedBodyAttrs(dynamicAttrs?: Record<string, string>): string;
+  /**
+       * 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?: SimpleHead, includeOriginal?: boolean): string;
+  /**
+       * Render a meta tag.
+       */
+  protected renderMetaTag(meta: {
+    name?: string;
+    property?: string;
+    content: string;
+  }): string;
+  /**
+       * Render a link tag.
+       */
+  protected renderLinkTag(link: {
+    rel: string;
+    href: string;
+    as?: string;
+    crossorigin?: string;
+  }): string;
+  /**
+       * Render a script tag.
+       */
+  protected renderScriptTag(script: Record<string, string | boolean>): string;
+  /**
+       * Escape HTML special characters.
+       */
+  escapeHtml(str: string): string;
+  /**
+       * Safely serialize data to JSON for embedding in HTML.
+       * Escapes characters that could break out of script tags.
+       */
+  safeJsonSerialize(data: unknown): string;
+  /**
+       * Build hydration data from router state.
+       *
+       * This creates the data structure that will be serialized to window.__ssr
+       * for client-side rehydration.
+       */
+  buildHydrationData(state: ReactRouterState): HydrationData;
+  /**
+       * Encode a string to Uint8Array using the shared encoder.
+       */
+  encode(str: string): Uint8Array;
+  /**
+       * Get the pre-encoded hydration script prefix.
+       */
+  get hydrationPrefix(): Uint8Array;
+  /**
+       * Get the pre-encoded hydration script suffix.
+       */
+  get hydrationSuffix(): Uint8Array;
+  /**
+       * 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: ReadableStream<Uint8Array>, state: ReactRouterState, options?: {
+    hydration?: boolean;
+    onError?: (error: unknown) => void;
+  }): ReadableStream<Uint8Array>;
+  /**
+       * Early head content for preloading.
+       *
+       * Contains entry assets (JS + CSS) that are always required and can be
+       * sent before page loaders run.
+       */
+  protected earlyHeadContent: string;
+  /**
+       * 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: string, entryAssets?: {
+    js?: string;
+    css: string[];
+  }): void;
+  /**
+       * Escape special regex characters in a string.
+       */
+  protected escapeRegExp(str: string): string;
+  /**
+       * 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: SimpleHead, asyncWork: () => Promise<{
+    state: ReactRouterState;
+    reactStream: ReadableStream<Uint8Array>;
+  } | {
+    redirect: string;
+  } | null>, options?: {
+    hydration?: boolean;
+    onError?: (error: unknown) => void;
+  }): ReadableStream<Uint8Array>;
 }
 /**
- * React server provider configuration atom
+ * Template slots - the template split into logical parts for efficient streaming.
+ *
+ * Static parts are pre-encoded as Uint8Array for zero-copy streaming.
+ * Dynamic parts (attributes, head content) are kept as strings/objects for merging.
+ */
+interface TemplateSlots {
+  doctype: Uint8Array;
+  htmlOpen: Uint8Array;
+  htmlClose: Uint8Array;
+  headOpen: Uint8Array;
+  headClose: Uint8Array;
+  bodyOpen: Uint8Array;
+  bodyClose: Uint8Array;
+  rootOpen: Uint8Array;
+  rootClose: Uint8Array;
+  scriptClose: Uint8Array;
+  htmlOriginalAttrs: Record<string, string>;
+  bodyOriginalAttrs: Record<string, string>;
+  headOriginalContent: string;
+  beforeRoot: string;
+  afterRoot: string;
+}
+/**
+ * Hydration state that gets serialized to window.__ssr
  */
-declare const reactServerOptions: alepha12.Atom<alepha12.TObject<{
-  publicDir: alepha12.TString;
-  staticServer: alepha12.TObject<{
-    disabled: alepha12.TBoolean;
-    path: alepha12.TString;
+interface HydrationData {
+  layers: Array<{
+    data?: unknown;
+    error?: {
+      name: string;
+      message: string;
+      stack?: string;
+    };
+  }>;
+  [key: string]: unknown;
+}
+//#endregion
+//#region ../../src/router/atoms/ssrManifestAtom.d.ts
+/**
+ * Schema for the SSR manifest atom.
+ */
+declare const ssrManifestAtomSchema: alepha1.TObject<{
+  /**
+       * Preload manifest mapping short keys to source paths.
+       * Generated by viteAlephaSsrPreload plugin at build time.
+       */
+  preload: alepha1.TOptional<alepha1.TRecord<"^.*$", alepha1.TString>>;
+  /**
+       * SSR manifest mapping source files to their required chunks.
+       */
+  ssr: alepha1.TOptional<alepha1.TRecord<"^.*$", alepha1.TArray<alepha1.TString>>>;
+  /**
+       * Client manifest mapping source files to their output information.
+       */
+  client: alepha1.TOptional<alepha1.TRecord<"^.*$", alepha1.TObject<{
+    file: alepha1.TString;
+    src: alepha1.TOptional<alepha1.TString>;
+    isEntry: alepha1.TOptional<alepha1.TBoolean>;
+    isDynamicEntry: alepha1.TOptional<alepha1.TBoolean>;
+    imports: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
+    dynamicImports: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
+    css: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
+    assets: alepha1.TOptional<alepha1.TArray<alepha1.TString>>;
+  }>>>;
+}>;
+/**
+ * Type for the SSR manifest schema.
+ */
+type SsrManifestAtomSchema = typeof ssrManifestAtomSchema;
+//#endregion
+//#region ../../src/router/providers/SSRManifestProvider.d.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)
+ */
+declare class SSRManifestProvider {
+  protected readonly alepha: Alepha;
+  /**
+       * Get the manifest from the store at runtime.
+       * This ensures the manifest is available even when set after module load.
+       */
+  protected get manifest(): Static<SsrManifestAtomSchema>;
+  /**
+       * Get the preload manifest.
+       */
+  protected get preloadManifest(): PreloadManifest | undefined;
+  /**
+       * Get the SSR manifest.
+       */
+  protected get ssrManifest(): SSRManifest | undefined;
+  /**
+       * Get the client manifest.
+       */
+  protected get clientManifest(): ClientManifest | undefined;
+  /**
+       * 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: string): string | undefined;
+  /**
+       * 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: string): string[];
+  /**
+       * Find manifest entry for a source path, trying different extensions.
+       */
+  protected findManifestEntry(sourcePath: string): {
+    file: string;
+    src?: string;
+    isEntry?: boolean;
+    isDynamicEntry?: boolean;
+    imports?: string[];
+    dynamicImports?: string[];
+    css?: string[];
+    assets?: string[];
+  } | undefined;
+  /**
+       * Recursively collect all chunk URLs for a manifest entry.
+       */
+  protected collectChunksRecursive(key: string, chunks: Set<string>, visited: Set<string>): void;
+  /**
+       * Fallback to SSR manifest for chunk lookup.
+       */
+  protected getChunksFromSSRManifest(sourcePath: string): string[];
+  /**
+       * Collect modulepreload links for a route and its parent chain.
+       */
+  collectPreloadLinks(route: PageRoute): Array<{
+    rel: string;
+    href: string;
+    as?: string;
+    crossorigin?: string;
+  }>;
+  /**
+       * Get all chunks for multiple source files.
+       *
+       * @param sourcePaths - Array of source file paths
+       * @returns Deduplicated array of chunk URLs
+       */
+  getChunksForMultiple(sourcePaths: string[]): string[];
+  /**
+       * Check if manifests are loaded and available.
+       */
+  isAvailable(): boolean;
+  /**
+       * Cached entry assets - computed once at first access.
+       */
+  protected cachedEntryAssets: EntryAssets | 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(): EntryAssets | null;
+  /**
+       * Build preload link tags for entry assets.
+       *
+       * @returns Array of link objects ready to be rendered
+       */
+  getEntryPreloadLinks(): Array<{
+    rel: string;
+    href: string;
+    as?: string;
+    crossorigin?: string;
   }>;
-}>, "alepha.react.server.options">;
-type ReactServerProviderOptions = Static<typeof reactServerOptions.schema>;
-declare module "alepha" {
-  interface State {
-    [reactServerOptions.key]: ReactServerProviderOptions;
-  }
 }
+/**
+ * Entry assets structure containing the main entry JS and associated CSS files.
+ */
+interface EntryAssets {
+  /** Main entry JavaScript file (e.g., "/assets/entry.abc123.js") */
+  js?: string;
+  /** Associated CSS files (e.g., ["/assets/style.abc123.css"]) */
+  css: string[];
+}
+/**
+ * SSR Manifest structure from Vite.
+ * Maps source file paths to their required chunks/assets.
+ */
+type SSRManifest = Record<string, string[]>;
+/**
+ * Client manifest structure from Vite.
+ * Maps source files to their output information.
+ */
+interface ClientManifest {
+  [key: string]: {
+    file: string;
+    src?: string;
+    isEntry?: boolean;
+    isDynamicEntry?: boolean;
+    imports?: string[];
+    dynamicImports?: string[];
+    css?: string[];
+    assets?: string[];
+  };
+}
+/**
+ * Preload manifest mapping short keys to source paths.
+ * Generated by viteAlephaSsrPreload plugin at build time.
+ */
+type PreloadManifest = Record<string, string>;
+//#endregion
+//#region ../../src/router/providers/ReactServerProvider.d.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.
  */
 declare class ReactServerProvider {
+  /**
+       * SSR response headers - pre-allocated to avoid object creation per request.
+       */
+  protected readonly SSR_HEADERS: {
+    readonly "content-type": "text/html";
+    readonly "cache-control": "no-store, no-cache, must-revalidate, proxy-revalidate";
+    readonly pragma: "no-cache";
+    readonly expires: "0";
+  };
+  protected readonly fs: FileSystemProvider;
   protected readonly log: alepha_logger0.Logger;
   protected readonly alepha: Alepha;
   protected readonly env: {
     REACT_SSR_ENABLED?: boolean | undefined;
-    REACT_ROOT_ID: string;
   };
   protected readonly pageApi: ReactPageProvider;
+  protected readonly templateProvider: ReactServerTemplateProvider;
+  protected readonly serverHeadProvider: ServerHeadProvider;
   protected readonly serverStaticProvider: ServerStaticProvider;
   protected readonly serverRouterProvider: ServerRouterProvider;
   protected readonly serverTimingProvider: ServerTimingProvider;
-  readonly ROOT_DIV_REGEX: RegExp;
-  protected preprocessedTemplate: PreprocessedTemplate | null;
+  protected readonly ssrManifestProvider: SSRManifestProvider;
+  /**
+       * Cached check for ServerLinksProvider - avoids has() lookup per request.
+       */
+  protected hasServerLinksProvider: boolean;
   protected readonly options: Readonly<{
     publicDir: string;
     staticServer: {
@@ -1219,40 +1577,103 @@ declare class ReactServerProvider {
     };
   }>;
   /**
-   * Configure the React server provider.
-   */
-  readonly onConfigure: alepha12.HookPrimitive<"configure">;
+       * Configure the React server provider.
+       */
+  readonly onConfigure: alepha1.HookPrimitive<"configure">;
+  /**
+       * Get the current HTML template.
+       */
   get template(): string;
+  /**
+       * Register all pages as server routes.
+       */
   protected registerPages(templateLoader: TemplateLoader): Promise<void>;
   /**
-   * Get the public directory path where static files are located.
-   */
-  protected getPublicDirectory(): string;
+       * 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.
+       */
+  protected setupEarlyHeadContent(): void;
+  /**
+       * Get the public directory path where static files are located.
+       */
+  protected getPublicDirectory(): Promise<string>;
   /**
-   * Configure the static file server to serve files from the given root directory.
-   */
+       * Configure the static file server to serve files from the given root directory.
+       */
   protected configureStaticServer(root: string): Promise<void>;
   /**
-   * Configure Vite for SSR.
-   */
+       * Configure Vite for SSR in development mode.
+       */
   protected configureVite(ssrEnabled: boolean): Promise<void>;
   /**
-   * For testing purposes, creates a render function that can be used.
-   */
-  render(name: string, options?: PagePrimitiveRenderOptions): Promise<PagePrimitiveRenderResult>;
+       * Create the request handler for a page route.
+       */
   protected createHandler(route: PageRoute, templateLoader: TemplateLoader): ServerHandler;
-  renderToHtml(template: string, state: ReactRouterState, hydration?: boolean): string | Redirection;
-  protected preprocessTemplate(template: string): PreprocessedTemplate;
-  protected fillTemplate(response: {
-    html: string;
-  }, app: string, script: string): void;
+  /**
+       * 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
+       */
+  protected renderPage(route: PageRoute, state: ReactRouterState): Promise<{
+    redirect?: string;
+    reactStream?: ReadableStream<Uint8Array>;
+  }>;
+  /**
+       * 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)
+       */
+  render(name: string, options?: PagePrimitiveRenderOptions): Promise<PagePrimitiveRenderResult>;
+  /**
+       * Collect a ReadableStream into a string.
+       */
+  protected streamToString(stream: ReadableStream<Uint8Array>): Promise<string>;
 }
 type TemplateLoader = () => Promise<string | undefined>;
-interface PreprocessedTemplate {
-  beforeApp: string;
-  afterApp: string;
-  beforeScript: string;
-  afterScript: string;
+declare const envSchema: alepha1.TObject<{
+  REACT_SSR_ENABLED: alepha1.TOptional<alepha1.TBoolean>;
+}>;
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+  interface State {
+    "alepha.react.server.ssr"?: boolean;
+    "alepha.react.server.template"?: string;
+  }
+}
+/**
+ * React server provider configuration atom
+ */
+declare const reactServerOptions: alepha1.Atom<alepha1.TObject<{
+  publicDir: alepha1.TString;
+  staticServer: alepha1.TObject<{
+    disabled: alepha1.TBoolean;
+    path: alepha1.TString;
+  }>;
+}>, "alepha.react.server.options">;
+type ReactServerProviderOptions = Static<typeof reactServerOptions.schema>;
+declare module "alepha" {
+  interface State {
+    [reactServerOptions.key]: ReactServerProviderOptions;
+  }
 }
 //#endregion
 //#region ../../src/router/index.d.ts
@@ -1262,23 +1683,26 @@ declare module "alepha" {
   }
   interface Hooks {
     /**
-     * Fires when the React application is starting to be rendered on the server.
-     */
+             * Fires when the React application is starting to be rendered on the server.
+             */
     "react:server:render:begin": {
       request?: ServerRequest;
       state: ReactRouterState;
     };
     /**
-     * Fires when the React application has been rendered on the server.
-     */
+             * Fires when the React application has been rendered on the server.
+             */
     "react:server:render:end": {
       request?: ServerRequest;
       state: ReactRouterState;
       html: string;
     };
     /**
-     * Fires when the React application is being rendered on the browser.
-     */
+             * Fires when the React application is being rendered on the browser.
+             *
+             * Note: this one is not really necessary, it's a hack because we need to isolate renderer from server code in order
+             * to avoid including react-dom/client in server bundles.
+             */
     "react:browser:render": {
       root: HTMLElement;
       element: ReactNode;
@@ -1286,29 +1710,29 @@ declare module "alepha" {
       hydration?: ReactHydrationState;
     };
     /**
-     * Fires when a route transition is starting.
-     */
+             * Fires when a route transition is starting.
+             */
     "react:transition:begin": {
       previous: ReactRouterState;
       state: ReactRouterState;
       animation?: PageAnimation;
     };
     /**
-     * Fires when a route transition has succeeded.
-     */
+             * Fires when a route transition has succeeded.
+             */
     "react:transition:success": {
       state: ReactRouterState;
     };
     /**
-     * Fires when a route transition has failed.
-     */
+             * Fires when a route transition has failed.
+             */
     "react:transition:error": {
       state: ReactRouterState;
       error: Error;
     };
     /**
-     * Fires when a route transition has completed, regardless of success or failure.
-     */
+             * Fires when a route transition has completed, regardless of success or failure.
+             */
     "react:transition:end": {
       state: ReactRouterState;
     };
@@ -1321,14 +1745,14 @@ declare module "alepha" {
  * - 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
  *
  * @see {@link $page}
  * @module alepha.react.router
  */
-declare const AlephaReactRouter: alepha12.Service<alepha12.Module>;
+declare const AlephaReactRouter: alepha1.Service<alepha1.Module>;
 //#endregion
-export { $page, AlephaReactRouter, AnchorProps, ConcretePageRoute, CreateLayersResult, ErrorHandler, ErrorViewer, Layer, Link, type LinkProps, _default as NestedView, NestedViewProps, NotFound, PageAnimation, PageConfigSchema, PagePrimitive, PagePrimitiveOptions, PagePrimitiveRenderOptions, PagePrimitiveRenderResult, PageRequestConfig, PageResolve, PageRoute, PageRouteEntry, PreviousLayerData, ReactBrowserProvider, ReactBrowserRendererOptions, ReactHydrationState, ReactPageProvider, ReactPageService, ReactRouter, ReactRouterState, ReactServerProvider, ReactServerProviderOptions, Redirection, type RouterGoOptions, RouterLayerContext, RouterLayerContextValue, RouterRenderOptions, RouterStackItem, TPropsDefault, TPropsParentDefault, TransitionOptions, UseActiveHook, UseActiveOptions, UseQueryParamsHookOptions, VirtualRouter, isPageRoute, reactBrowserOptions, reactServerOptions, useActive, useQueryParams, useRouter, useRouterState };
+export { $page, AlephaReactRouter, AnchorProps, ClientManifest, ConcretePageRoute, CreateLayersResult, EntryAssets, ErrorHandler, ErrorViewer, HydrationData, Layer, Link, type LinkProps, _default as NestedView, NestedViewProps, NotFound, PAGE_PRELOAD_KEY, PageAnimation, PageConfigSchema, PageLoader, PagePrimitive, PagePrimitiveOptions, PagePrimitiveRenderOptions, PagePrimitiveRenderResult, PageRequestConfig, PageRoute, PageRouteEntry, PreloadManifest, PreviousLayerData, ReactBrowserProvider, ReactBrowserRendererOptions, ReactHydrationState, ReactPageProvider, ReactPageService, ReactRouter, ReactRouterState, ReactServerProvider, ReactServerProviderOptions, ReactServerTemplateProvider, Redirection, type RouterGoOptions, RouterLayerContext, RouterLayerContextValue, RouterRenderOptions, RouterStackItem, SSRManifest, SSRManifestProvider, TPropsDefault, TPropsParentDefault, TemplateSlots, TransitionOptions, UseActiveHook, UseActiveOptions, UseQueryParamsHookOptions, VirtualRouter, isPageRoute, reactBrowserOptions, reactServerOptions, useActive, useQueryParams, useRouter, useRouterState };
 //# sourceMappingURL=index.d.ts.map