@saolabs/client 1.0.0 → 1.1.0

package/src/core/routers/Router.ts

@@ -1,5 +1,5 @@
 /**
- * Router — SPA Router cho OneView v3.
+ * Router — SPA Router cho SaoView v3.
  *
  * Port từ core/Router nhưng nhẹ hơn (~400 dòng thay vì 960),
  * tích hợp trực tiếp với ViewManager mới.
@@ -14,7 +14,7 @@
  *   - Browser back/forward handling
  */
 
-import type { ViewManagerInterface } from "../contracts/ViewManagerInterface";
+import type { ViewManagerInterface } from "../contracts/ViewManagerInterface.js";
 
 // ─── Types ──────────────────────────────────────────────────────
 
@@ -23,12 +23,24 @@ export interface RouteDefinition {
     path: string;
     /** View name: 'web.home', 'layouts.main' */
     component?: string;
+    /** Worker-stable alias retained by the server route registry. */
+    logicalComponent?: string;
     /** @deprecated Use component */
     view?: string;
     /** Named route identifier */
     name?: string;
     /** Route metadata (auth, roles, etc.) */
     meta?: Record<string, any>;
+    /**
+     * Route con — path nối vào path cha, `meta` kế thừa từ cha (con ghi đè khi
+     * trùng key). Chỉ là tầng CẤU HÌNH: bảng route vẫn phẳng sau khi flatten.
+     *
+     * Việc giữ nguyên view cha khi chuyển giữa các con là do chuỗi layout lo
+     * (`@extends` + `@useBlock`) — view con khai báo cha bằng `@extends`, và
+     * `ViewManager` tái dùng đúng instance layout đang active thay vì render
+     * lại. Xem docs/GAPS_AND_ROADMAP.md §2.17.
+     */
+    children?: RouteDefinition[];
 }
 
 export interface Route {
@@ -59,12 +71,16 @@ export interface RouterConfig {
 
 export type NavigationGuard = (to: Route, from: ActiveRoute | null, urlPath: string) => boolean | Promise<boolean>;
 export type AfterNavigationHook = (to: Route, from: ActiveRoute | null) => void;
+type NavigationType = 'push' | 'replace' | 'pop' | 'initial';
+type NavigationRequest = { id: number; path: string; type: NavigationType };
 
 // ─── ActiveRoute ────────────────────────────────────────────────
 
 export class ActiveRoute {
     public readonly $route: Route;
     public readonly $urlPath: string;
+    /** Request URI = path + query string (KHÔNG gồm hash) — dùng làm cache key */
+    public readonly $uri: string;
     public readonly $params: Record<string, string>;
     public readonly $query: Record<string, string>;
     public readonly $fragment: string;
@@ -74,10 +90,12 @@ export class ActiveRoute {
         urlPath: string,
         params: Record<string, string> = {},
         query: Record<string, string> = {},
-        fragment: string = ''
+        fragment: string = '',
+        uri?: string
     ) {
         this.$route = route;
         this.$urlPath = urlPath;
+        this.$uri = uri ?? urlPath;
         this.$params = params;
         this.$query = query;
         this.$fragment = fragment;
@@ -158,7 +176,15 @@ export class Router {
 
     /** Navigation guards */
     private _beforeEach: NavigationGuard | null = null;
-    private _afterEach: AfterNavigationHook | null = null;
+    /**
+     * NHIỀU hook, không phải một.
+     *
+     * Trước đây đây là một slot duy nhất, và mỗi layout muốn biết "đã điều hướng
+     * xong" đều phải giành lấy nó: layout mới đăng ký đè hook của layout cũ, rồi
+     * layout cũ destroy lại xoá hook của layout mới → không còn hook nào. Đúng
+     * chuỗi docs → demo → docs. Hook giờ là tập hợp, `afterEach()` trả về hàm huỷ.
+     */
+    private afterHooks = new Set<AfterNavigationHook>();
 
     /** Caches */
     private routeCache: Map<string, RouteMatch | null> = new Map();
@@ -166,10 +192,13 @@ export class Router {
     /** State */
     private isStarted = false;
     private isNavigating = false;
+    private navigationSequence = 0;
+    private activeNavigationUrl: string | null = null;
 
     /** Bound handlers for cleanup */
     private _handlePopState: () => void;
     private _handleAutoNavigation: (e: MouseEvent) => void;
+    private _handleViewContextChange: (e: Event) => void;
 
     constructor(app?: any) {
         this.App = app || null;
@@ -179,12 +208,30 @@ export class Router {
 
         this._handlePopState = this.handlePopState.bind(this);
         this._handleAutoNavigation = this.handleAutoNavigation.bind(this);
+        this._handleViewContextChange = this.handleViewContextChange.bind(this);
     }
 
     // ─── Configuration ──────────────────────────────────────────
 
+    /**
+     * init — nạp config và wire các dependency.
+     * Gọi bởi RouteServiceProvider.boot() sau khi tất cả providers đã boot.
+     *
+     * Thực hiện:
+     *   1. configure() — load routes, mode, guards từ config
+     *   2. Wire ViewManager — lấy từ App.View nếu chưa set thủ công
+     */
     init(config: RouterConfig): this {
-
+        if (config && Object.keys(config).length > 0) {
+            this.configure(config);
+        }
+        // Auto-wire ViewManager nếu App đã có View registered
+        if (this.App && !this.viewManager) {
+            try {
+                const vm = (this.App as any).View ?? this.App.get?.('View') ?? null;
+                if (vm) this.viewManager = vm;
+            } catch (_) { /* View chưa sẵn sàng — sẽ fallback lúc handleRoute */ }
+        }
         return this;
     }
 
@@ -235,10 +282,71 @@ export class Router {
     }
 
     /**
-     * Add multiple routes at once.
+     * Nối path con vào path cha. Con bắt đầu bằng '/' là ĐƯỜNG TUYỆT ĐỐI —
+     * bỏ qua prefix cha (lối thoát cho route lệch khỏi cây, như Vue Router).
+     * Con rỗng ('') = index route, trùng đúng path cha.
+     */
+    private static joinRoutePath(parent: string, child: string): string {
+        if (child.startsWith('/')) return child;
+        const base = parent.replace(/\/+$/, '');
+        if (!child) return base || '/';
+        return `${base}/${child}`.replace(/\/{2,}/g, '/');
+    }
+
+    /**
+     * Trải cây route thành bảng phẳng — bảng phẳng là thứ `matchRoute()` duyệt,
+     * và nó khớp THEO THỨ TỰ (first match wins), nên thứ tự emit ở đây chính là
+     * độ ưu tiên: giữ nguyên thứ tự khai báo để `/users/profile` đứng trước
+     * `/users/{id}` đúng như người viết mong đợi.
+     *
+     * Cha có `children` mà KHÔNG có `component` = nhóm thuần tuý (gom prefix +
+     * meta dùng chung), không sinh route nào cho chính nó.
+     *
+     * Index child (`path: ''`) sinh ra đúng path của cha → khi đó bỏ route
+     * riêng của cha, vì khai báo con là chỉ định cụ thể hơn cho URL đó.
+     */
+    private flattenRouteTree(
+        routes: RouteDefinition[],
+        parentPath = '',
+        parentMeta: Record<string, any> = {},
+    ): RouteDefinition[] {
+        const flat: RouteDefinition[] = [];
+
+        for (const route of routes) {
+            const { children, ...own } = route;
+            const path = Router.joinRoutePath(parentPath, route.path ?? '');
+            const meta = { ...parentMeta, ...(route.meta ?? {}) };
+
+            const flatChildren = children && children.length
+                ? this.flattenRouteTree(children, path, meta)
+                : [];
+
+            const component = route.component || route.view || '';
+            const coveredByIndexChild = flatChildren.some(c => c.path === path);
+            if (component && !coveredByIndexChild) {
+                flat.push({ ...own, path, meta });
+            }
+            flat.push(...flatChildren);
+        }
+
+        return flat;
+    }
+
+    /**
+     * Add multiple routes at once. Chấp nhận cây lồng qua `children` — mọi
+     * đường vào (`configure`, `replaceRoutes`) đều đi qua đây nên chỉ cần
+     * flatten một chỗ.
      */
     addRoutes(routes: RouteDefinition[]): this {
+        // Route KHÔNG có component (API, redirect, fallback) vẫn cần TÊN để
+        // sinh URL — chỉ không vào bảng khớp path. flattenRouteTree lọc chúng
+        // ra khỏi nhánh khớp, nên đăng ký tên riêng ở đây.
         for (const route of routes) {
+            if (route.name && !(route.component || route.view)) {
+                this.addRouteConfig(route);
+            }
+        }
+        for (const route of this.flattenRouteTree(routes)) {
             const component = route.component || route.view || '';
             this.addRoute(route.path, component, route.meta || {});
             if (route.name) {
@@ -248,6 +356,14 @@ export class Router {
         return this;
     }
 
+    /** Atomically replace the materialized route table for a new context revision. */
+    replaceRoutes(routes: RouteDefinition[]): this {
+        this.routes = [];
+        this.routeConfigs = {};
+        this.routeCache.clear();
+        return this.addRoutes(routes);
+    }
+
     /**
      * Configure router from a config object.
      */
@@ -255,10 +371,14 @@ export class Router {
         if (config.mode) this.mode = config.mode;
         if (config.base) this.base = config.base;
         if (config.defaultRoute) this.defaultRoute = config.defaultRoute;
-        if (config.routes) this.addRoutes(config.routes);
-        if (config.allRoutes) this.addRoutes(config.allRoutes);
+        // MỘT danh sách thôi. Server từng phát cả `routes` (chỉ route có
+        // component) lẫn `allRoutes` (đủ) — tập con của nhau, nên đăng ký cả
+        // hai là mỗi route vào bảng hai lần. `allRoutes` giữ lại làm bí danh
+        // cho payload cũ.
+        const routes = config.routes ?? config.allRoutes;
+        if (routes) this.addRoutes(routes);
         if (config.beforeEach) this._beforeEach = config.beforeEach;
-        if (config.afterEach) this._afterEach = config.afterEach;
+        if (config.afterEach) this.afterEach(config.afterEach);
         return this;
     }
 
@@ -269,24 +389,21 @@ export class Router {
         return this;
     }
 
-    afterEach(hook: AfterNavigationHook): this {
-        this._afterEach = hook;
-        return this;
+    /** Đăng ký hook chạy sau mỗi lần điều hướng. Trả về hàm HUỶ đăng ký. */
+    afterEach(hook: AfterNavigationHook): () => void {
+        this.afterHooks.add(hook);
+        return () => { this.afterHooks.delete(hook); };
     }
 
     // ─── Navigation ─────────────────────────────────────────────
 
     /**
      * Navigate to a URL path.
+     * History chỉ được cập nhật SAU khi guard cho phép (trong handleRoute) —
+     * guard chặn thì URL không đổi, tránh desync URL ↔ view.
      */
     navigate(path: string): void {
-        if (this.mode === 'history') {
-            window.history.pushState({}, '', path);
-        } else {
-            window.location.hash = path;
-        }
-        this.handleRoute(path);
-        this.currentUri = path;
+        this.requestNavigation(path, 'push');
     }
 
     /** Alias for navigate */
@@ -310,13 +427,7 @@ export class Router {
      * Replace current history entry without adding to stack.
      */
     replace(path: string): void {
-        if (this.mode === 'history') {
-            window.history.replaceState({}, '', path);
-        } else {
-            window.location.hash = path;
-        }
-        this.handleRoute(path);
-        this.currentUri = path;
+        this.requestNavigation(path, 'replace');
     }
 
     /**
@@ -446,10 +557,11 @@ export class Router {
             window.addEventListener('hashchange', this._handlePopState);
         }
         document.addEventListener('click', this._handleAutoNavigation);
+        window.addEventListener('saola:view-context', this._handleViewContextChange);
 
         // Handle initial route
         if (!skipInitial) {
-            this.handleRoute(initialPath);
+            this.requestNavigation(initialPath, 'initial');
         }
 
         this.isStarted = true;
@@ -462,41 +574,168 @@ export class Router {
         window.removeEventListener('popstate', this._handlePopState);
         window.removeEventListener('hashchange', this._handlePopState);
         document.removeEventListener('click', this._handleAutoNavigation);
+        window.removeEventListener('saola:view-context', this._handleViewContextChange);
         this.isStarted = false;
     }
 
+    private handleViewContextChange(event: Event): void {
+        const state = (event as CustomEvent<Record<string, any>>).detail;
+        if (!state || state.changed !== true) return;
+
+        const vm = this.viewManager ?? this.App?.View;
+        const target = this.activeNavigationUrl || this.currentUri
+            || (typeof window !== 'undefined'
+                ? window.location.pathname + window.location.search + window.location.hash
+                : '/');
+
+        if (vm?.requiresReloadForViewContext?.(state)) {
+            vm.cancelNavigation?.();
+            this.reloadForViewContext(target, state);
+            return;
+        }
+
+        const applied = vm?.applyViewContext?.(state) ?? false;
+        if (!applied) return;
+
+        if (Array.isArray(state.routes)) {
+            this.replaceRoutes(state.routes);
+        }
+
+        // If a fetch discovered the change mid-navigation, requestNavigation
+        // queues the same target and invalidates the old render generation.
+        if (target) this.requestNavigation(target, 'replace');
+    }
+
+    /**
+     * Switch to a coherent server-rendered document when the view namespace
+     * changes. A short-lived token prevents a bad deployment from reloading the
+     * same URL/revision forever.
+     */
+    private reloadForViewContext(target: string, state: Record<string, any>): void {
+        if (typeof window === 'undefined') return;
+
+        const url = new URL(target || '/', window.location.href);
+        const revision = typeof state.revision === 'string' ? state.revision : 'unknown';
+        const token = `${revision}:${url.pathname}${url.search}`;
+        const storageKey = 'saola:view-context-reload';
+        const now = Date.now();
+
+        try {
+            const previousRaw = window.sessionStorage.getItem(storageKey);
+            const previous = previousRaw ? JSON.parse(previousRaw) : null;
+            if (previous?.token === token && typeof previous.at === 'number' && now - previous.at < 15_000) {
+                const message = 'Không thể đồng bộ view context sau khi tải lại. Vui lòng kiểm tra revision và asset đã triển khai.';
+                console.error(`[Router] ${message}`, { revision, target: url.href });
+                (this.viewManager ?? this.App?.View)?.showError?.(message, {
+                    revision,
+                    target: url.href,
+                });
+                return;
+            }
+            window.sessionStorage.setItem(storageKey, JSON.stringify({ token, at: now }));
+        } catch {
+            // Storage có thể bị chặn; coherence vẫn quan trọng hơn loop guard.
+        }
+
+        window.dispatchEvent(new CustomEvent('saola:view-context-reload', {
+            detail: { ...state, target: url.href },
+        }));
+        window.location.replace(url.href);
+    }
+
     /**
      * Full destroy — cleanup everything.
      */
     destroy(): void {
         this.stop();
+        this.navigationSequence++;
+        this.pendingNavigation = null;
+        this.activeNavigationUrl = null;
+        this.viewManager?.cancelNavigation?.();
         this.routes = [];
         this.routeConfigs = {};
         this.routeCache.clear();
         this._beforeEach = null;
-        this._afterEach = null;
+        this.afterHooks.clear();
         this.currentRoute = null;
+        this.liveRegion?.remove();
+        this.liveRegion = null;
         Router.activeRoute = null;
     }
 
     // ─── Helper ────────────────────────────────
     getFullUrl(): string {
         if (typeof window === 'undefined') return '';
+        if (this.activeNavigationUrl) {
+            return new URL(this.activeNavigationUrl, window.location.href).href;
+        }
         return window.location.href;
     }
     // ─── Internal: Route Handling ────────────────────────────────
 
+    /** Kiểu navigation nội bộ — quyết định thao tác history + nav type xuống ViewManager */
+    private pendingNavigation: NavigationRequest | null = null;
+
+    /**
+     * Tách một URL string thành pathname / query string / fragment.
+     * PHẢI tách query + hash TRƯỚC khi match route — pattern chỉ match pathname.
+     */
+    private splitLocation(raw: string): { pathname: string; queryString: string; fragment: string } {
+        let rest = raw ?? '';
+        let fragment = '';
+        const hashIdx = rest.indexOf('#');
+        if (hashIdx !== -1) {
+            fragment = rest.slice(hashIdx + 1);
+            rest = rest.slice(0, hashIdx);
+        }
+        let queryString = '';
+        const queryIdx = rest.indexOf('?');
+        if (queryIdx !== -1) {
+            queryString = rest.slice(queryIdx + 1);
+            rest = rest.slice(0, queryIdx);
+        }
+        return { pathname: rest, queryString, fragment };
+    }
+
     /**
-     * Core route handler — match route, run guards, mount view.
+     * Điểm vào duy nhất cho mọi navigation (navigate/replace/popstate/initial).
+     * Đang navigate dở → ghi nhận request MỚI NHẤT, xử lý sau khi xong
+     * (không drop im lặng như trước).
      */
-    private async handleRoute(path: string): Promise<void> {
-        if (this.isNavigating) return;
+    private requestNavigation(path: string, type: NavigationType): void {
+        const request: NavigationRequest = { id: ++this.navigationSequence, path, type };
+        if (this.isNavigating) {
+            this.pendingNavigation = request;
+            // Cho ViewManager thoát sớm khỏi fetch/render cũ. Request mới nhất
+            // sẽ được chạy trong finally, không commit DOM/history trung gian.
+            (this.viewManager ?? this.App?.View)?.cancelNavigation?.();
+            return;
+        }
+        void this.handleRoute(path, type, request.id);
+    }
+
+    /**
+     * Core route handler — prepare/guard/render trước, chỉ commit history +
+     * active route sau khi ViewManager đã mount/hydrate thành công.
+     */
+    private async handleRoute(
+        path: string,
+        type: NavigationType = 'push',
+        requestId: number = ++this.navigationSequence,
+    ): Promise<void> {
         this.isNavigating = true;
+        // Khai ngoài try: `finally` phải nhả được kể cả khi render ném giữa chừng.
+        let releaseHeight: () => void = () => {};
 
         try {
-            const normalizedPath = this.normalizePath(path);
-            const query = this.parseQuery(window.location.search);
-            const fragment = window.location.hash.substring(1);
+            const { pathname, queryString, fragment } = this.splitLocation(path);
+            const normalizedPath = this.normalizePath(pathname);
+            // Request URI = path + query, KHÔNG gồm hash — cache key của ViewManager
+            const uri = queryString ? `${normalizedPath}?${queryString}` : normalizedPath;
+            const query = this.parseQuery(queryString);
+
+            // popstate/hashchange echo về đúng URI đang đứng → bỏ qua
+            if (type === 'pop' && uri === this.currentUri) return;
 
             const match = this.matchRoute(normalizedPath);
             if (!match) {
@@ -508,64 +747,208 @@ export class Router {
             const from = this.currentRoute;
 
             // Create ActiveRoute
-            const activeRoute = new ActiveRoute(route, normalizedPath, params, query, fragment);
+            const activeRoute = new ActiveRoute(route, normalizedPath, params, query, fragment, uri);
 
-            // Before guard
+            // Before guard — chạy TRƯỚC khi đụng vào history: guard chặn thì URL giữ nguyên
             if (this._beforeEach) {
                 const allow = await this._beforeEach(route, from, normalizedPath);
                 if (allow === false) return;
             }
+            if (requestId !== this.navigationSequence) return;
 
-            // Update global state
-            Router.activeRoute = activeRoute;
-            this.currentRoute = activeRoute;
+            const historyTarget = fragment ? `${uri}#${fragment}` : uri;
+            this.activeNavigationUrl = historyTarget;
 
-            // Mount view via ViewManager
+            // Mount view via ViewManager.
+            // Route ĐẦU TIÊN sau SSR: nếu view khớp entry server đã render →
+            // hydrateView (claim DOM) thay vì mountView. consumeSSRViewId() chỉ
+            // trả id 1 lần → các navigate sau là CSR (SPA takeover).
             const viewComponent = route.component || route.view;
+            let transitionSucceeded = true;
+            // View cũ bị gỡ trước khi cây mới dựng xong, nên tài liệu sập chiều
+            // cao trong vài frame — footer nhảy vọt lên, thanh cuộn biến mất,
+            // trình duyệt kẹp lại scrollY. Giữ chiều cao cũ tới khi thay xong.
+            releaseHeight = this.freezeDocumentHeight();
             if (viewComponent) {
-                if (this.viewManager) {
-                    await this.viewManager.mountView(viewComponent, params, activeRoute);
-                } else if (this.App?.View) {
-                    // Fallback: App.View is the ViewManager (registered on app)
-                    await this.App.View.mountView(viewComponent, params, activeRoute);
+                const vm = this.viewManager ?? this.App?.View;
+                if (vm) {
+                    const ssrViewId = vm.consumeSSRViewId?.(viewComponent) ?? null;
+                    let result: any;
+                    if (ssrViewId) {
+                        result = await vm.hydrateView(viewComponent, { __SSR_VIEW_ID__: ssrViewId, ...params }, activeRoute);
+                    } else {
+                        result = await vm.mountView(viewComponent, params, activeRoute, type === 'pop' ? 'pop' : 'push');
+                    }
+                    // mountView(null) có thể là duplicate no-op; xác nhận chain
+                    // active đang thật sự thuộc URI đích trước khi commit Router.
+                    transitionSucceeded = result != null
+                        || vm.getCurrentView?.()?.__ctrl__?.urlPath === uri;
+                } else {
+                    transitionSucceeded = false;
                 }
             }
+            if (requestId !== this.navigationSequence) return;
+            if (!transitionSucceeded) {
+                if (type === 'pop') this.restoreUrlAfterFailedPop(from);
+                return;
+            }
 
-            // After hook
-            if (this._afterEach) {
-                this._afterEach({ ...route, path: normalizedPath }, from);
+            // Commit point: từ đây URL, Router state và mounted view cùng
+            // đại diện cho một navigation duy nhất.
+            if (this.mode === 'history') {
+                if (type === 'push') window.history.pushState({}, '', historyTarget);
+                else if (type === 'replace') window.history.replaceState({}, '', historyTarget);
+            } else if (type === 'push' || type === 'replace') {
+                window.location.hash = historyTarget;
+            }
+
+            Router.activeRoute = activeRoute;
+            this.currentRoute = activeRoute;
+            this.currentUri = uri;
+            this.applyScroll(type, fragment);
+            this.announceNavigation(type);
+
+            // After hook — chạy trên BẢN SAO: hook được phép tự huỷ đăng ký trong
+            // lúc chạy. Bọc try/catch từng hook: một hook hỏng (view đã destroy
+            // chẳng hạn) không được phép làm chết điều hướng của tất cả phần còn lại.
+            for (const hook of [...this.afterHooks]) {
+                try {
+                    hook({ ...route, path: normalizedPath }, from);
+                } catch (error) {
+                    console.error('[Router] afterEach hook lỗi:', error);
+                }
             }
         } catch (error) {
             console.error('[Router] Navigation error:', error);
         } finally {
+            releaseHeight();
             this.isNavigating = false;
+            if (requestId === this.navigationSequence) this.activeNavigationUrl = null;
+            // Có navigation đến trong lúc đang xử lý → chạy request mới nhất
+            const pending = this.pendingNavigation;
+            this.pendingNavigation = null;
+            if (pending) {
+                void this.handleRoute(pending.path, pending.type, pending.id);
+            }
+        }
+    }
+
+    /** Pop đã đổi address bar; render fail thì đưa URL về chain còn active. */
+    private restoreUrlAfterFailedPop(from: ActiveRoute | null): void {
+        if (this.mode !== 'history' || !from) return;
+        const target = from.$fragment ? `${from.$uri}#${from.$fragment}` : from.$uri;
+        window.history.replaceState(window.history.state, '', target);
+    }
+
+    /**
+     * Ghim chiều cao tài liệu bằng đúng chiều cao hiện tại, trả về hàm nhả.
+     * Chỉ chạm `min-height` của body nên không đụng layout khi đã nhả.
+     */
+    private freezeDocumentHeight(): () => void {
+        if (typeof document === 'undefined' || !document.body) return () => {};
+        const body = document.body;
+        const previous = body.style.minHeight;
+        try {
+            body.style.minHeight = `${document.documentElement.scrollHeight}px`;
+        } catch {
+            return () => {};
+        }
+        return () => { try { body.style.minHeight = previous; } catch { /* noop */ } };
+    }
+
+    private applyScroll(type: NavigationType, fragment: string): void {
+        if (typeof window === 'undefined') return;
+        if (fragment) {
+            let id = fragment;
+            try { id = decodeURIComponent(fragment); } catch { /* malformed fragment */ }
+            const target = document.getElementById(id) || document.getElementsByName(id)[0];
+            target?.scrollIntoView?.();
+            return;
+        }
+        // PageCache tự khôi phục pop position; initial giữ vị trí SSR/browser.
+        if (type === 'push' || type === 'replace') {
+            // scrollTo(0,0) tuân theo `html { scroll-behavior: smooth }` nếu trang
+            // có đặt — biến cú nhảy về đầu thành cuộn chậm ~0.4s chạy SAU khi nội
+            // dung đã thay xong, nhìn như treo. Đổi route phải tức thì; smooth để
+            // dành cho anchor trong trang (nhánh fragment ở trên).
+            try {
+                window.scrollTo({ top: 0, left: 0, behavior: 'instant' as ScrollBehavior });
+            } catch {
+                // Engine cũ chưa biết 'instant' sẽ ném khi validate enum.
+                try { window.scrollTo(0, 0); } catch { /* non-browser/test runtime */ }
+            }
         }
     }
 
+    /** Live region dùng lại giữa các lần điều hướng — tạo lười, chỉ 1 node. */
+    private liveRegion: HTMLElement | null = null;
+
+    /**
+     * A11y sau khi điều hướng xong (SPA không tự làm được như full page load):
+     *   1. Đưa focus về container view — không làm thì bàn phím vẫn ở link cũ
+     *      của trang TRƯỚC, Tab tiếp tục từ vị trí không còn tồn tại.
+     *   2. Đọc tên trang mới qua live region — screen reader không hề biết
+     *      nội dung đã đổi vì document không reload.
+     *
+     * `preventScroll` để không phá `applyScroll()` vừa chạy. Bỏ qua `initial`:
+     * lần paint đầu/hydrate không được cướp focus khỏi thứ user đang thao tác.
+     */
+    private announceNavigation(type: NavigationType): void {
+        if (typeof document === 'undefined' || type === 'initial') return;
+
+        const container = (this.viewManager ?? this.App?.View)?.getContainer?.();
+        if (container instanceof HTMLElement) {
+            // tabindex=-1: focus được bằng script nhưng KHÔNG chen vào thứ tự Tab.
+            if (!container.hasAttribute('tabindex')) container.setAttribute('tabindex', '-1');
+            try { container.focus({ preventScroll: true }); } catch { /* jsdom/older browsers */ }
+        }
+
+        if (!this.liveRegion || !this.liveRegion.isConnected) {
+            const region = document.createElement('div');
+            region.setAttribute('aria-live', 'polite');
+            region.setAttribute('aria-atomic', 'true');
+            // Ẩn khỏi mắt nhưng KHÔNG display:none / visibility:hidden —
+            // hai cái đó làm screen reader bỏ qua luôn.
+            region.style.cssText =
+                'position:absolute;width:1px;height:1px;margin:-1px;padding:0;'
+                + 'overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0';
+            document.body.appendChild(region);
+            this.liveRegion = region;
+        }
+        // Ghi ở frame sau: nội dung mới phải khác nội dung cũ thì AT mới đọc lại.
+        const label = document.title || this.currentUri || '';
+        this.liveRegion.textContent = '';
+        requestAnimationFrame(() => {
+            if (this.liveRegion) this.liveRegion.textContent = label;
+        });
+    }
+
     /**
      * Handle browser back/forward.
      */
     private handlePopState(): void {
         const path = this.mode === 'history'
-            ? window.location.pathname + window.location.search
+            ? window.location.pathname + window.location.search + window.location.hash
             : window.location.hash.slice(1) || this.defaultRoute;
-        this.handleRoute(path);
+        this.requestNavigation(path, 'pop');
     }
 
     /**
      * Auto-navigation: intercept clicks on <a>, [data-nav-link], [data-navigate].
      */
     private handleAutoNavigation(e: MouseEvent): void {
+        if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
         const target = e.target as HTMLElement;
+        if (!target?.closest) return;
 
         // 1. [data-nav-link] — highest priority
         const navLinkEl = target.closest('[data-nav-link]') as HTMLElement;
         if (navLinkEl) {
             if (navLinkEl.hasAttribute('data-nav-disabled')) return;
             const navPath = navLinkEl.getAttribute('data-nav-link');
-            if (navPath && navPath.trim() !== '' && navPath !== this.currentUri) {
+            if (navPath && navPath.trim() !== '') {
                 e.preventDefault();
-                this.navigate(navPath);
+                if (navPath !== this.currentUri) this.navigate(navPath);
                 return;
             }
         }
@@ -575,9 +958,9 @@ export class Router {
         if (navigateEl) {
             if (navigateEl.hasAttribute('data-nav-disabled')) return;
             const navPath = navigateEl.getAttribute('data-navigate');
-            if (navPath && navPath.trim() !== '' && navPath !== this.currentUri) {
+            if (navPath && navPath.trim() !== '') {
                 e.preventDefault();
-                this.navigate(navPath);
+                if (navPath !== this.currentUri) this.navigate(navPath);
                 return;
             }
         }
@@ -587,7 +970,8 @@ export class Router {
         if (!link) return;
 
         // Skip: target="_blank", disabled, special protocols
-        if (link.target === '_blank') return;
+        if (link.target && link.target !== '_self') return;
+        if (link.hasAttribute('download')) return;
         if (link.dataset.nav === 'disabled' || link.dataset.nav === 'false') return;
         const href = link.href;
         if (href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('javascript:')) return;
@@ -598,15 +982,18 @@ export class Router {
             const currentUrl = new URL(window.location.href);
             if (linkUrl.host !== currentUrl.host) return; // External
 
-            const path = linkUrl.pathname + linkUrl.search;
-            if (path === this.currentUri) return; // Same page
+            const path = linkUrl.pathname + linkUrl.search + linkUrl.hash;
+            // Link trỏ về đúng route đang đứng vẫn phải nuốt click. Thoát sớm mà
+            // không preventDefault là để browser tự điều hướng — reload cả tài
+            // liệu, mất sạch state SPA. Đây là logo và mục menu đang active.
             e.preventDefault();
+            if (path === this.currentUri && !linkUrl.hash) return; // Same page — no-op
             this.navigate(path);
         } catch {
             // Relative URL
             if (href && !href.startsWith('http') && !href.startsWith('//')) {
-                if (href === this.currentUri) return;
                 e.preventDefault();
+                if (href === this.currentUri) return; // Same page — no-op
                 this.navigate(href);
             }
         }
@@ -615,7 +1002,8 @@ export class Router {
     // ─── Internal: Pattern Matching ─────────────────────────────
 
     private matchRoute(path: string): RouteMatch | null {
-        const normalizedPath = this.normalizePath(path);
+        // Defensive: strip query/hash nếu caller truyền URI đầy đủ
+        const normalizedPath = this.normalizePath(this.splitLocation(path).pathname);
 
         if (this.routeCache.has(normalizedPath)) {
             return this.routeCache.get(normalizedPath)!;
@@ -681,7 +1069,9 @@ export class Router {
             regexParts.push('\\/' + escaped);
         }
 
-        const regex = new RegExp(`^${regexParts.join('')}$`);
+        // Root path '/' → mọi segment rỗng → regexParts rỗng. Phải khớp '\/'
+        // (nếu để '^$' thì route '/' không bao giờ match — bug gốc).
+        const regex = new RegExp(`^${regexParts.join('') || '\\/'}$`);
         const match = normalizedPath.match(regex);
         if (!match) return null;
 
@@ -714,12 +1104,16 @@ export class Router {
     }
 
     private setActiveRouteForPath(path: string): void {
-        const normalizedPath = this.normalizePath(path);
+        const { pathname, queryString, fragment } = this.splitLocation(path);
+        const normalizedPath = this.normalizePath(pathname);
         const match = this.matchRoute(normalizedPath);
         if (match) {
-            const query = this.parseQuery(window.location.search);
-            const fragment = window.location.hash.substring(1);
-            const activeRoute = new ActiveRoute(match.route, normalizedPath, match.params, query, fragment);
+            const uri = queryString ? `${normalizedPath}?${queryString}` : normalizedPath;
+            const query = this.parseQuery(queryString || window.location.search);
+            const activeRoute = new ActiveRoute(
+                match.route, normalizedPath, match.params, query,
+                fragment || window.location.hash.substring(1), uri
+            );
             Router.activeRoute = activeRoute;
             this.currentRoute = activeRoute;
         }