@nestjs-ssr/react 0.3.4 → 0.3.5

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { Injectable, Logger, Optional, Inject, Global, Module, SetMetadata } from '@nestjs/common';
-import { HttpAdapterHost, APP_INTERCEPTOR, Reflector } from '@nestjs/core';
+import { Reflector, HttpAdapterHost, APP_INTERCEPTOR } from '@nestjs/core';
 import { existsSync, readFileSync } from 'fs';
 import { join, relative } from 'path';
 import { uneval } from 'devalue';
@@ -308,9 +308,13 @@ var StringRenderer = class _StringRenderer {
         throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
       }
     }
-    const { data: pageData, __context: pageContext } = data;
+    const { data: pageData, __context: pageContext, __layouts: layouts } = data;
     const html = await renderModule.renderSegment(viewComponent, data);
     const componentName = viewComponent.displayName || viewComponent.name || "Component";
+    const layoutMetadata = layouts ? layouts.map((l) => ({
+      name: l.layout.displayName || l.layout.name || "default",
+      props: l.props
+    })) : [];
     if (context.isDevelopment) {
       const duration = Date.now() - startTime;
       this.logger.log(`[SSR] ${componentName} segment rendered in ${duration}ms`);
@@ -321,7 +325,8 @@ var StringRenderer = class _StringRenderer {
       props: pageData,
       swapTarget,
       componentName,
-      context: pageContext
+      context: pageContext,
+      layouts: layoutMetadata
     };
   }
 };
@@ -1090,11 +1095,13 @@ var RenderInterceptor = class {
   renderService;
   allowedHeaders;
   allowedCookies;
-  constructor(reflector, renderService, allowedHeaders, allowedCookies) {
+  contextFactory;
+  constructor(reflector, renderService, allowedHeaders, allowedCookies, contextFactory) {
     this.reflector = reflector;
     this.renderService = renderService;
     this.allowedHeaders = allowedHeaders;
     this.allowedCookies = allowedCookies;
+    this.contextFactory = contextFactory;
   }
   /**
   * Resolve the layout hierarchy for a given route
@@ -1234,6 +1241,14 @@ var RenderInterceptor = class {
           renderContext.cookies = cookies;
         }
       }
+      if (this.contextFactory) {
+        const customContext = await this.contextFactory({
+          req: request
+        });
+        if (customContext) {
+          Object.assign(renderContext, customContext);
+        }
+      }
       const renderResponse = isRenderResponse(data) ? data : {
         props: data
       };
@@ -1280,12 +1295,15 @@ RenderInterceptor = _ts_decorate6([
   _ts_param3(2, Inject("ALLOWED_HEADERS")),
   _ts_param3(3, Optional()),
   _ts_param3(3, Inject("ALLOWED_COOKIES")),
+  _ts_param3(4, Optional()),
+  _ts_param3(4, Inject("CONTEXT_FACTORY")),
   _ts_metadata5("design:type", Function),
   _ts_metadata5("design:paramtypes", [
     typeof Reflector === "undefined" ? Object : Reflector,
     typeof RenderService === "undefined" ? Object : RenderService,
     Array,
-    Array
+    Array,
+    typeof ContextFactory === "undefined" ? Object : ContextFactory
   ])
 ], RenderInterceptor);
 function _ts_decorate7(decorators, target, key, desc) {
@@ -1529,6 +1547,12 @@ var RenderModule = class _RenderModule {
       provide: "ALLOWED_COOKIES",
       useValue: config?.allowedCookies || []
     });
+    if (config?.context) {
+      providers.push({
+        provide: "CONTEXT_FACTORY",
+        useValue: config.context
+      });
+    }
     return {
       global: true,
       module: _RenderModule,
@@ -1647,6 +1671,13 @@ var RenderModule = class _RenderModule {
         inject: [
           "RENDER_CONFIG"
         ]
+      },
+      {
+        provide: "CONTEXT_FACTORY",
+        useFactory: /* @__PURE__ */ __name((config) => config?.context, "useFactory"),
+        inject: [
+          "RENDER_CONFIG"
+        ]
       }
     ];
     return {
@@ -1709,9 +1740,28 @@ var PageContext = getOrCreateContext();
 function registerPageContextState(setter) {
 }
 __name(registerPageContextState, "registerPageContextState");
+var segmentSetters = /* @__PURE__ */ new Set();
+function registerSegmentSetter(setter) {
+  segmentSetters.add(setter);
+}
+__name(registerSegmentSetter, "registerSegmentSetter");
+function unregisterSegmentSetter(setter) {
+  segmentSetters.delete(setter);
+}
+__name(unregisterSegmentSetter, "unregisterSegmentSetter");
+function broadcastToSegments(context) {
+  segmentSetters.forEach((setter) => setter(context));
+}
+__name(broadcastToSegments, "broadcastToSegments");
 function PageContextProvider({ context: initialContext, children, isSegment = false }) {
   const [context, setContext] = useState(initialContext);
   useEffect(() => {
+    if (!isSegment) {
+      return void 0;
+    } else {
+      registerSegmentSetter(setContext);
+      return () => unregisterSegmentSetter(setContext);
+    }
   }, [
     isSegment
   ]);

package/dist/render/index.d.mts

@@ -1,9 +1,9 @@
-export { E as ErrorPageDevelopment, e as ErrorPageProduction, b as RenderInterceptor, R as RenderModule, a as RenderService, S as StreamingErrorHandler, T as TemplateParserService } from '../index-DdE--mA2.mjs';
+export { E as ErrorPageDevelopment, e as ErrorPageProduction, b as RenderInterceptor, R as RenderModule, a as RenderService, S as StreamingErrorHandler, T as TemplateParserService } from '../index-CiYcz-1T.mjs';
 import '@nestjs/common';
 import 'react';
-import '../render-response.interface-CxbuKGnV.mjs';
-import 'vite';
 import 'express';
+import '../render-response.interface-ClWJXKL4.mjs';
+import 'vite';
 import '@nestjs/core';
 import 'rxjs';
 import 'react/jsx-runtime';

package/dist/render/index.d.ts

@@ -1,9 +1,9 @@
-export { E as ErrorPageDevelopment, e as ErrorPageProduction, b as RenderInterceptor, R as RenderModule, a as RenderService, S as StreamingErrorHandler, T as TemplateParserService } from '../index-BzOLOiIZ.js';
+export { E as ErrorPageDevelopment, e as ErrorPageProduction, b as RenderInterceptor, R as RenderModule, a as RenderService, S as StreamingErrorHandler, T as TemplateParserService } from '../index-Dq2qZSge.js';
 import '@nestjs/common';
 import 'react';
-import '../render-response.interface-CxbuKGnV.js';
-import 'vite';
 import 'express';
+import '../render-response.interface-ClWJXKL4.js';
+import 'vite';
 import '@nestjs/core';
 import 'rxjs';
 import 'react/jsx-runtime';

package/dist/render/index.js

@@ -314,9 +314,13 @@ var StringRenderer = class _StringRenderer {
         throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
       }
     }
-    const { data: pageData, __context: pageContext } = data;
+    const { data: pageData, __context: pageContext, __layouts: layouts } = data;
     const html = await renderModule.renderSegment(viewComponent, data);
     const componentName = viewComponent.displayName || viewComponent.name || "Component";
+    const layoutMetadata = layouts ? layouts.map((l) => ({
+      name: l.layout.displayName || l.layout.name || "default",
+      props: l.props
+    })) : [];
     if (context.isDevelopment) {
       const duration = Date.now() - startTime;
       this.logger.log(`[SSR] ${componentName} segment rendered in ${duration}ms`);
@@ -327,7 +331,8 @@ var StringRenderer = class _StringRenderer {
       props: pageData,
       swapTarget,
       componentName,
-      context: pageContext
+      context: pageContext,
+      layouts: layoutMetadata
     };
   }
 };
@@ -1078,11 +1083,13 @@ exports.RenderInterceptor = class RenderInterceptor {
   renderService;
   allowedHeaders;
   allowedCookies;
-  constructor(reflector, renderService, allowedHeaders, allowedCookies) {
+  contextFactory;
+  constructor(reflector, renderService, allowedHeaders, allowedCookies, contextFactory) {
     this.reflector = reflector;
     this.renderService = renderService;
     this.allowedHeaders = allowedHeaders;
     this.allowedCookies = allowedCookies;
+    this.contextFactory = contextFactory;
   }
   /**
   * Resolve the layout hierarchy for a given route
@@ -1222,6 +1229,14 @@ exports.RenderInterceptor = class RenderInterceptor {
           renderContext.cookies = cookies;
         }
       }
+      if (this.contextFactory) {
+        const customContext = await this.contextFactory({
+          req: request
+        });
+        if (customContext) {
+          Object.assign(renderContext, customContext);
+        }
+      }
       const renderResponse = isRenderResponse(data) ? data : {
         props: data
       };
@@ -1268,12 +1283,15 @@ exports.RenderInterceptor = _ts_decorate6([
   _ts_param3(2, common.Inject("ALLOWED_HEADERS")),
   _ts_param3(3, common.Optional()),
   _ts_param3(3, common.Inject("ALLOWED_COOKIES")),
+  _ts_param3(4, common.Optional()),
+  _ts_param3(4, common.Inject("CONTEXT_FACTORY")),
   _ts_metadata5("design:type", Function),
   _ts_metadata5("design:paramtypes", [
     typeof core.Reflector === "undefined" ? Object : core.Reflector,
     typeof exports.RenderService === "undefined" ? Object : exports.RenderService,
     Array,
-    Array
+    Array,
+    typeof ContextFactory === "undefined" ? Object : ContextFactory
   ])
 ], exports.RenderInterceptor);
 function _ts_decorate7(decorators, target, key, desc) {
@@ -1517,6 +1535,12 @@ exports.RenderModule = class _RenderModule {
       provide: "ALLOWED_COOKIES",
       useValue: config?.allowedCookies || []
     });
+    if (config?.context) {
+      providers.push({
+        provide: "CONTEXT_FACTORY",
+        useValue: config.context
+      });
+    }
     return {
       global: true,
       module: _RenderModule,
@@ -1635,6 +1659,13 @@ exports.RenderModule = class _RenderModule {
         inject: [
           "RENDER_CONFIG"
         ]
+      },
+      {
+        provide: "CONTEXT_FACTORY",
+        useFactory: /* @__PURE__ */ __name((config) => config?.context, "useFactory"),
+        inject: [
+          "RENDER_CONFIG"
+        ]
       }
     ];
     return {

package/dist/render/index.mjs

@@ -1,5 +1,5 @@
 import { Injectable, Logger, Optional, Inject, Global, Module } from '@nestjs/common';
-import { HttpAdapterHost, APP_INTERCEPTOR, Reflector } from '@nestjs/core';
+import { Reflector, HttpAdapterHost, APP_INTERCEPTOR } from '@nestjs/core';
 import { existsSync, readFileSync } from 'fs';
 import { join, relative } from 'path';
 import { uneval } from 'devalue';
@@ -308,9 +308,13 @@ var StringRenderer = class _StringRenderer {
         throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
       }
     }
-    const { data: pageData, __context: pageContext } = data;
+    const { data: pageData, __context: pageContext, __layouts: layouts } = data;
     const html = await renderModule.renderSegment(viewComponent, data);
     const componentName = viewComponent.displayName || viewComponent.name || "Component";
+    const layoutMetadata = layouts ? layouts.map((l) => ({
+      name: l.layout.displayName || l.layout.name || "default",
+      props: l.props
+    })) : [];
     if (context.isDevelopment) {
       const duration = Date.now() - startTime;
       this.logger.log(`[SSR] ${componentName} segment rendered in ${duration}ms`);
@@ -321,7 +325,8 @@ var StringRenderer = class _StringRenderer {
       props: pageData,
       swapTarget,
       componentName,
-      context: pageContext
+      context: pageContext,
+      layouts: layoutMetadata
     };
   }
 };
@@ -1072,11 +1077,13 @@ var RenderInterceptor = class {
   renderService;
   allowedHeaders;
   allowedCookies;
-  constructor(reflector, renderService, allowedHeaders, allowedCookies) {
+  contextFactory;
+  constructor(reflector, renderService, allowedHeaders, allowedCookies, contextFactory) {
     this.reflector = reflector;
     this.renderService = renderService;
     this.allowedHeaders = allowedHeaders;
     this.allowedCookies = allowedCookies;
+    this.contextFactory = contextFactory;
   }
   /**
   * Resolve the layout hierarchy for a given route
@@ -1216,6 +1223,14 @@ var RenderInterceptor = class {
           renderContext.cookies = cookies;
         }
       }
+      if (this.contextFactory) {
+        const customContext = await this.contextFactory({
+          req: request
+        });
+        if (customContext) {
+          Object.assign(renderContext, customContext);
+        }
+      }
       const renderResponse = isRenderResponse(data) ? data : {
         props: data
       };
@@ -1262,12 +1277,15 @@ RenderInterceptor = _ts_decorate6([
   _ts_param3(2, Inject("ALLOWED_HEADERS")),
   _ts_param3(3, Optional()),
   _ts_param3(3, Inject("ALLOWED_COOKIES")),
+  _ts_param3(4, Optional()),
+  _ts_param3(4, Inject("CONTEXT_FACTORY")),
   _ts_metadata5("design:type", Function),
   _ts_metadata5("design:paramtypes", [
     typeof Reflector === "undefined" ? Object : Reflector,
     typeof RenderService === "undefined" ? Object : RenderService,
     Array,
-    Array
+    Array,
+    typeof ContextFactory === "undefined" ? Object : ContextFactory
   ])
 ], RenderInterceptor);
 function _ts_decorate7(decorators, target, key, desc) {
@@ -1511,6 +1529,12 @@ var RenderModule = class _RenderModule {
       provide: "ALLOWED_COOKIES",
       useValue: config?.allowedCookies || []
     });
+    if (config?.context) {
+      providers.push({
+        provide: "CONTEXT_FACTORY",
+        useValue: config.context
+      });
+    }
     return {
       global: true,
       module: _RenderModule,
@@ -1629,6 +1653,13 @@ var RenderModule = class _RenderModule {
         inject: [
           "RENDER_CONFIG"
         ]
+      },
+      {
+        provide: "CONTEXT_FACTORY",
+        useFactory: /* @__PURE__ */ __name((config) => config?.context, "useFactory"),
+        inject: [
+          "RENDER_CONFIG"
+        ]
       }
     ];
     return {

package/dist/{render-response.interface-CxbuKGnV.d.mts → render-response.interface-ClWJXKL4.d.mts}

@@ -3,7 +3,7 @@
  * Contains safe request metadata that can be exposed to the client.
  *
  * Extend this interface to add app-specific properties (user, tenant, feature flags, etc.).
- * Use module configuration to pass additional headers or cookies safely.
+ * Use the `context` option in module configuration to enrich the context.
  *
  * @example
  * // Basic usage - use as-is
@@ -32,19 +32,28 @@
  *   theme?: string;  // From cookie
  * }
  *
- * // Configure module to pass specific cookies/headers
- * ReactSSRModule.forRoot({
+ * // Configure module with context factory to enrich context
+ * RenderModule.forRoot({
  *   allowedCookies: ['theme', 'locale'],
  *   allowedHeaders: ['x-tenant-id'],
+ *   context: ({ req }) => ({
+ *     user: req.user,  // From Passport JWT strategy
+ *     tenant: req.tenant,
+ *     featureFlags: req.featureFlags,
+ *   }),
  * })
  *
- * // Use in interceptor/controller
- * const context: AppRenderContext = {
- *   ...baseContext,
- *   user: req.user,
- *   tenant: req.tenant,
- *   featureFlags: await featureFlagService.getFlags(req),
- * };
+ * // Or with async factory (use forRootAsync)
+ * RenderModule.forRootAsync({
+ *   imports: [PermissionModule],
+ *   inject: [PermissionService],
+ *   useFactory: (permissionService) => ({
+ *     context: async ({ req }) => ({
+ *       user: req.user,
+ *       permissions: await permissionService.getForUser(req.user),
+ *     }),
+ *   }),
+ * })
  */
 interface RenderContext {
     url: string;

package/dist/{render-response.interface-CxbuKGnV.d.ts → render-response.interface-ClWJXKL4.d.ts}

@@ -3,7 +3,7 @@
  * Contains safe request metadata that can be exposed to the client.
  *
  * Extend this interface to add app-specific properties (user, tenant, feature flags, etc.).
- * Use module configuration to pass additional headers or cookies safely.
+ * Use the `context` option in module configuration to enrich the context.
  *
  * @example
  * // Basic usage - use as-is
@@ -32,19 +32,28 @@
  *   theme?: string;  // From cookie
  * }
  *
- * // Configure module to pass specific cookies/headers
- * ReactSSRModule.forRoot({
+ * // Configure module with context factory to enrich context
+ * RenderModule.forRoot({
  *   allowedCookies: ['theme', 'locale'],
  *   allowedHeaders: ['x-tenant-id'],
+ *   context: ({ req }) => ({
+ *     user: req.user,  // From Passport JWT strategy
+ *     tenant: req.tenant,
+ *     featureFlags: req.featureFlags,
+ *   }),
  * })
  *
- * // Use in interceptor/controller
- * const context: AppRenderContext = {
- *   ...baseContext,
- *   user: req.user,
- *   tenant: req.tenant,
- *   featureFlags: await featureFlagService.getFlags(req),
- * };
+ * // Or with async factory (use forRootAsync)
+ * RenderModule.forRootAsync({
+ *   imports: [PermissionModule],
+ *   inject: [PermissionService],
+ *   useFactory: (permissionService) => ({
+ *     context: async ({ req }) => ({
+ *       user: req.user,
+ *       permissions: await permissionService.getForUser(req.user),
+ *     }),
+ *   }),
+ * })
  */
 interface RenderContext {
     url: string;

package/dist/templates/entry-client.tsx

@@ -115,8 +115,15 @@ function hasLayout(
 }
 
 /**
- * Compose a component with its layout (and nested layouts if any)
- * This must match the server-side composition in entry-server.tsx
+ * Compose a component with its layout (and nested layouts if any).
+ * This must match the server-side composition in entry-server.tsx.
+ *
+ * The layouts array is ordered [RootLayout, ControllerLayout, MethodLayout] (outer to inner).
+ * We iterate in REVERSE order because wrapping happens inside-out:
+ * - Start with Page
+ * - Wrap with innermost layout first (MethodLayout)
+ * - Then wrap with ControllerLayout
+ * - Finally wrap with RootLayout (outermost)
  */
 function composeWithLayout(
   ViewComponent: React.ComponentType<any>,
@@ -139,9 +146,11 @@ function composeWithLayout(
     }
   }
 
-  // Wrap with each layout in the chain
+  // Wrap with each layout in REVERSE order (innermost to outermost)
+  // This produces the correct nesting: RootLayout > ControllerLayout > Page
   // Must match server-side wrapping with data-layout and data-outlet attributes
-  for (const { layout: Layout, props: layoutProps } of layouts) {
+  for (let i = layouts.length - 1; i >= 0; i--) {
+    const { layout: Layout, props: layoutProps } = layouts[i];
     const layoutName = Layout.displayName || Layout.name || 'Layout';
     result = (
       <div data-layout={layoutName}>
@@ -183,8 +192,18 @@ hydrateRoot(
   <StrictMode>{wrappedElement}</StrictMode>,
 );
 
+// Track if initial hydration is complete to ignore false popstate events
+let hydrationComplete = false;
+requestAnimationFrame(() => {
+  hydrationComplete = true;
+});
+
 // Handle browser back/forward navigation
 window.addEventListener('popstate', async () => {
+  // Ignore popstate events that fire before hydration is complete
+  // (some browsers fire popstate on initial page load)
+  if (!hydrationComplete) return;
+
   // Dynamically import navigate to avoid circular dependency with hydrate-segment
   const { navigate } = await import('@nestjs-ssr/react/client');
   // Re-navigate to the current URL (browser already updated location)

package/dist/templates/entry-server.tsx

@@ -25,6 +25,13 @@ export function getRootLayout(): React.ComponentType<any> | null {
  * Layouts are passed from the RenderInterceptor based on decorators.
  * Each layout is wrapped with data-layout and data-outlet attributes
  * for client-side navigation segment swapping.
+ *
+ * The layouts array is ordered [RootLayout, ControllerLayout, MethodLayout] (outer to inner).
+ * We iterate in REVERSE order because wrapping happens inside-out:
+ * - Start with Page
+ * - Wrap with innermost layout first (MethodLayout)
+ * - Then wrap with ControllerLayout
+ * - Finally wrap with RootLayout (outermost)
  */
 function composeWithLayouts(
   ViewComponent: React.ComponentType<any>,
@@ -35,11 +42,12 @@ function composeWithLayouts(
   // Start with the page component
   let result = <ViewComponent {...props} />;
 
-  // Wrap with each layout in the chain (outermost to innermost in array)
-  // We iterate normally because layouts are already in correct order from interceptor
+  // Wrap with each layout in REVERSE order (innermost to outermost)
+  // This produces the correct nesting: RootLayout > ControllerLayout > Page
   // Pass context to layouts so they can access path, params, etc. for navigation
   // Each layout gets data-layout attribute and children are wrapped in data-outlet
-  for (const { layout: Layout, props: layoutProps } of layouts) {
+  for (let i = layouts.length - 1; i >= 0; i--) {
+    const { layout: Layout, props: layoutProps } = layouts[i];
     const layoutName = Layout.displayName || Layout.name || 'Layout';
     result = (
       <div data-layout={layoutName}>
@@ -80,19 +88,28 @@ export function renderComponent(
 }
 
 /**
- * Render just the page component for segment navigation.
- * No layout wrappers - the layout already exists on the client.
+ * Render a segment for client-side navigation.
+ * Includes any layouts below the swap target (e.g., nested layouts).
+ * The swap target's outlet will receive this rendered content.
  */
 export function renderSegment(
   ViewComponent: React.ComponentType<any>,
   data: any,
 ) {
-  const { data: pageData, __context: context } = data;
+  const { data: pageData, __context: context, __layouts: layouts } = data;
+
+  // Compose with filtered layouts (layouts below the swap target)
+  const composedElement = composeWithLayouts(
+    ViewComponent,
+    pageData,
+    layouts,
+    context,
+  );
 
-  // Render just the page component, no layout wrappers
+  // Wrap with PageContextProvider to make context available via hooks
   const element = (
     <PageContextProvider context={context}>
-      <ViewComponent {...pageData} />
+      {composedElement}
     </PageContextProvider>
   );
 

package/dist/{use-page-context-CGT9woWe.d.mts → use-page-context-CVC9DHcL.d.mts}

@@ -1,4 +1,4 @@
-import { H as HeadData, R as RenderContext } from './render-response.interface-CxbuKGnV.mjs';
+import { H as HeadData, R as RenderContext } from './render-response.interface-ClWJXKL4.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 
@@ -85,6 +85,7 @@ declare function updatePageContext(context: RenderContext): void;
  *
  * @param isSegment - If true, this is a segment provider (for hydrated segments)
  *                    and won't register its setter to avoid overwriting the root provider's.
+ *                    However, it will still receive broadcasts when context updates.
  */
 declare function PageContextProvider({ context: initialContext, children, isSegment, }: {
     context: RenderContext;

package/dist/{use-page-context-05ODF4zW.d.ts → use-page-context-DChgHhL9.d.ts}

@@ -1,4 +1,4 @@
-import { H as HeadData, R as RenderContext } from './render-response.interface-CxbuKGnV.js';
+import { H as HeadData, R as RenderContext } from './render-response.interface-ClWJXKL4.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 
@@ -85,6 +85,7 @@ declare function updatePageContext(context: RenderContext): void;
  *
  * @param isSegment - If true, this is a segment provider (for hydrated segments)
  *                    and won't register its setter to avoid overwriting the root provider's.
+ *                    However, it will still receive broadcasts when context updates.
  */
 declare function PageContextProvider({ context: initialContext, children, isSegment, }: {
     context: RenderContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs-ssr/react",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "React SSR for NestJS that respects Clean Architecture. Proper DI, SOLID principles, clear separation of concerns.",
   "keywords": [
     "nestjs",

package/src/templates/entry-client.tsx

@@ -115,8 +115,15 @@ function hasLayout(
 }
 
 /**
- * Compose a component with its layout (and nested layouts if any)
- * This must match the server-side composition in entry-server.tsx
+ * Compose a component with its layout (and nested layouts if any).
+ * This must match the server-side composition in entry-server.tsx.
+ *
+ * The layouts array is ordered [RootLayout, ControllerLayout, MethodLayout] (outer to inner).
+ * We iterate in REVERSE order because wrapping happens inside-out:
+ * - Start with Page
+ * - Wrap with innermost layout first (MethodLayout)
+ * - Then wrap with ControllerLayout
+ * - Finally wrap with RootLayout (outermost)
  */
 function composeWithLayout(
   ViewComponent: React.ComponentType<any>,
@@ -139,9 +146,11 @@ function composeWithLayout(
     }
   }
 
-  // Wrap with each layout in the chain
+  // Wrap with each layout in REVERSE order (innermost to outermost)
+  // This produces the correct nesting: RootLayout > ControllerLayout > Page
   // Must match server-side wrapping with data-layout and data-outlet attributes
-  for (const { layout: Layout, props: layoutProps } of layouts) {
+  for (let i = layouts.length - 1; i >= 0; i--) {
+    const { layout: Layout, props: layoutProps } = layouts[i];
     const layoutName = Layout.displayName || Layout.name || 'Layout';
     result = (
       <div data-layout={layoutName}>
@@ -183,8 +192,18 @@ hydrateRoot(
   <StrictMode>{wrappedElement}</StrictMode>,
 );
 
+// Track if initial hydration is complete to ignore false popstate events
+let hydrationComplete = false;
+requestAnimationFrame(() => {
+  hydrationComplete = true;
+});
+
 // Handle browser back/forward navigation
 window.addEventListener('popstate', async () => {
+  // Ignore popstate events that fire before hydration is complete
+  // (some browsers fire popstate on initial page load)
+  if (!hydrationComplete) return;
+
   // Dynamically import navigate to avoid circular dependency with hydrate-segment
   const { navigate } = await import('@nestjs-ssr/react/client');
   // Re-navigate to the current URL (browser already updated location)