@viewfly/router 3.0.0-alpha.8 → 3.0.0

package/dist/index.esm.js

@@ -1,14 +1,39 @@
-import { Injectable, comparePropsWithCallbacks, createContext, inject, internalWrite, jsx, makeError, onUnmounted, reactive, readonlyProxyHandler, shallowReactive } from "@viewfly/core";
-import { Subject, Subscription, fromEvent } from "@tanbo/stream";
+import { Injectable, InjectionToken, comparePropsWithCallbacks, createContext, inject, internalWrite, jsx, makeError, onUnmounted, reactive, readonlyProxyHandler, shallowReactive, watch } from "@viewfly/core";
+import { Subject, Subscription, fromEvent, microTask } from "@tanbo/stream";
 //#region src/providers/router.ts
 var routerErrorFn$1 = makeError("Router");
-var Router = class {
+/** 与 matchRoute 的 pathname 参数同粒度比较（去掉首尾 `/`） */
+function normalizeRoutePathSegment(path) {
+	return path.replace(/^\/+|\/+$/g, "") || "";
+}
+var Router = class Router {
 	onRefresh;
+	lastResolvedParams = null;
+	/** 当前重定向链上已解析过的 path 段（规范化后）；非重定向成功匹配后清空 */
+	redirectTrail = null;
+	static maxRedirectHops = 32;
+	/** 当前层最近一次匹配所消费的 URL 段数（默认 1，保持历史行为） */
+	consumedSegments = 1;
+	routeParams = {};
+	/**
+	* 本次 `resolve` 命中的 `route.path` 上的动态段（供子 Router、`canActivate`、`redirectTo`）。
+	* 与 `params` 按层隔离（对齐 Angular）：有 `parent` 时 `params` 只表示本层注入域，不由子级匹配覆盖。
+	*/
+	lastResolvePathParams = {};
 	get deep() {
-		return this.parent ? this.parent.deep + 1 : 0;
+		return this.parent ? this.parent.deep + this.parent.consumedSegments : 0;
+	}
+	get remainingPaths() {
+		return this.navigator.urlTree.paths.slice(this.deep);
 	}
 	get path() {
-		return this.navigator.urlTree.paths.at(this.deep) || "";
+		return this.remainingPaths[0] || "";
+	}
+	get params() {
+		return this.routeParams;
+	}
+	setParams(params) {
+		this.routeParams = { ...params };
 	}
 	refreshEvent = new Subject();
 	constructor(navigator, parent) {
@@ -16,17 +41,17 @@ var Router = class {
 		this.parent = parent;
 		this.onRefresh = this.refreshEvent.asObservable();
 	}
-	navigateTo(path, params, fragment) {
-		this.navigator.to(path, this, params, fragment || void 0);
+	navigateTo(path, queryParams, hash) {
+		this.navigator.to(path, this, queryParams, hash);
 	}
-	replaceTo(path, params) {
-		this.navigator.replace(path, this, params);
+	replaceTo(path, queryParams, hash) {
+		this.navigator.replace(path, this, queryParams, hash);
 	}
 	refresh() {
 		this.refreshEvent.next();
 	}
-	consumeConfig(routes) {
-		return this.matchRoute(routes, this.path);
+	resolve(routes) {
+		return this.matchRoute(routes, this.remainingPaths);
 	}
 	back() {
 		this.navigator.back();
@@ -37,35 +62,217 @@ var Router = class {
 	go(offset) {
 		this.navigator.go(offset);
 	}
-	matchRoute(configs, pathname) {
-		let matchedConfig = null;
-		let defaultConfig = null;
-		let fallbackConfig = null;
-		for (const item of configs) if (item.path === pathname) {
-			matchedConfig = item;
-			break;
-		} else if (item.path === "*") {
-			if (!fallbackConfig) fallbackConfig = item;
-		} else if (item.path === "") {
-			if (!defaultConfig) defaultConfig = item;
+	clearRedirectTrail() {
+		this.redirectTrail = null;
+	}
+	getNavigatorParams() {
+		const pathname = "/" + this.navigator.urlTree.paths.join("/");
+		return {
+			pathname: pathname === "/" ? pathname : pathname.replace(/\/+/g, "/"),
+			queryParams: this.navigator.urlTree.queryParams,
+			hash: this.navigator.urlTree.hash
+		};
+	}
+	cloneNavigatorParams(params) {
+		return {
+			pathname: params.pathname,
+			queryParams: { ...params.queryParams },
+			hash: params.hash
+		};
+	}
+	beginRedirectResolution(pathname) {
+		const key = normalizeRoutePathSegment(pathname);
+		if (this.redirectTrail === null) this.redirectTrail = /* @__PURE__ */ new Set();
+		if (this.redirectTrail.size >= Router.maxRedirectHops) {
+			const chain = [...this.redirectTrail].join(" -> ");
+			this.clearRedirectTrail();
+			throw routerErrorFn$1(`Redirect chain exceeded ${Router.maxRedirectHops} hops (last segment: '${pathname}', chain: ${chain})`);
+		}
+		this.redirectTrail.add(key);
+	}
+	assertRedirectTarget(pathname, target) {
+		const cur = normalizeRoutePathSegment(pathname);
+		const next = normalizeRoutePathSegment(target);
+		if (next === cur) {
+			this.clearRedirectTrail();
+			throw routerErrorFn$1(`Self-redirect at '${pathname}' (redirect target equals current path)`);
 		}
-		const config = matchedConfig || defaultConfig || fallbackConfig;
-		if (!config) return config;
-		if (typeof config.redirectTo === "function") {
-			const p = config.redirectTo(pathname);
-			if (typeof p === "string") this.navigateTo(p);
-			else if (typeof p === "object") this.navigateTo(p.pathname, p.queryParams, p.fragment);
-			else throw routerErrorFn$1(`Router redirect to '${pathname}' not supported`);
+		if (this.redirectTrail.has(next)) {
+			const chain = `${[...this.redirectTrail].join(" -> ")} -> ${next}`;
+			this.clearRedirectTrail();
+			throw routerErrorFn$1(`Redirect cycle detected (chain: ${chain})`);
+		}
+	}
+	splitRoutePath(path) {
+		const normalized = normalizeRoutePathSegment(path);
+		return normalized ? normalized.split("/") : [];
+	}
+	/** 单段路由：`user` | `:id` | `:id?`（`?` 仅表示可选；整条 path 里 `:…?` 只允许出现在最后一段，由 matchRoutePath 校验） */
+	parseRouteSegment(segment) {
+		if (!segment) return null;
+		if (segment.startsWith(":")) {
+			const optionalMatch = /^:([^:?]+)\?$/.exec(segment);
+			if (optionalMatch) {
+				const name = optionalMatch[1];
+				return name ? {
+					kind: "param",
+					name,
+					optional: true
+				} : null;
+			}
+			const name = segment.slice(1);
+			if (!name || name.includes("?")) return null;
+			return {
+				kind: "param",
+				name,
+				optional: false
+			};
+		}
+		return {
+			kind: "static",
+			value: segment
+		};
+	}
+	matchRoutePath(routePath, remainingPaths) {
+		if (!routePath || routePath === "*") return null;
+		const rawSegments = this.splitRoutePath(routePath);
+		const segments = [];
+		for (const s of rawSegments) {
+			const parsed = this.parseRouteSegment(s);
+			if (!parsed) {
+				if (s.startsWith(":")) throw routerErrorFn$1(`Empty or invalid path parameter segment '${s}' in '${routePath}' (use ':name' with a non-empty name).`);
+				return null;
+			}
+			segments.push(parsed);
+		}
+		for (let i = 0; i < segments.length; i++) {
+			const s = segments[i];
+			if (s.kind === "param" && s.optional && i !== segments.length - 1) throw routerErrorFn$1(`Optional path parameter ':${s.name}?' must be the last segment of '${routePath}' (optional params are only allowed at the end of the path).`);
+		}
+		const seenParamNames = /* @__PURE__ */ new Set();
+		for (const s of segments) if (s.kind === "param") {
+			if (seenParamNames.has(s.name)) throw routerErrorFn$1(`Duplicate path parameter ':${s.name}' in '${routePath}' (each name must appear at most once).`);
+			seenParamNames.add(s.name);
+		}
+		const urlLen = remainingPaths.length;
+		let ui = 0;
+		const pathParams = {};
+		for (let ri = 0; ri < segments.length; ri++) {
+			const seg = segments[ri];
+			if (seg.kind === "static") {
+				if (ui >= urlLen || remainingPaths[ui] !== seg.value) return null;
+				ui++;
+				continue;
+			}
+			if (!seg.optional) {
+				if (ui >= urlLen) return null;
+				pathParams[seg.name] = remainingPaths[ui];
+				ui++;
+				continue;
+			}
+			if (ui >= urlLen) {
+				pathParams[seg.name] = "";
+				continue;
+			}
+			pathParams[seg.name] = remainingPaths[ui];
+			ui++;
+		}
+		return {
+			consumedSegments: ui,
+			params: pathParams
+		};
+	}
+	matchRoute(routes, remainingPaths) {
+		this.lastResolvePathParams = {};
+		const pathname = remainingPaths[0] || "";
+		this.beginRedirectResolution(pathname);
+		let matchedRoute = null;
+		let matchedRouteResult = null;
+		let defaultRoute = null;
+		let fallbackRoute = null;
+		for (const item of routes) {
+			const matchResult = this.matchRoutePath(item.path, remainingPaths);
+			if (matchResult) {
+				matchedRoute = item;
+				matchedRouteResult = matchResult;
+				break;
+			} else if (item.path === "*") {
+				if (!fallbackRoute) fallbackRoute = item;
+			} else if (item.path === "") {
+				if (!defaultRoute) defaultRoute = item;
+			}
+		}
+		const route = matchedRoute || defaultRoute || fallbackRoute;
+		if (!route) {
+			this.consumedSegments = 0;
+			this.routeParams = {};
+			this.lastResolvePathParams = {};
+			this.clearRedirectTrail();
+			this.lastResolvedParams = this.cloneNavigatorParams(this.getNavigatorParams());
+			return route;
+		}
+		if (route === defaultRoute) {
+			this.consumedSegments = 0;
+			this.routeParams = {};
+			this.lastResolvePathParams = {};
+		} else if (route === matchedRoute && matchedRouteResult) {
+			this.consumedSegments = matchedRouteResult.consumedSegments;
+			this.lastResolvePathParams = { ...matchedRouteResult.params };
+			if (this.parent === null) this.routeParams = { ...matchedRouteResult.params };
+		} else {
+			this.consumedSegments = remainingPaths.length > 0 ? 1 : 0;
+			this.routeParams = {};
+			this.lastResolvePathParams = {};
+		}
+		if (typeof route.redirectTo === "function") {
+			const to = this.cloneNavigatorParams(this.getNavigatorParams());
+			const from = this.lastResolvedParams ? this.cloneNavigatorParams(this.lastResolvedParams) : null;
+			const p = route.redirectTo({
+				to,
+				from,
+				router: this,
+				params: this.lastResolvePathParams
+			});
+			if (typeof p === "string") {
+				this.assertRedirectTarget(pathname, p);
+				this.navigateTo(p);
+			} else if (typeof p === "object") {
+				this.assertRedirectTarget(pathname, p.pathname);
+				this.navigateTo(p.pathname, p.queryParams, p.hash);
+			} else {
+				this.clearRedirectTrail();
+				throw routerErrorFn$1(`Router redirect to '${pathname}' not supported`);
+			}
 			return null;
 		}
-		if (typeof config.redirectTo === "string") {
-			this.navigateTo(config.redirectTo);
+		if (typeof route.redirectTo === "string") {
+			this.assertRedirectTarget(pathname, route.redirectTo);
+			this.navigateTo(route.redirectTo);
 			return null;
 		}
-		return config;
+		this.clearRedirectTrail();
+		this.lastResolvedParams = this.cloneNavigatorParams(this.getNavigatorParams());
+		return route;
 	}
 };
 //#endregion
+//#region src/providers/query-encoding.ts
+/** 查询串组件：写入 URL 时 encode，从 URL 解析出对象时 decode（与常见路由约定一致）。 */
+function encodeQueryParamComponent(value) {
+	try {
+		return encodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function decodeQueryParamComponent(value) {
+	try {
+		return decodeURIComponent(value.replace(/\+/g, " "));
+	} catch {
+		return value;
+	}
+}
+//#endregion
 //#region src/providers/url-parser.ts
 var UrlParser = class {
 	index = 0;
@@ -84,7 +291,7 @@ var UrlParser = class {
 				this.index++;
 				this.tokens.push({
 					type: "query",
-					params: this.readQuery()
+					queryParams: this.readQuery()
 				});
 			} else if (this.peek("#")) {
 				this.index++;
@@ -114,7 +321,7 @@ var UrlParser = class {
 				urlTree.paths.push(item.value);
 				break;
 			case "query":
-				urlTree.queryParams = item.params;
+				urlTree.queryParams = item.queryParams;
 				break;
 			case "hash": urlTree.hash = item.value;
 		}
@@ -128,11 +335,11 @@ var UrlParser = class {
 	readQuery() {
 		const query = {};
 		while (this.index < this.url.length) {
-			const key = this.readQueryKey();
+			const key = decodeQueryParamComponent(this.readQueryKey());
 			let value = "";
 			if (this.peek("=")) {
 				this.index++;
-				value = this.readQueryValue();
+				value = decodeQueryParamComponent(this.readQueryValue());
 			}
 			const oldValue = query[key];
 			if (oldValue) if (Array.isArray(oldValue)) oldValue.push(value);
@@ -215,33 +422,33 @@ var Navigator = class {
 };
 function formatUrl(pathname, urlFormatParams) {
 	pathname = pathname.replace(/\/+/g, "/");
-	const { queryParams, fragment } = urlFormatParams;
-	return pathname + (queryParams ? "?" + formatQueryParams(queryParams) : "") + (fragment ? "#" + fragment : "");
+	const { queryParams, hash } = urlFormatParams;
+	return pathname + (queryParams ? "?" + formatQueryParams(queryParams) : "") + (hash !== void 0 && hash !== null ? "#" + hash : "");
 }
 function formatQueryParams(queryParams) {
 	const params = [];
 	Object.keys(queryParams).forEach((key) => {
+		const encKey = encodeQueryParamComponent(key);
 		const values = queryParams[key];
 		if (Array.isArray(values)) values.forEach((i) => {
-			params.push(`${key}=${decodeURIComponent(i)}`);
+			params.push(`${encKey}=${encodeQueryParamComponent(i)}`);
 		});
-		else params.push(`${key}=${decodeURIComponent(values)}`);
+		else params.push(`${encKey}=${encodeQueryParamComponent(values)}`);
 	});
 	return params.join("&");
 }
 var BrowserNavigator = class BrowserNavigator extends Navigator {
 	onUrlChanged;
+	pendingNavigation = null;
 	/** 挂载在 location 上的路径前缀；'' 或 '/' 表示站点根，不做剥离 */
 	get basePathPrefix() {
 		return this.baseUrl === "/" || this.baseUrl === "" ? "" : this.baseUrl;
 	}
 	get pathname() {
-		const pathname = location.pathname;
-		if (!this.basePathPrefix) return pathname;
-		return pathname.startsWith(this.basePathPrefix) ? pathname.substring(this.basePathPrefix.length) : pathname;
+		return this.stripBaseFromLocationPathname(location.pathname);
 	}
 	urlParser = new UrlParser();
-	urlTree = this.getUrlTree();
+	urlTree = this.readUrlTreeFromLocation();
 	urlChangeEvent = new Subject();
 	subscription = new Subscription();
 	constructor(baseUrl, hooks = {}) {
@@ -249,51 +456,62 @@ var BrowserNavigator = class BrowserNavigator extends Navigator {
 		this.hooks = hooks;
 		this.onUrlChanged = this.urlChangeEvent.asObservable();
 		this.subscription.add(fromEvent(window, "popstate").subscribe(() => {
-			this.urlTree = this.getUrlTree();
+			this.urlTree = this.readUrlTreeFromLocation();
 			this.urlChangeEvent.next();
 		}));
-		if (this.basePathPrefix && !location.pathname.startsWith(this.basePathPrefix)) history.replaceState(null, "", this.baseUrl);
+		if (this.basePathPrefix && !location.pathname.startsWith(this.basePathPrefix)) {
+			history.replaceState(null, "", this.baseUrl);
+			this.urlTree = this.readUrlTreeFromHistoryHref(this.baseUrl);
+		}
 	}
-	to(pathName, relative, queryParams, fragment) {
-		const url = this.join(pathName, relative, queryParams, fragment);
+	to(pathName, relative, queryParams, hash) {
+		const url = this.join(pathName, relative, queryParams, hash);
 		if (location.origin + url === location.href) return true;
 		this.runHooks({
 			pathname: this.pathname,
 			queryParams: this.urlTree.queryParams,
-			fragment: this.urlTree.hash
+			hash: this.urlTree.hash
 		}, {
 			pathname: pathName,
 			queryParams: queryParams || {},
-			fragment: fragment || null
+			hash: hash ?? null
 		}, () => {
+			this.pendingNavigation = {
+				type: "push",
+				from: this.getCurrentUrl()
+			};
 			history.pushState(null, "", url);
-			this.urlTree = this.getUrlTree();
+			this.urlTree = this.readUrlTreeFromHistoryHref(url);
 			this.urlChangeEvent.next();
 		});
 		return true;
 	}
-	replace(pathName, relative, queryParams, fragment) {
-		const url = this.join(pathName, relative, queryParams, fragment);
+	replace(pathName, relative, queryParams, hash) {
+		const url = this.join(pathName, relative, queryParams, hash);
 		if (location.origin + url === location.href) return true;
 		this.runHooks({
 			pathname: this.pathname,
 			queryParams: this.urlTree.queryParams,
-			fragment: this.urlTree.hash
+			hash: this.urlTree.hash
 		}, {
 			pathname: pathName,
 			queryParams: queryParams || {},
-			fragment: fragment || null
+			hash: hash ?? null
 		}, () => {
+			this.pendingNavigation = {
+				type: "replace",
+				from: this.getCurrentUrl()
+			};
 			history.replaceState(null, "", url);
-			this.urlTree = this.getUrlTree();
+			this.urlTree = this.readUrlTreeFromHistoryHref(url);
 			this.urlChangeEvent.next();
 		});
 		return true;
 	}
-	join(pathname, relative, queryParams, fragment) {
+	join(pathname, relative, queryParams, hash) {
 		if (pathname.startsWith("/")) return formatUrl(this.baseUrl + pathname, {
 			queryParams,
-			fragment
+			hash
 		});
 		const beforePath = this.urlTree.paths.slice(0, relative.deep);
 		while (true) {
@@ -308,9 +526,11 @@ var BrowserNavigator = class BrowserNavigator extends Navigator {
 			}
 			break;
 		}
-		return formatUrl(this.baseUrl + "/" + beforePath.join("/") + "/" + pathname, {
+		const tail = [...beforePath, pathname].join("/");
+		const base = this.baseUrl.replace(/\/+$/, "");
+		return formatUrl((base ? `${base}/${tail}` : `/${tail}`).replace(/\/+/g, "/"), {
 			queryParams,
-			fragment
+			hash
 		});
 	}
 	back() {
@@ -322,22 +542,64 @@ var BrowserNavigator = class BrowserNavigator extends Navigator {
 	go(offset) {
 		history.go(offset);
 	}
+	confirmNavigation() {
+		this.pendingNavigation = null;
+	}
+	cancelNavigation() {
+		const pending = this.pendingNavigation;
+		this.pendingNavigation = null;
+		if (!pending) return;
+		if (pending.type === "push") {
+			history.back();
+			return;
+		}
+		history.replaceState(null, "", pending.from);
+		this.urlTree = this.readUrlTreeFromHistoryHref(pending.from);
+		this.urlChangeEvent.next();
+	}
 	destroy() {
 		this.subscription.unsubscribe();
 	}
 	runHooks(beforeParams, currentParams, next) {
-		if (typeof this.hooks.beforeEach === "function") this.hooks.beforeEach?.(beforeParams, currentParams, () => {
-			next();
-			this.hooks.afterEach?.(currentParams);
-		});
-		else {
+		if (typeof this.hooks.beforeEach === "function") {
+			let called = false;
+			let warningTimer = null;
+			const proceed = () => {
+				if (called) return;
+				called = true;
+				if (warningTimer) clearTimeout(warningTimer);
+				next();
+				this.hooks.afterEach?.(currentParams);
+			};
+			this.hooks.beforeEach?.(beforeParams, currentParams, proceed);
+			const env = globalThis?.process?.env;
+			if (!(env?.env === "production" || env?.NODE_ENV === "production") && !called) warningTimer = setTimeout(() => {
+				if (!called) console.warn("[Viewfly Router] NavigatorHooks.beforeEach did not call next(); navigation remains pending.");
+			}, 300);
+		} else {
 			next();
 			this.hooks.afterEach?.(currentParams);
 		}
 	}
-	getUrlTree() {
+	stripBaseFromLocationPathname(fullPathname) {
+		if (!this.basePathPrefix) return fullPathname;
+		return fullPathname.startsWith(this.basePathPrefix) ? fullPathname.substring(this.basePathPrefix.length) : fullPathname;
+	}
+	/**
+	* 按与 `history.pushState` / `replaceState` 写入会话的 URL 解析 urlTree（与传入 `join` 的相对路径一致）。
+	* History 更新后若仍仅从 `Location` 读路径，可能与实际会话 URL 不一致（如 Location 与 document 的同步时序、部分宿主环境）。
+	*/
+	readUrlTreeFromHistoryHref(hrefRelativeToOrigin) {
+		const abs = new URL(hrefRelativeToOrigin, location.origin);
+		const logicalPathname = this.stripBaseFromLocationPathname(abs.pathname);
+		return this.urlParser.parse(`${logicalPathname}${abs.search}${abs.hash}`);
+	}
+	readUrlTreeFromLocation() {
 		return this.urlParser.parse(this.pathname + location.search + location.hash);
 	}
+	getCurrentUrl() {
+		return location.pathname + location.search + location.hash;
+	}
 };
 BrowserNavigator = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [String, Object])], BrowserNavigator);
 //#endregion
@@ -368,12 +630,68 @@ function useQueryParams() {
 	return queryParams;
 }
 //#endregion
+//#region src/hooks/use-params.ts
+function useParams() {
+	const router = inject(Router);
+	const pathParams = { ...router.params };
+	const readonlyParams = new Proxy(pathParams, readonlyProxyHandler);
+	const subscription = router.onRefresh.subscribe(() => {
+		comparePropsWithCallbacks(pathParams, router.params, (key) => {
+			internalWrite(() => {
+				Reflect.deleteProperty(pathParams, key);
+			});
+		}, (key, value) => {
+			internalWrite(() => {
+				pathParams[key] = value;
+			});
+		}, (key, value) => {
+			internalWrite(() => {
+				pathParams[key] = value;
+			});
+		});
+	});
+	onUnmounted(() => {
+		subscription.unsubscribe();
+	});
+	return readonlyParams;
+}
+//#endregion
+//#region src/providers/routes.ts
+var Routes = new InjectionToken("Routes");
+//#endregion
 //#region src/link.tsx
 function Link(props) {
 	const navigator = inject(Navigator);
 	const router = inject(Router);
+	function buildDomAttrs() {
+		const attrs = {};
+		Object.keys(props).forEach((key) => {
+			switch (key) {
+				case "to":
+				case "active":
+				case "exact":
+				case "queryParams":
+				case "hash":
+				case "tag":
+				case "children": return;
+				default: attrs[key] = props[key];
+			}
+		});
+		return attrs;
+	}
+	function normalizePathname(path) {
+		const pathname = (path.split("#")[0].split("?")[0] || "/").replace(/\/+$/, "") || "/";
+		const baseUrl = navigator.baseUrl === "/" || navigator.baseUrl === "" ? "" : navigator.baseUrl;
+		if (!baseUrl) return pathname;
+		const base = baseUrl.replace(/\/+$/, "") || "/";
+		if (pathname === base) return "/";
+		if (pathname.startsWith(base + "/")) return pathname.substring(base.length);
+		return pathname;
+	}
 	function getActive() {
-		return props.exact ? navigator.pathname === navigator.join(props.to, router) || navigator.pathname + "/" === navigator.join(props.to, router) : navigator.pathname.startsWith(navigator.join(props.to, router));
+		const currentPathname = normalizePathname(navigator.pathname);
+		const targetPathname = normalizePathname(navigator.join(props.to, router));
+		return props.exact ? currentPathname === targetPathname : currentPathname === targetPathname || currentPathname.startsWith(targetPathname + "/");
 	}
 	const isActive = reactive({ value: getActive() });
 	const subscription = navigator.onUrlChanged.subscribe(() => {
@@ -382,21 +700,27 @@ function Link(props) {
 	onUnmounted(() => {
 		subscription.unsubscribe();
 	});
+	/** 仅左键且无修饰键时由 SPA 接管，其余交给浏览器（新标签、下载默认等） */
+	function shouldHandleSpaClick(ev) {
+		if (ev.button !== 0) return false;
+		if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return false;
+		return true;
+	}
 	function navigate(ev) {
-		if ((!props.tag || props.tag === "a") && props.target === "_blank") return;
-		ev.preventDefault();
-		router.navigateTo(props.to, props.queryParams, props.fragment);
+		const isAnchorTag = !props.tag || props.tag === "a";
+		if (isAnchorTag && props.target === "_blank") return;
+		if (isAnchorTag && ev.cancelable) ev.preventDefault();
+		router.navigateTo(props.to, props.queryParams, props.hash);
 	}
 	return () => {
 		const Tag = props.tag || "a";
-		const attrs = Object.assign({}, props, {
-			onClick(ev) {
-				navigate(ev);
-				props.onClick?.(ev);
-			},
-			...props
-		});
-		if (Tag === "a") attrs.href = navigator.join(props.to, router, props.queryParams, props.fragment);
+		const attrs = Object.assign(buildDomAttrs(), { onClick(ev) {
+			props.onClick?.(ev);
+			if (ev.defaultPrevented) return;
+			if (!shouldHandleSpaClick(ev)) return;
+			navigate(ev);
+		} });
+		if (Tag === "a") attrs.href = navigator.join(props.to, router, props.queryParams, props.hash);
 		if (isActive.value && props.active) attrs.class = [attrs.class, props.active];
 		return /* @__PURE__ */ jsx(Tag, {
 			...attrs,
@@ -409,9 +733,9 @@ function Link(props) {
 var RouterModule = class {
 	subscription = new Subscription();
 	navigator;
-	constructor(baseUrl = "", hooks = {}) {
-		this.baseUrl = baseUrl;
-		this.navigator = new BrowserNavigator(this.baseUrl, hooks);
+	constructor(config) {
+		this.config = config;
+		this.navigator = new BrowserNavigator(config.baseUrl || "", config.hooks);
 	}
 	setup(app) {
 		const navigator = this.navigator;
@@ -419,13 +743,20 @@ var RouterModule = class {
 		this.subscription.add(navigator.onUrlChanged.subscribe(() => {
 			router.refresh();
 		}));
-		app.provide([{
-			provide: Navigator,
-			useValue: navigator
-		}, {
-			provide: Router,
-			useValue: router
-		}]);
+		app.provide([
+			{
+				provide: Navigator,
+				useValue: navigator
+			},
+			{
+				provide: Router,
+				useValue: router
+			},
+			{
+				provide: Routes,
+				useValue: this.config.routes || []
+			}
+		]);
 	}
 	onDestroy() {
 		this.subscription.unsubscribe();
@@ -438,37 +769,127 @@ var routerErrorFn = makeError("RouterOutlet");
 function RouterOutlet(props) {
 	const router = inject(Router, null);
 	if (router === null) throw routerErrorFn("cannot found parent Router.");
-	const childRouter = new Router(inject(Navigator), router);
+	const currentRouter = router;
+	const routes = inject(Routes, []);
+	const navigator = inject(Navigator);
+	const childRouter = new Router(navigator, currentRouter);
 	const Context = createContext([{
 		provide: Router,
 		useValue: childRouter
 	}]);
 	const children = shallowReactive({ value: null });
-	const subscription = router.onRefresh.subscribe(() => {
+	let confirmedParams = null;
+	const subscription = currentRouter.onRefresh.pipe(microTask()).subscribe(() => {
 		updateChildren();
 	});
+	/** 每次 `updateChildren` 调用递增；并发/卸载时旧的一次性任务应放弃写 UI */
+	let navigationGeneration = 0;
 	onUnmounted(() => {
+		navigationGeneration += 1;
 		subscription.unsubscribe();
 	});
-	let currentComponent = null;
+	let activateRoute = null;
+	let activateRouteParamsKey = "";
+	watch(() => props.name, () => {
+		activateRoute = null;
+		updateChildren();
+	});
+	watch(() => props.children, () => {
+		if (activateRoute) return;
+		updateChildren();
+	});
+	function isStaleNavigation(token) {
+		return token !== navigationGeneration;
+	}
+	function getParamsKey(params) {
+		return Object.keys(params).sort().map((key) => `${key}=${params[key]}`).join("&");
+	}
+	function getNavigatorParams() {
+		const pathname = "/" + navigator.urlTree.paths.join("/");
+		return {
+			pathname: pathname === "/" ? pathname : pathname.replace(/\/+/g, "/"),
+			queryParams: navigator.urlTree.queryParams,
+			hash: navigator.urlTree.hash
+		};
+	}
 	async function updateChildren() {
-		const routeConfig = router.consumeConfig(props.config);
-		if (!routeConfig) {
-			currentComponent = null;
+		const token = navigationGeneration += 1;
+		const to = getNavigatorParams();
+		const route = currentRouter.resolve(routes);
+		if (!route) {
+			navigator.confirmNavigation();
+			childRouter.setParams({});
+			confirmedParams = to;
+			activateRoute = null;
+			activateRouteParamsKey = "";
 			children.value = props.children || null;
 			return;
 		}
-		if (typeof routeConfig.beforeEach === "function") {
-			if (!await routeConfig.beforeEach()) return;
+		childRouter.setParams({ ...currentRouter.lastResolvePathParams });
+		if (route === activateRoute && activateRouteParamsKey === getParamsKey(currentRouter.lastResolvePathParams)) {
+			navigator.confirmNavigation();
+			confirmedParams = to;
+			childRouter.refresh();
+			return;
 		}
-		if (routeConfig.component) _updateChildren(routeConfig.component);
-		else if (routeConfig.asyncComponent) _updateChildren(await routeConfig.asyncComponent());
-		if (typeof routeConfig.afterEach === "function") routeConfig.afterEach();
-	}
-	function _updateChildren(Component) {
-		childRouter.refresh();
-		if (Component !== currentComponent) children.value = /* @__PURE__ */ jsx(Component, {});
-		currentComponent = Component;
+		if (typeof route.canActivate === "function") {
+			const ok = await route.canActivate({
+				to,
+				from: confirmedParams,
+				router: childRouter,
+				params: currentRouter.lastResolvePathParams
+			});
+			if (isStaleNavigation(token)) return;
+			if (!ok) {
+				navigator.cancelNavigation();
+				return;
+			}
+		}
+		await applyRoute(route, token);
+		if (isStaleNavigation(token)) return;
+		navigator.confirmNavigation();
+		confirmedParams = to;
+	}
+	async function applyRoute(route, token) {
+		let Component = null;
+		if (props.name) {
+			const namedComponents = route.namedComponents || [];
+			for (const named of namedComponents) if (named.name === props.name) {
+				if (named.component) Component = named.component;
+				else if (typeof named.asyncComponent === "function") {
+					Component = await named.asyncComponent();
+					if (isStaleNavigation(token)) return;
+				}
+				break;
+			}
+		} else if (route.component) Component = route.component;
+		else if (typeof route.asyncComponent === "function") {
+			Component = await route.asyncComponent();
+			if (isStaleNavigation(token)) return;
+			if (!Component) {
+				activateRoute = null;
+				children.value = props.children || null;
+				return;
+			}
+		}
+		if (!Component) Component = RouterOutlet;
+		let subRoutes = [];
+		if (route.path !== "*") {
+			if (Array.isArray(route.children)) subRoutes = route.children;
+			else if (typeof route.children === "function") {
+				subRoutes = await route.children();
+				if (isStaleNavigation(token)) return;
+			}
+		}
+		if (!Array.isArray(subRoutes)) subRoutes = [];
+		const Context = createContext([{
+			provide: Routes,
+			useValue: subRoutes
+		}]);
+		if (isStaleNavigation(token)) return;
+		activateRoute = route;
+		activateRouteParamsKey = getParamsKey(currentRouter.lastResolvePathParams);
+		children.value = /* @__PURE__ */ jsx(Context, { children: /* @__PURE__ */ jsx(Component, {}) });
 	}
 	updateChildren();
 	return () => {
@@ -476,4 +897,4 @@ function RouterOutlet(props) {
 	};
 }
 //#endregion
-export { BrowserNavigator, Link, Navigator, Router, RouterModule, RouterOutlet, UrlParser, formatQueryParams, formatUrl, useQueryParams };
+export { BrowserNavigator, Link, Navigator, Router, RouterModule, RouterOutlet, Routes, UrlParser, formatQueryParams, formatUrl, useParams, useQueryParams };