@alepha/react 0.14.2 → 0.14.4

package/dist/router/index.d.ts

@@ -1,17 +1,17 @@
 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
@@ -26,7 +26,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 +40,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)
@@ -86,7 +86,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;
@@ -157,6 +157,11 @@ interface ReactRouterState {
    * 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 +191,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 +212,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 +249,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 +262,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 +281,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 };
  *   }
@@ -309,12 +322,12 @@ interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSche
    *
    * > 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.
+   * 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.
    */
-  resolve?: (context: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
+  loader?: (context: PageLoader<TConfig, TPropsParent>) => Async<TProps>;
   /**
    * Default props to pass to the component when rendering the page.
    *
@@ -354,7 +367,7 @@ interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSche
    */
   can?: () => boolean;
   /**
-   * Catch any error from the `resolve` function or during `rendering`.
+   * Catch any error from the `loader` function or during `rendering`.
    *
    * Expected to return one of the following:
    * - a ReactNode to render an error page
@@ -366,7 +379,7 @@ interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSche
    *
    * @example Catch a 404 from API and render a custom not found component:
    * ```ts
-   * resolve: async ({ params, query }) => {
+   * loader: async ({ params, query }) => {
    *    api.fetch("/api/resource", { params, query });
    * },
    * errorHandler: (error, context) => {
@@ -378,7 +391,7 @@ interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSche
    *
    * @example Catch an 401 error and redirect the user to the login page:
    * ```ts
-   * resolve: async ({ params, query }) => {
+   * loader: async ({ params, query }) => {
    *   // but the user is not authenticated
    *   api.fetch("/api/resource", { params, query });
    * },
@@ -459,6 +472,37 @@ interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSche
    * ```
    */
   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>> {
@@ -506,7 +550,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 +574,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;
@@ -607,7 +597,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,62 +607,11 @@ 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;
@@ -690,9 +629,9 @@ 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.
@@ -707,20 +646,14 @@ declare class ReactRouter<T$1 extends object> {
     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 +662,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;
@@ -768,8 +700,8 @@ declare class ReactBrowserProvider {
    * 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 +1070,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 +1092,483 @@ 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>;
+  } | null>, options?: {
+    hydration?: boolean;
+    onError?: (error: unknown) => void;
+    onRedirect?: (url: string) => 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: {
@@ -1221,38 +1579,101 @@ declare class ReactServerProvider {
   /**
    * Configure the React server provider.
    */
-  readonly onConfigure: alepha12.HookPrimitive<"configure">;
+  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>;
+  /**
+   * 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(): string;
+  protected getPublicDirectory(): Promise<string>;
   /**
    * 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.
+   * Create the request handler for a page route.
    */
-  render(name: string, options?: PagePrimitiveRenderOptions): Promise<PagePrimitiveRenderResult>;
   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
@@ -1278,6 +1699,9 @@ declare module "alepha" {
     };
     /**
      * 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;
@@ -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