wevu 7.2.2 → 7.4.0

package/dist/dev/router/scrollRestoration/controller.mjs

@@ -0,0 +1,148 @@
+import { getCurrentMiniProgramPages } from "../../runtime/platform.mjs";
+import { resolvePageRoute } from "../../routerInternal/location.mjs";
+import { getActiveRouter } from "../instance.mjs";
+import { currentScrollPage, subscribeScrollRouteEvents, supportsScrollRouteEvents } from "./host.mjs";
+
+//#region src/router/scrollRestoration/controller.ts
+const controllers = /* @__PURE__ */ new WeakMap();
+const routerControllers = /* @__PURE__ */ new WeakMap();
+/** 创建显式启用的路由会话；不会安装全局默认滚动行为。 */
+function createScrollRestoration(options) {
+	if (routerControllers.has(options.router)) throw new Error("该 router 已创建 scroll restoration 会话，请复用或先 dispose()。");
+	const router = options.router;
+	const snapshots = /* @__PURE__ */ new Map();
+	const registrations = /* @__PURE__ */ new Map();
+	const seenPages = new WeakSet(getCurrentMiniProgramPages());
+	const report = options.onError ?? ((error) => console.error("[wevu/router] scroll restoration:", error));
+	let disposed = false;
+	let generation = 0;
+	let transition;
+	let unsubscribe;
+	const controller = {
+		automatic: supportsScrollRouteEvents(),
+		clear(key) {
+			if (key === void 0) snapshots.clear();
+			else snapshots.delete(key);
+			for (const records of registrations.values()) for (const record of records) if (key === void 0 || record.key === key) record.invalidate();
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			generation++;
+			unsubscribe?.();
+			for (const records of registrations.values()) for (const record of records) record.stop();
+			registrations.clear();
+			snapshots.clear();
+			transition = void 0;
+			routerControllers.delete(options.router);
+			controllers.delete(controller);
+		}
+	};
+	const state = {
+		controller,
+		get disposed() {
+			return disposed;
+		},
+		get transition() {
+			return transition;
+		},
+		get generation() {
+			return generation;
+		},
+		resolveRoute: (page) => router.resolve(resolvePageRoute(page)),
+		register(page, registration) {
+			if (disposed) throw new Error("scroll restoration 会话已 dispose()。");
+			let records = registrations.get(page);
+			if (!records) {
+				records = /* @__PURE__ */ new Set();
+				registrations.set(page, records);
+			}
+			for (const record of records) if (record.key === registration.key && record.id === registration.id) throw new Error(`同一页面重复注册 scroll restoration key/id: ${registration.key} / ${registration.id}`);
+			records.add(registration);
+			return () => {
+				records.delete(registration);
+				if (records.size === 0) registrations.delete(page);
+			};
+		},
+		read: (key, id) => snapshots.get(key)?.get(id),
+		save(key, id, value) {
+			if (disposed) return;
+			if (value === null) {
+				state.clear(key, id);
+				return;
+			}
+			let entries = snapshots.get(key);
+			if (!entries) {
+				entries = /* @__PURE__ */ new Map();
+				snapshots.set(key, entries);
+			}
+			entries.set(id, value);
+		},
+		clear(key, id) {
+			const entries = snapshots.get(key);
+			entries?.delete(id);
+			if (entries?.size === 0) snapshots.delete(key);
+			for (const records of registrations.values()) for (const record of records) if (record.key === key && record.id === id) record.invalidate();
+		},
+		report
+	};
+	if (controller.automatic) unsubscribe = subscribeScrollRouteEvents({
+		BeforeAppRoute(event) {
+			if (disposed || transition?.event.routeEventId === event.routeEventId) return;
+			const page = currentScrollPage();
+			if (page) {
+				seenPages.add(page);
+				for (const record of registrations.get(page) ?? []) record.capture();
+			}
+			generation++;
+			for (const records of registrations.values()) for (const record of records) record.invalidate();
+			transition = {
+				event,
+				fresh: false,
+				done: false
+			};
+		},
+		BeforePageUnload(event) {
+			const page = event.page;
+			if (!page) return;
+			if (transition?.event.routeEventId !== event.routeEventId && page === currentScrollPage()) for (const record of registrations.get(page) ?? []) record.capture();
+			for (const record of registrations.get(page) ?? []) record.stop();
+		},
+		AppRoute(event) {
+			if (disposed || transition && transition.event.routeEventId !== event.routeEventId) return;
+			const page = currentScrollPage();
+			if (!page || resolvePageRoute(page).path !== event.path.replace(/^\/+/, "")) return;
+			transition ?? (transition = {
+				event,
+				fresh: false,
+				done: false
+			});
+			if (transition.page) return;
+			transition.page = page;
+			transition.fresh = !seenPages.has(page);
+			seenPages.add(page);
+		},
+		AppRouteDone(event) {
+			if (disposed || !transition) return;
+			const completesFreshPage = event.routeEventId === "" && transition.fresh && Number.isInteger(transition.event.webviewId) && event.webviewId === transition.event.webviewId && event.path === transition.event.path && typeof event.openType === "string" && event.openType === transition.event.openType;
+			if (transition.event.routeEventId !== event.routeEventId && !completesFreshPage) return;
+			if (!transition.page || transition.page !== currentScrollPage() || transition.done) return;
+			transition.done = true;
+			for (const record of registrations.get(transition.page) ?? []) record.restoreAutomatic();
+		}
+	});
+	controllers.set(controller, state);
+	routerControllers.set(options.router, controller);
+	return controller;
+}
+function resolveScrollController(controller) {
+	const router = getActiveRouter();
+	const resolved = controller ?? (router && routerControllers.get(router));
+	const state = resolved && controllers.get(resolved);
+	if (!state || state.disposed) throw new Error("请先在应用启动时调用 createScrollRestoration({ router })，或传入有效的 controller。");
+	return state;
+}
+
+//#endregion
+export { createScrollRestoration, resolveScrollController };
+//# sourceMappingURL=controller.mjs.map

package/dist/dev/router/scrollRestoration/controller.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.mjs","names":[],"sources":["../../../../src/router/scrollRestoration/controller.ts"],"sourcesContent":["import type { RouteLocationNormalizedLoaded, RouterNavigation } from '../types'\nimport type { ScrollPage, ScrollRouteEvent } from './host'\nimport type { ScrollRestorationController, ScrollRestorationOptions } from './types'\nimport { resolvePageRoute } from '../../routerInternal/shared'\nimport { getCurrentMiniProgramPages } from '../../runtime/platform'\nimport { getActiveRouter } from '../instance'\nimport { currentScrollPage, subscribeScrollRouteEvents, supportsScrollRouteEvents } from './host'\n\nexport interface ScrollRegistration {\n  key: string\n  id: string\n  capture: () => void\n  invalidate: () => void\n  restoreAutomatic: () => void\n  stop: () => void\n}\n\ninterface ScrollTransition {\n  event: ScrollRouteEvent\n  page?: ScrollPage\n  fresh: boolean\n  done: boolean\n}\n\nexport interface ScrollControllerState {\n  readonly controller: ScrollRestorationController\n  readonly disposed: boolean\n  readonly transition: ScrollTransition | undefined\n  readonly generation: number\n  resolveRoute: (page: ScrollPage) => RouteLocationNormalizedLoaded\n  register: (page: ScrollPage, registration: ScrollRegistration) => () => void\n  read: (key: string, id: string) => object | undefined\n  save: (key: string, id: string, value: object | null) => void\n  clear: (key: string, id: string) => void\n  report: (error: unknown) => void\n}\n\nconst controllers = new WeakMap<ScrollRestorationController, ScrollControllerState>()\nconst routerControllers = new WeakMap<object, ScrollRestorationController>()\n\n/** 创建显式启用的路由会话；不会安装全局默认滚动行为。 */\nexport function createScrollRestoration<TRouteMap extends object>(options: ScrollRestorationOptions<TRouteMap>): ScrollRestorationController {\n  if (routerControllers.has(options.router)) {\n    throw new Error('该 router 已创建 scroll restoration 会话，请复用或先 dispose()。')\n  }\n  // 泛型仅约束公开路由名，内部处理来自原生页面的标准化路径。\n  const router = options.router as unknown as RouterNavigation\n  const snapshots = new Map<string, Map<string, object>>()\n  const registrations = new Map<ScrollPage, Set<ScrollRegistration>>()\n  const seenPages = new WeakSet<object>(getCurrentMiniProgramPages())\n  // eslint-disable-next-line no-console -- 自动恢复没有调用方 Promise；默认处理必须报告错误。\n  const report = options.onError ?? ((error: unknown) => console.error('[wevu/router] scroll restoration:', error))\n  let disposed = false\n  let generation = 0\n  let transition: ScrollTransition | undefined\n  let unsubscribe: (() => void) | undefined\n\n  const controller: ScrollRestorationController = {\n    automatic: supportsScrollRouteEvents(),\n    clear(key) {\n      if (key === undefined) {\n        snapshots.clear()\n      }\n      else {\n        snapshots.delete(key)\n      }\n      for (const records of registrations.values()) {\n        for (const record of records) {\n          if (key === undefined || record.key === key) {\n            record.invalidate()\n          }\n        }\n      }\n    },\n    dispose() {\n      if (disposed) {\n        return\n      }\n      disposed = true\n      generation++\n      unsubscribe?.()\n      for (const records of registrations.values()) {\n        for (const record of records) {\n          record.stop()\n        }\n      }\n      registrations.clear()\n      snapshots.clear()\n      transition = undefined\n      routerControllers.delete(options.router)\n      controllers.delete(controller)\n    },\n  }\n\n  const state: ScrollControllerState = {\n    controller,\n    get disposed() {\n      return disposed\n    },\n    get transition() {\n      return transition\n    },\n    get generation() {\n      return generation\n    },\n    resolveRoute: page => router.resolve(resolvePageRoute(page)),\n    register(page, registration) {\n      if (disposed) {\n        throw new Error('scroll restoration 会话已 dispose()。')\n      }\n      let records = registrations.get(page)\n      if (!records) {\n        records = new Set()\n        registrations.set(page, records)\n      }\n      for (const record of records) {\n        if (record.key === registration.key && record.id === registration.id) {\n          throw new Error(`同一页面重复注册 scroll restoration key/id: ${registration.key} / ${registration.id}`)\n        }\n      }\n      records.add(registration)\n      return () => {\n        records.delete(registration)\n        if (records.size === 0) {\n          registrations.delete(page)\n        }\n      }\n    },\n    read: (key, id) => snapshots.get(key)?.get(id),\n    save(key, id, value) {\n      if (disposed) {\n        return\n      }\n      if (value === null) {\n        state.clear(key, id)\n        return\n      }\n      let entries = snapshots.get(key)\n      if (!entries) {\n        entries = new Map()\n        snapshots.set(key, entries)\n      }\n      entries.set(id, value)\n    },\n    clear(key, id) {\n      const entries = snapshots.get(key)\n      entries?.delete(id)\n      if (entries?.size === 0) {\n        snapshots.delete(key)\n      }\n      for (const records of registrations.values()) {\n        for (const record of records) {\n          if (record.key === key && record.id === id) {\n            record.invalidate()\n          }\n        }\n      }\n    },\n    report,\n  }\n\n  if (controller.automatic) {\n    unsubscribe = subscribeScrollRouteEvents({\n      BeforeAppRoute(event) {\n        if (disposed || transition?.event.routeEventId === event.routeEventId) {\n          return\n        }\n        const page = currentScrollPage()\n        if (page) {\n          seenPages.add(page)\n          for (const record of registrations.get(page) ?? []) {\n            record.capture()\n          }\n        }\n        generation++\n        for (const records of registrations.values()) {\n          for (const record of records) {\n            record.invalidate()\n          }\n        }\n        transition = { event, fresh: false, done: false }\n      },\n      BeforePageUnload(event) {\n        const page = event.page\n        if (!page) {\n          return\n        }\n        // 低层卸载可能没有前置路由通知；仍在当前页时最后同步读取内存缓存。\n        if (transition?.event.routeEventId !== event.routeEventId && page === currentScrollPage()) {\n          for (const record of registrations.get(page) ?? []) {\n            record.capture()\n          }\n        }\n        for (const record of registrations.get(page) ?? []) {\n          record.stop()\n        }\n      },\n      AppRoute(event) {\n        if (disposed || (transition && transition.event.routeEventId !== event.routeEventId)) {\n          return\n        }\n        const page = currentScrollPage()\n        if (!page || resolvePageRoute(page).path !== event.path.replace(/^\\/+/, '')) {\n          return\n        }\n        transition ??= { event, fresh: false, done: false }\n        if (transition.page) {\n          return\n        }\n        transition.page = page\n        transition.fresh = !seenPages.has(page)\n        seenPages.add(page)\n      },\n      AppRouteDone(event) {\n        if (disposed || !transition) {\n          return\n        }\n        // 原生同路径 reLaunch 可能返回空 id；只接受已确认的新页面对应的宿主 webview，\n        // 不把旧页面、保留页面或仅路径相同的完成事件认作当前导航。\n        const completesFreshPage = event.routeEventId === ''\n          && transition.fresh\n          && Number.isInteger(transition.event.webviewId)\n          && event.webviewId === transition.event.webviewId\n          && event.path === transition.event.path\n          && typeof event.openType === 'string'\n          && event.openType === transition.event.openType\n        if (transition.event.routeEventId !== event.routeEventId && !completesFreshPage) {\n          return\n        }\n        if (!transition.page || transition.page !== currentScrollPage() || transition.done) {\n          return\n        }\n        transition.done = true\n        for (const record of registrations.get(transition.page) ?? []) {\n          record.restoreAutomatic()\n        }\n      },\n    })\n  }\n  controllers.set(controller, state)\n  routerControllers.set(options.router, controller)\n  return controller\n}\n\nexport function resolveScrollController(controller?: ScrollRestorationController): ScrollControllerState {\n  const router = getActiveRouter()\n  const resolved = controller ?? (router && routerControllers.get(router))\n  const state = resolved && controllers.get(resolved)\n  if (!state || state.disposed) {\n    throw new Error('请先在应用启动时调用 createScrollRestoration({ router })，或传入有效的 controller。')\n  }\n  return state\n}\n"],"mappings":"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"}

package/dist/dev/router/scrollRestoration/host.d.mts

@@ -0,0 +1,3 @@
+import "../../routerInternal/types.mjs";
+import "../types.mjs";
+import { WEVU_HOOKS_KEY, WEVU_NATIVE_INSTANCE_KEY, WEVU_READY_CALLED_KEY } from "@weapp-core/constants";

package/dist/dev/router/scrollRestoration/host.mjs

@@ -0,0 +1,76 @@
+import { getCurrentMiniProgramGlobalObject } from "../../runtime/platform/current.mjs";
+import { getCurrentMiniProgramPages } from "../../runtime/platform.mjs";
+import { pushHook } from "../../runtime/hooks/base.mjs";
+import { WEVU_HOOKS_KEY, WEVU_NATIVE_INSTANCE_KEY, WEVU_ROUTE_EVENT_CONTRACT_KEY } from "@weapp-core/constants";
+
+//#region src/router/scrollRestoration/host.ts
+const routeEvents = [
+	"BeforeAppRoute",
+	"BeforePageUnload",
+	"AppRoute",
+	"AppRouteDone"
+];
+function supportsScrollRouteEvents(host = getCurrentMiniProgramGlobalObject()) {
+	if (!host || !routeEvents.every((name) => typeof host[`on${name}`] === "function" && typeof host[`off${name}`] === "function")) return false;
+	if (host[WEVU_ROUTE_EVENT_CONTRACT_KEY] === 1) return true;
+	const version = host.getAppBaseInfo?.().SDKVersion ?? host.getSystemInfoSync?.().SDKVersion;
+	if (typeof version !== "string") return false;
+	const match = /^(\d+)\.(\d+)\.(\d+)(?:\D|$)/.exec(version);
+	if (!match) return false;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	return major > 3 || major === 3 && (minor > 5 || minor === 5 && patch >= 5);
+}
+function subscribeScrollRouteEvents(handlers) {
+	const host = getCurrentMiniProgramGlobalObject();
+	const cleanups = [];
+	try {
+		for (const name of routeEvents) {
+			const listener = (event) => {
+				if (typeof event?.routeEventId === "string" && typeof event.path === "string") handlers[name](event);
+			};
+			host[`on${name}`](listener);
+			cleanups.push(() => host[`off${name}`](listener));
+		}
+	} catch (error) {
+		for (const cleanup of cleanups) cleanup();
+		throw error;
+	}
+	return () => {
+		for (const cleanup of cleanups) cleanup();
+	};
+}
+function currentScrollPage() {
+	const pages = getCurrentMiniProgramPages();
+	return pages[pages.length - 1];
+}
+/** 按实例或宿主页面 id 查找归属，不用路径猜测同路由的多个页面。 */
+function resolveScrollPage(instance) {
+	const pages = getCurrentMiniProgramPages();
+	const visited = /* @__PURE__ */ new Set();
+	let owner = instance;
+	while (owner && !visited.has(owner)) {
+		visited.add(owner);
+		if (pages.includes(owner)) return owner;
+		const pageId = owner.__wxWebviewId__;
+		if (pageId !== void 0) {
+			const page = pages.find((candidate) => candidate.__wxWebviewId__ === pageId);
+			if (page) return page;
+		}
+		const native = owner[WEVU_NATIVE_INSTANCE_KEY] ?? owner.$;
+		owner = native && native !== owner ? native : owner.selectOwnerComponent?.();
+	}
+}
+function addScrollHook(instance, name, handler) {
+	pushHook(instance, name, handler);
+	return () => {
+		const bucket = instance[WEVU_HOOKS_KEY];
+		const hooks = bucket?.[name];
+		if (bucket && Array.isArray(hooks)) bucket[name] = hooks.filter((hook) => hook !== handler);
+	};
+}
+
+//#endregion
+export { addScrollHook, currentScrollPage, resolveScrollPage, subscribeScrollRouteEvents, supportsScrollRouteEvents };
+//# sourceMappingURL=host.mjs.map

package/dist/dev/router/scrollRestoration/host.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.mjs","names":[],"sources":["../../../../src/router/scrollRestoration/host.ts"],"sourcesContent":["import type { WEVU_READY_CALLED_KEY } from '@weapp-core/constants'\nimport type { MiniProgramPageLike } from '../../routerInternal/types'\nimport type { InternalRuntimeState } from '../../runtime/types'\nimport type { LocationQueryRaw } from '../types'\nimport { WEVU_HOOKS_KEY, WEVU_NATIVE_INSTANCE_KEY, WEVU_ROUTE_EVENT_CONTRACT_KEY } from '@weapp-core/constants'\nimport { pushHook } from '../../runtime/hooks/base'\nimport { getCurrentMiniProgramGlobalObject, getCurrentMiniProgramPages } from '../../runtime/platform'\n\ntype ScrollHook = (...args: unknown[]) => void\n\nexport interface ScrollPage extends MiniProgramPageLike {\n  __wxWebviewId__?: number | string\n  [WEVU_NATIVE_INSTANCE_KEY]?: ScrollPage\n  [WEVU_READY_CALLED_KEY]?: boolean\n  [WEVU_HOOKS_KEY]?: Record<string, ScrollHook | ScrollHook[]>\n  $?: ScrollPage\n  selectOwnerComponent?: () => ScrollPage | undefined\n  onPageScroll?: (event: { scrollTop: number }) => unknown\n}\n\nexport interface ScrollRouteEvent {\n  routeEventId: string\n  path: string\n  query?: LocationQueryRaw\n  openType?: string\n  webviewId?: number\n  renderer?: string\n  page?: ScrollPage\n}\n\nconst routeEvents = ['BeforeAppRoute', 'BeforePageUnload', 'AppRoute', 'AppRouteDone'] as const\nexport type ScrollRouteEventName = typeof routeEvents[number]\n\nexport function supportsScrollRouteEvents(host = getCurrentMiniProgramGlobalObject()): boolean {\n  if (!host || !routeEvents.every(name => typeof host[`on${name}`] === 'function' && typeof host[`off${name}`] === 'function')) {\n    return false\n  }\n  if (host[WEVU_ROUTE_EVENT_CONTRACT_KEY] === 1) {\n    return true\n  }\n  const version = host.getAppBaseInfo?.().SDKVersion ?? host.getSystemInfoSync?.().SDKVersion\n  if (typeof version !== 'string') {\n    return false\n  }\n  const match = /^(\\d+)\\.(\\d+)\\.(\\d+)(?:\\D|$)/.exec(version)\n  if (!match) {\n    return false\n  }\n  const major = Number(match[1])\n  const minor = Number(match[2])\n  const patch = Number(match[3])\n  return major > 3 || (major === 3 && (minor > 5 || (minor === 5 && patch >= 5)))\n}\n\nexport function subscribeScrollRouteEvents(handlers: Record<ScrollRouteEventName, (event: ScrollRouteEvent) => void>): () => void {\n  const host = getCurrentMiniProgramGlobalObject()!\n  const cleanups: Array<() => void> = []\n  try {\n    for (const name of routeEvents) {\n      const listener = (event: ScrollRouteEvent) => {\n        if (typeof event?.routeEventId === 'string' && typeof event.path === 'string') {\n          handlers[name](event)\n        }\n      }\n      host[`on${name}`](listener)\n      cleanups.push(() => host[`off${name}`](listener))\n    }\n  }\n  catch (error) {\n    for (const cleanup of cleanups) {\n      cleanup()\n    }\n    throw error\n  }\n  return () => {\n    for (const cleanup of cleanups) {\n      cleanup()\n    }\n  }\n}\n\nexport function currentScrollPage(): ScrollPage | undefined {\n  const pages = getCurrentMiniProgramPages()\n  return pages[pages.length - 1]\n}\n\n/** 按实例或宿主页面 id 查找归属，不用路径猜测同路由的多个页面。 */\nexport function resolveScrollPage(instance: ScrollPage): ScrollPage | undefined {\n  const pages = getCurrentMiniProgramPages()\n  const visited = new Set<object>()\n  let owner: ScrollPage | undefined = instance\n  while (owner && !visited.has(owner)) {\n    visited.add(owner)\n    if (pages.includes(owner)) {\n      return owner\n    }\n    const pageId = owner.__wxWebviewId__\n    if (pageId !== undefined) {\n      const page = pages.find(candidate => candidate.__wxWebviewId__ === pageId)\n      if (page) {\n        return page\n      }\n    }\n    const native: ScrollPage | undefined = owner[WEVU_NATIVE_INSTANCE_KEY] ?? owner.$\n    owner = native && native !== owner\n      ? native\n      : owner.selectOwnerComponent?.()\n  }\n  return undefined\n}\n\nexport function addScrollHook(instance: ScrollPage, name: string, handler: ScrollHook): () => void {\n  pushHook(instance as InternalRuntimeState, name, handler)\n  return () => {\n    const bucket = instance[WEVU_HOOKS_KEY]\n    const hooks = bucket?.[name]\n    if (bucket && Array.isArray(hooks)) {\n      // 不原地修改正在被生命周期分发器遍历的数组，避免跳过后续用户 hook。\n      bucket[name] = hooks.filter(hook => hook !== handler)\n    }\n  }\n}\n"],"mappings":";;;;;;AA8BA,MAAM,cAAc;CAAC;CAAkB;CAAoB;CAAY;AAAc;AAGrF,SAAgB,0BAA0B,OAAO,kCAAkC,GAAY;CAC7F,IAAI,CAAC,QAAQ,CAAC,YAAY,OAAM,SAAQ,OAAO,KAAK,KAAK,YAAY,cAAc,OAAO,KAAK,MAAM,YAAY,UAAU,GACzH,OAAO;CAET,IAAI,KAAK,mCAAmC,GAC1C,OAAO;CAET,MAAM,UAAU,KAAK,iBAAiB,CAAC,CAAC,cAAc,KAAK,oBAAoB,CAAC,CAAC;CACjF,IAAI,OAAO,YAAY,UACrB,OAAO;CAET,MAAM,QAAQ,+BAA+B,KAAK,OAAO;CACzD,IAAI,CAAC,OACH,OAAO;CAET,MAAM,QAAQ,OAAO,MAAM,EAAE;CAC7B,MAAM,QAAQ,OAAO,MAAM,EAAE;CAC7B,MAAM,QAAQ,OAAO,MAAM,EAAE;CAC7B,OAAO,QAAQ,KAAM,UAAU,MAAM,QAAQ,KAAM,UAAU,KAAK,SAAS;AAC7E;AAEA,SAAgB,2BAA2B,UAAuF;CAChI,MAAM,OAAO,kCAAkC;CAC/C,MAAM,WAA8B,CAAC;CACrC,IAAI;EACF,KAAK,MAAM,QAAQ,aAAa;GAC9B,MAAM,YAAY,UAA4B;IAC5C,IAAI,OAAO,OAAO,iBAAiB,YAAY,OAAO,MAAM,SAAS,UACnE,SAAS,KAAK,CAAC,KAAK;GAExB;GACA,KAAK,KAAK,OAAO,CAAC,QAAQ;GAC1B,SAAS,WAAW,KAAK,MAAM,OAAO,CAAC,QAAQ,CAAC;EAClD;CACF,SACO,OAAO;EACZ,KAAK,MAAM,WAAW,UACpB,QAAQ;EAEV,MAAM;CACR;CACA,aAAa;EACX,KAAK,MAAM,WAAW,UACpB,QAAQ;CAEZ;AACF;AAEA,SAAgB,oBAA4C;CAC1D,MAAM,QAAQ,2BAA2B;CACzC,OAAO,MAAM,MAAM,SAAS;AAC9B;;AAGA,SAAgB,kBAAkB,UAA8C;CAC9E,MAAM,QAAQ,2BAA2B;CACzC,MAAM,0BAAU,IAAI,IAAY;CAChC,IAAI,QAAgC;CACpC,OAAO,SAAS,CAAC,QAAQ,IAAI,KAAK,GAAG;EACnC,QAAQ,IAAI,KAAK;EACjB,IAAI,MAAM,SAAS,KAAK,GACtB,OAAO;EAET,MAAM,SAAS,MAAM;EACrB,IAAI,WAAW,QAAW;GACxB,MAAM,OAAO,MAAM,MAAK,cAAa,UAAU,oBAAoB,MAAM;GACzE,IAAI,MACF,OAAO;EAEX;EACA,MAAM,SAAiC,MAAM,6BAA6B,MAAM;EAChF,QAAQ,UAAU,WAAW,QACzB,SACA,MAAM,uBAAuB;CACnC;AAEF;AAEA,SAAgB,cAAc,UAAsB,MAAc,SAAiC;CACjG,SAAS,UAAkC,MAAM,OAAO;CACxD,aAAa;EACX,MAAM,SAAS,SAAS;EACxB,MAAM,QAAQ,SAAS;EACvB,IAAI,UAAU,MAAM,QAAQ,KAAK,GAE/B,OAAO,QAAQ,MAAM,QAAO,SAAQ,SAAS,OAAO;CAExD;AACF"}

package/dist/dev/router/scrollRestoration/index.d.mts

@@ -0,0 +1,9 @@
+import { ScrollRestorationContext, ScrollRestorationController, ScrollRestorationHandle, ScrollRestorationOptions, ScrollRestorationRegistrationOptions, ScrollViewRestorationHandle, UseScrollRestorationOptions } from "./types.mjs";
+import "./host.mjs";
+import { createScrollRestoration } from "./controller.mjs";
+//#region src/router/scrollRestoration/index.d.ts
+/** 在同步 setup 中注册快照；只恢复新实例，不覆盖原生保留页的位置。 */
+export declare function useScrollRestoration<T extends object>(options: UseScrollRestorationOptions<T>): ScrollRestorationHandle;
+//#endregion
+export { type ScrollRestorationContext, type ScrollRestorationController, type ScrollRestorationHandle, type ScrollRestorationOptions, type ScrollRestorationRegistrationOptions, type ScrollViewRestorationHandle, type UseScrollRestorationOptions, createScrollRestoration };
+//# sourceMappingURL=index.d.mts.map

package/dist/dev/router/scrollRestoration/index.mjs

@@ -0,0 +1,156 @@
+import { onScopeDispose } from "../../reactivity/core.mjs";
+import { assertInSetup, getCurrentSetupContext } from "../../runtime/hooks/base.mjs";
+import { getInitialNavigationPromise } from "../initialNavigation.mjs";
+import { addScrollHook, currentScrollPage, resolveScrollPage } from "./host.mjs";
+import { createScrollRestoration, resolveScrollController } from "./controller.mjs";
+import { WEVU_READY_CALLED_KEY } from "@weapp-core/constants";
+
+//#region src/router/scrollRestoration/index.ts
+function getScrollSetupScope() {
+	const instance = assertInSetup("useScrollRestoration");
+	const proxy = getCurrentSetupContext()?.proxy;
+	if (typeof proxy?.$nextTick !== "function") throw new TypeError("scroll restoration 需要具有宿主提交屏障的 wevu setup 实例。");
+	return {
+		instance,
+		commit: () => proxy.$nextTick()
+	};
+}
+function registerScrollRestoration(options, lifecycle) {
+	const { instance, commit } = getScrollSetupScope();
+	const state = resolveScrollController(options.controller);
+	const cleanups = [];
+	let page;
+	let route;
+	let stopped = false;
+	let visible = true;
+	let captured = false;
+	let attempted = false;
+	let request = 0;
+	let instanceReady = Boolean(instance[WEVU_READY_CALLED_KEY]);
+	let pageReady = false;
+	let readyPromise;
+	let resolveReady;
+	let registration;
+	function releaseReady() {
+		if (stopped || instanceReady && pageReady) resolveReady?.();
+	}
+	function bindPage() {
+		if (page || stopped) return;
+		const owner = resolveScrollPage(instance);
+		if (!owner) return;
+		const nextRoute = state.resolveRoute(owner);
+		registration.key = typeof options.key === "function" ? options.key(nextRoute) : options.key ?? nextRoute.fullPath;
+		const unregister = state.register(owner, registration);
+		page = owner;
+		route = nextRoute;
+		cleanups.push(unregister);
+		pageReady = Boolean(owner[WEVU_READY_CALLED_KEY]);
+		cleanups.push(addScrollHook(owner, "onReady", () => {
+			pageReady = true;
+			releaseReady();
+			registration.restoreAutomatic();
+		}));
+		lifecycle?.onBindPage?.(owner);
+	}
+	async function scroll() {
+		if (stopped || state.disposed) return false;
+		bindPage();
+		if (!page || !route) throw new Error("无法确定 scroll restoration 的原生归属页面，请在页面 attached 后恢复。");
+		if (!visible || currentScrollPage() !== page) return false;
+		const ticket = ++request;
+		const generation = state.generation;
+		const context = {
+			route,
+			routeEventId: state.transition?.page === page ? state.transition.event.routeEventId : void 0,
+			isActive: () => !stopped && !state.disposed && visible && ticket === request && generation === state.generation && currentScrollPage() === page
+		};
+		if (!instanceReady || !pageReady) {
+			readyPromise ?? (readyPromise = new Promise((resolve) => {
+				resolveReady = resolve;
+			}));
+			await readyPromise;
+		}
+		if (!context.isActive()) return false;
+		if (await getInitialNavigationPromise(page) === false || !context.isActive()) return false;
+		await commit();
+		if (!context.isActive()) return false;
+		const snapshot = state.read(registration.key, registration.id);
+		await options.restore(snapshot, context);
+		return context.isActive();
+	}
+	registration = {
+		key: "",
+		id: options.id ?? "default",
+		capture() {
+			if (stopped || state.disposed || !page || !visible || captured) return;
+			captured = true;
+			try {
+				const snapshot = options.capture();
+				if (snapshot !== null && "then" in snapshot && typeof snapshot.then === "function") throw new TypeError("scroll restoration capture 必须同步返回快照，不能返回 Promise。");
+				state.save(registration.key, registration.id, snapshot);
+			} catch (error) {
+				state.clear(registration.key, registration.id);
+				state.report(error);
+			}
+		},
+		invalidate() {
+			request++;
+			resolveReady?.();
+			readyPromise = void 0;
+			resolveReady = void 0;
+		},
+		restoreAutomatic() {
+			const transition = state.transition;
+			if (stopped || options.manual || attempted || !instanceReady || !pageReady || !transition?.fresh || !transition.done || transition.page !== page) return;
+			attempted = true;
+			scroll().catch(state.report);
+		},
+		stop() {
+			if (stopped) return;
+			stopped = true;
+			request++;
+			releaseReady();
+			for (const cleanup of cleanups) cleanup();
+			cleanups.length = 0;
+			lifecycle?.onStop?.();
+		}
+	};
+	function captureBeforeStop() {
+		registration.capture();
+		registration.stop();
+	}
+	cleanups.push(addScrollHook(instance, "onAttached", bindPage), addScrollHook(instance, "onReady", () => {
+		bindPage();
+		instanceReady = true;
+		releaseReady();
+		registration.restoreAutomatic();
+	}), addScrollHook(instance, "onShow", () => {
+		bindPage();
+		visible = true;
+		captured = false;
+	}), addScrollHook(instance, "onHide", () => {
+		registration.capture();
+		visible = false;
+		registration.invalidate();
+	}), addScrollHook(instance, "onDetached", captureBeforeStop), addScrollHook(instance, "onUnload", captureBeforeStop));
+	onScopeDispose(captureBeforeStop);
+	bindPage();
+	registration.restoreAutomatic();
+	return {
+		automatic: state.controller.automatic && !options.manual,
+		scroll,
+		clear: () => {
+			bindPage();
+			if (page) state.clear(registration.key, registration.id);
+		},
+		stop: registration.stop
+	};
+}
+/** 在同步 setup 中注册快照；只恢复新实例，不覆盖原生保留页的位置。 */
+function useScrollRestoration(options) {
+	return registerScrollRestoration(options);
+}
+
+//#endregion
+export { createScrollRestoration, getScrollSetupScope, registerScrollRestoration, useScrollRestoration };
+//# sourceMappingURL=index.mjs.map

package/dist/dev/router/scrollRestoration/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/router/scrollRestoration/index.ts"],"sourcesContent":["import type { ScrollRegistration } from './controller'\nimport type { ScrollPage } from './host'\nimport type { ScrollRestorationContext, ScrollRestorationHandle, UseScrollRestorationOptions } from './types'\nimport { WEVU_READY_CALLED_KEY } from '@weapp-core/constants'\nimport { onScopeDispose } from '../../reactivity'\nimport { assertInSetup, getCurrentSetupContext } from '../../runtime/hooks/base'\nimport { getInitialNavigationPromise } from '../initialNavigation'\nimport { resolveScrollController } from './controller'\nimport { addScrollHook, currentScrollPage, resolveScrollPage } from './host'\n\nexport { createScrollRestoration } from './controller'\nexport type * from './types'\n\nexport function getScrollSetupScope() {\n  const instance: ScrollPage = assertInSetup('useScrollRestoration')\n  const proxy = getCurrentSetupContext<{ proxy: { $nextTick: () => Promise<void> } }>()?.proxy\n  if (typeof proxy?.$nextTick !== 'function') {\n    throw new TypeError('scroll restoration 需要具有宿主提交屏障的 wevu setup 实例。')\n  }\n  return { instance, commit: () => proxy.$nextTick() }\n}\n\nexport function registerScrollRestoration<T extends object>(\n  options: UseScrollRestorationOptions<T>,\n  lifecycle?: { onBindPage?: (page: ScrollPage) => void, onStop?: () => void },\n): ScrollRestorationHandle {\n  const { instance, commit } = getScrollSetupScope()\n  const state = resolveScrollController(options.controller)\n  const cleanups: Array<() => void> = []\n  let page: ScrollPage | undefined\n  let route: ScrollRestorationContext['route'] | undefined\n  let stopped = false\n  let visible = true\n  let captured = false\n  let attempted = false\n  let request = 0\n  let instanceReady = Boolean(instance[WEVU_READY_CALLED_KEY])\n  let pageReady = false\n  let readyPromise: Promise<void> | undefined\n  let resolveReady: (() => void) | undefined\n  let registration: ScrollRegistration\n\n  function releaseReady() {\n    if (stopped || (instanceReady && pageReady)) {\n      resolveReady?.()\n    }\n  }\n\n  function bindPage() {\n    if (page || stopped) {\n      return\n    }\n    const owner = resolveScrollPage(instance)\n    if (!owner) {\n      return\n    }\n    const nextRoute = state.resolveRoute(owner)\n    registration.key = typeof options.key === 'function' ? options.key(nextRoute) : options.key ?? nextRoute.fullPath\n    const unregister = state.register(owner, registration)\n    page = owner\n    route = nextRoute\n    cleanups.push(unregister)\n    pageReady = Boolean(owner[WEVU_READY_CALLED_KEY])\n    cleanups.push(addScrollHook(owner, 'onReady', () => {\n      pageReady = true\n      releaseReady()\n      registration.restoreAutomatic()\n    }))\n    lifecycle?.onBindPage?.(owner)\n  }\n\n  async function scroll(): Promise<boolean> {\n    if (stopped || state.disposed) {\n      return false\n    }\n    bindPage()\n    if (!page || !route) {\n      throw new Error('无法确定 scroll restoration 的原生归属页面，请在页面 attached 后恢复。')\n    }\n    if (!visible || currentScrollPage() !== page) {\n      return false\n    }\n    const ticket = ++request\n    const generation = state.generation\n    const context: ScrollRestorationContext = {\n      route,\n      routeEventId: state.transition?.page === page ? state.transition.event.routeEventId : undefined,\n      isActive: () => !stopped && !state.disposed && visible && ticket === request\n        && generation === state.generation && currentScrollPage() === page,\n    }\n    if (!instanceReady || !pageReady) {\n      readyPromise ??= new Promise<void>((resolve) => {\n        resolveReady = resolve\n      })\n      await readyPromise\n    }\n    if (!context.isActive()) {\n      return false\n    }\n    const shouldMount = await getInitialNavigationPromise(page)\n    if (shouldMount === false || !context.isActive()) {\n      return false\n    }\n    await commit()\n    if (!context.isActive()) {\n      return false\n    }\n    // 同一个 key/id 的注册共享快照格式；格式由使用者的 T 契约约束。\n    const snapshot = state.read(registration.key, registration.id) as T | undefined\n    await options.restore(snapshot, context)\n    return context.isActive()\n  }\n\n  registration = {\n    key: '',\n    id: options.id ?? 'default',\n    capture() {\n      if (stopped || state.disposed || !page || !visible || captured) {\n        return\n      }\n      captured = true\n      try {\n        const snapshot = options.capture()\n        if (snapshot !== null && 'then' in snapshot && typeof snapshot.then === 'function') {\n          throw new TypeError('scroll restoration capture 必须同步返回快照，不能返回 Promise。')\n        }\n        state.save(registration.key, registration.id, snapshot)\n      }\n      catch (error) {\n        state.clear(registration.key, registration.id)\n        state.report(error)\n      }\n    },\n    invalidate() {\n      request++\n      resolveReady?.()\n      readyPromise = undefined\n      resolveReady = undefined\n    },\n    restoreAutomatic() {\n      const transition = state.transition\n      if (stopped || options.manual || attempted || !instanceReady || !pageReady\n        || !transition?.fresh || !transition.done || transition.page !== page) {\n        return\n      }\n      attempted = true\n      void scroll().catch(state.report)\n    },\n    stop() {\n      if (stopped) {\n        return\n      }\n      stopped = true\n      request++\n      releaseReady()\n      for (const cleanup of cleanups) {\n        cleanup()\n      }\n      cleanups.length = 0\n      lifecycle?.onStop?.()\n    },\n  }\n\n  function captureBeforeStop() {\n    // 生命周期销毁保留最后快照；显式 stop 只注销，不能撤销先前的 clear。\n    registration.capture()\n    registration.stop()\n  }\n\n  cleanups.push(\n    addScrollHook(instance, 'onAttached', bindPage),\n    addScrollHook(instance, 'onReady', () => {\n      bindPage()\n      instanceReady = true\n      releaseReady()\n      registration.restoreAutomatic()\n    }),\n    addScrollHook(instance, 'onShow', () => {\n      bindPage()\n      visible = true\n      captured = false\n    }),\n    addScrollHook(instance, 'onHide', () => {\n      registration.capture()\n      visible = false\n      registration.invalidate()\n    }),\n    addScrollHook(instance, 'onDetached', captureBeforeStop),\n    addScrollHook(instance, 'onUnload', captureBeforeStop),\n  )\n  onScopeDispose(captureBeforeStop)\n  bindPage()\n  registration.restoreAutomatic()\n  return {\n    automatic: state.controller.automatic && !options.manual,\n    scroll,\n    clear: () => {\n      bindPage()\n      if (page) {\n        state.clear(registration.key, registration.id)\n      }\n    },\n    stop: registration.stop,\n  }\n}\n\n/** 在同步 setup 中注册快照；只恢复新实例，不覆盖原生保留页的位置。 */\nexport function useScrollRestoration<T extends object>(options: UseScrollRestorationOptions<T>): ScrollRestorationHandle {\n  return registerScrollRestoration(options)\n}\n"],"mappings":"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"}

package/dist/dev/router/scrollRestoration/types.d.mts

@@ -0,0 +1,61 @@
+import { Ref } from "../../reactivity/ref.mjs";
+import "../../reactivity/index.mjs";
+import { RouteLocationNormalizedLoaded, RouterNavigation } from "../types.mjs";
+//#region src/router/scrollRestoration/types.d.ts
+export interface ScrollRestorationController {
+  /** 当前宿主是否支持带 routeEventId 的自动路由关联。 */
+  readonly automatic: boolean;
+  /** 清除整个会话或指定路由 key 的快照，不注销组件。 */
+  clear: (key?: string) => void;
+  /** 注销宿主监听、组件注册和未完成的恢复，并清空会话。 */
+  dispose: () => void;
+}
+export interface ScrollRestorationOptions<TRouteMap extends object = object> {
+  router: RouterNavigation<TRouteMap>;
+  /** 自动捕获或恢复失败时调用；手动 scroll 的错误由调用者处理。 */
+  onError?: (error: unknown) => void;
+}
+export interface ScrollRestorationContext {
+  readonly route: Readonly<RouteLocationNormalizedLoaded>;
+  readonly routeEventId?: string;
+  /** 异步自定义恢复在每次 await 后、写入宿主前必须重新检查。 */
+  isActive: () => boolean;
+}
+export interface ScrollRestorationRegistrationOptions {
+  controller?: ScrollRestorationController;
+  /** 默认使用包含 query 的 route.fullPath。 */
+  key?: string | ((route: Readonly<RouteLocationNormalizedLoaded>) => string);
+  /** 同一页面和路由 key 内的独立容器名，默认为 default。 */
+  id?: string;
+  /** 只捕获，不在原生路由完成后自动恢复。 */
+  manual?: boolean;
+}
+export interface UseScrollRestorationOptions<T extends object> extends ScrollRestorationRegistrationOptions {
+  /** 同步返回独立快照；不能返回响应式活动对象或 Promise，null 表示清除。 */
+  capture: () => (T & {
+    then?: never;
+  }) | null;
+  restore: (snapshot: T | undefined, context: ScrollRestorationContext) => void | Promise<void>;
+}
+export interface ScrollRestorationHandle {
+  readonly automatic: boolean;
+  /** 等待组件就绪及宿主提交后恢复；已离开或失效时返回 false。 */
+  scroll: () => Promise<boolean>;
+  /** 只清除当前 key/id 的快照。 */
+  clear: () => void;
+  /** 停止当前注册；保留已捕获快照。 */
+  stop: () => void;
+}
+export interface ScrollViewRestorationHandle extends ScrollRestorationHandle {
+  scrollTop: Ref<number>;
+  scrollLeft: Ref<number>;
+  /** 绑定 scroll-view 的 scroll 事件，只更新非响应式缓存。 */
+  onScroll: (event: {
+    detail: {
+      scrollTop: number;
+      scrollLeft: number;
+    };
+  }) => void;
+}
+//#endregion
+//# sourceMappingURL=types.d.mts.map

package/dist/dev/router/useRoute.mjs

@@ -3,11 +3,11 @@ import { readonly } from "../reactivity/readonly.mjs";
 import { getCurrentMiniProgramPages } from "../runtime/platform.mjs";
 import { getCurrentSetupContext } from "../runtime/hooks/base.mjs";
 import { onLoad, onReady, onRouteDone, onShow, onUnload } from "../runtime/hooks/register.mjs";
-import { getActiveRouter } from "./instance.mjs";
 import { registerRouteStateSyncHandler } from "./routeSync.mjs";
 import { resolveCurrentRoute, resolvePageRoute } from "../routerInternal/location.mjs";
 import { cloneLocationQuery, cloneRouteLocationRedirectedFrom, cloneRouteMeta, cloneRouteParams, cloneRouteRecordMatchedList } from "../routerInternal/snapshots.mjs";
 import { useNativePageRouter as useNativePageRouter$1, useNativeRouter as useNativeRouter$1 } from "../runtime/vueCompat/router.mjs";
+import { getActiveRouter } from "./instance.mjs";
 import { resolveRouteLocation } from "./resolve.mjs";
 import { WEVU_NATIVE_INSTANCE_KEY } from "@weapp-core/constants";
 
@@ -20,10 +20,10 @@ function resolveRouteControllerInstance(instance) {
 	return nativeInstance && typeof nativeInstance === "object" ? nativeInstance : instance;
 }
 function shouldSyncRouteStateForInstance(instance, isPageController, payload) {
-	if ((payload === null || payload === void 0 ? void 0 : payload.source) === "router") return true;
+	if (payload?.source === "router") return true;
 	if (!isPageController) return true;
 	const routeControllerInstance = resolveRouteControllerInstance(instance);
-	if (payload === null || payload === void 0 ? void 0 : payload.page) return payload.page === routeControllerInstance;
+	if (payload?.page) return payload.page === routeControllerInstance;
 	const pages = getCurrentMiniProgramPages();
 	return pages[pages.length - 1] === routeControllerInstance;
 }
@@ -45,13 +45,9 @@ function applyRouteState(routeState, nextRoute) {
 	else routeState.redirectedFrom = cloneRouteLocationRedirectedFrom(nextRoute.redirectedFrom);
 }
 function createRouteStateController(options = {}) {
-	var _options$resolveRoute;
 	const setupContext = getCurrentSetupContext();
-	const fallbackPage = (setupContext === null || setupContext === void 0 ? void 0 : setupContext.instance) && typeof setupContext.instance === "object" ? setupContext.instance : void 0;
-	const resolveRoute = (_options$resolveRoute = options.resolveRoute) !== null && _options$resolveRoute !== void 0 ? _options$resolveRoute : ((route) => {
-		var _getActiveRouter$reso, _getActiveRouter;
-		return (_getActiveRouter$reso = (_getActiveRouter = getActiveRouter()) === null || _getActiveRouter === void 0 ? void 0 : _getActiveRouter.resolve(route)) !== null && _getActiveRouter$reso !== void 0 ? _getActiveRouter$reso : route;
-	});
+	const fallbackPage = setupContext?.instance && typeof setupContext.instance === "object" ? setupContext.instance : void 0;
+	const resolveRoute = options.resolveRoute ?? ((route) => getActiveRouter()?.resolve(route) ?? route);
 	const currentRoute = resolveRoute(resolveCurrentRoute(void 0, fallbackPage));
 	const routeState = reactive({
 		path: currentRoute.path,
@@ -63,23 +59,20 @@ function createRouteStateController(options = {}) {
 	applyRouteState(routeState, currentRoute);
 	function syncRoute(queryOverride, routeOverride, payload) {
 		const nextRoute = routeOverride ? resolveRoute(routeOverride) : resolveRoute(resolveCurrentRoute(queryOverride, fallbackPage));
-		if (payload) {
-			var _options$beforeRouteS;
-			(_options$beforeRouteS = options.beforeRouteStateSync) === null || _options$beforeRouteS === void 0 || _options$beforeRouteS.call(options, nextRoute, payload);
-		}
+		if (payload) options.beforeRouteStateSync?.(nextRoute, payload);
 		applyRouteState(routeState, nextRoute);
 	}
 	if (!fallbackPage) {
 		registerRouteStateSyncHandler((payload) => {
-			if (payload === null || payload === void 0 ? void 0 : payload.route) {
+			if (payload?.route) {
 				syncRoute(void 0, payload.route, payload);
 				return;
 			}
-			if (payload === null || payload === void 0 ? void 0 : payload.url) {
+			if (payload?.url) {
 				syncRoute(void 0, resolveRouteLocation(payload.url, routeState.path), payload);
 				return;
 			}
-			if (payload === null || payload === void 0 ? void 0 : payload.page) {
+			if (payload?.page) {
 				syncRoute(void 0, resolvePageRoute(payload.page), payload);
 				return;
 			}
@@ -104,15 +97,15 @@ function createRouteStateController(options = {}) {
 	});
 	const unregisterRouteStateSync = registerRouteStateSyncHandler((payload) => {
 		if (!shouldSyncRouteStateForInstance(pageInstance, isPageController, payload)) return;
-		if (payload === null || payload === void 0 ? void 0 : payload.route) {
+		if (payload?.route) {
 			syncRoute(void 0, payload.route, payload);
 			return;
 		}
-		if (payload === null || payload === void 0 ? void 0 : payload.url) {
+		if (payload?.url) {
 			syncRoute(void 0, resolveRouteLocation(payload.url, routeState.path), payload);
 			return;
 		}
-		if (payload === null || payload === void 0 ? void 0 : payload.page) {
+		if (payload?.page) {
 			syncRoute(void 0, resolvePageRoute(payload.page), payload);
 			return;
 		}