@saolabs/client 1.0.0 → 1.0.2

package/src/core/view/ViewManager.ts

@@ -17,22 +17,39 @@
  *   - Section system → Block/BlockOutlet
  */
 
-import type { ApplicationInterface } from "../contracts/ApplicationInterface";
-import { ActiveRouteInterface, RouterNavigationType } from "../contracts/RouterInterface";
-import { FragmentInterface, HtmlInterface } from "../contracts/utils";
-import type { ViewControllerConfig, ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import type { ViewInterface } from "../contracts/ViewInterface";
-import type { ViewManagerInterface, ActiveViewInfo } from "../contracts/ViewManagerInterface";
-import { BlockManager, BlockManagerService } from "../services/BlockManager";
-import { Html } from "../elements/Html";
-import { hasData } from "../hellpers/utils";
-import logger from "../services/LoggerService";
-import { StoreService } from "../services/StoreService";
-import { View } from "./View";
-import { InitMode, InitModes } from "../contracts/common";
-import { OOTEnum } from "../types/utils";
-import { WrapperInterface } from "../contracts/ElementInterface";
-import { app } from "../hellpers/app";
+import type { ApplicationInterface } from "../contracts/ApplicationInterface.js";
+import { ActiveRouteInterface, RouterNavigationType } from "../contracts/RouterInterface.js";
+import { FragmentInterface, HtmlInterface } from "../contracts/utils.js";
+import type { ViewControllerConfig, ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import type { ViewInterface } from "../contracts/ViewInterface.js";
+import type { ViewManagerInterface, ActiveViewInfo } from "../contracts/ViewManagerInterface.js";
+import { BlockManager, BlockManagerService } from "../services/BlockManager.js";
+import { SectionManager, SectionManagerService } from "../services/SectionManager.js";
+import devtools from "../devtools/hook.js";
+import { BlockOutlet } from "../elements/BlockOutlet.js";
+import { PageCacheService, PageCacheEntry, detachWrapperDOM } from "../services/PageCache.js";
+import { Html } from "../elements/Html.js";
+import { hasData } from "../helpers/utils.js";
+import { activateView, claimHydratedView, commitView, flushView } from "../helpers/view.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import logger from "../services/LoggerService.js";
+import { StoreService } from "../services/StoreService.js";
+import { View } from "./View.js";
+import { InitMode, InitModes } from "../contracts/common.js";
+import { OOTEnum } from "../types/utils.js";
+import { WrapperInterface } from "../contracts/ElementInterface.js";
+import { app } from "../helpers/app.js";
+
+/**
+ * SSR boot info — server nhúng sau khi render xong (RUNTIME_CONTRACT §6).
+ * `view` = registry path của page entry, `viewId` = id server đã dùng để prefix
+ * markers/classes của page. viewId của layout chain được client discover từ DOM.
+ */
+export type SSRBootInfo = {
+    view: string;
+    viewId: string;
+    container?: string;
+};
 
 type RenderPageViewSuccess = {
     type: 'success';
@@ -41,6 +58,8 @@ type RenderPageViewSuccess = {
     result: ViewInterface | unknown;
     superView: ViewInterface | null;
     finalView: ViewInterface;
+    /** Origin → outermost: [page, inner layout, ..., root layout]. */
+    chain: ViewInterface[];
 };
 
 type RenderPageViewError = {
@@ -50,12 +69,23 @@ type RenderPageViewError = {
     result: null;
     superView: null;
     finalView: ViewInterface;
+    chain: ViewInterface[];
+};
+
+type RenderPageViewCancelled = {
+    type: 'cancelled';
+    message: string;
+    view: ViewInterface;
+    result: null;
+    superView: null;
+    finalView: ViewInterface;
+    chain: ViewInterface[];
 };
 
-type RenderPageViewResult = RenderPageViewSuccess | RenderPageViewError;
+type RenderPageViewResult = RenderPageViewSuccess | RenderPageViewError | RenderPageViewCancelled;
 
-function isRenderableObject(result: unknown): result is { oneType: string } {
-    return typeof result === 'object' && result !== null && 'oneType' in result;
+function isRenderableObject(result: unknown): result is { saoType: string } {
+    return typeof result === 'object' && result !== null && 'saoType' in result;
 }
 
 export class ViewManager implements ViewManagerInterface {
@@ -63,15 +93,16 @@ export class ViewManager implements ViewManagerInterface {
     private App: ApplicationInterface | null = null;
 
     private systemData: Record<string, any> = {}; // For internal use, not exposed to views
+    private contextRevision: string | null = null;
+    private contextViews: string | null = null;
 
     /** ROOT DOM container where views mount */
     private container: HTMLElement | null = null;
-    private rootElement: Html | null = null; // Html wrapper for the root container
+    private rootElement: HtmlInterface | null = null; // Html wrapper for the root container
     /** View module registry: name → factory or async loader */
     private viewRegistry: Record<string, ((...args: any[]) => any) | (() => Promise<any>)> = {};
 
     /** Currently mounted views (keyed by path) */
-    private activeViews: Map<string, ActiveViewInfo> = new Map();
 
     /** The outermost active view (layout or page) */
     private currentView: ActiveViewInfo | null = null;
@@ -80,14 +111,28 @@ export class ViewManager implements ViewManagerInterface {
     private currentLayoutPath: string | null = null;
 
     private currentLayoutView: ViewInterface | null = null; // Store the current layout view instance for reuse
+    /** Mounted layouts ordered outermost → innermost. */
+    private currentLayoutChain: ViewInterface[] = [];
     private currentPageView: ViewInterface | null = null; // Store the current page view instance for reference in blocks and sections
     private currentViewType: 'view' | 'layout' | null = null; // Track whether the current view is a page or layout for correct lifecycle handling
 
+    /**
+     * SSR boot info — view entry (page) + viewId server đã render. Set ở init()
+     * từ config.ssr (đọc từ DOM lúc boot). Router consume 1 lần cho route đầu
+     * tiên → hydrateView; các route sau là CSR (SPA takeover).
+     */
+    private ssrBoot: SSRBootInfo | null = null;
+    /** Standalone SPA: Laravel data requests may live on a different host. */
+    private dataEndpoint: string | null = null;
+    private fetchOptions: Record<string, any> = {};
+
+    /** Exact Page/Layout instance relationships exported by Blade for hydration. */
+    private ssrViewData: Record<string, any> = {};
+
 
     /** Current layout view info — reused if same layout */
     private currentLayout: ActiveViewInfo | null = null;
 
-    private cachedLayouts: Map<string, ViewInterface> = new Map(); // Cache for previously mounted layouts
 
     /** All views in the current mount chain (outermost → innermost) */
     private viewStack: ViewInterface[] = [];
@@ -98,18 +143,82 @@ export class ViewManager implements ViewManagerInterface {
     /** Render counter for debugging */
     private renderCount = 0;
 
+    /** Invalidates fire-and-forget render work when a newer navigation begins. */
+    /**
+     * Số lượt render `@await` đang bay.
+     *
+     * Nhánh "có prerender" cố ý fire-and-forget: nó trả skeleton về NGAY rồi
+     * mới fetch, nên người gọi không có promise nào để đợi và không có cách
+     * nào biết nội dung thật đã vào chưa. Đếm ở đây để {@link isSettled} trả
+     * lời được câu đó — công cụ đo, chụp ảnh trang, hay test parity SSR↔CSR
+     * đều cần một tín hiệu THẬT thay vì đoán bằng "DOM đứng yên": trang đang
+     * chờ dữ liệu thì DOM cũng đứng yên y như đã xong.
+     */
+    private pendingAsyncRenders = 0;
+
+    /** Không còn render `@await` nào đang bay — nội dung thật đã vào DOM. */
+    get isSettled(): boolean {
+        return this.pendingAsyncRenders === 0;
+    }
+
+    private navigationGeneration = 0;
+
     public store: StoreService = StoreService.instance("ViewManager");
 
     public blockManager: BlockManagerService = BlockManager;
+    public sectionManager: SectionManagerService = SectionManager;
 
     constructor(app?: ApplicationInterface) {
         if (app) this.App = app;
+
+        // Layout instance sống ở CẢ HAI nơi: PageCache (DOM detached) + store
+        // (để extendView trả lại đúng instance). Entry bị evict/expire → instance
+        // đã destroy → PHẢI gỡ khỏi store, nếu không extendView trả instance chết.
+        this.pageCache.onEvict = (entry) => {
+            for (const v of entry.views) {
+                const path = v.__ctrl__?.path;
+                if (path && this.store.has(path) && this.store.get(path) === v) {
+                    this.store.remove?.(path);
+                }
+            }
+        };
     }
+    /**
+     * Kiểm tra một view có đang mount (active) không.
+     * Dùng để guard duplicate mount hoặc kiểm tra trạng thái từ bên ngoài.
+     */
     isViewMounted(path: string): boolean {
-        throw new Error("Method not implemented.");
+        if (this.currentPageView?.__ctrl__.path === path) return true;
+        return this.currentLayoutChain.some(v => v.__ctrl__.path === path);
     }
+
+    /** Invalidate async render/fetch work owned by the current navigation. */
+    cancelNavigation(): void {
+        this.navigationGeneration++;
+    }
+
+    /**
+     * Destroy ViewManager hoàn toàn — dọn sạch mọi view, DOM, state.
+     * Gọi khi teardown app (hot reload, test cleanup, unmount root).
+     */
     destroy(): void {
-        throw new Error("Method not implemented.");
+        this.navigationGeneration++;
+        // 1. Stop và destroy tất cả views đang active
+        this.unmountAll();
+        // 2. Dọn PageCache
+        this.pageCache.clear();
+        // 3. Reset registry và internal state
+        this.viewRegistry = {};
+        this.rootElement = null;
+        this.container = null;
+        this._isInitialized = false;
+        this.renderCount = 0;
+        this.store.clear();
+        // MarkerRegistry là singleton TOÀN CỤC ở tầng module — không thuộc view
+        // nào nên không teardown nào khác chạm tới. Teardown app (hot reload,
+        // unmount root, dọn giữa các test) là chỗ duy nhất dọn được nó.
+        markerRegistry.clear();
+        logger.info('[ViewManager] destroyed.');
     }
 
 
@@ -160,7 +269,28 @@ export class ViewManager implements ViewManagerInterface {
     /**
      * Initialize the ViewManager.
      */
-    init(config?: { container?: HTMLElement | string; registry?: Record<string, any> }): void {
+    init(config?: { container?: HTMLElement | string; registry?: Record<string, any>; ssr?: SSRBootInfo | null; systemData?: Record<string, any>; ssrData?: Record<string, any>; revision?: string; contextViews?: string; dataEndpoint?: string; fetchOptions?: Record<string, any> }): void {
+        if (typeof config?.dataEndpoint === 'string') this.dataEndpoint = config.dataEndpoint;
+        if (config?.fetchOptions) this.fetchOptions = { ...config.fetchOptions };
+        // SSR boot info (server-rendered): chứa view entry + viewId để route đầu
+        // tiên gọi hydrateView thay vì mountView. Xem RUNTIME_CONTRACT §6 (boot).
+        if (config?.ssr && config.ssr.view && config.ssr.viewId) {
+            this.ssrBoot = config.ssr;
+        }
+        // systemData (server __layout__/__base__/__page__/...): spread vào mọi
+        // view factory ở view() để compiled view resolve superView/namespace.
+        if (config?.systemData && typeof config.systemData === 'object') {
+            this.systemData = { ...this.systemData, ...config.systemData };
+        }
+        if (typeof config?.revision === 'string') {
+            this.contextRevision = config.revision;
+        }
+        if (typeof config?.contextViews === 'string') {
+            this.contextViews = config.contextViews;
+        }
+        if (config?.ssrData && typeof config.ssrData === 'object') {
+            this.ssrViewData = config.ssrData;
+        }
         if (config?.container) {
             if (typeof config.container === 'string') {
                 const found = document.querySelector(config.container);
@@ -181,58 +311,187 @@ export class ViewManager implements ViewManagerInterface {
             ctx: this,
             tagName: this.container.tagName.toLowerCase(),
             element: this.container,
-            initMode: 'hydrate',
+            initMode: InitModes.HYDRATE,
+            childrenFactory: () => [],
         });
         if (config?.registry) {
             this.setViewRegistry(config.registry);
         }
         this._isInitialized = true;
+        devtools.attach(this);
     }
 
+    /**
+     * Phương án CUỐI khi không error boundary nào xử lý (xem ViewController.onError):
+     * ghi đè cả container. Dựng bằng DOM API + textContent — message/details có thể
+     * mang nội dung từ server/URL, nội suy vào innerHTML là đường tiêm HTML.
+     */
     showError(message: string, details?: any) {
         logger.error(message, details);
-        if (this.container) {
-            this.container.innerHTML = `<div style="padding: 20px; background: #fee; color: #900; border: 1px solid #900;">
-                <h2>Error</h2>
-                <p>${message}</p>
-                ${details ? `<pre style="white-space: pre-wrap; background: #fdd; padding: 10px; border: 1px solid #900;">${JSON.stringify(details, null, 2)}</pre>` : ''}
-            </div>`;
+        if (!this.container) return;
+
+        const box = document.createElement('div');
+        box.style.cssText = 'padding:20px;background:#fee;color:#900;border:1px solid #900';
+
+        const title = document.createElement('h2');
+        title.textContent = 'Error';
+        box.appendChild(title);
+
+        const text = document.createElement('p');
+        text.textContent = message;
+        box.appendChild(text);
+
+        if (details) {
+            const pre = document.createElement('pre');
+            pre.style.cssText = 'white-space:pre-wrap;background:#fdd;padding:10px;border:1px solid #900';
+            let serialized: string;
+            try {
+                serialized = JSON.stringify(details, null, 2) ?? String(details);
+            } catch {
+                serialized = String(details); // circular / getter throw
+            }
+            pre.textContent = serialized;
+            box.appendChild(pre);
         }
+
+        this.container.replaceChildren(box);
     }
 
     // ─── View Loading ───────────────────────────────────────────
+    /**
+     * Khoá registry thật sự dùng cho `name`.
+     *
+     * Server có ThemeAwareViewFinder nên một view theme không đè vẫn render
+     * được từ base. Client không có đường đó: `__layout__` là tiền tố của CẢ
+     * context, nên `@extends(__layout__ + "workspace")` sinh khoá
+     * `themes.{slug}.layouts.workspace` dù registry chỉ có bản của base.
+     * Server gửi kèm cặp `__view_fallback_from__/to__` trong systemData; ở đây
+     * chỉ đổi tiền tố khi khoá gốc không có.
+     */
+    private resolveRegistryKey(name: string): string {
+        if (Object.prototype.hasOwnProperty.call(this.viewRegistry, name)) return name;
+
+        const from = (this.systemData as any)?.__view_fallback_from__;
+        const to = (this.systemData as any)?.__view_fallback_to__;
+        if (typeof from !== 'string' || typeof to !== 'string' || !from || !to) return name;
+
+        const rebased = name === from
+            ? to
+            : (name.startsWith(from + '.') ? to + name.slice(from.length) : name);
+
+        return Object.prototype.hasOwnProperty.call(this.viewRegistry, rebased) ? rebased : name;
+    }
+
     hasView(name: string): boolean {
-        return Object.prototype.hasOwnProperty.call(this.viewRegistry, name);
+        return Object.prototype.hasOwnProperty.call(this.viewRegistry, this.resolveRegistryKey(name));
     }
 
     exists(name: string): boolean {
         return this.hasView(name);
     }
 
-    view(name: string, data: Record<string, any>, cache: boolean): any {
+    /**
+     * generateViewId — tạo unique ID cho mỗi view instance.
+     *
+     * Compiled output gọi:
+     *   const __VIEW_ID__ = __data__.__SSR_VIEW_ID__ || App.View.generateViewId();
+     *
+     * Dùng trong constructor của compiled View class để gán viewId
+     * (tránh hai instance cùng view path dùng chung ID gây clobber registry).
+     */
+    generateViewId(): string {
+        return `c${(this.viewSeq++).toString(36)}`;
+    }
+
+    /**
+     * Bộ đếm cho view do CLIENT tạo (CSR / điều hướng SPA).
+     *
+     * Tiền tố 'c' — server dùng 'v' (ViewContextServiceProvider) — nên hai nguồn
+     * id không thể trùng nhau theo cấu trúc, không phải nhờ may mắn ngẫu nhiên.
+     * View hydrate từ SSR KHÔNG đi qua đây: nó nhận thẳng __SSR_VIEW_ID__ của
+     * server, nên hai phía luôn khớp.
+     */
+    private viewSeq = 0;
+
+    /** Factory đã unwrap của các view lazy — tránh await + unwrap lại mỗi lần navigate. */
+    private resolvedFactories: Map<string, (...args: any[]) => any> = new Map();
+
+    /**
+     * Tạo View instance. Hỗ trợ registry lazy (`() => import('./x.js')`) — dùng
+     * cho view cấp ROUTE (mountView/hydrateView). `@include`/`@extends` chạy
+     * trong render tree đồng bộ nên dùng `resolveViewSync()`.
+     */
+    async view(name: string, data: Record<string, any>, cache: boolean): Promise<any> {
         try {
-            if (cache && this.store.has(name)) {
-                const cachedView = this.store.get<View>(name);
-                if (hasData(data)) {
-                    cachedView?.__ctrl__.updateData(data);
+            // Khoá store phải là khoá registry ĐÃ RESOLVE, không phải tên được
+            // yêu cầu. Khi theme đang bật, `__layout__` là tiền tố của cả context
+            // nên tên yêu cầu là `themes.{slug}.layouts.docs` còn view thật lấy
+            // từ base: `ctrl.path` = `web.layouts.docs`. Hai chỗ dọn store
+            // (`pageCache.onEvict` và `destroyLayoutView`) đều xoá theo
+            // `ctrl.path`, nên lưu theo tên yêu cầu là instance ĐÃ DESTROY nằm
+            // lại trong store vĩnh viễn — lần điều hướng sau `extendView` trả về
+            // nó và `render()` trả rỗng. Không bật theme thì hai khoá trùng nhau
+            // nên bug này ẩn hoàn toàn.
+            const key = this.resolveRegistryKey(name);
+            const cached = this.viewFromStore(key, data, cache);
+            if (cached) return cached;
+            const factory = this.resolvedFactories.get(key) ?? this.viewRegistry[key];
+            if (!factory || typeof factory !== 'function') {
+                logger.error(`View "${name}" not found in registry.`);
+                return null;
+            }
+
+            const systemData = this.buildSystemData();
+            let view = factory(data ?? {}, systemData);
+
+            // Registry lazy → Promise<module>. Await, chuẩn hoá, cache factory đã
+            // unwrap để lần navigate sau không phải await/unwrap lại.
+            if (view && typeof view.then === 'function') {
+                const lazyFactory = this.unwrapLazyFactory(await view);
+                if (!lazyFactory) {
+                    logger.error(`Lazy view "${name}" did not resolve to a factory or View.`);
+                    return null;
                 }
-                return cachedView;
+                // Cache theo `key` cho khớp chỗ đọc ở trên; theo `name` thì
+                // lần sau luôn trượt cache khi theme đang bật.
+                this.resolvedFactories.set(key, lazyFactory);
+                view = lazyFactory(data ?? {}, systemData);
             }
-            const factory = this.viewRegistry[name];
+            return this.finalizeView(key, view, cache);
+        }
+        catch (err) {
+            // Gồm cả chunk 404 / mạng lỗi khi import() — không để throw ra Router.
+            logger.error(`Error loading view ${name}:`, err);
+            return null;
+        }
+    }
+
+    /**
+     * Bản đồng bộ cho `@include`/`@extends` — render tree không await được.
+     * View lazy CHƯA preload → null + hướng dẫn, thay vì trả Promise làm vỡ
+     * ngầm ở `view.__ctrl__` phía sau.
+     */
+    resolveViewSync(name: string, data: Record<string, any>, cache: boolean): any {
+        try {
+            // Xem ghi chú ở view(): khoá store bám khoá registry đã resolve.
+            const key = this.resolveRegistryKey(name);
+            const cached = this.viewFromStore(key, data, cache);
+            if (cached) return cached;
+            const factory = this.resolvedFactories.get(key) ?? this.viewRegistry[key];
             if (!factory || typeof factory !== 'function') {
                 logger.error(`View "${name}" not found in registry.`);
                 return null;
             }
-            const view = factory(data ? { data } : {}, { App: this.App, View: this, ...this.systemData });
-            if (!view) {
-                logger.error(`Factory for view "${name}" did not return a valid view instance.`);
+
+            const view = factory(data ?? {}, this.buildSystemData());
+            if (view && typeof view.then === 'function') {
+                logger.error(
+                    `View "${name}" là lazy nhưng được dùng qua @include/@extends — render tree đồng bộ ` +
+                    `không await được. Gọi App.View.preloadView("${name}") trước, hoặc để view này eager trong registry.`
+                );
                 return null;
             }
-            if (cache) {
-                this.store.set(name, view);
-            }
-            return view;
-
+            return this.finalizeView(key, view, cache);
         }
         catch (err) {
             logger.error(`Error loading view ${name}:`, err);
@@ -240,6 +499,54 @@ export class ViewManager implements ViewManagerInterface {
         }
     }
 
+    /** Nạp trước một view lazy để `@include`/`@extends` dùng được đồng bộ sau đó. */
+    async preloadView(name: string): Promise<boolean> {
+        if (this.resolvedFactories.has(name)) return true;
+        const view = await this.view(name, {}, false);
+        if (!view) return false;
+        view.__ctrl__?.destroy?.(); // instance dò đường — chỉ cần factory đã cache
+        return true;
+    }
+
+    private viewFromStore(name: string, data: Record<string, any>, cache: boolean): any {
+        if (!cache || !this.store.has(name)) return null;
+        const cachedView = this.store.get<View>(name);
+        if (hasData(data)) cachedView?.__ctrl__.updateData(data);
+        return cachedView;
+    }
+
+    /**
+     * Truyền data PHẲNG cho factory: compiled factory nhận __data__ là chính
+     * object data (đọc __data__.__SSR_VIEW_ID__, setup({data:__data__})).
+     * Trước đây bọc { data } → __data__.__SSR_VIEW_ID__ = undefined và ctrl.data
+     * bị lồng (vỡ route-param). Xem docs/HYDRATION.md §9.2.
+     */
+    private buildSystemData(): Record<string, any> {
+        return { App: this.App, View: this, ...this.systemData };
+    }
+
+    private finalizeView(name: string, view: any, cache: boolean): any {
+        if (!view) {
+            logger.error(`Factory for view "${name}" did not return a valid view instance.`);
+            return null;
+        }
+        if (cache) this.store.set(name, view);
+        return view;
+    }
+
+    /**
+     * Chuẩn hoá kết quả resolve của registry lazy về factory `(data, sys) => View`.
+     * Chấp nhận: module namespace (`{ default: factory }`), factory trần, hoặc
+     * View instance — người viết registry không phải tự `.then(m => m.default)`.
+     */
+    private unwrapLazyFactory(resolved: any): ((...args: any[]) => any) | null {
+        if (!resolved) return null;
+        if (typeof resolved === 'function') return resolved;
+        if (typeof resolved.default === 'function') return resolved.default;
+        if (resolved.__ctrl__) return () => resolved; // đã là View instance
+        return null;
+    }
+
     private createRenderPageViewError(view: ViewInterface, renderLevel: number, message?: string): RenderPageViewError {
         return {
             type: 'error',
@@ -250,14 +557,32 @@ export class ViewManager implements ViewManagerInterface {
             result: null,
             superView: null,
             finalView: view,
+            chain: [view],
         };
     }
 
+    private createRenderPageViewCancelled(view: ViewInterface): RenderPageViewCancelled {
+        return {
+            type: 'cancelled',
+            message: '',
+            view,
+            result: null,
+            superView: null,
+            finalView: view,
+            chain: [view],
+        };
+    }
+
+    private isNavigationCurrent(generation: number): boolean {
+        return generation === this.navigationGeneration;
+    }
+
     private createRenderPageViewSuccess(
         view: ViewInterface,
         result: ViewInterface | unknown,
         superView: ViewInterface | null,
-        finalView: ViewInterface
+        finalView: ViewInterface,
+        chain: ViewInterface[] = [view],
     ): RenderPageViewSuccess {
         return {
             type: 'success',
@@ -266,11 +591,12 @@ export class ViewManager implements ViewManagerInterface {
             result,
             superView,
             finalView,
+            chain,
         };
     }
 
     private getRenderResultType(result: unknown): OOTEnum {
-        return isRenderableObject(result) ? result.oneType as OOTEnum : OOTEnum.UNKNOWN;
+        return isRenderableObject(result) ? result.saoType as OOTEnum : OOTEnum.UNKNOWN;
     }
 
 
@@ -281,14 +607,23 @@ export class ViewManager implements ViewManagerInterface {
         mountRoot: HtmlInterface | null = null,
         initMode: InitMode = InitModes.CREATE,
         cache: boolean = false,
-        renderLevel: number = 0
+        renderLevel: number = 0,
+        navigationGeneration: number = this.navigationGeneration,
     ): Promise<RenderPageViewResult> {
+        if (!this.isNavigationCurrent(navigationGeneration)) {
+            return this.createRenderPageViewCancelled(view);
+        }
         const ctrl = view.__ctrl__;
 
         if (hasData(data)) {
             ctrl.updateData(data);
         }
 
+        // Truyền initMode vào controller TRƯỚC khi render —
+        // để tất cả elements con (Html, Wrapper, Reactive, Output...)
+        // biết mình đang ở chế độ hydrate hay create.
+        ctrl.initMode = initMode;
+
         const result = method === 'render'
             ? ctrl.render()
             : (ctrl.prerender ? ctrl.prerender() : null);
@@ -305,17 +640,58 @@ export class ViewManager implements ViewManagerInterface {
         }
 
         if (resultType === OOTEnum.VIEW) {
+            const superView = result as ViewInterface;
+
+            // CSR navigation may resolve @extends to the exact Layout instance
+            // that is already active. Its DOM, outlets and lifecycle are retained,
+            // so rendering it again only recreates declarations and can repeat
+            // user side effects. Reuse the already-resolved outer chain instead.
+            // Hydration must still render every level to claim Blade's SSR DOM.
+            if (initMode === InitModes.CREATE) {
+                const activeLayoutIndex = this.currentLayoutChain.indexOf(superView);
+                if (activeLayoutIndex >= 0) {
+                    const reusedChain = this.currentLayoutChain
+                        .slice(0, activeLayoutIndex + 1)
+                        .reverse();
+                    return this.createRenderPageViewSuccess(
+                        view,
+                        superView,
+                        superView,
+                        reusedChain[reusedChain.length - 1] ?? superView,
+                        [view, ...reusedChain],
+                    );
+                }
+            }
+
+            // ── Hydrate: gán viewId của layout TRƯỚC khi render nó ──────────
+            // Page gọi extendView(layoutPath, {}) → layout tự sinh viewId ngẫu
+            // nhiên, KHÔNG khớp viewId server đã render. Phải gán đúng id ở đây
+            // (trước render → trước khi Wrapper layout capture ctx.viewId), bằng
+            // cách đọc lại từ DOM view marker <!--s:v:{id}-s--> server để lại.
+            if (initMode === InitModes.HYDRATE) {
+                const discovered = this.discoverChainViewId(
+                    mountRoot,
+                    new Set([ctrl.viewId]),
+                    superView.__ctrl__.path,
+                    ctrl.viewId,
+                );
+                if (discovered) {
+                    superView.__ctrl__.viewId = discovered;
+                }
+            }
+
             const superResult = await this.renderPageView(
-                result as ViewInterface, {}, mountRoot, initMode, cache, renderLevel + 1
+                superView, {}, mountRoot, initMode, cache, renderLevel + 1, navigationGeneration
             );
-            if (superResult.type === 'error') {
+            if (superResult.type !== 'success') {
                 return { ...superResult, view };
             }
             return this.createRenderPageViewSuccess(
                 view,
-                result,
+                superView,
                 superResult.view,
-                superResult.finalView ?? (result as ViewInterface)
+                superResult.finalView ?? superView,
+                [view, ...superResult.chain],
             );
         }
 
@@ -323,15 +699,67 @@ export class ViewManager implements ViewManagerInterface {
             `View "${ctrl.path}" returned invalid content (type: ${resultType}) from ${method}().`);
     }
 
+    /**
+     * Discover viewId của một layout/superView từ SSR DOM (hydration).
+     *
+     * Page gọi extendView() KHÔNG truyền viewId của layout (server tự sinh id),
+     * nên client lấy lại id từ quan hệ instance mà Blade export. Nếu output cũ
+     * chưa có quan hệ này, client mới discover từ metadata/marker trong DOM.
+     *
+     * Nested chain ưu tiên quan hệ parent chính xác trong APP_CONFIGS.view.ssrData,
+     * sau đó mới tới `data-view-name`/`data-view-id`; marker scan là fallback.
+     */
+    private discoverChainViewId(
+        mountRoot: HtmlInterface | null,
+        excludeIds: Set<string>,
+        viewPath?: string,
+        parentViewId?: string,
+    ): string | null {
+        if (viewPath) {
+            const instances = this.ssrViewData[viewPath]?.instances;
+            if (instances && typeof instances === 'object') {
+                for (const [instanceId, instance] of Object.entries(instances)) {
+                    const id = (instance as any)?.viewId ?? instanceId;
+                    if (id && !excludeIds.has(id)
+                        && (!parentViewId || (instance as any)?.parent?.id === parentViewId)) {
+                        return id;
+                    }
+                }
+            }
+            const records = document.querySelectorAll('script[data-ref="view-data"][data-view-id]');
+            for (const record of records) {
+                const id = record.getAttribute('data-view-id');
+                if (record.getAttribute('data-view-name') === viewPath
+                    && id && !excludeIds.has(id)) return id;
+            }
+        }
+        const root = mountRoot?.getElement?.() ?? this.rootElement?.getElement?.();
+        if (!root) return null;
+
+        const walker = document.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+        let node: Comment | null;
+        while ((node = walker.nextNode() as Comment | null)) {
+            const parsed = markerRegistry.parseComment(node.nodeValue ?? '');
+            if (parsed && parsed.tag === 'view' && !parsed.isClose && !excludeIds.has(parsed.id)) {
+                return parsed.id;
+            }
+        }
+        return null;
+    }
+
     async renderPageView(
-        view: ViewInterface, 
-        data: Record<string, any>, 
-        mountRoot: HtmlInterface | null = null, 
-        initMode: InitMode = InitModes.CREATE, 
-        cache: boolean = false, 
-        renderLevel: number = 0
+        view: ViewInterface,
+        data: Record<string, any>,
+        mountRoot: HtmlInterface | null = null,
+        initMode: InitMode = InitModes.CREATE,
+        cache: boolean = false,
+        renderLevel: number = 0,
+        navigationGeneration: number = this.navigationGeneration,
     ): Promise<RenderPageViewResult> {
         try {
+            if (!this.isNavigationCurrent(navigationGeneration)) {
+                return this.createRenderPageViewCancelled(view);
+            }
             const ctrl = view.__ctrl__;
             if (hasData(data)) {
                 ctrl.updateData(data);
@@ -341,43 +769,124 @@ export class ViewManager implements ViewManagerInterface {
 
             // ── Case 1: Không có async data → render ngay ──
             if (!hasAsyncData) {
-                return this.callViewRenderFactory(view, 'render', data, mountRoot, initMode, cache, renderLevel);
+                return this.callViewRenderFactory(view, 'render', data, mountRoot, initMode, cache, renderLevel, navigationGeneration);
+            }
+
+            // ── Hydrate: SSR đã fetch + nhúng data rồi (qua __data__/ssrData) —
+            // KHÔNG fetch lại, KHÔNG hiện skeleton. Nhưng prerender() không chỉ
+            // là skeleton: với view @extends + @block, compiler gom phần block/
+            // section TĨNH (không phụ thuộc data await) VÀO PRERENDER, render()
+            // chỉ khai báo lại đúng (các) block phụ thuộc data (xem
+            // examples/sao/await.sao đã compile: prerender() có
+            // block-content(placeholder)+block-footer+section('sidebar'), còn
+            // render() chỉ có block-content — bỏ qua prerender() sẽ làm mất
+            // hẳn block-footer/sidebar khi hydrate).
+            // → Vẫn phải gọi prerender() để đăng ký các block/section tĩnh đó,
+            // rồi gọi NGAY render() (data đã có sẵn, không await fetch) — nó
+            // ghi đè contentRenderFactory của block phụ thuộc data (placeholder
+            // → nội dung thật) tại chỗ. Không có gì được mount ở bước nào cả
+            // (hydrate mode chỉ claim), nên không có flash trung gian.
+            if (initMode === InitModes.HYDRATE) {
+                if (config.hasPrerender) {
+                    const prerenderResult = await this.callViewRenderFactory(view, 'prerender', data, mountRoot, initMode, cache, renderLevel, navigationGeneration);
+                    if (prerenderResult.type === 'cancelled') return prerenderResult;
+                    if (prerenderResult.type === 'error') {
+                        logger.error(`Error prerendering view "${ctrl.path}" during hydrate:`, prerenderResult.message);
+                        // Tiếp tục render() — thà thiếu block tĩnh còn hơn vỡ cả trang.
+                    }
+                }
+                return this.callViewRenderFactory(view, 'render', data, mountRoot, initMode, cache, renderLevel, navigationGeneration);
             }
 
             // ── Resolve fetch URL từ ViewController config hoặc fallback Router ──
             const App = app() as ApplicationInterface;
             const Http = App.Http;
             const fetchConfig = config.fetch;
-            const fetchUrl = (config.hasAwaitData && fetchConfig?.url)? fetchConfig?.url : App.Router.getFullUrl();
+            const fetchUrl = (config.hasAwaitData && fetchConfig?.url) ? fetchConfig.url : resolveViewDataUrl(App.Router.getFullUrl(), this.dataEndpoint);
 
             // ── Case 2: Có async + có prerender → prerender skeleton trước, fetch sau ──
             if (config.hasPrerender) {
-                const prerenderResult = await this.callViewRenderFactory(view, 'prerender', data, mountRoot, initMode, cache, renderLevel);
+                const renderGeneration = navigationGeneration;
+                const prerenderResult = await this.callViewRenderFactory(view, 'prerender', data, mountRoot, initMode, cache, renderLevel, navigationGeneration);
+                if (prerenderResult.type === 'cancelled') return prerenderResult;
                 if (prerenderResult.type === 'error') {
                     logger.error(`Error prerendering view "${ctrl.path}":`, prerenderResult.message);
                     // Fallback: render trực tiếp không qua prerender
-                    return this.callViewRenderFactory(view, 'render', data, mountRoot, initMode, cache, renderLevel);
+                    return this.callViewRenderFactory(view, 'render', data, mountRoot, initMode, cache, renderLevel, navigationGeneration);
                 }
 
-                // Fire-and-forget: fetch data rồi re-render thay thế skeleton
-                // TODO: Sau khi render() xong, cần swap DOM từ preloadElement → mainElement
-                // ViewController.wrapper() tự động lưu prerender vào preloadElement, render vào mainElement
-                // Cần bổ sung logic: unmount preloadElement khỏi DOM → mount mainElement vào cùng vị trí
-                Http.get(fetchUrl).then(async (response: any) => {
-                    const asyncData = response?.data ?? {};
+                // Fire-and-forget: fetch data → re-render → swap skeleton → main
+                this.pendingAsyncRenders++;
+                Http.get(fetchUrl, this.fetchOptions).then(async (response: any) => {
+                    // Route mới hoặc manager teardown đã bắt đầu: tuyệt đối không
+                    // render/mount kết quả cũ trở lại root DOM.
+                    if (renderGeneration !== this.navigationGeneration
+                        || ctrl.lifecycleState === 'destroyed') return;
+
+                    const asyncData = this.extractAsyncData(response);
                     if (hasData(asyncData)) {
                         ctrl.updateData(asyncData);
                     }
-                    const finalResult = await this.callViewRenderFactory(view, 'render', asyncData, mountRoot, initMode, cache, renderLevel);
+
+                    // Render main content (kết quả sẽ nằm trong ctrl.mainElement)
+                    const finalResult = await this.callViewRenderFactory(view, 'render', asyncData, mountRoot, initMode, cache, renderLevel, navigationGeneration);
+                    if (renderGeneration !== this.navigationGeneration
+                        || ctrl.lifecycleState === 'destroyed') return;
                     if (finalResult.type === 'error') {
                         logger.error(`Error rendering view "${ctrl.path}" after async data fetch:`, finalResult.message);
+                        return;
+                    }
+
+                    if (finalResult.superView) {
+                        // ── @extends page: render() re-registered real block content
+                        // via this.block(...), but never called this.wrapper() — so
+                        // ctrl.mainElement/preloadElement (what the standalone swap
+                        // below acts on) were never set. The already-mounted layout's
+                        // outlet still shows the placeholder from the prerender-time
+                        // this.block(...) call; push the new content into it the same
+                        // way the initial mount does (mountViewBlocks clears the old
+                        // content first, so the placeholder is removed as part of this).
+                        // Block tìm outlet THEO TÊN nên viewId của page là đủ;
+                        // section thì không — xem mountSectionsAcrossChain().
+                        this.blockManager.mountViewBlocks(ctrl.viewId);
+                        this.mountSectionsAcrossChain(ctrl.viewId, this.currentLayoutChain);
+                        commitView(ctrl);
+                        this.blockManager.startAll();
+                        this.sectionManager.startAll();
+                        logger.info(`[ViewManager] prerender → main swap done for "${ctrl.path}" (block content)`);
+                        return;
+                    }
+
+                    // ── Swap: preloadElement (skeleton) → mainElement (real) ──
+                    // 1. Destroy skeleton khỏi DOM
+                    if (ctrl.preloadElement && typeof ctrl.preloadElement.destroy === 'function') {
+                        ctrl.preloadElement.stop?.();
+                        ctrl.preloadElement.destroy();
+                    }
+                    // 2. Mount mainElement vào cùng vị trí (mountRoot)
+                    if (ctrl.mainElement && mountRoot) {
+                        ctrl.mainElement.setParentElement(mountRoot);
+                        ctrl.mainElement.mountTo(mountRoot);
                     }
-                    // TODO: swap preloadElement → mainElement trong DOM
-                    // ctrl.preloadElement?.destroy();
-                    // ctrl.mainElement?.setParentElement(mountRoot);
-                    // ctrl.mainElement?.render();
+                    // 3. Commit data + start reactivity
+                    commitView(ctrl);
+                    ctrl.mainElement?.start?.();
+                    logger.info(`[ViewManager] prerender → main swap done for "${ctrl.path}"`);
                 }).catch((err: any) => {
-                    logger.error(`Error fetching async data for view "${ctrl.path}":`, err);
+                    if (!this.isNavigationCurrent(renderGeneration)) return;
+                    // Fetch hỏng khi skeleton đang hiển thị: không có boundary thì
+                    // trước giờ chỉ log → skeleton treo vĩnh viễn. Đưa vào boundary
+                    // để view tự hiện trạng thái lỗi.
+                    const handled = ctrl.handleError(err, { phase: 'async', path: ctrl.path }).handled;
+                    if (!handled) logger.error(`Error fetching async data for view "${ctrl.path}":`, err);
+                }).finally(() => {
+                    this.pendingAsyncRenders--;
+                    // Nội dung thật vừa thay chỗ skeleton. Ai đã trang trí DOM
+                    // trước đó (tô màu code, dựng mục lục…) phải được báo để
+                    // làm lại — bản trang trí cũ nằm trên node vừa bị thay.
+                    if (this.pendingAsyncRenders === 0) {
+                        (app() as ApplicationInterface).Event?.emit('view:settled');
+                    }
                 });
 
                 // Return prerender result ngay — mountView sẽ mount skeleton
@@ -387,17 +896,25 @@ export class ViewManager implements ViewManagerInterface {
             // ── Case 3: Có async + không prerender → await fetch rồi render ──
             let asyncData: Record<string, any> = {};
             try {
-                const response = await Http.get(fetchUrl);
-                asyncData = response?.data ?? {};
+                const response = await Http.get(fetchUrl, this.fetchOptions);
+                asyncData = this.extractAsyncData(response);
             } catch (err) {
-                logger.error(`Error fetching async data for view "${ctrl.path}":`, err);
+                if (!this.isNavigationCurrent(navigationGeneration)) {
+                    return this.createRenderPageViewCancelled(view);
+                }
+                const handled = ctrl.handleError(err, { phase: 'async', path: ctrl.path }).handled;
+                if (!handled) logger.error(`Error fetching async data for view "${ctrl.path}":`, err);
+            }
+
+            if (!this.isNavigationCurrent(navigationGeneration)) {
+                return this.createRenderPageViewCancelled(view);
             }
 
             if (!hasData(asyncData)) {
                 logger.warn(`View "${ctrl.path}" has async data config but fetch returned no data.`);
             }
 
-            return this.callViewRenderFactory(view, 'render', asyncData, mountRoot, initMode, cache, renderLevel);
+            return this.callViewRenderFactory(view, 'render', asyncData, mountRoot, initMode, cache, renderLevel, navigationGeneration);
         }
         catch (err) {
             logger.error(`Error rendering view ${view.__ctrl__.path}:`, err);
@@ -416,266 +933,790 @@ export class ViewManager implements ViewManagerInterface {
 
     // ─── Mount Orchestration ────────────────────────────────────
 
+    /**
+     * Mount view khi navigate — luồng chuẩn (ROUTE_RENDER_FLOW.md):
+     *   sweep TTL → duplicate guard → pause+cache trang cũ (standalone LẪN
+     *   page thuộc layout) → thử restore từ PageCache (theo view name + URI,
+     *   trong TTL, mọi navigation type) → mount mới
+     *   (render → mount DOM → commitData → start).
+     *
+     * Lifecycle khi RỜI trang (deactivatePage):
+     *   - page cacheable  → pause (pausing/paused) + detach DOM → PageCache
+     *   - page cache:false → destroy (stopping/stopped → unmounting/unmounted → destroyed)
+     *   - layout KHÔNG đổi → không hook nào fire trên layout (giữ nguyên DOM + subscription)
+     *   - layout đổi/về standalone → destroy layout chain
+     */
+    private localeInvalidated = false;
+
+    invalidateLocale(): void {
+        this.cancelNavigation();
+        this.localeInvalidated = true;
+        this.pageCache.clear();
+    }
+
     async mountView(name: string, data?: Record<string, any>, route?: ActiveRouteInterface, navigationType: RouterNavigationType = 'push'): Promise<any> {
-        // ── Phase 1: Load view ──
-        const view = this.view(name, data ?? {}, true);
-        if (!view) {
-            this.showError(`Failed to load view "${name}".`);
-            return null;
+        if (this.localeInvalidated) {
+            this.unmountAll();
+            this.store.clear();
+            this.ssrBoot = null;
+            this.localeInvalidated = false;
+        }
+        // Request URI = path + query (KHÔNG hash) — Router cung cấp qua $uri
+        const targetUrl = (route as any)?.$uri ?? route?.$urlPath ?? name;
+
+        // ── Phase 0: TTL sweep + duplicate guard ──
+        this.pageCache.sweep();
+        if (this.currentPageView
+            && this.currentPageView.__ctrl__.urlPath === targetUrl) {
+            return null; // đã đứng đúng trang này
         }
 
+        // Mọi async work của navigation trước trở thành stale từ thời điểm này.
+        const navigationGeneration = ++this.navigationGeneration;
+
+        // Head tags (title/meta) từ trang trước không được rò rỉ sang trang mới —
+        // mountViewSections() của layout/page mới sẽ set lại đúng phần chúng khai báo.
+        this.sectionManager.resetPageHead();
+
         const oldPageView = this.currentPageView;
         const oldLayoutView = this.currentLayoutView;
-        const oldLayoutPath = this.currentLayoutPath;
-
-        view.__ctrl__.urlPath = route?.$urlPath ?? null;
+        const oldLayoutChain = [...this.currentLayoutChain];
+        // BlockManager hiện đăng ký block theo outlet dùng chung. Với page
+        // thuộc Layout, phải detach ownership cũ trước khi render page mới;
+        // nếu không block mới sẽ ghi đè registry và cache sai DOM.
+        // Standalone không có ràng buộc này nên được giữ active tới commit.
+        const oldPageRequiresEarlyDeactivate = oldPageView !== null && oldLayoutChain.length > 0;
+        let oldPageDeactivated = false;
+        if (oldPageRequiresEarlyDeactivate) {
+            this.deactivatePage(oldPageView!, oldLayoutView);
+            this.currentPageView = null;
+            oldPageDeactivated = true;
+        }
 
-        if(oldLayoutView){
-            oldLayoutView.__ctrl__.stop();
+        // ── Phase 1: thử restore từ PageCache (key = view name + request URI) ──
+        // Trong TTL: mọi navigation type đều restore (bfcache). Hết TTL → mount tươi.
+        const cachedEntry = this.pageCache.take(this.cacheKey(name, targetUrl));
+        if (cachedEntry) {
+            if (oldPageView && !oldPageDeactivated) {
+                this.deactivatePage(oldPageView, oldLayoutView);
+                oldPageDeactivated = true;
+            }
+            this.currentPageView = null;
+            const restored = this.restoreFromCache(cachedEntry, oldLayoutView, navigationType);
+            if (restored) return restored;
         }
-        oldPageView?.__ctrl__.stop();
 
-        // ── Phase 2: Render chain ──
-        const renderResult = await this.renderPageView(view, data ?? {}, this.rootElement, InitModes.CREATE, true);
+        // ── Phase 2: Load + render chain trong khi page cũ vẫn active. ──
+        // Chỉ khi render thành công mới pause/destroy page cũ; fetch/render lỗi
+        // không được làm màn hình hiện tại biến mất.
+        const view = await this.view(name, data ?? {}, false);
+        if (!view) {
+            const message = `Failed to load view "${name}".`;
+            if (oldPageView && oldPageDeactivated) {
+                this.restoreDeactivatedPage(oldPageView!, oldLayoutView);
+            }
+            if (oldPageView) logger.error(message);
+            else this.showError(message);
+            return null;
+        }
+        view.__ctrl__.urlPath = targetUrl;
+
+        const renderResult = await this.renderPageView(
+            view, data ?? {}, this.rootElement, InitModes.CREATE, false, 0, navigationGeneration
+        );
+        if (renderResult.type === 'cancelled') {
+            view.__ctrl__.destroy();
+            if (oldPageView && oldPageDeactivated) {
+                this.restoreDeactivatedPage(oldPageView!, oldLayoutView);
+            }
+            return null;
+        }
         if (renderResult.type === 'error') {
-            this.showError(renderResult.message);
+            view.__ctrl__.destroy();
+            if (oldPageView && oldPageDeactivated) {
+                this.restoreDeactivatedPage(oldPageView!, oldLayoutView);
+            }
+            if (oldPageView) logger.error(renderResult.message);
+            else this.showError(renderResult.message);
+            return null;
+        }
+
+        // ── Phase 3: commit transition ──
+        // Page/Layout mới đã resolve xong; bây giờ mới rời chain cũ và mount chain mới.
+        if (oldPageView && !oldPageDeactivated) {
+            this.deactivatePage(oldPageView, oldLayoutView);
+        }
+        this.currentPageView = null;
+        // Phase mount nằm NGOÀI try/catch của renderPageView: lỗi phát sinh khi
+        // gắn tree vào DOM (vd @include con throw) trước đây thoát hẳn ra ngoài
+        // → unhandled rejection + trang mount dở. Error boundary đã xử lý phần
+        // lớn (Component/Reactive); đây là lưới cuối khi không boundary nào nhận.
+        try {
+            this.activateRenderedChain(renderResult, InitModes.CREATE, oldLayoutChain);
+        } catch (err) {
+            logger.error(`Error mounting view "${name}":`, err);
+            this.showError(`Error mounting view "${name}".`, err instanceof Error ? err.message : err);
             return null;
         }
 
-        const pageView: ViewInterface = renderResult.view;
-        const finalView: ViewInterface = renderResult.finalView;
-        const hasSuperView = renderResult.superView !== null;
-        const newLayoutPath = hasSuperView ? finalView.__ctrl__.path : null;
-
-        // bắt đầu logic
-
-        // ── Phase 3: Classify mount scenario ──
-        const isSameLayout = hasSuperView
-            && oldLayoutView !== null
-            && finalView === oldLayoutView;
-
-        // ── Duplicate navigation guard ──
-        if (oldPageView === pageView
-            && view.__ctrl__.urlPath === oldPageView?.__ctrl__?.urlPath) {
-            return renderResult;
-        }
-
-        // ══════════════════════════════════════════════════════════
-        // Case 1: Có superView + cùng layout instance (reuse layout)
-        // ══════════════════════════════════════════════════════════
-        if (hasSuperView && isSameLayout) {
-            // Cắt origin chain cũ → gắn page mới vào layout
-            oldLayoutView!.__ctrl__.ejectOriginChain();
-            pageView.__ctrl__.setChainFromOrigin();
-
-            
-            // Mount block content mới vào layout outlets
-            this.blockManager.mountAll();
-            
-        }
-        // ══════════════════════════════════════════════════════════
-        // Case 2: Có superView + layout khác (hoặc first mount có layout)
-        // ══════════════════════════════════════════════════════════
-        else if (hasSuperView) {
-            // Cleanup toàn bộ old views
-            oldLayoutView?.__ctrl__.ejectOriginChain();
-            this.stopPageView(oldPageView);
-            this.stopLayoutView(oldLayoutView);
-            this.blockManager.clearAllOutlets();
-            this.unmountLayoutDOM(oldLayoutView);
-
-            // Gắn origin chain cho layout mới
-            pageView.__ctrl__.setChainFromOrigin();
-
-            // Build DOM từ layout wrapper vào container
-            this.buildViewDOM(finalView);
-
-            // Mount block content vào layout outlets
-            this.blockManager.mountAll();
-
-            // Commit & Start toàn bộ chain
-            this.commitViewChain(pageView, finalView, true);
-            this.startViewChain(pageView, finalView, true);
-        }
-        // ══════════════════════════════════════════════════════════
-        // Case 3: Không có superView (standalone view)
-        // ══════════════════════════════════════════════════════════
-        else {
-            // Cleanup toàn bộ old views
-            oldLayoutView?.__ctrl__.ejectOriginChain();
-            this.stopPageView(oldPageView);
-            this.stopLayoutView(oldLayoutView);
-            this.blockManager.clearAllOutlets();
-            this.unmountLayoutDOM(oldLayoutView);
-
-            // Build DOM trực tiếp vào container
-            this.buildViewDOM(pageView);
-
-            // Commit & Start
-            this.commitViewChain(pageView, pageView, false);
-            this.startViewChain(pageView, pageView, false);
-        }
-
-        // ── Update state ──
+        return renderResult;
+    }
+
+    /** Commit the successfully mounted/hydrated chain as the only active route state. */
+    private commitActiveChain(
+        pageView: ViewInterface,
+        layoutChain: ViewInterface[],
+    ): void {
         this.currentPageView = pageView;
-        this.currentLayoutView = hasSuperView ? finalView : null;
-        this.currentLayoutPath = newLayoutPath;
-        this.currentViewType = hasSuperView ? 'layout' : 'view';
-        this.viewStack = hasSuperView ? [finalView, pageView] : [pageView];
+        this.currentLayoutChain = [...layoutChain];
+        this.currentLayoutView = layoutChain[0] ?? null;
+        this.currentLayoutPath = this.currentLayoutView?.__ctrl__.path ?? null;
+        this.currentViewType = layoutChain.length > 0 ? 'layout' : 'view';
+        this.viewStack = [...layoutChain, pageView];
         this.renderCount++;
+    }
 
-        return renderResult;
+    /**
+     * Common post-render transaction. Rendering decides the Page/Layout chain;
+     * this step applies the DOM strategy, activates it, then publishes one
+     * coherent active-chain state.
+     */
+    private activateRenderedChain(
+        renderResult: RenderPageViewSuccess,
+        initMode: InitMode,
+        oldLayoutChain: ViewInterface[] = [],
+    ): void {
+        const pageView = renderResult.view;
+        const layoutChain = renderResult.chain.slice(1).reverse();
+
+        if (initMode === InitModes.HYDRATE) {
+            this.activateHydratedChain(pageView, layoutChain);
+        } else {
+            this.activateCreatedChain(pageView, layoutChain, oldLayoutChain);
+        }
+
+        this.commitActiveChain(pageView, layoutChain);
     }
 
-    // ─── DOM Building ───────────────────────────────────────────
+    /** CSR strategy: insert new DOM, while preserving/reusing a compatible Layout. */
+    private activateCreatedChain(
+        pageView: ViewInterface,
+        layoutChain: ViewInterface[],
+        oldLayoutChain: ViewInterface[],
+    ): void {
+        const pageCtrl = pageView.__ctrl__;
+
+        if (layoutChain.length === 0) {
+            if (oldLayoutChain.length > 0) {
+                this.deactivateLayoutChain(oldLayoutChain);
+                this.currentLayoutView = null;
+                this.currentLayoutChain = [];
+                this.currentLayoutPath = null;
+            }
+            pageCtrl.mount(this.rootElement!);
+            commitView(pageCtrl);
+            activateView(pageCtrl);
+            this.sectionManager.mountViewSections(pageCtrl.viewId);
+            this.sectionManager.startAll();
+            return;
+        }
+
+        let common = 0;
+        while (common < oldLayoutChain.length
+            && common < layoutChain.length
+            && oldLayoutChain[common] === layoutChain[common]) {
+            common++;
+        }
+
+        if (common === 0 && oldLayoutChain.length > 0) {
+            this.deactivateLayoutChain(oldLayoutChain);
+        } else {
+            // Root layout vẫn dùng chung; chỉ dọn phần chain không còn reuse.
+            for (let i = oldLayoutChain.length - 1; i >= common; i--) {
+                this.destroyLayoutView(oldLayoutChain[i]);
+            }
+        }
+
+        const resumed = common === 0 && this.resumeLayoutChainFromCache(layoutChain);
+        const newLayouts: ViewInterface[] = [];
+
+        if (!resumed) {
+            let start = common;
+            if (common === 0) {
+                layoutChain[0].__ctrl__.mount(this.rootElement!);
+                newLayouts.push(layoutChain[0]);
+                start = 1;
+            }
+            for (let i = start; i < layoutChain.length; i++) {
+                const layout = layoutChain[i];
+                this.blockManager.mountViewBlocks(layout.__ctrl__.viewId);
+                this.sectionManager.mountViewSections(layout.__ctrl__.viewId);
+                layout.__ctrl__.mount();
+                newLayouts.push(layout);
+            }
+        }
+
+        this.blockManager.mountViewBlocks(pageCtrl.viewId);
+        this.mountSectionsAcrossChain(pageCtrl.viewId, layoutChain);
+        pageCtrl.mount();
+        for (const layout of newLayouts) commitView(layout.__ctrl__);
+        commitView(pageCtrl);
+
+        for (const layout of newLayouts) activateView(layout.__ctrl__);
+        this.blockManager.startAll();
+        this.sectionManager.startAll();
+        activateView(pageCtrl);
+    }
 
     /**
-     * Build DOM từ finalView's Wrapper vào container.
-     * Wrapper.render() sẽ execute childrenFactory → tạo DOM tree.
+     * Đưa `@section` của page tới `@yield` của layout.
+     *
+     * `mountViewSections` lọc yield theo `yieldEl.ctx.viewId`, mà YIELD THUỘC
+     * LAYOUT khai báo nó chứ không thuộc page — nên gọi riêng với viewId của
+     * page thì không yield nào khớp. Chỉ quét các layout MỚI cũng không đủ:
+     * điều hướng giữa hai trang dùng chung một layout thì `common` phủ hết
+     * chuỗi, vòng lặp mount layout không chạy lần nào, và section của trang mới
+     * không bao giờ tới nơi.
+     *
+     * Quét cả chuỗi là an toàn: mountViewSections chỉ áp lại `activeSections`
+     * hiện hành vào từng yield, gọi thừa không đổi kết quả.
      */
-    private buildViewDOM(finalView: ViewInterface): void {
-        const wrapper = finalView.__ctrl__.mainElement;
-        if (!wrapper) {
-            logger.error(`[ViewManager] finalView "${finalView.__ctrl__.path}" has no mainElement (Wrapper).`);
+    private mountSectionsAcrossChain(pageViewId: string, layoutChain: ViewInterface[]): void {
+        this.sectionManager.mountViewSections(pageViewId);
+        for (const layout of layoutChain) {
+            const layoutId = layout?.__ctrl__?.viewId;
+            if (layoutId && layoutId !== pageViewId) {
+                this.sectionManager.mountViewSections(layoutId);
+            }
+        }
+    }
+
+    /** Hydration strategy: claim Blade DOM without insert/clear mutations. */
+    private activateHydratedChain(
+        pageView: ViewInterface,
+        layoutChain: ViewInterface[],
+    ): void {
+        const pageCtrl = pageView.__ctrl__;
+
+        if (layoutChain.length === 0) {
+            commitView(pageCtrl, true);
+            claimHydratedView(pageCtrl, this.rootElement!);
+            pageCtrl.mount();
+            pageCtrl.initMode = InitModes.CREATE;
+            activateView(pageCtrl);
+            this.sectionManager.hydrateViewSections(pageCtrl.viewId);
+            this.sectionManager.startAll();
             return;
         }
-        wrapper.setParentElement(this.rootElement);
-        wrapper.render();
+
+        for (const layout of layoutChain) commitView(layout.__ctrl__, true);
+        commitView(pageCtrl, true);
+        const rootLayoutCtrl = layoutChain[0].__ctrl__;
+        claimHydratedView(rootLayoutCtrl, this.rootElement!);
+        rootLayoutCtrl.mount();
+        for (let i = 1; i < layoutChain.length; i++) {
+            const ctrl = layoutChain[i].__ctrl__;
+            this.blockManager.hydrateViewBlocks(ctrl.viewId);
+            this.sectionManager.hydrateViewSections(ctrl.viewId);
+            ctrl.mount();
+        }
+        this.blockManager.hydrateViewBlocks(pageCtrl.viewId);
+        this.sectionManager.hydrateViewSections(pageCtrl.viewId);
+        pageCtrl.mount();
+        for (const layout of layoutChain) layout.__ctrl__.initMode = InitModes.CREATE;
+        pageCtrl.initMode = InitModes.CREATE;
+
+        for (const layout of layoutChain) activateView(layout.__ctrl__);
+        this.blockManager.startAll();
+        this.sectionManager.startAll();
+        activateView(pageCtrl);
     }
 
-    // ─── Lifecycle: Stop ────────────────────────────────────────
+    /**
+     * Destroy layout cũ (đổi layout hoặc về standalone).
+     * Page cũ đã rời ở Phase 1 (deactivatePage) — không destroy tại đây.
+     */
+    private destroyLayoutView(layoutView: ViewInterface): void {
+        const layoutPath = layoutView.__ctrl__.path;
+        layoutView.__ctrl__.destroy();
+        // Layout cached theo path trong store (extendView dùng cache=true) —
+        // instance đã destroy không được phép trả về từ cache nữa
+        if (layoutPath && this.store.has(layoutPath)) {
+            this.store.remove?.(layoutPath);
+        }
+    }
 
-    private stopPageView(pageView: ViewInterface | null): void {
-        if (!pageView) return;
-        // Stop block content (tracked by BlockManager)
-        this.stopBlockContent();
-        // Fire onDeactivated hook
-        if (typeof pageView.onDeactivated === 'function') {
-            try { pageView.onDeactivated(); }
-            catch (e) { logger.error(`[ViewManager] onDeactivated error:`, e); }
+    private destroyLayoutChain(layoutChain: ViewInterface[]): void {
+        for (let i = layoutChain.length - 1; i >= 0; i--) {
+            this.destroyLayoutView(layoutChain[i]);
         }
     }
 
-    private stopLayoutView(layoutView: ViewInterface | null): void {
-        if (!layoutView) return;
-        const wrapper = layoutView.__ctrl__.mainElement;
-        if (wrapper && typeof wrapper.stop === 'function') {
-            wrapper.stop();
+    // ─── PageCache integration ──────────────────────────────────
+
+    /** bfcache-style cache cho trang đã ghé (ROUTE_RENDER_FLOW.md §8) */
+    public pageCache: PageCacheService = new PageCacheService();
+
+    /**
+     * Cache key = `${viewName}::${requestUri}` — URI gồm path + query,
+     * KHÔNG gồm hash (strip defensive tại đây).
+     */
+    private cacheKey(viewName: string, uri: string): string {
+        return `${viewName}::${(uri ?? '').split('#')[0]}`;
+    }
+
+    /** Cache key cho layout — namespace riêng, không đụng key page (name::uri) */
+    private layoutCacheKey(layoutPath: string): string {
+        return `__layout__::${layoutPath}`;
+    }
+
+    private layoutChainIdentity(layoutChain: ViewInterface[]): string {
+        return layoutChain.map(view => view.__ctrl__.path).join('>');
+    }
+
+    /**
+     * Rời một layout (đổi layout / về standalone): pause + detach toàn vùng DOM
+     * → PageCache (key `__layout__::{path}`). KHÁC destroy ở 2 điểm:
+     *   1. Instance GIỮ NGUYÊN trong store — extendView của page sau trả lại
+     *      đúng instance này (đang paused) → resumeLayoutFromCache nhận ra.
+     *   2. Outlets gỡ khỏi BlockManager registry (không destroy) — tránh
+     *      mountAll đụng outlet trùng tên của layout đang nằm trong cache.
+     * Layout khai cache:false (hoặc ttl 0) → destroy như cũ.
+     */
+    private deactivateLayout(layoutView: ViewInterface): void {
+        this.deactivateLayoutChain([layoutView]);
+    }
+
+    private deactivateLayoutChain(layoutChain: ViewInterface[]): void {
+        const rootCtrl = layoutChain[0]?.__ctrl__;
+        if (!rootCtrl) return;
+        const cacheConfig = rootCtrl.getConfig('cache');
+        const ttl = typeof cacheConfig === 'object' && cacheConfig?.ttl != null ? cacheConfig.ttl : undefined;
+        const wrapper = rootCtrl.mainElement;
+
+        if (!wrapper || cacheConfig === false || ttl === 0) {
+            this.destroyLayoutChain(layoutChain);
+            return;
+        }
+
+        for (let i = layoutChain.length - 1; i >= 0; i--) {
+            layoutChain[i].__ctrl__.pause();
         }
-        if (typeof layoutView.onDeactivated === 'function') {
-            try { layoutView.onDeactivated(); }
-            catch (e) { logger.error(`[ViewManager] layout onDeactivated error:`, e); }
+        for (const layout of layoutChain) {
+            this.blockManager.detachOutletsOfView(layout.__ctrl__.viewId);
         }
+        const fragment = detachWrapperDOM(wrapper);
+        this.pageCache.set(this.layoutCacheKey(this.layoutChainIdentity(layoutChain)), {
+            views: [...layoutChain],
+            fragment,
+            layoutPath: null,
+            scroll: { x: 0, y: 0 },
+            ttl,
+        });
     }
 
-    private stopBlockContent(): void {
-        // BlockManager tracks mounted children per outlet
-        for (const [name, children] of (this.blockManager as any).mountedChildren) {
-            if (Array.isArray(children)) {
-                for (const child of children) {
-                    if (child && typeof child.stop === 'function') {
-                        child.stop();
-                    }
-                }
+    /**
+     * Layout lấy từ store đang PAUSED (đã vào cache trước đó) → reattach
+     * fragment + resume thay vì mount lại. Trả false nếu layout không paused
+     * (layout mới tạo → caller mount bình thường).
+     */
+    private resumeLayoutChainFromCache(layoutChain: ViewInterface[]): boolean {
+        if (layoutChain.length === 0
+            || layoutChain.some(layout => layout.__ctrl__.lifecycleState !== 'paused')) return false;
+
+        const entry = this.pageCache.take(this.layoutCacheKey(this.layoutChainIdentity(layoutChain)));
+        if (entry) {
+            this.rootElement!.getElement().appendChild(entry.fragment);
+            for (const layout of layoutChain) layout.__ctrl__.resume();
+        } else {
+            return false;
+        }
+        for (const layout of layoutChain) this.reregisterLayoutOutlets(layout.__ctrl__);
+        return true;
+    }
+
+    /** Đăng ký lại outlets của layout vừa resume vào BlockManager registry */
+    private reregisterLayoutOutlets(layoutCtrl: ViewControllerInterface): void {
+        const elements: Map<string, any> | undefined = (layoutCtrl as any).elements;
+        if (!elements) return;
+        for (const [id, el] of elements) {
+            if (el instanceof BlockOutlet && !(el as any).__destroyed__) {
+                this.blockManager.addOutlet(id, el);
             }
         }
     }
 
-    // ─── Lifecycle: Start ───────────────────────────────────────
+    /**
+     * Navigate rời một page: pause + detach DOM → PageCache.
+     *   - Standalone: detach toàn vùng wrapper (markers + content).
+     *   - Page thuộc layout: detach block content THEO OUTLET — layout giữ nguyên,
+     *     không hook nào fire trên layout.
+     * View khai cache:false (hoặc ttl 0) → destroy luôn.
+     */
+    private deactivatePage(
+        pageView: ViewInterface,
+        layoutView: ViewInterface | null,
+        layoutChain: ViewInterface[] = this.currentLayoutChain,
+    ): void {
+        const ctrl = pageView.__ctrl__;
+        const urlPath = ctrl.urlPath;
+        const cacheConfig = ctrl.getConfig('cache');
+        const ttl = typeof cacheConfig === 'object' && cacheConfig?.ttl != null ? cacheConfig.ttl : undefined;
+
+        if (!urlPath || cacheConfig === false || ttl === 0) {
+            ctrl.destroy();
+            return;
+        }
+
+        const scroll = {
+            x: typeof window !== 'undefined' ? window.scrollX ?? 0 : 0,
+            y: typeof window !== 'undefined' ? window.scrollY ?? 0 : 0,
+        };
 
-    private startViewChain(pageView: ViewInterface, finalView: ViewInterface, hasSuperView: boolean): void {
-        if (hasSuperView) {
-            // 1. Start layout element tree
-            this.startLayoutView(finalView);
-            // 2. Start page's block content
-            this.startBlockContent();
-            // 3. Fire page onMounted
-            if (typeof pageView.onMounted === 'function') {
-                try { pageView.onMounted(); }
-                catch (e) { logger.error(`[ViewManager] page onMounted error:`, e); }
+        if (!layoutView) {
+            const wrapper = ctrl.mainElement;
+            if (!wrapper) {
+                ctrl.destroy();
+                return;
             }
+            // pause TRƯỚC detach: flush pending → DOM snapshot nhất quán rồi mới rời
+            ctrl.pause();
+            const fragment = detachWrapperDOM(wrapper);
+            this.pageCache.set(this.cacheKey(ctrl.path, urlPath), {
+                views: [pageView], fragment, layoutPath: null, scroll, ttl,
+            });
         } else {
-            // Standalone view — start wrapper tree directly
-            const wrapper = pageView.__ctrl__.mainElement;
-            if (wrapper && typeof wrapper.start === 'function') {
-                wrapper.start();
-            }
-            if (typeof pageView.onMounted === 'function') {
-                try { pageView.onMounted(); }
-                catch (e) { logger.error(`[ViewManager] onMounted error:`, e); }
-            }
+            ctrl.pause();
+            const outletContents = this.blockManager.detachPageContent(ctrl.viewId);
+            this.pageCache.set(this.cacheKey(ctrl.path, urlPath), {
+                views: [pageView],
+                outletContents,
+                layoutPath: this.layoutChainIdentity(layoutChain.length > 0 ? layoutChain : [layoutView]),
+                scroll,
+                ttl,
+            });
         }
     }
 
-    private startLayoutView(layoutView: ViewInterface): void {
-        const wrapper = layoutView.__ctrl__.mainElement;
-        if (wrapper && typeof wrapper.start === 'function') {
-            wrapper.start();
-        }
-        if (typeof layoutView.onMounted === 'function') {
-            try { layoutView.onMounted(); }
-            catch (e) { logger.error(`[ViewManager] layout onMounted error:`, e); }
-        }
+    /** Roll back an early Layout-page detach when prepare/render did not commit. */
+    private restoreDeactivatedPage(
+        pageView: ViewInterface,
+        layoutView: ViewInterface | null,
+    ): boolean {
+        const ctrl = pageView.__ctrl__;
+        if (!ctrl.urlPath) return false;
+        const entry = this.pageCache.take(this.cacheKey(ctrl.path, ctrl.urlPath));
+        if (!entry) return false;
+        return this.restoreFromCache(entry, layoutView, 'pop') !== null;
     }
 
-    private startBlockContent(): void {
-        for (const [name, children] of (this.blockManager as any).mountedChildren) {
-            if (Array.isArray(children)) {
-                for (const child of children) {
-                    if (child && typeof child.start === 'function') {
-                        child.start();
+    /**
+     * Cache hit: gắn lại DOM + resume — không render, không gọi API.
+     *   - Entry standalone: layout cũ (nếu còn) pause+cache → gắn fragment vào container.
+     *   - Entry layout-page: layout đang mount trùng layoutPath → restore thẳng
+     *     vào outlets. Không trùng → thử resurrect layout từ layout cache
+     *     (bfcache đầy đủ: restore CẢ layout LẪN page trong một lần). Layout
+     *     cũng không có trong cache → putBack entry (còn TTL thì lần điều hướng
+     *     sau restore được), trả null để caller mount tươi.
+     * Scroll: pop → khôi phục vị trí cũ; push → về đầu trang.
+     */
+    private restoreFromCache(
+        entry: PageCacheEntry,
+        oldLayoutView: ViewInterface | null,
+        navigationType: RouterNavigationType
+    ): any {
+        const pageView = entry.views[entry.views.length - 1];
+
+        if (entry.layoutPath) {
+            // ── Page thuộc layout ────────────────────────────────────────
+            // 1. Layout đang mount trùng path? → dùng luôn
+            let layoutChain = this.layoutChainIdentity(this.currentLayoutChain) === entry.layoutPath
+                ? [...this.currentLayoutChain]
+                : [];
+            let layoutView: ViewInterface | null = layoutChain[0] ?? null;
+
+            // 2. Không trùng → thử resurrect layout từ layout cache
+            if (!layoutView && entry.outletContents) {
+                const layoutEntry = this.pageCache.take(this.layoutCacheKey(entry.layoutPath));
+                if (layoutEntry) {
+                    if (this.currentLayoutChain.length > 0) {
+                        this.deactivateLayoutChain(this.currentLayoutChain);
                     }
+                    layoutChain = [...layoutEntry.views];
+                    const lv = layoutChain[0];
+                    this.rootElement!.getElement().appendChild(layoutEntry.fragment);
+                    for (const layout of layoutChain) layout.__ctrl__.resume();
+                    for (const layout of layoutChain) this.reregisterLayoutOutlets(layout.__ctrl__);
+                    layoutView = lv;
                 }
             }
-        }
-    }
 
-    // ─── Lifecycle: Commit Data ─────────────────────────────────
+            // 3. Không có layout để restore vào → trả entry lại cache, mount tươi
+            if (!layoutView || !entry.outletContents) {
+                this.pageCache.putBack(entry);
+                return null;
+            }
 
-    private commitViewChain(pageView: ViewInterface, finalView: ViewInterface, hasSuperView: boolean): void {
-        if (hasSuperView) {
-            finalView.__ctrl__.commitData();
-            pageView.__ctrl__.commitData();
+            this.blockManager.restorePageContent(pageView.__ctrl__.viewId, entry.outletContents);
+            for (const v of entry.views) {
+                v.__ctrl__.resume();
+            }
+            for (const v of entry.views) {
+                this.sectionManager.mountViewSections(v.__ctrl__.viewId);
+            }
+            this.currentPageView = pageView;
+            this.currentLayoutView = layoutView;
+            this.currentLayoutChain = layoutChain;
+            this.currentLayoutPath = layoutView.__ctrl__.path;
+            this.currentViewType = 'layout';
+            this.viewStack = [...layoutChain, pageView];
         } else {
-            pageView.__ctrl__.commitData();
+            // ── Standalone ───────────────────────────────────────────────
+            if (this.currentLayoutChain.length > 0) {
+                this.deactivateLayoutChain(this.currentLayoutChain);
+                this.currentLayoutView = null;
+                this.currentLayoutChain = [];
+                this.currentLayoutPath = null;
+            }
+            const container = this.rootElement!.getElement();
+            container.appendChild(entry.fragment);
+            for (const v of entry.views) {
+                v.__ctrl__.resume();
+            }
+            for (const v of entry.views) {
+                this.sectionManager.mountViewSections(v.__ctrl__.viewId);
+            }
+            this.currentPageView = pageView;
+            this.currentLayoutView = null;
+            this.currentLayoutChain = [];
+            this.currentLayoutPath = null;
+            this.currentViewType = 'view';
+            this.viewStack = [...entry.views];
         }
-    }
+        this.renderCount++;
 
-    // ─── Unmount ────────────────────────────────────────────────
+        try {
+            if (typeof window !== 'undefined' && typeof window.scrollTo === 'function') {
+                if (navigationType === 'pop') {
+                    window.scrollTo(entry.scroll.x, entry.scroll.y);
+                } else {
+                    window.scrollTo(0, 0);
+                }
+            }
+        } catch { /* jsdom không hỗ trợ — bỏ qua */ }
 
-    private unmountLayoutDOM(layoutView: ViewInterface | null): void {
-        if (!layoutView) return;
-        const wrapper = layoutView.__ctrl__.mainElement;
-        if (wrapper && typeof wrapper.destroy === 'function') {
-            wrapper.destroy();
-        }
+        return {
+            type: 'restored',
+            view: pageView,
+            finalView: this.currentLayoutView ?? pageView,
+            superView: this.currentLayoutView,
+        };
     }
 
+    // ─── Unmount ────────────────────────────────────────────────
+
     unmountAll(): void {
-        this.stopPageView(this.currentPageView);
-        this.stopLayoutView(this.currentLayoutView);
-        this.blockManager.clearAllOutlets();
-        this.blockManager.destroy();
+        // Stop block content (unsubscribe) trước, rồi destroy chain trong → ngoài.
+        // ctrl.destroy() tự fire đủ hook: stopping/stopped → unmounting/unmounted → destroyed.
+        this.blockManager.stopAll();
+        this.sectionManager.stopAll();
 
         if (this.currentPageView) {
             this.currentPageView.__ctrl__.destroy();
         }
-        if (this.currentLayoutView) {
-            this.currentLayoutView.__ctrl__.destroy();
+        for (let i = this.currentLayoutChain.length - 1; i >= 0; i--) {
+            this.currentLayoutChain[i].__ctrl__.destroy();
         }
 
+        this.blockManager.clearAllOutlets();
+        this.blockManager.destroy();
+        this.sectionManager.destroy();
+
         this.currentPageView = null;
         this.currentLayoutView = null;
+        this.currentLayoutChain = [];
         this.currentLayoutPath = null;
         this.currentViewType = null;
-        this.activeViews.clear();
         this.viewStack = [];
     }
 
-    unmountView(path: string): void {
-        const info = this.activeViews.get(path);
-        if (!info) return;
-        this.activeViews.delete(path);
+    /**
+     * Apply an atomic context update received from a JSON response before the
+     * Router retries navigation with the newly materialized route table.
+     */
+    requiresReloadForViewContext(state: Record<string, any>): boolean {
+        const revision = typeof state?.revision === 'string' ? state.revision : null;
+        if (!revision || revision === this.contextRevision) return false;
+
+        const nextViews = typeof state?.views === 'string' && state.views !== ''
+            ? state.views
+            : this.contextViews;
+
+        // The current registry was built for one namespace. Changing only its
+        // string prefix cannot materialize the new theme factories/CSS and can
+        // mix new Blade names with old JavaScript. Until a staged registry swap
+        // exists, a document load is the only coherent transition.
+        return nextViews !== this.contextViews;
+    }
+
+    applyViewContext(state: Record<string, any>): boolean {
+        if (this.requiresReloadForViewContext(state)) {
+            // Router owns the document transition. A direct caller must not
+            // mutate revision/systemData while the matching registry is absent.
+            return false;
+        }
+
+        const revision = typeof state?.revision === 'string' ? state.revision : null;
+        if (!revision || revision === this.contextRevision) return false;
+
+        this.cancelNavigation();
+        this.contextRevision = revision;
+        this.contextViews = typeof state.views === 'string' ? state.views : this.contextViews;
+        if (state.systemData && typeof state.systemData === 'object') {
+            this.systemData = { ...this.systemData, ...state.systemData };
+        }
+
+        // Cached pages/layout factories belong to the previous namespace.
+        this.pageCache.clear();
+        this.store.clear();
+        this.ssrBoot = null;
+
+        if (typeof window !== 'undefined') {
+            const appConfigs = (window as any).APP_CONFIGS ??= {};
+            appConfigs.view ??= {};
+            appConfigs.view.revision = revision;
+            appConfigs.view.contextViews = this.contextViews;
+            appConfigs.view.systemData = { ...this.systemData };
+        }
+
+        return true;
+    }
+
+    getContextRevision(): string | null {
+        return this.contextRevision;
+    }
+
+    private extractAsyncData(response: any): Record<string, any> {
+        const payload = response?.data ?? {};
+        if (payload && typeof payload === 'object'
+            && Object.prototype.hasOwnProperty.call(payload, 'data')
+            && (Object.prototype.hasOwnProperty.call(payload, 'viewContext')
+                || Object.prototype.hasOwnProperty.call(payload, 'view'))) {
+            return payload.data ?? {};
+        }
+        return payload;
+    }
+
+    /**
+     * hydrateView — Hydrate một view đã được server-side render.
+     *
+     * SSR flow:
+     *   1. Laravel render Blade template → HTML gửi về client
+     *   2. Blade dùng $__VIEW_ID__ để prefix class của mỗi element (e.g. "v12345-af0882bc")
+     *   3. Laravel truyền $__VIEW_ID__ về client qua page data (__SSR_VIEW_ID__)
+     *   4. Client gọi hydrateView() — view được tạo với cùng viewId
+     *   5. Html elements tìm server-rendered DOM nodes bằng class {viewId}-{elementId}
+     *   6. Reactive regions claim server markers via markerRegistry.claim()
+     *   7. Event handlers và state subscriptions được gắn vào DOM đã có
+     *
+     * Lưu ý: Không gây layout shift vì cấu trúc DOM được reuse (Html claim),
+     * chỉ text nodes và markers được re-tạo (nội dung giống nhau nên không thấy được).
+     *
+     * @param name - View registry key (e.g. 'web.home')
+     * @param data - View data, PHẢI chứa __SSR_VIEW_ID__ từ server
+     * @param route - Active route (optional)
+     *
+     * Tham chiếu: COMPILER_CONTRACT.md §hydration, Html.ts §constructor
+     */
+    /**
+     * hydrateView — Hydrate một view đã được server-side render (SSR).
+     *
+     * Flow:
+     *   1. Server (Laravel) render Blade → HTML gửi về client
+     *   2. Blade dùng $__VIEW_ID__ prefix class mỗi element ("v12345-af0882bc")
+     *   3. Client gọi hydrateView() với __SSR_VIEW_ID__ = cùng viewId
+     *   4. Html elements claim server DOM nodes bằng class {viewId}-{elementId}
+     *   5. Output claim comment markers + text nodes giữa markers
+     *   6. Event handlers và state subscriptions gắn vào DOM có sẵn
+     *
+     * Khác mountView:
+     *   - Không xoá DOM cũ, không tạo HTML element mới (claim cái đã có)
+     *   - Markers (Reactive, Output) vẫn được tạo mới nếu server không emit
+     *   - Sau hydrate, SPA navigation dùng mountView bình thường (CSR)
+     */
+    async hydrateView(
+        name: string,
+        data: Record<string, any> & { __SSR_VIEW_ID__: string },
+        route?: ActiveRouteInterface,
+    ): Promise<any> {
+        // Không có viewId từ server → không hydrate được, fallback CSR
+        if (!data.__SSR_VIEW_ID__) {
+            console.warn('[ViewManager] hydrateView: __SSR_VIEW_ID__ không có. Fallback → mountView.');
+            return this.mountView(name, data, route);
+        }
+
+        const navigationGeneration = ++this.navigationGeneration;
+
+        // HTML server của lượt này là nguồn duy nhất để claim marker — bỏ index
+        // của lượt hydrate trước (bfcache / test / re-hydrate) trước khi quét.
+        markerRegistry.invalidateIndex();
+
+        const targetUrl = (route as any)?.$uri ?? route?.$urlPath ?? name;
+
+        // Router only supplies route params and the SSR id. Seed the page from
+        // the matching server instance before constructing data-derived states.
+        const { __SSR_VIEW_ID__: ssrViewId, ...routeData } = data;
+        const key = this.resolveRegistryKey(name);
+        const serverData = this.ssrViewData[key]?.instances?.[ssrViewId]?.data ?? {};
+        const viewData = { ...serverData, ...routeData };
+        // Compiled factories capture this id in their render closures; assigning
+        // ctrl.viewId afterwards alone cannot update those closures.
+        const constructorData = { ...viewData, __SSR_VIEW_ID__: ssrViewId };
+        const view = await this.view(name, constructorData, false);
+        // Keep the internal id out of application data after factory setup.
+        delete (constructorData as Record<string, any>).__SSR_VIEW_ID__;
+        if (!view) {
+            this.showError(`hydrateView: View "${name}" không tìm thấy.`);
+            return null;
+        }
+        view.__ctrl__.urlPath = targetUrl;
+
+        // Ghi đè viewId bằng SSR viewId — đảm bảo Html elements claim đúng
+        // server DOM nodes có class prefix = viewId (e.g. "vssr-abc12-page-root").
+        // (Belt-and-suspenders: đúng cả khi factory không đọc __SSR_VIEW_ID__.)
+        view.__ctrl__.viewId = ssrViewId;
+
+        // Render ở HYDRATE mode — elements claim DOM thay vì tạo mới
+        const renderResult = await this.renderPageView(
+            view, viewData, this.rootElement, InitModes.HYDRATE, false, 0, navigationGeneration
+        );
+        if (renderResult.type === 'cancelled') {
+            view.__ctrl__.destroy();
+            return null;
+        }
+        if (renderResult.type === 'error') {
+            view.__ctrl__.destroy();
+            this.showError(renderResult.message);
+            return null;
+        }
+
+        // Lưới cuối như mountView — hydrate claim lỗi không được làm chết cả app.
+        try {
+            this.activateRenderedChain(renderResult, InitModes.HYDRATE);
+        } catch (err) {
+            logger.error(`Error hydrating view "${name}":`, err);
+            this.showError(`Error hydrating view "${name}".`, err instanceof Error ? err.message : err);
+            return null;
+        } finally {
+            // Hết lượt hydrate thì KHÔNG ai đọc index nữa (claim chỉ có ở đường
+            // HYDRATE, mà mỗi lần nạp trang chỉ hydrate một lượt) — giữ lại chỉ
+            // để Map trỏ vào comment của trang đầu suốt phiên: đo trên /docs
+            // thấy 94/106 entry thành node rời DOM ngay sau lần SPA nav đầu.
+            // Claim đến muộn (@await hydrate sau) vẫn đúng: miss sẽ tự dựng lại.
+            markerRegistry.invalidateIndex();
+        }
+
+        return renderResult;
     }
 
     // ─── Getters ────────────────────────────────────────────────
@@ -688,6 +1729,32 @@ export class ViewManager implements ViewManagerInterface {
         return this.currentPageView;
     }
 
+    /** Layout chain đang mount, ngoài → trong (devtools/debug). */
+    getLayoutChain(): ViewInterface[] {
+        return [...this.currentLayoutChain];
+    }
+
+    // ─── SSR boot ───────────────────────────────────────────────
+
+    /** Còn SSR boot chưa consume? (route đầu tiên nên hydrate thay vì mount) */
+    hasSSRBoot(): boolean {
+        return this.ssrBoot !== null;
+    }
+
+    /**
+     * Lấy viewId SSR cho một view name nếu nó là entry server đã render, rồi
+     * CONSUME (xoá) — đảm bảo chỉ route ĐẦU TIÊN hydrate; navigate sau là CSR.
+     * Trả null nếu không có SSR boot hoặc view không khớp entry.
+     */
+    consumeSSRViewId(viewName: string): string | null {
+        if (this.ssrBoot && this.ssrBoot.view === viewName) {
+            const id = this.ssrBoot.viewId;
+            this.ssrBoot = null;
+            return id;
+        }
+        return null;
+    }
+
     getViewStack(): ViewInterface[] {
         return this.viewStack;
     }
@@ -698,3 +1765,10 @@ export class ViewManager implements ViewManagerInterface {
 
 
 }
+
+/** Remap only implicit page-data requests; explicit @await URLs keep their meaning. */
+export function resolveViewDataUrl(routeUrl: string, dataEndpoint?: string | null): string {
+    if (!dataEndpoint) return routeUrl;
+    const route = new URL(routeUrl, typeof window !== 'undefined' ? window.location.href : 'http://localhost');
+    return dataEndpoint.replace(/\/+$/, '') + route.pathname + route.search;
+}