@saolabs/client 1.0.0 → 1.0.2

package/dist/src/core/routers/Router.js

@@ -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.
@@ -15,9 +15,10 @@
  */
 // ─── ActiveRoute ────────────────────────────────────────────────
 export class ActiveRoute {
-    constructor(route, urlPath, params = {}, query = {}, fragment = '') {
+    constructor(route, urlPath, params = {}, query = {}, fragment = '', uri) {
         this.$route = route;
         this.$urlPath = urlPath;
+        this.$uri = uri ?? urlPath;
         this.$params = params;
         this.$query = query;
         this.$fragment = fragment;
@@ -83,21 +84,57 @@ export class Router {
         this.currentUri = '';
         /** Navigation guards */
         this._beforeEach = null;
-        this._afterEach = 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ỷ.
+         */
+        this.afterHooks = new Set();
         /** Caches */
         this.routeCache = new Map();
         /** State */
         this.isStarted = false;
         this.isNavigating = false;
+        this.navigationSequence = 0;
+        this.activeNavigationUrl = null;
+        // ─── Internal: Route Handling ────────────────────────────────
+        /** Kiểu navigation nội bộ — quyết định thao tác history + nav type xuống ViewManager */
+        this.pendingNavigation = null;
+        /** Live region dùng lại giữa các lần điều hướng — tạo lười, chỉ 1 node. */
+        this.liveRegion = null;
         this.App = app || null;
         this.currentUri = typeof window !== 'undefined'
             ? window.location.pathname + window.location.search
             : '/';
         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) {
+        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.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;
     }
     setApp(app) {
@@ -139,10 +176,63 @@ export class Router {
         return this;
     }
     /**
-     * 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.
+     */
+    static joinRoutePath(parent, child) {
+        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 đó.
+     */
+    flattenRouteTree(routes, parentPath = '', parentMeta = {}) {
+        const flat = [];
+        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) {
+        // 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) {
@@ -151,6 +241,13 @@ export class Router {
         }
         return this;
     }
+    /** Atomically replace the materialized route table for a new context revision. */
+    replaceRoutes(routes) {
+        this.routes = [];
+        this.routeConfigs = {};
+        this.routeCache.clear();
+        return this.addRoutes(routes);
+    }
     /**
      * Configure router from a config object.
      */
@@ -161,14 +258,17 @@ export class Router {
             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;
+            this.afterEach(config.afterEach);
         return this;
     }
     // ─── Guards ─────────────────────────────────────────────────
@@ -176,23 +276,19 @@ export class Router {
         this._beforeEach = guard;
         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) {
-        this._afterEach = hook;
-        return this;
+        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) {
-        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 */
     push(path) {
@@ -214,14 +310,7 @@ export class Router {
      * Replace current history entry without adding to stack.
      */
     replace(path) {
-        if (this.mode === 'history') {
-            window.history.replaceState({}, '', path);
-        }
-        else {
-            window.location.hash = path;
-        }
-        this.handleRoute(path);
-        this.currentUri = path;
+        this.requestNavigation(path, 'replace');
     }
     /**
      * Go back in history.
@@ -333,9 +422,10 @@ 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;
     }
@@ -346,39 +436,150 @@ 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;
     }
+    handleViewContextChange(event) {
+        const state = event.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.
+     */
+    reloadForViewContext(target, state) {
+        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 < 15000) {
+                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() {
         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() {
         if (typeof window === 'undefined')
             return '';
+        if (this.activeNavigationUrl) {
+            return new URL(this.activeNavigationUrl, window.location.href).href;
+        }
         return window.location.href;
     }
-    // ─── Internal: Route Handling ────────────────────────────────
     /**
-     * Core route handler — match route, run guards, mount view.
+     * 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.
+     */
+    splitLocation(raw) {
+        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 };
+    }
+    /**
+     * Đ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).
      */
-    async handleRoute(path) {
-        if (this.isNavigating)
+    requestNavigation(path, type) {
+        const request = { 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.
+     */
+    async handleRoute(path, type = 'push', requestId = ++this.navigationSequence) {
         this.isNavigating = true;
+        // Khai ngoài try: `finally` phải nhả được kể cả khi render ném giữa chừng.
+        let releaseHeight = () => { };
         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) {
                 console.warn(`[Router] No route matched: ${path}`);
@@ -387,62 +588,227 @@ export class Router {
             const { route, params } = match;
             const from = this.currentRoute;
             // Create ActiveRoute
-            const activeRoute = new ActiveRoute(route, normalizedPath, params, query, fragment);
-            // Before guard
+            const activeRoute = new ActiveRoute(route, normalizedPath, params, query, fragment, uri);
+            // 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;
             }
-            // Update global state
-            Router.activeRoute = activeRoute;
-            this.currentRoute = activeRoute;
-            // Mount view via ViewManager
+            if (requestId !== this.navigationSequence)
+                return;
+            const historyTarget = fragment ? `${uri}#${fragment}` : uri;
+            this.activeNavigationUrl = historyTarget;
+            // 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);
+                const vm = this.viewManager ?? this.App?.View;
+                if (vm) {
+                    const ssrViewId = vm.consumeSSRViewId?.(viewComponent) ?? null;
+                    let result;
+                    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 if (this.App?.View) {
-                    // Fallback: App.View is the ViewManager (registered on app)
-                    await this.App.View.mountView(viewComponent, params, activeRoute);
+                else {
+                    transitionSucceeded = false;
                 }
             }
-            // After hook
-            if (this._afterEach) {
-                this._afterEach({ ...route, path: normalizedPath }, from);
+            if (requestId !== this.navigationSequence)
+                return;
+            if (!transitionSucceeded) {
+                if (type === 'pop')
+                    this.restoreUrlAfterFailedPop(from);
+                return;
+            }
+            // 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. */
+    restoreUrlAfterFailedPop(from) {
+        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ả.
+     */
+    freezeDocumentHeight() {
+        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 */ } };
+    }
+    applyScroll(type, fragment) {
+        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' });
+            }
+            catch {
+                // Engine cũ chưa biết 'instant' sẽ ném khi validate enum.
+                try {
+                    window.scrollTo(0, 0);
+                }
+                catch { /* non-browser/test runtime */ }
+            }
         }
     }
+    /**
+     * 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.
+     */
+    announceNavigation(type) {
+        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.
      */
     handlePopState() {
         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].
      */
     handleAutoNavigation(e) {
+        if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+            return;
         const target = e.target;
+        if (!target?.closest)
+            return;
         // 1. [data-nav-link] — highest priority
         const navLinkEl = target.closest('[data-nav-link]');
         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;
             }
         }
@@ -452,9 +818,10 @@ export class Router {
             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;
             }
         }
@@ -463,7 +830,9 @@ export class Router {
         if (!link)
             return;
         // Skip: target="_blank", disabled, special protocols
-        if (link.target === '_blank')
+        if (link.target && link.target !== '_self')
+            return;
+        if (link.hasAttribute('download'))
             return;
         if (link.dataset.nav === 'disabled' || link.dataset.nav === 'false')
             return;
@@ -476,25 +845,29 @@ 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);
             }
         }
     }
     // ─── Internal: Pattern Matching ─────────────────────────────
     matchRoute(path) {
-        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);
         }
@@ -550,7 +923,9 @@ export class Router {
             const escaped = seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
             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;
@@ -578,12 +953,13 @@ export class Router {
         return query;
     }
     setActiveRouteForPath(path) {
-        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;
         }