wevu 6.7.6 → 6.8.0

package/README.md

@@ -14,7 +14,7 @@ Vue 3 风格的小程序运行时，复用同款响应式与调度器，通过
 ## 安装
 
 ```bash
-pnpm add wevu
+pnpm add -D wevu
 # 或 npm/yarn/pnpm dlx 按需安装
 ```
 

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { A as track, C as effect, D as onScopeDispose, E as getCurrentScope, M as triggerEffects, N as nextTick, O as startBatch, P as queueJob, S as batch, T as endBatch, _ as ReactiveFlags, a as toValue, b as addMutationRecorder, c as isRaw, d as reactive, f as isShallowReactive, g as touchReactive, h as prelinkReactiveTree, i as ref, j as trigger, k as stop, l as isReactive, m as clearPatchIndices, n as isRef, o as unref, p as shallowReactive, r as markAsRef, s as getReactiveVersion, t as customRef, u as markRaw, v as isObject$1, w as effectScope, x as removeMutationRecorder, y as toRaw } from "./ref-BjmD-qct.mjs";
 import { i as computed, n as defineStore, r as createStore, t as storeToRefs } from "./store-Ct-o7qtH.mjs";
-import { A as getCurrentInstance, C as onTabItemTap, D as assertInSetup, E as onUnload, F as getMiniProgramGlobalObject, I as getScopedSlotHostGlobalObject, L as readonly, M as pushHook, N as setCurrentInstance, O as callHookList, P as setCurrentSetupContext, S as onShow, T as onUnhandledRejection, _ as onResize, a as onDetached, b as onShareAppMessage, c as onLaunch, d as onMoved, f as onPageNotFound, g as onReady, h as onReachBottom, i as onAttached, j as getCurrentSetupContext, k as callHookReturn, l as onLoad, m as onPullDownRefresh, n as useNativeRouter, o as onError, p as onPageScroll, r as onAddToFavorites, s as onHide, t as useNativePageRouter, u as onMemoryWarning, v as onRouteDone, w as onThemeChange, x as onShareTimeline, y as onSaveExitState } from "./router-CcoGUezU.mjs";
+import { A as onUnload, B as getScopedSlotHostGlobalObject, C as onSaveExitState, D as onTabItemTap, E as onShow, F as getCurrentSetupContext, I as pushHook, L as setCurrentInstance, M as callHookList, N as callHookReturn, O as onThemeChange, P as getCurrentInstance, R as setCurrentSetupContext, S as onRouteDone, T as onShareTimeline, V as readonly, _ as onPageScroll, a as provide, b as onReady, c as onAttached, d as onHide, f as onLaunch, g as onPageNotFound, h as onMoved, i as injectGlobal, j as assertInSetup, k as onUnhandledRejection, l as onDetached, m as onMemoryWarning, n as useNativeRouter, o as provideGlobal, p as onLoad, r as inject, s as onAddToFavorites, t as useNativePageRouter, u as onError, v as onPullDownRefresh, w as onShareAppMessage, x as onResize, y as onReachBottom, z as getMiniProgramGlobalObject } from "./router-BoEmd9rt.mjs";
 //#region src/reactivity/shallowRef.ts
 /**
 * 创建一个“浅层” ref：它只在 .value 被整体替换时触发依赖，不会对内部对象做深层响应式处理。
@@ -4651,87 +4651,6 @@ function usePageScrollThrottle(handler, options = {}) {
 	return stop;
 }
 //#endregion
-//#region src/runtime/provide.ts
-const PROVIDE_SCOPE_KEY = Symbol("wevu.provideScope");
-const __wevuGlobalProvideStore = /* @__PURE__ */ new Map();
-/**
-* 在组件上下文中向后代注入值（与 Vue 3 行为兼容），若没有当前实例则回落到全局存储。
-*
-* @param key 注入键，可为字符串、Symbol 或对象
-* @param value 提供的值
-*
-* @example
-* ```ts
-* defineComponent({
-*   setup() {
-*     provide(TOKEN_KEY, { data: 'value' })
-*   }
-* })
-* ```
-*/
-function provide(key, value) {
-	const instance = getCurrentInstance();
-	if (instance) {
-		let scope = instance[PROVIDE_SCOPE_KEY];
-		if (!scope) {
-			scope = /* @__PURE__ */ new Map();
-			instance[PROVIDE_SCOPE_KEY] = scope;
-		}
-		scope.set(key, value);
-	} else __wevuGlobalProvideStore.set(key, value);
-}
-/**
-* 从祖先组件（或全局存储）读取提供的值。
-*
-* @param key 注入键，需与 provide 使用的键保持一致
-* @param defaultValue 未找到提供者时的默认值
-* @returns 匹配到的值或默认值
-*
-* @example
-* ```ts
-* defineComponent({
-*   setup() {
-*     const data = inject(TOKEN_KEY)
-*     const value = inject('key', 'default')
-*   }
-* })
-* ```
-*/
-function inject(key, defaultValue) {
-	const instance = getCurrentInstance();
-	if (instance) {
-		let current = instance;
-		while (current) {
-			const scope = current[PROVIDE_SCOPE_KEY];
-			if (scope && scope.has(key)) return scope.get(key);
-			current = null;
-		}
-	}
-	if (__wevuGlobalProvideStore.has(key)) return __wevuGlobalProvideStore.get(key);
-	if (arguments.length >= 2) return defaultValue;
-	throw new Error("wevu.inject：未找到对应 key 的值");
-}
-/**
-* 全局注入值，适用于历史兼容场景。
-*
-* @deprecated 已弃用，仅用于兼容/过渡。推荐优先使用 `provide()`，
-* 在无实例上下文时 `provide()` 会自动回落到全局存储。
-*/
-function provideGlobal(key, value) {
-	__wevuGlobalProvideStore.set(key, value);
-}
-/**
-* 从全局存储读取值，适用于历史兼容场景。
-*
-* @deprecated 已弃用，仅用于兼容/过渡。推荐优先使用 `inject()`，
-* 在无实例上下文时 `inject()` 会自动从全局存储读取。
-*/
-function injectGlobal(key, defaultValue) {
-	if (__wevuGlobalProvideStore.has(key)) return __wevuGlobalProvideStore.get(key);
-	if (arguments.length >= 2) return defaultValue;
-	throw new Error(`injectGlobal()：未找到对应 key 的 provider：${String(key)}`);
-}
-//#endregion
 //#region src/runtime/template.ts
 const hyphenateRE = /\B([A-Z])/g;
 function hyphenate(value) {

package/dist/{router-CcoGUezU.mjs → router-BoEmd9rt.mjs}

@@ -262,6 +262,87 @@ function onAddToFavorites(handler) {
 	ensureSinglePageHookOnInstance(instance, "onAddToFavorites");
 }
 //#endregion
+//#region src/runtime/provide.ts
+const PROVIDE_SCOPE_KEY = Symbol("wevu.provideScope");
+const __wevuGlobalProvideStore = /* @__PURE__ */ new Map();
+/**
+* 在组件上下文中向后代注入值（与 Vue 3 行为兼容），若没有当前实例则回落到全局存储。
+*
+* @param key 注入键，可为字符串、Symbol 或对象
+* @param value 提供的值
+*
+* @example
+* ```ts
+* defineComponent({
+*   setup() {
+*     provide(TOKEN_KEY, { data: 'value' })
+*   }
+* })
+* ```
+*/
+function provide(key, value) {
+	const instance = getCurrentInstance();
+	if (instance) {
+		let scope = instance[PROVIDE_SCOPE_KEY];
+		if (!scope) {
+			scope = /* @__PURE__ */ new Map();
+			instance[PROVIDE_SCOPE_KEY] = scope;
+		}
+		scope.set(key, value);
+	} else __wevuGlobalProvideStore.set(key, value);
+}
+/**
+* 从祖先组件（或全局存储）读取提供的值。
+*
+* @param key 注入键，需与 provide 使用的键保持一致
+* @param defaultValue 未找到提供者时的默认值
+* @returns 匹配到的值或默认值
+*
+* @example
+* ```ts
+* defineComponent({
+*   setup() {
+*     const data = inject(TOKEN_KEY)
+*     const value = inject('key', 'default')
+*   }
+* })
+* ```
+*/
+function inject(key, defaultValue) {
+	const instance = getCurrentInstance();
+	if (instance) {
+		let current = instance;
+		while (current) {
+			const scope = current[PROVIDE_SCOPE_KEY];
+			if (scope && scope.has(key)) return scope.get(key);
+			current = null;
+		}
+	}
+	if (__wevuGlobalProvideStore.has(key)) return __wevuGlobalProvideStore.get(key);
+	if (arguments.length >= 2) return defaultValue;
+	throw new Error("wevu.inject：未找到对应 key 的值");
+}
+/**
+* 全局注入值，适用于历史兼容场景。
+*
+* @deprecated 已弃用，仅用于兼容/过渡。推荐优先使用 `provide()`，
+* 在无实例上下文时 `provide()` 会自动回落到全局存储。
+*/
+function provideGlobal(key, value) {
+	__wevuGlobalProvideStore.set(key, value);
+}
+/**
+* 从全局存储读取值，适用于历史兼容场景。
+*
+* @deprecated 已弃用，仅用于兼容/过渡。推荐优先使用 `inject()`，
+* 在无实例上下文时 `inject()` 会自动从全局存储读取。
+*/
+function injectGlobal(key, defaultValue) {
+	if (__wevuGlobalProvideStore.has(key)) return __wevuGlobalProvideStore.get(key);
+	if (arguments.length >= 2) return defaultValue;
+	throw new Error(`injectGlobal()：未找到对应 key 的 provider：${String(key)}`);
+}
+//#endregion
 //#region src/runtime/vueCompat/router.ts
 const RUNTIME_ROUTER_METHODS = [
 	"switchTab",
@@ -326,4 +407,4 @@ function useNativePageRouter() {
 	return useRuntimeRouterByAccessor("pageRouter", "router", "useNativePageRouter");
 }
 //#endregion
-export { getCurrentInstance as A, onTabItemTap as C, assertInSetup as D, onUnload as E, getMiniProgramGlobalObject as F, getScopedSlotHostGlobalObject as I, readonly as L, pushHook as M, setCurrentInstance as N, callHookList as O, setCurrentSetupContext as P, onShow as S, onUnhandledRejection as T, onResize as _, onDetached as a, onShareAppMessage as b, onLaunch as c, onMoved as d, onPageNotFound as f, onReady as g, onReachBottom as h, onAttached as i, getCurrentSetupContext as j, callHookReturn as k, onLoad as l, onPullDownRefresh as m, useNativeRouter as n, onError as o, onPageScroll as p, onAddToFavorites as r, onHide as s, useNativePageRouter as t, onMemoryWarning as u, onRouteDone as v, onThemeChange as w, onShareTimeline as x, onSaveExitState as y };
+export { onUnload as A, getScopedSlotHostGlobalObject as B, onSaveExitState as C, onTabItemTap as D, onShow as E, getCurrentSetupContext as F, pushHook as I, setCurrentInstance as L, callHookList as M, callHookReturn as N, onThemeChange as O, getCurrentInstance as P, setCurrentSetupContext as R, onRouteDone as S, onShareTimeline as T, readonly as V, onPageScroll as _, provide as a, onReady as b, onAttached as c, onHide as d, onLaunch as f, onPageNotFound as g, onMoved as h, injectGlobal as i, assertInSetup as j, onUnhandledRejection as k, onDetached as l, onMemoryWarning as m, useNativeRouter as n, provideGlobal as o, onLoad as p, inject as r, onAddToFavorites as s, useNativePageRouter as t, onError as u, onPullDownRefresh as v, onShareAppMessage as w, onResize as x, onReachBottom as y, getMiniProgramGlobalObject as z };

package/dist/router.d.mts

@@ -27,6 +27,15 @@ interface NamedRouteRecord {
   name: string;
   path: string;
 }
+interface RouteRecordInput {
+  name?: string;
+  path: string;
+  meta?: RouteMeta;
+  alias?: string | readonly string[];
+  children?: readonly RouteRecordInput[];
+  beforeEnter?: NavigationGuard | readonly NavigationGuard[];
+  redirect?: RouteRecordRedirect;
+}
 type NamedRoutes = Readonly<Record<string, string>> | readonly RouteRecordRaw[];
 type RouteLocationRaw = string | {
   path?: string;
@@ -68,12 +77,8 @@ interface NavigationRedirect {
   replace?: boolean;
 }
 type RouteRecordRedirect = RouteLocationRaw | NavigationRedirect | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => RouteLocationRaw | NavigationRedirect | Promise<RouteLocationRaw | NavigationRedirect>);
-interface RouteRecordRaw extends NamedRouteRecord {
-  meta?: RouteMeta;
-  alias?: string | readonly string[];
+interface RouteRecordRaw extends Omit<RouteRecordInput, 'name' | 'children'>, NamedRouteRecord {
   children?: readonly RouteRecordRaw[];
-  beforeEnter?: NavigationGuard | readonly NavigationGuard[];
-  redirect?: RouteRecordRedirect;
 }
 interface RouteRecordMatched {
   name: string;
@@ -121,7 +126,7 @@ interface UseRouterOptions {
   /**
    * Vue Router 对齐入口：推荐使用 `routes`
    */
-  routes?: readonly RouteRecordRaw[];
+  routes?: readonly RouteRecordInput[];
   /**
    * 兼容入口：支持对象 map 或路由记录数组
    */
@@ -165,6 +170,12 @@ interface AddRoute {
   (parentName: string, route: RouteRecordRaw): () => void;
 }
 //#endregion
+//#region src/router/createRouter.d.ts
+/**
+ * @description 创建高阶路由导航器（对齐 Vue Router 的 createRouter 心智）
+ */
+declare function createRouter(options?: UseRouterOptions): RouterNavigation;
+//#endregion
 //#region src/router/navigationCore.d.ts
 declare function createNavigationFailure(type: NavigationFailureTypeValue, to?: RouteLocationNormalizedLoaded, from?: RouteLocationNormalizedLoaded, cause?: unknown): NavigationFailure;
 declare function isNavigationFailure(error: unknown, type?: NavigationFailureTypeValue): error is NavigationFailure;
@@ -185,8 +196,8 @@ declare function useNativePageRouter(): SetupContextRouter;
 //#endregion
 //#region src/router/useRouter.d.ts
 /**
- * @description 获取高阶路由导航器（对齐 Vue Router 心智）
+ * @description 获取当前已创建的路由实例。
  */
-declare function useRouter(options?: UseRouterOptions): RouterNavigation;
+declare function useRouter(): RouterNavigation;
 //#endregion
-export { type AddRoute, type LocationQuery, type LocationQueryRaw, type LocationQueryValue, type LocationQueryValueRaw, type NamedRouteRecord, type NamedRoutes, type NavigationAfterEach, type NavigationAfterEachContext, type NavigationErrorContext, type NavigationErrorHandler, type NavigationFailure, NavigationFailureType, type NavigationFailureTypeValue, type NavigationGuard, type NavigationGuardContext, type NavigationGuardResult, type NavigationMode, type NavigationRedirect, type RouteLocationNormalizedLoaded, type RouteLocationRaw, type RouteLocationRedirectedFrom, type RouteMeta, type RouteParamValue, type RouteParamValueRaw, type RouteParams, type RouteParamsMode, type RouteParamsRaw, type RouteQueryParser, type RouteQueryStringifier, type RouteRecordMatched, type RouteRecordRaw, type RouteRecordRedirect, type RouterNavigateToOption, type RouterNavigation, type RouterReLaunchOption, type RouterRedirectToOption, type RouterSwitchTabOption, type SetupContextRouter, type TypedRouterTabBarUrl, type TypedRouterUrl, type UseRouterOptions, type WevuTypedRouterRouteMap, createNavigationFailure, isNavigationFailure, parseQuery, resolveRouteLocation, stringifyQuery, useNativePageRouter, useNativeRouter, useRoute, useRouter };
+export { type AddRoute, type LocationQuery, type LocationQueryRaw, type LocationQueryValue, type LocationQueryValueRaw, type NamedRouteRecord, type NamedRoutes, type NavigationAfterEach, type NavigationAfterEachContext, type NavigationErrorContext, type NavigationErrorHandler, type NavigationFailure, NavigationFailureType, type NavigationFailureTypeValue, type NavigationGuard, type NavigationGuardContext, type NavigationGuardResult, type NavigationMode, type NavigationRedirect, type RouteLocationNormalizedLoaded, type RouteLocationRaw, type RouteLocationRedirectedFrom, type RouteMeta, type RouteParamValue, type RouteParamValueRaw, type RouteParams, type RouteParamsMode, type RouteParamsRaw, type RouteQueryParser, type RouteQueryStringifier, type RouteRecordInput, type RouteRecordMatched, type RouteRecordRaw, type RouteRecordRedirect, type RouterNavigateToOption, type RouterNavigation, type RouterReLaunchOption, type RouterRedirectToOption, type RouterSwitchTabOption, type SetupContextRouter, type TypedRouterTabBarUrl, type TypedRouterUrl, type UseRouterOptions, type WevuTypedRouterRouteMap, createNavigationFailure, createRouter, isNavigationFailure, parseQuery, resolveRouteLocation, stringifyQuery, useNativePageRouter, useNativeRouter, useRoute, useRouter };

package/dist/router.mjs

@@ -1,5 +1,5 @@
 import { d as reactive } from "./ref-BjmD-qct.mjs";
-import { L as readonly, S as onShow, j as getCurrentSetupContext, l as onLoad, n as useNativeRouter$1, t as useNativePageRouter$1, v as onRouteDone } from "./router-CcoGUezU.mjs";
+import { E as onShow, F as getCurrentSetupContext, S as onRouteDone, V as readonly, i as injectGlobal, n as useNativeRouter$1, o as provideGlobal, p as onLoad, t as useNativePageRouter$1 } from "./router-BoEmd9rt.mjs";
 //#region src/routerInternal/path.ts
 function normalizePathSegments(path) {
 	const segments = [];
@@ -283,7 +283,7 @@ function resolveNamedRouteLocation(to, lookup, paramsMode) {
 	if (typeof routeName !== "string" || !routeName) return to;
 	if (to.path !== void 0 || to.fullPath !== void 0) return to;
 	const routeRecord = lookup.recordByName.get(routeName);
-	if (!routeRecord) throw new Error(`Named route "${routeName}" is not defined in useRouter({ routes | namedRoutes })`);
+	if (!routeRecord) throw new Error(`Named route "${routeName}" is not defined in createRouter({ routes | namedRoutes })`);
 	const params = to.params ? normalizeRouteParams(to.params) : {};
 	const resolvedResult = resolveNamedRoutePath(routeRecord.path, params, routeName);
 	if (paramsMode === "strict") assertNoUnexpectedNamedRouteParams(params, resolvedResult.consumedKeys, routeName);
@@ -466,7 +466,7 @@ function warnDuplicateRouteEntries(routeEntries) {
 	const duplicateMessages = [];
 	for (const routeEntry of routeEntries) {
 		var _routeEntry$source;
-		const routeName = routeEntry.route.name.trim();
+		const routeName = typeof routeEntry.route.name === "string" ? routeEntry.route.name.trim() : "";
 		if (!routeName) continue;
 		const currentSource = (_routeEntry$source = routeEntry.source) !== null && _routeEntry$source !== void 0 ? _routeEntry$source : "namedRoutes";
 		const currentPath = formatRoutePathForWarning(routeEntry.route.path);
@@ -487,11 +487,16 @@ function normalizeBeforeEnterGuards(beforeEnter) {
 	if (Array.isArray(beforeEnter)) return beforeEnter;
 	return [beforeEnter];
 }
-function normalizeRouteRecordRaw(route, parentName) {
-	const routeName = route.name.trim();
-	if (!routeName) return;
+function resolveRouteRecordName(route, normalizedPath, source = "namedRoutes") {
+	if (typeof route.name === "string" && route.name.trim()) return route.name.trim();
+	if (source === "routes") return normalizedPath || "/";
+	return "";
+}
+function normalizeRouteRecordRaw(route, parentName, source = "namedRoutes") {
 	const normalizedPath = resolvePath(route.path, "");
-	if (!normalizedPath) return;
+	if (!normalizedPath && route.path !== "/") return;
+	const routeName = resolveRouteRecordName(route, normalizedPath, source);
+	if (!routeName) return;
 	return {
 		name: routeName,
 		path: normalizedPath,
@@ -571,16 +576,16 @@ function flattenNamedRouteRecords(records, parentPath, parentName, parentAliasPa
 			warnRouteConfig(`ignored route record at ${routeConfigPath}: detected circular children reference`);
 			continue;
 		}
-		const routeName = typeof (record === null || record === void 0 ? void 0 : record.name) === "string" ? record.name.trim() : "";
-		if (!routeName) {
-			warnRouteConfig(`ignored route record at ${routeConfigPath}: route name is required`);
-			continue;
-		}
 		if (typeof record.path !== "string" || !record.path) {
-			warnRouteConfig(`ignored route record "${routeName}" at ${routeConfigPath}: route path is required`);
+			warnRouteConfig(`ignored route record "${typeof (record === null || record === void 0 ? void 0 : record.name) === "string" ? record.name.trim() : ""}" at ${routeConfigPath}: route path is required`);
 			continue;
 		}
 		const normalizedPath = normalizeNestedRoutePath(record.path, parentPath);
+		const routeName = resolveRouteRecordName(record, normalizedPath, source);
+		if (!routeName) {
+			warnRouteConfig(`ignored route record at ${routeConfigPath}: route name is required`);
+			continue;
+		}
 		const normalizedDirectAliasPaths = [];
 		const directAliasByNormalizedPath = /* @__PURE__ */ new Map();
 		for (const rawAliasPath of normalizeAliasInputList(record.alias)) {
@@ -630,7 +635,7 @@ function createNamedRouteNameByStaticPath(recordByName) {
 function createNamedRouteLookup(routeEntries) {
 	const recordByName = /* @__PURE__ */ new Map();
 	for (const routeRecord of routeEntries) {
-		const normalizedRecord = normalizeRouteRecordRaw(routeRecord.route, routeRecord.parentName);
+		const normalizedRecord = normalizeRouteRecordRaw(routeRecord.route, routeRecord.parentName, routeRecord.source);
 		if (!normalizedRecord) continue;
 		recordByName.set(normalizedRecord.name, normalizedRecord);
 	}
@@ -760,6 +765,18 @@ function hasLocationQuery(query) {
 	return Object.keys(query).length > 0;
 }
 //#endregion
+//#region src/router/instance.ts
+const ROUTER_INSTANCE_KEY = Symbol("wevu.router.instance");
+let activeRouter;
+function setActiveRouter(router) {
+	activeRouter = router;
+	provideGlobal(ROUTER_INSTANCE_KEY, router);
+}
+function getActiveRouter() {
+	var _activeRouter;
+	return (_activeRouter = activeRouter) !== null && _activeRouter !== void 0 ? _activeRouter : injectGlobal(ROUTER_INSTANCE_KEY, void 0);
+}
+//#endregion
 //#region src/router/types.ts
 const NavigationFailureType = {
 	unknown: 1,
@@ -902,69 +919,6 @@ function shouldEmitNavigationError(failure) {
 	return false;
 }
 //#endregion
-//#region src/router/resolve.ts
-const DEFAULT_ROUTE_RESOLVE_CODEC = {
-	parseQuery,
-	stringifyQuery
-};
-function resolveRouteLocation(to, currentPath = "", codec = DEFAULT_ROUTE_RESOLVE_CODEC) {
-	var _ref, _to$path, _parsedFromFullPath$q, _to$hash;
-	if (typeof to === "string") {
-		const parsed = parsePathInput(to, codec);
-		return createRouteLocation(resolvePath(parsed.path, currentPath), parsed.query, parsed.hash, void 0, {}, codec.stringifyQuery);
-	}
-	const parsedFromFullPath = typeof to.fullPath === "string" ? parsePathInput(to.fullPath, codec) : void 0;
-	return createRouteLocation(resolvePath((_ref = (_to$path = to.path) !== null && _to$path !== void 0 ? _to$path : parsedFromFullPath === null || parsedFromFullPath === void 0 ? void 0 : parsedFromFullPath.path) !== null && _ref !== void 0 ? _ref : currentPath, currentPath), to.query ? normalizeQuery(to.query) : (_parsedFromFullPath$q = parsedFromFullPath === null || parsedFromFullPath === void 0 ? void 0 : parsedFromFullPath.query) !== null && _parsedFromFullPath$q !== void 0 ? _parsedFromFullPath$q : {}, normalizeHash((_to$hash = to.hash) !== null && _to$hash !== void 0 ? _to$hash : parsedFromFullPath === null || parsedFromFullPath === void 0 ? void 0 : parsedFromFullPath.hash), typeof to.name === "string" ? to.name : void 0, to.params ? normalizeRouteParams(to.params) : {}, codec.stringifyQuery);
-}
-//#endregion
-//#region src/router/useRoute.ts
-function useRoute() {
-	if (!getCurrentSetupContext()) throw new Error("useRoute() 必须在 setup() 的同步阶段调用");
-	const currentRoute = resolveCurrentRoute();
-	const routeState = reactive({
-		path: currentRoute.path,
-		fullPath: currentRoute.fullPath,
-		query: currentRoute.query,
-		hash: currentRoute.hash,
-		params: currentRoute.params,
-		name: currentRoute.name
-	});
-	if (currentRoute.meta !== void 0) routeState.meta = currentRoute.meta;
-	function syncRoute(queryOverride) {
-		const nextRoute = resolveCurrentRoute(queryOverride);
-		routeState.path = nextRoute.path;
-		routeState.fullPath = nextRoute.fullPath;
-		routeState.query = nextRoute.query;
-		routeState.hash = nextRoute.hash;
-		if (nextRoute.meta === void 0) delete routeState.meta;
-		else routeState.meta = nextRoute.meta;
-		routeState.params = nextRoute.params;
-		routeState.name = nextRoute.name;
-	}
-	onLoad((query) => {
-		syncRoute(query);
-	});
-	onShow(() => {
-		syncRoute();
-	});
-	onRouteDone(() => {
-		syncRoute();
-	});
-	return readonly(routeState);
-}
-/**
-* @description 获取当前组件路径语义的原生 Router
-*/
-function useNativeRouter() {
-	return useNativeRouter$1();
-}
-/**
-* @description 获取当前页面路径语义的原生 Page Router
-*/
-function useNativePageRouter() {
-	return useNativePageRouter$1();
-}
-//#endregion
 //#region src/router/navigationResult.ts
 function createNavigationRunResult(mode, from, to, failure) {
 	return {
@@ -1231,6 +1185,21 @@ function createNavigationApi(options) {
 	};
 }
 //#endregion
+//#region src/router/resolve.ts
+const DEFAULT_ROUTE_RESOLVE_CODEC = {
+	parseQuery,
+	stringifyQuery
+};
+function resolveRouteLocation(to, currentPath = "", codec = DEFAULT_ROUTE_RESOLVE_CODEC) {
+	var _ref, _to$path, _parsedFromFullPath$q, _to$hash;
+	if (typeof to === "string") {
+		const parsed = parsePathInput(to, codec);
+		return createRouteLocation(resolvePath(parsed.path, currentPath), parsed.query, parsed.hash, void 0, {}, codec.stringifyQuery);
+	}
+	const parsedFromFullPath = typeof to.fullPath === "string" ? parsePathInput(to.fullPath, codec) : void 0;
+	return createRouteLocation(resolvePath((_ref = (_to$path = to.path) !== null && _to$path !== void 0 ? _to$path : parsedFromFullPath === null || parsedFromFullPath === void 0 ? void 0 : parsedFromFullPath.path) !== null && _ref !== void 0 ? _ref : currentPath, currentPath), to.query ? normalizeQuery(to.query) : (_parsedFromFullPath$q = parsedFromFullPath === null || parsedFromFullPath === void 0 ? void 0 : parsedFromFullPath.query) !== null && _parsedFromFullPath$q !== void 0 ? _parsedFromFullPath$q : {}, normalizeHash((_to$hash = to.hash) !== null && _to$hash !== void 0 ? _to$hash : parsedFromFullPath === null || parsedFromFullPath === void 0 ? void 0 : parsedFromFullPath.hash), typeof to.name === "string" ? to.name : void 0, to.params ? normalizeRouteParams(to.params) : {}, codec.stringifyQuery);
+}
+//#endregion
 //#region src/router/routeRegistry.ts
 function normalizeRouteRecordForOutput(record) {
 	const normalizedRoute = {
@@ -1254,7 +1223,7 @@ function createRouteRegistry(namedRouteLookup) {
 		assertValidAddRouteInput(route);
 		const parentRouteName = typeof parentNameOrRoute === "string" ? parentNameOrRoute : void 0;
 		const parentRouteRecord = parentRouteName ? namedRouteLookup.recordByName.get(parentRouteName) : void 0;
-		if (parentRouteName && !parentRouteRecord) throw new Error(`Parent route "${parentRouteName}" is not defined in useRouter({ routes | namedRoutes })`);
+		if (parentRouteName && !parentRouteRecord) throw new Error(`Parent route "${parentRouteName}" is not defined in createRouter({ routes | namedRoutes })`);
 		const routeRecords = flattenNamedRouteRecords([route], parentRouteRecord === null || parentRouteRecord === void 0 ? void 0 : parentRouteRecord.path, parentRouteName, parentRouteRecord === null || parentRouteRecord === void 0 ? void 0 : parentRouteRecord.aliasPaths, void 0, "addRoute");
 		if (routeRecords.length === 0) throw new Error("Route name and path are required when adding a named route");
 		const addedRoutes = [];
@@ -1300,11 +1269,59 @@ function createRouteRegistry(namedRouteLookup) {
 	};
 }
 //#endregion
-//#region src/router/useRouter.ts
+//#region src/router/useRoute.ts
+function useRoute() {
+	if (!getCurrentSetupContext()) throw new Error("useRoute() 必须在 setup() 的同步阶段调用");
+	const currentRoute = resolveCurrentRoute();
+	const routeState = reactive({
+		path: currentRoute.path,
+		fullPath: currentRoute.fullPath,
+		query: currentRoute.query,
+		hash: currentRoute.hash,
+		params: currentRoute.params,
+		name: currentRoute.name
+	});
+	if (currentRoute.meta !== void 0) routeState.meta = currentRoute.meta;
+	function syncRoute(queryOverride) {
+		const nextRoute = resolveCurrentRoute(queryOverride);
+		routeState.path = nextRoute.path;
+		routeState.fullPath = nextRoute.fullPath;
+		routeState.query = nextRoute.query;
+		routeState.hash = nextRoute.hash;
+		if (nextRoute.meta === void 0) delete routeState.meta;
+		else routeState.meta = nextRoute.meta;
+		routeState.params = nextRoute.params;
+		routeState.name = nextRoute.name;
+	}
+	onLoad((query) => {
+		syncRoute(query);
+	});
+	onShow(() => {
+		syncRoute();
+	});
+	onRouteDone(() => {
+		syncRoute();
+	});
+	return readonly(routeState);
+}
 /**
-* @description 获取高阶路由导航器（对齐 Vue Router 心智）
+* @description 获取当前组件路径语义的原生 Router
 */
-function useRouter(options = {}) {
+function useNativeRouter() {
+	return useNativeRouter$1();
+}
+/**
+* @description 获取当前页面路径语义的原生 Page Router
+*/
+function useNativePageRouter() {
+	return useNativePageRouter$1();
+}
+//#endregion
+//#region src/router/createRouter.ts
+/**
+* @description 创建高阶路由导航器（对齐 Vue Router 的 createRouter 心智）
+*/
+function createRouter(options = {}) {
 	var _options$maxRedirects, _options$paramsMode, _options$rejectOnErro, _options$parseQuery, _options$stringifyQue, _options$tabBarEntrie;
 	const nativeRouter = useNativeRouter();
 	const route = useRoute();
@@ -1346,10 +1363,6 @@ function useRouter(options = {}) {
 	function resolve(to) {
 		return resolveWithCodec(to, route.path);
 	}
-	function install(_app) {}
-	function isReady() {
-		return readyPromise;
-	}
 	const navigationApi = createNavigationApi({
 		nativeRouter,
 		route,
@@ -1391,13 +1404,20 @@ function useRouter(options = {}) {
 			errorHandlers.delete(handler);
 		};
 	}
-	return {
+	const router = {
 		nativeRouter,
 		options: routerOptions,
 		currentRoute: route,
-		install,
+		install(app) {
+			var _config;
+			setActiveRouter(router);
+			const globalProperties = app === null || app === void 0 || (_config = app.config) === null || _config === void 0 ? void 0 : _config.globalProperties;
+			if (globalProperties) globalProperties.$router = router;
+		},
 		resolve,
-		isReady,
+		isReady() {
+			return readyPromise;
+		},
 		push: navigationApi.push,
 		replace: navigationApi.replace,
 		back: navigationApi.back,
@@ -1413,6 +1433,18 @@ function useRouter(options = {}) {
 		afterEach,
 		onError
 	};
+	setActiveRouter(router);
+	return router;
+}
+//#endregion
+//#region src/router/useRouter.ts
+/**
+* @description 获取当前已创建的路由实例。
+*/
+function useRouter() {
+	const router = getActiveRouter();
+	if (router) return router;
+	throw new Error("useRouter() 未找到已创建的 router 实例。请先在 setup() 中调用 createRouter()。");
 }
 //#endregion
-export { NavigationFailureType, createNavigationFailure, isNavigationFailure, parseQuery, resolveRouteLocation, stringifyQuery, useNativePageRouter, useNativeRouter, useRoute, useRouter };
+export { NavigationFailureType, createNavigationFailure, createRouter, isNavigationFailure, parseQuery, resolveRouteLocation, stringifyQuery, useNativePageRouter, useNativeRouter, useRoute, useRouter };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wevu",
   "type": "module",
-  "version": "6.7.6",
+  "version": "6.8.0",
   "description": "Vue 3 风格的小程序运行时，包含响应式、diff+setData 与轻量状态管理",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -95,8 +95,8 @@
   },
   "dependencies": {
     "vue": "^3.5.30",
-    "@wevu/api": "0.2.0",
-    "@wevu/compiler": "6.7.6"
+    "@wevu/api": "0.2.1",
+    "@wevu/compiler": "6.8.0"
   },
   "scripts": {
     "dev": "tsdown -w",