@esmx/router 3.0.0-rc.116 → 3.0.0-rc.118

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Esmx Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -33,7 +33,7 @@
 - **Universal Support** - Runs in both browser and Node.js environments
 - **TypeScript Ready** - Full TypeScript support with excellent type inference
 - **High Performance** - Optimized for production use with minimal bundle size
-- **SSR Compatible** - Complete server-side rendering support
+- **SSR Compatible** - Complete SSR support
 - **Modern API** - Clean and intuitive API design
 
 ## 📦 Installation
@@ -56,7 +56,7 @@ import { Router, RouterMode } from '@esmx/router';
 
 // Create router instance
 const router = new Router({
-  root: '#app', // Required in browser environment
+  appId: 'app', // Application mount container ID (optional, defaults to 'app')
   mode: RouterMode.history,
   routes: [
     { path: '/', component: () => 'Home Page' },
@@ -72,6 +72,87 @@ await router.push('/about');
 
 Visit the [official documentation](https://esmx.dev) for detailed usage guides and API reference.
 
+### Route Navigation Flow
+
+```mermaid
+flowchart TD
+  start(["Start"]):::Terminal --> normalizeURL["normalizeURL"]
+  normalizeURL --> isExternalUrl{"Internal URL"}:::Decision
+  isExternalUrl -- Yes --> matchInRouteTable["Match in route table"]
+  isExternalUrl -- No --> fallback["fallback"] --> End
+  matchInRouteTable --> isExist{"Match found"}:::Decision
+  isExist -- No --> fallback
+  isExist -- Yes --> execGuard["Execute hooks/guards"] --> End(["End"]):::Terminal
+  classDef Terminal fill:#FFF9C4,color:#000
+  classDef Decision fill:#C8E6C9,color:#000
+```
+
+#### Route Hook Pipeline
+
+|  | fallback | override | beforeLeave | beforeEach | beforeUpdate | beforeEnter | asyncComponent | confirm |
+|---------|----------|----------|-------------|------------|--------------|-------------|----------------|---------|
+| `push` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `replace` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `pushWindow` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| `pushLayer` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| `replaceWindow` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| `restartApp` | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `unknown` | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+```mermaid
+gantt
+  title Route Hook Execution Comparison
+  dateFormat X
+  axisFormat %s
+  section push\nreplace
+    fallback      :0, 1
+    override      :1, 2
+    beforeLeave   :2, 3
+    beforeEach    :3, 4
+    beforeUpdate  :4, 5
+    beforeEnter   :5, 6
+    asyncComponent:6, 7
+    confirm       :7, 8
+  section pushWindow\npushLayer
+    fallback      :0, 1
+    override      :1, 2
+    beforeEach    :3, 4
+    confirm       :7, 8
+  section replaceWindow
+    fallback      :0, 1
+    override      :1, 2
+    beforeLeave   :2, 3
+    beforeEach    :3, 4
+    confirm       :7, 8
+  section restartApp\nunknown
+    fallback      :0, 1
+    beforeLeave   :2, 3
+    beforeEach    :3, 4
+    beforeUpdate  :4, 5
+    beforeEnter   :5, 6
+    asyncComponent:6, 7
+    confirm       :7, 8
+```
+
+#### Hook Functions
+
+- **fallback**: Handle unmatched routes
+- **override**: Allow route override logic
+- **beforeLeave**: Execute before leaving current route
+- **beforeEach**: Global navigation guard
+- **beforeUpdate**: Execute before route update (same component)
+- **beforeEnter**: Execute before entering new route
+- **asyncComponent**: Load async component
+- **confirm**: Final confirmation and navigation execution
+
+#### Navigation Types
+
+- **Standard Navigation** (`push`, `replace`): Execute full hook chain
+- **Window Operations** (`pushWindow`, `replaceWindow`): Simplified hook chain for window-level navigation
+- **Layer Operations** (`pushLayer`): Minimal hook chain for layer navigation
+- **App Restart** (`restartApp`): Full hook chain but skip override
+- **Unknown Type** (`unknown`): Full hook chain but skip override, used as default handling
+
 ## 📄 License
 
-MIT © [Esmx Team](https://github.com/esmnext/esmx) 
+MIT © [Esmx Team](https://github.com/esmnext/esmx)

package/README.zh-CN.md

@@ -31,9 +31,9 @@
 
 - **框架无关** - 适用于任何前端框架（Vue、React、Preact、Solid 等）
 - **通用支持** - 在浏览器和 Node.js 环境中运行
-- **TypeScript 就绪** - 完整的 TypeScript 支持，出色的类型推断
-- **高性能** - 为生产环境优化，最小化包体积
-- **SSR 兼容** - 完整的服务端渲染支持
+- **TypeScript 支持** - 完整的 TypeScript 类型推断与类型安全
+- **高性能** - 针对生产环境优化，极小的包体积
+- **SSR 兼容** - 完整的 SSR 支持
 - **现代 API** - 简洁直观的 API 设计
 
 ## 📦 安装
@@ -56,7 +56,7 @@ import { Router, RouterMode } from '@esmx/router';
 
 // 创建路由器实例
 const router = new Router({
-  root: '#app', // 浏览器环境中必需
+  appId: 'app', // 应用挂载容器 ID（可选，默认 'app'）
   mode: RouterMode.history,
   routes: [
     { path: '/', component: () => '首页' },

package/dist/micro-app.d.ts

@@ -1,13 +1,13 @@
 import type { Router } from './router';
 import type { RouterMicroAppOptions } from './types';
 /**
- * Resolves the root container element.
- * Supports a DOM selector string or a direct HTMLElement.
+ * Gets the root container element by ID.
+ * If not found, creates a new div with the given ID and appends it to document.body.
  *
- * @param rootConfig - The root container configuration, can be a selector string or an HTMLElement.
+ * @param appId - The application container ID.
  * @returns The resolved HTMLElement.
  */
-export declare function resolveRootElement(rootConfig?: string | HTMLElement): HTMLElement;
+export declare function getRootElement(appId: string): HTMLElement;
 export declare class MicroApp {
     app: RouterMicroAppOptions | null;
     root: HTMLElement | null;
@@ -16,4 +16,5 @@ export declare class MicroApp {
     _update(router: Router, force?: boolean): void;
     private _getNextFactory;
     destroy(): void;
+    private _clearRoot;
 }

package/dist/micro-app.mjs

@@ -2,22 +2,15 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 import { isBrowser, isPlainObject } from "./util.mjs";
-export function resolveRootElement(rootConfig) {
-  let el = null;
-  if (rootConfig instanceof HTMLElement) {
-    el = rootConfig;
+export function getRootElement(appId) {
+  const el = document.getElementById(appId);
+  if (el) {
+    return el;
   }
-  if (typeof rootConfig === "string" && rootConfig) {
-    try {
-      el = document.querySelector(rootConfig);
-    } catch (error) {
-      console.warn("Failed to resolve root element: ".concat(rootConfig));
-    }
-  }
-  if (el === null) {
-    el = document.createElement("div");
-  }
-  return el;
+  const newEl = document.createElement("div");
+  newEl.id = appId;
+  document.body.appendChild(newEl);
+  return newEl;
 }
 export class MicroApp {
   constructor() {
@@ -39,21 +32,62 @@ export class MicroApp {
     if (isBrowser && app) {
       let root = this.root;
       if (root === null) {
-        root = resolveRootElement(router.root);
+        root = getRootElement(router.appId);
         const { rootStyle } = router.parsedOptions;
         if (root && isPlainObject(rootStyle)) {
           Object.assign(root.style, router.parsedOptions.rootStyle);
         }
+        this.root = root;
       }
       if (root) {
-        app.mount(root);
-        if (root.parentNode === null) {
-          document.body.appendChild(root);
+        const isHydration = root.hasAttribute("data-ssr");
+        if (isHydration) {
+          const appRoot = root.firstElementChild;
+          if (appRoot) {
+            if (app.hydration) {
+              app.hydration(appRoot);
+            } else {
+              throw new Error(
+                "SSR content detected but hydration function not provided"
+              );
+            }
+          } else {
+            const el = document.createElement("div");
+            root.appendChild(el);
+            try {
+              app.mount(el);
+            } catch (e) {
+              el.remove();
+              throw e;
+            }
+          }
+          root.removeAttribute("data-ssr");
+        } else {
+          const oldChildren = Array.from(root.childNodes);
+          const el = document.createElement("div");
+          root.appendChild(el);
+          try {
+            app.mount(el);
+          } catch (e) {
+            el.remove();
+            throw e;
+          }
+          if (oldApp) {
+            try {
+              oldApp.unmount();
+            } catch (e) {
+              console.error(
+                "[@esmx/router] MicroApp unmount failed during route transition. Check the framework unmount hook returned by your render function (Vue: app.unmount, React: root.unmount, etc.).",
+                e
+              );
+            }
+          }
+          oldChildren.forEach((child) => {
+            if (child.parentNode) {
+              child.remove();
+            }
+          });
         }
-        this.root = root;
-      }
-      if (oldApp) {
-        oldApp.unmount();
       }
     }
     this.app = app;
@@ -79,12 +113,20 @@ export class MicroApp {
     return null;
   }
   destroy() {
-    var _a, _b;
+    var _a;
     (_a = this.app) == null ? void 0 : _a.unmount();
+    this._clearRoot();
     this.app = null;
-    (_b = this.root) == null ? void 0 : _b.remove();
     this.root = null;
     this._factory = null;
     this.destroyed = true;
   }
+  _clearRoot() {
+    if (!this.root) {
+      return;
+    }
+    Array.from(this.root.childNodes).forEach((child) => {
+      child.remove();
+    });
+  }
 }

package/dist/options.mjs

@@ -30,13 +30,13 @@ function getBaseUrl(options) {
   return base;
 }
 export function parsedOptions(options = {}) {
-  var _a, _b, _c, _d, _e, _f, _g;
+  var _a, _b, _c, _d, _e, _f, _g, _h;
   const base = getBaseUrl(options);
   const routes = (_a = options.routes) != null ? _a : [];
   const compiledRoutes = createRouteMatches(routes);
   return Object.freeze({
     rootStyle: options.rootStyle || false,
-    root: options.root || "",
+    appId: options.appId || "app",
     context: options.context || {},
     data: options.data || {},
     req: options.req || null,
@@ -56,7 +56,8 @@ export function parsedOptions(options = {}) {
     handleBackBoundary: (_f = options.handleBackBoundary) != null ? _f : (() => {
     }),
     handleLayerClose: (_g = options.handleLayerClose) != null ? _g : (() => {
-    })
+    }),
+    resolveLink: (_h = options.resolveLink) != null ? _h : ((link) => link)
   });
 }
 export function fallback(to, from, router) {

package/dist/router-link.mjs

@@ -125,15 +125,18 @@ export function createLinkResolver(router, props) {
     eventTypes
   );
   const navigate = createNavigateFunction(router, props, type);
-  return {
-    route,
-    type,
-    isActive,
-    isExactActive,
-    isExternal,
-    tag: props.tag || "a",
-    attributes,
-    navigate,
-    createEventHandlers
-  };
+  return router.parsedOptions.resolveLink(
+    {
+      route,
+      type,
+      isActive,
+      isExactActive,
+      isExternal,
+      tag: props.tag || "a",
+      attributes,
+      navigate,
+      createEventHandlers
+    },
+    props
+  );
 }

package/dist/router.d.ts

@@ -14,7 +14,7 @@ export declare class Router {
     get route(): Route;
     get context(): Record<string | symbol, unknown>;
     get data(): Record<string | symbol, unknown>;
-    get root(): string | HTMLElement;
+    get appId(): string;
     get mode(): RouterMode;
     get base(): URL;
     get req(): import("http").IncomingMessage | null;

package/dist/router.mjs

@@ -9,7 +9,19 @@ import { Route } from "./route.mjs";
 import { RouteTransition } from "./route-transition.mjs";
 import { createLinkResolver } from "./router-link.mjs";
 import { RouterMode, RouteType } from "./types.mjs";
-import { isNotNullish, isPlainObject, isRouteMatched } from "./util.mjs";
+import {
+  isNotNullish,
+  isPlainObject,
+  isRouteMatched,
+  validateSsrRootElement
+} from "./util.mjs";
+const LAYER_SKIP_TYPES = /* @__PURE__ */ new Set([
+  RouteType.pushWindow,
+  RouteType.replaceWindow,
+  RouteType.replace,
+  RouteType.restartApp,
+  RouteType.pushLayer
+]);
 export class Router {
   constructor(options) {
     __publicField(this, "options");
@@ -47,8 +59,8 @@ export class Router {
   get data() {
     return this.parsedOptions.data;
   }
-  get root() {
-    return this.parsedOptions.root;
+  get appId() {
+    return this.parsedOptions.appId;
   }
   get mode() {
     return this.parsedOptions.mode;
@@ -234,7 +246,7 @@ export class Router {
       ...this.options,
       context: this.parsedOptions.context,
       mode: RouterMode.memory,
-      root: void 0,
+      appId: void 0,
       ...layerOptions.routerOptions,
       handleBackBoundary(router2) {
         router2.destroy();
@@ -262,14 +274,7 @@ export class Router {
     });
     const initRoute = await router.replace(toInput);
     router.afterEach(async (to, from) => {
-      if ([
-        RouteType.pushWindow,
-        RouteType.replaceWindow,
-        RouteType.replace,
-        RouteType.restartApp,
-        RouteType.pushLayer
-      ].includes(to.type))
-        return;
+      if (LAYER_SKIP_TYPES.has(to.type)) return;
       let keepAlive = false;
       if (layerOptions.keepAlive === "exact") {
         keepAlive = to.path === initRoute.path;
@@ -334,10 +339,16 @@ export class Router {
     var _a, _b;
     try {
       const result = await ((_b = (_a = this.microApp.app) == null ? void 0 : _a.renderToString) == null ? void 0 : _b.call(_a));
-      return result != null ? result : null;
+      const trimmed = result == null ? void 0 : result.trim();
+      const hasContent = trimmed && trimmed.length > 0;
+      if (hasContent && process.env.NODE_ENV !== "production") {
+        validateSsrRootElement(trimmed);
+      }
+      const ssrAttr = hasContent ? " data-ssr" : "";
+      return '<div id="'.concat(this.appId, '"').concat(ssrAttr, ">").concat(result != null ? result : "", "</div>");
     } catch (e) {
       if (throwError) throw e;
-      else console.error(e);
+      else console.error("[@esmx/router] SSR render failed:", e);
       return null;
     }
   }

package/dist/types.d.ts

@@ -215,6 +215,7 @@ export type RouteLayerResult = {
 export type RouterLayerOptions = Omit<RouterOptions, 'handleBackBoundary' | 'handleLayerClose' | 'layer'>;
 export interface RouterMicroAppOptions {
     mount: (el: HTMLElement) => void;
+    hydration?: (el: HTMLElement) => void;
     unmount: () => void;
     renderToString?: () => Awaitable<string>;
 }
@@ -222,28 +223,18 @@ export type RouterMicroAppCallback = (router: Router) => RouterMicroAppOptions;
 export type RouterMicroApp = Record<string, RouterMicroAppCallback | undefined> | RouterMicroAppCallback;
 export interface RouterOptions {
     /**
-     * Application mounting container
-     * - Can be a DOM selector string (e.g., '#app', '.container', '[data-mount]')
-     * - Can be an HTMLElement object
-     * - Defaults to '#root'
+     * Application mount container ID
+     * - Pure string ID, no '#' prefix needed
+     * - Client-side: uses document.getElementById(appId)
+     * - Server-side: generates <div id="${appId}"> wrapper
+     * - Defaults to 'app'
      *
      * @example
      * ```typescript
-     * // Using ID selector
-     * new Router({ root: '#my-app' })
-     *
-     * // Using class selector
-     * new Router({ root: '.app-container' })
-     *
-     * // Using attribute selector
-     * new Router({ root: '[data-router-mount]' })
-     *
-     * // Passing DOM element directly
-     * const element = document.getElementById('app');
-     * new Router({ root: element })
+     * new Router({ appId: 'app' })
      * ```
      */
-    root?: string | HTMLElement;
+    appId?: string;
     context?: Record<string | symbol, unknown>;
     data?: Record<string | symbol, unknown>;
     routes?: RouteConfig[];
@@ -261,6 +252,7 @@ export interface RouterOptions {
     zIndex?: number;
     handleBackBoundary?: (router: Router) => void;
     handleLayerClose?: (router: Router, data?: any) => void;
+    resolveLink?: (link: RouterLinkResolved, props: RouterLinkProps) => RouterLinkResolved;
 }
 export interface RouterParsedOptions extends Readonly<Required<RouterOptions>> {
     readonly compiledRoutes: readonly RouteParsedConfig[];

package/dist/util.d.ts

@@ -25,3 +25,8 @@ export declare function isUrlEqual(url1: URL, url2?: URL | null): boolean;
  */
 export declare function isRouteMatched(fromRoute: Route, toRoute: Route | null, matchType: RouteMatchType): boolean;
 export declare function decodeParams<T extends Record<string, string | string[]>>(params: T): T;
+/**
+ * Validates that SSR renderToString output contains exactly one root HTML element.
+ * Non-production only - throws if validation fails.
+ */
+export declare function validateSsrRootElement(html: string): void;

package/dist/util.mjs

@@ -65,3 +65,36 @@ export function decodeParams(params) {
   }
   return result;
 }
+export function validateSsrRootElement(html) {
+  var _a;
+  const trimmed = html.trim();
+  const firstMatch = trimmed.match(/^<([a-zA-Z][^\s>]*)/);
+  const firstTag = firstMatch == null ? void 0 : firstMatch[1];
+  const lastTag = (_a = trimmed.match(/<\/([a-zA-Z][^\s>]*)>\s*$/)) == null ? void 0 : _a[1];
+  if (!firstTag || firstTag !== lastTag) {
+    throw new Error(
+      "SSR renderToString() must return exactly one root HTML element. Current output: " + trimmed.slice(0, 100)
+    );
+  }
+  const tagRe = new RegExp("<(/?)".concat(firstTag, "(?:\\s[^>]*)?(/?)>"), "g");
+  let depth = 0;
+  let rootCloseEnd = -1;
+  let tag = tagRe.exec(trimmed);
+  while (tag !== null) {
+    if (tag[1] === "/") {
+      depth--;
+      if (depth === 0) {
+        rootCloseEnd = tagRe.lastIndex;
+        break;
+      }
+    } else if (tag[2] !== "/") {
+      depth++;
+    }
+    tag = tagRe.exec(trimmed);
+  }
+  if (rootCloseEnd === -1 || trimmed.slice(rootCloseEnd).trim().length > 0) {
+    throw new Error(
+      "SSR renderToString() must return exactly one root HTML element. Current output: " + trimmed.slice(0, 100)
+    );
+  }
+}

package/package.json

@@ -1,5 +1,30 @@
 {
     "name": "@esmx/router",
+    "description": "Framework-agnostic universal router for browser and Node.js SSR, with micro-frontend and layer navigation support",
+    "keywords": [
+        "router",
+        "routing",
+        "ssr",
+        "micro-frontend",
+        "typescript",
+        "universal",
+        "navigation",
+        "esmx",
+        "esm",
+        "spa",
+        "framework",
+        "frontend"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/esmnext/esmx.git",
+        "directory": "packages/router"
+    },
+    "homepage": "https://github.com/esmnext/esmx",
+    "bugs": {
+        "url": "https://github.com/esmnext/esmx/issues"
+    },
+    "license": "MIT",
     "template": "library",
     "scripts": {
         "lint:js": "biome check --write --no-errors-on-unmatched",
@@ -33,13 +58,13 @@
     "devDependencies": {
         "@biomejs/biome": "2.3.7",
         "@types/node": "^24.0.0",
-        "@vitest/coverage-v8": "3.2.4",
+        "@vitest/coverage-v8": "3.2.6",
         "happy-dom": "^20.0.10",
         "typescript": "5.9.3",
         "unbuild": "3.6.1",
-        "vitest": "3.2.4"
+        "vitest": "3.2.6"
     },
-    "version": "3.0.0-rc.116",
+    "version": "3.0.0-rc.118",
     "type": "module",
     "private": false,
     "exports": {
@@ -58,5 +83,11 @@
         "template",
         "public"
     ],
-    "gitHead": "3e692857ccb65e7d1fdf689e30eb5d935e8bda77"
+    "gitHead": "2fdbd62470f64e6e45568550941c78cb259e4917",
+    "engines": {
+        "node": ">=24"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/src/micro-app.ts

@@ -3,31 +3,21 @@ import type { RouterMicroAppCallback, RouterMicroAppOptions } from './types';
 import { isBrowser, isPlainObject } from './util';
 
 /**
- * Resolves the root container element.
- * Supports a DOM selector string or a direct HTMLElement.
+ * Gets the root container element by ID.
+ * If not found, creates a new div with the given ID and appends it to document.body.
  *
- * @param rootConfig - The root container configuration, can be a selector string or an HTMLElement.
+ * @param appId - The application container ID.
  * @returns The resolved HTMLElement.
  */
-export function resolveRootElement(
-    rootConfig?: string | HTMLElement
-): HTMLElement {
-    let el: HTMLElement | null = null;
-    // Direct HTMLElement provided
-    if (rootConfig instanceof HTMLElement) {
-        el = rootConfig;
+export function getRootElement(appId: string): HTMLElement {
+    const el = document.getElementById(appId);
+    if (el) {
+        return el;
     }
-    if (typeof rootConfig === 'string' && rootConfig) {
-        try {
-            el = document.querySelector(rootConfig);
-        } catch (error) {
-            console.warn(`Failed to resolve root element: ${rootConfig}`);
-        }
-    }
-    if (el === null) {
-        el = document.createElement('div');
-    }
-    return el;
+    const newEl = document.createElement('div');
+    newEl.id = appId;
+    document.body.appendChild(newEl);
+    return newEl;
 }
 
 export class MicroApp {
@@ -50,21 +40,69 @@ export class MicroApp {
         if (isBrowser && app) {
             let root: HTMLElement | null = this.root;
             if (root === null) {
-                root = resolveRootElement(router.root);
+                root = getRootElement(router.appId);
                 const { rootStyle } = router.parsedOptions;
                 if (root && isPlainObject(rootStyle)) {
                     Object.assign(root.style, router.parsedOptions.rootStyle);
                 }
+                this.root = root;
             }
             if (root) {
-                app.mount(root);
-                if (root.parentNode === null) {
-                    document.body.appendChild(root);
+                const isHydration = root.hasAttribute('data-ssr');
+                if (isHydration) {
+                    const appRoot = root.firstElementChild as HTMLElement;
+                    if (appRoot) {
+                        if (app.hydration) {
+                            app.hydration(appRoot);
+                        } else {
+                            throw new Error(
+                                'SSR content detected but hydration function not provided'
+                            );
+                        }
+                    } else {
+                        // No child elements (e.g., Vue 2 comment nodes), fallback to mount
+                        const el = document.createElement('div');
+                        root.appendChild(el);
+                        try {
+                            app.mount(el);
+                        } catch (e) {
+                            el.remove();
+                            throw e;
+                        }
+                    }
+                    // Remove data-ssr attribute after hydration
+                    root.removeAttribute('data-ssr');
+                } else {
+                    // Capture all existing children before inserting the new container.
+                    // Old app may have created multiple sibling nodes during its lifecycle.
+                    const oldChildren = Array.from(root.childNodes);
+                    const el = document.createElement('div');
+                    root.appendChild(el);
+                    try {
+                        app.mount(el);
+                    } catch (e) {
+                        el.remove();
+                        throw e;
+                    }
+                    if (oldApp) {
+                        try {
+                            oldApp.unmount();
+                        } catch (e) {
+                            // eslint-disable-next-line no-console
+                            console.error(
+                                '[@esmx/router] MicroApp unmount failed during route transition. Check the framework unmount hook returned by your render function (Vue: app.unmount, React: root.unmount, etc.).',
+                                e
+                            );
+                        }
+                    }
+                    // Remove old children that are still attached to the DOM.
+                    // Some frameworks may have already removed their own nodes during unmount.
+                    oldChildren.forEach((child) => {
+                        if (child.parentNode) {
+                            child.remove();
+                        }
+                    });
                 }
-                this.root = root;
-            }
-            if (oldApp) {
-                oldApp.unmount();
             }
         }
         this.app = app;
@@ -97,10 +135,19 @@ export class MicroApp {
 
     public destroy() {
         this.app?.unmount();
+        this._clearRoot();
         this.app = null;
-        this.root?.remove();
         this.root = null;
         this._factory = null;
         this.destroyed = true;
     }
+
+    private _clearRoot(): void {
+        if (!this.root) {
+            return;
+        }
+        Array.from(this.root.childNodes).forEach((child) => {
+            child.remove();
+        });
+    }
 }

package/src/options.ts

@@ -64,7 +64,7 @@ export function parsedOptions(
     const compiledRoutes = createRouteMatches(routes);
     return Object.freeze<RouterParsedOptions>({
         rootStyle: options.rootStyle || false,
-        root: options.root || '',
+        appId: options.appId || 'app',
         context: options.context || {},
         data: options.data || {},
         req: options.req || null,
@@ -86,7 +86,8 @@ export function parsedOptions(
         fallback: options.fallback ?? fallback,
         nextTick: options.nextTick ?? (() => {}),
         handleBackBoundary: options.handleBackBoundary ?? (() => {}),
-        handleLayerClose: options.handleLayerClose ?? (() => {})
+        handleLayerClose: options.handleLayerClose ?? (() => {}),
+        resolveLink: options.resolveLink ?? ((link) => link)
     });
 }
 

package/src/router-link.ts

@@ -224,15 +224,18 @@ export function createLinkResolver(
 
     const navigate = createNavigateFunction(router, props, type);
 
-    return {
-        route,
-        type,
-        isActive,
-        isExactActive,
-        isExternal,
-        tag: props.tag || 'a',
-        attributes,
-        navigate,
-        createEventHandlers
-    };
+    return router.parsedOptions.resolveLink(
+        {
+            route,
+            type,
+            isActive,
+            isExactActive,
+            isExternal,
+            tag: props.tag || 'a',
+            attributes,
+            navigate,
+            createEventHandlers
+        },
+        props
+    );
 }

package/src/router.ts

@@ -19,7 +19,20 @@ import type {
     RouteState
 } from './types';
 import { RouterMode, RouteType } from './types';
-import { isNotNullish, isPlainObject, isRouteMatched } from './util';
+import {
+    isNotNullish,
+    isPlainObject,
+    isRouteMatched,
+    validateSsrRootElement
+} from './util';
+
+const LAYER_SKIP_TYPES = new Set([
+    RouteType.pushWindow,
+    RouteType.replaceWindow,
+    RouteType.replace,
+    RouteType.restartApp,
+    RouteType.pushLayer
+]);
 
 export class Router {
     public readonly options: RouterOptions;
@@ -47,8 +60,8 @@ export class Router {
         return this.parsedOptions.data;
     }
 
-    public get root() {
-        return this.parsedOptions.root;
+    public get appId() {
+        return this.parsedOptions.appId;
     }
     public get mode(): RouterMode {
         return this.parsedOptions.mode;
@@ -266,7 +279,7 @@ export class Router {
             ...this.options,
             context: this.parsedOptions.context,
             mode: RouterMode.memory,
-            root: undefined,
+            appId: undefined,
             ...layerOptions.routerOptions,
             handleBackBoundary(router) {
                 router.destroy();
@@ -295,16 +308,7 @@ export class Router {
         const initRoute = await router.replace(toInput);
 
         router.afterEach(async (to, from) => {
-            if (
-                [
-                    RouteType.pushWindow,
-                    RouteType.replaceWindow,
-                    RouteType.replace,
-                    RouteType.restartApp,
-                    RouteType.pushLayer
-                ].includes(to.type)
-            )
-                return;
+            if (LAYER_SKIP_TYPES.has(to.type)) return;
             let keepAlive = false;
             if (layerOptions.keepAlive === 'exact') {
                 keepAlive = to.path === initRoute.path;
@@ -372,10 +376,16 @@ export class Router {
     public async renderToString(throwError = false): Promise<string | null> {
         try {
             const result = await this.microApp.app?.renderToString?.();
-            return result ?? null;
+            const trimmed = result?.trim();
+            const hasContent = trimmed && trimmed.length > 0;
+            if (hasContent && process.env.NODE_ENV !== 'production') {
+                validateSsrRootElement(trimmed);
+            }
+            const ssrAttr = hasContent ? ' data-ssr' : '';
+            return `<div id="${this.appId}"${ssrAttr}>${result ?? ''}</div>`;
         } catch (e) {
             if (throwError) throw e;
-            else console.error(e);
+            else console.error('[@esmx/router] SSR render failed:', e);
             return null;
         }
     }

package/src/types.ts

@@ -280,6 +280,7 @@ export type RouterLayerOptions = Omit<
 // ============================================================================
 export interface RouterMicroAppOptions {
     mount: (el: HTMLElement) => void;
+    hydration?: (el: HTMLElement) => void;
     unmount: () => void;
     renderToString?: () => Awaitable<string>;
 }
@@ -295,28 +296,18 @@ export type RouterMicroApp =
 // ============================================================================
 export interface RouterOptions {
     /**
-     * Application mounting container
-     * - Can be a DOM selector string (e.g., '#app', '.container', '[data-mount]')
-     * - Can be an HTMLElement object
-     * - Defaults to '#root'
+     * Application mount container ID
+     * - Pure string ID, no '#' prefix needed
+     * - Client-side: uses document.getElementById(appId)
+     * - Server-side: generates <div id="${appId}"> wrapper
+     * - Defaults to 'app'
      *
      * @example
      * ```typescript
-     * // Using ID selector
-     * new Router({ root: '#my-app' })
-     *
-     * // Using class selector
-     * new Router({ root: '.app-container' })
-     *
-     * // Using attribute selector
-     * new Router({ root: '[data-router-mount]' })
-     *
-     * // Passing DOM element directly
-     * const element = document.getElementById('app');
-     * new Router({ root: element })
+     * new Router({ appId: 'app' })
      * ```
      */
-    root?: string | HTMLElement;
+    appId?: string;
     context?: Record<string | symbol, unknown>;
     data?: Record<string | symbol, unknown>;
     routes?: RouteConfig[];
@@ -335,6 +326,10 @@ export interface RouterOptions {
     zIndex?: number;
     handleBackBoundary?: (router: Router) => void;
     handleLayerClose?: (router: Router, data?: any) => void;
+    resolveLink?: (
+        link: RouterLinkResolved,
+        props: RouterLinkProps
+    ) => RouterLinkResolved;
 }
 
 export interface RouterParsedOptions extends Readonly<Required<RouterOptions>> {

package/src/util.ts

@@ -71,7 +71,11 @@ export function isUrlEqual(url1: URL, url2?: URL | null): boolean {
     // Copy and sort query parameters
     (url1 = new URL(url1)).searchParams.sort();
     (url2 = new URL(url2)).searchParams.sort();
-    // Avoid trailing hash symbol impact from empty hash
+    // Normalize trailing empty hash:
+    // new URL('https://a.com/path#').href includes a trailing '#',
+    // but new URL('https://a.com/path').href does not.
+    // Assigning hash to itself triggers the setter to re-normalize the URL,
+    // ensuring both forms produce the same href.
     url1.hash = url1.hash;
     url2.hash = url2.hash;
     return url1.href === url2.href;
@@ -131,3 +135,50 @@ export function decodeParams<T extends Record<string, string | string[]>>(
 
     return result;
 }
+
+/**
+ * Validates that SSR renderToString output contains exactly one root HTML element.
+ * Non-production only - throws if validation fails.
+ */
+export function validateSsrRootElement(html: string): void {
+    const trimmed = html.trim();
+    const firstMatch = trimmed.match(/^<([a-zA-Z][^\s>]*)/);
+    const firstTag = firstMatch?.[1];
+    const lastTag = trimmed.match(/<\/([a-zA-Z][^\s>]*)>\s*$/)?.[1];
+    if (!firstTag || firstTag !== lastTag) {
+        throw new Error(
+            'SSR renderToString() must return exactly one root HTML element. ' +
+                'Current output: ' +
+                trimmed.slice(0, 100)
+        );
+    }
+    // Find the ROOT element's matching close tag by depth-counting occurrences
+    // of the root tag, so a single root that nests same-tag children (e.g. a
+    // `<div>` wrapping child `<div>`s — very common) is not mistaken for
+    // multiple roots. A naive "first `</tag>`" scan matches an inner close and
+    // wrongly reports trailing content. Anything after the matched root close is
+    // a sibling root → invalid.
+    const tagRe = new RegExp(`<(/?)${firstTag}(?:\\s[^>]*)?(/?)>`, 'g');
+    let depth = 0;
+    let rootCloseEnd = -1;
+    let tag: RegExpExecArray | null = tagRe.exec(trimmed);
+    while (tag !== null) {
+        if (tag[1] === '/') {
+            depth--;
+            if (depth === 0) {
+                rootCloseEnd = tagRe.lastIndex;
+                break;
+            }
+        } else if (tag[2] !== '/') {
+            depth++;
+        }
+        tag = tagRe.exec(trimmed);
+    }
+    if (rootCloseEnd === -1 || trimmed.slice(rootCloseEnd).trim().length > 0) {
+        throw new Error(
+            'SSR renderToString() must return exactly one root HTML element. ' +
+                'Current output: ' +
+                trimmed.slice(0, 100)
+        );
+    }
+}