@ubean/vue 0.2.0

package/dist/index.js

@@ -0,0 +1,1073 @@
+import { KeepAlive, Suspense, Transition, computed, createCommentVNode, defineAsyncComponent, defineComponent, h, inject, nextTick, onErrorCaptured, provide, reactive, ref, shallowRef, watch } from "vue";
+import { RouterLink, RouterView, useRoute } from "vue-router";
+//#region src/cache-views.ts
+/**
+* Page cache (keep-alive) store — a module-level singleton.
+*
+* ubean uses flat single-layer layout, so all page components are direct
+* children of a single layout's `<RouterView>`. A `<keep-alive :include="...">`
+* wraps that `<RouterView>`; the `include` list is the reactive array exposed
+* here. Caching is keyed by the page's **route name**, which is injected as the
+* component `name` at render time (see `createLayoutWrapper` in `app.ts`).
+*
+* In addition to the `include` list, an `exclude` list is also maintained.
+* `<keep-alive :exclude="...">` skips caching for matched names even if they
+* appear in `include`. This is useful for the "reload current page" pattern:
+* temporarily push a route name into `exclude`, wait a tick, then remove it —
+* the cached instance is pruned and the page remounts fresh on next visit.
+*
+* Usage:
+*   // declarative (compile-time): enable caching for a page
+*   definePage({ cache: true })
+*
+*   // runtime: toggle caching imperatively
+*   import { enablePageCache, disablePageCache } from '@ubean/client';
+*   enablePageCache('DashboardIndex');
+*   disablePageCache('DashboardIndex');
+*
+*   // reload a cached page (clears its instance, forces remount)
+*   import { resetRouteCache } from '@ubean/client';
+*   await resetRouteCache('DashboardIndex');
+*/
+const _g$1 = globalThis;
+const _cachedViewNames = _g$1.__ubeanCachedViewNames ??= ref([]);
+const _excludedViewNames = _g$1.__ubeanExcludedViewNames ??= ref([]);
+const _cacheEnabled = _g$1.__ubeanCacheEnabled ??= ref(true);
+const _wrapperRegistry = _g$1.__ubeanWrapperRegistry ??= /* @__PURE__ */ new Map();
+/**
+* Composable for reactive access to the page cache store.
+*
+* Safe to call inside any component `setup()`; the returned computeds are
+* tracked by the rendering effect so `<keep-alive :include>` stays in sync.
+*/
+function useCacheViews() {
+	return {
+		cachedViews: computed(() => _cacheEnabled.value ? _cachedViewNames.value : []),
+		cachedViewNames: computed(() => _cachedViewNames.value),
+		excludedViews: computed(() => _excludedViewNames.value),
+		enabled: computed(() => _cacheEnabled.value),
+		enable: () => {
+			_cacheEnabled.value = true;
+		},
+		disable: () => {
+			_cacheEnabled.value = false;
+		},
+		add: (name) => {
+			if (name && !_cachedViewNames.value.includes(name)) _cachedViewNames.value = [..._cachedViewNames.value, name];
+		},
+		remove: (name) => {
+			_cachedViewNames.value = _cachedViewNames.value.filter((n) => n !== name);
+		},
+		has: (name) => _cachedViewNames.value.includes(name),
+		clear: () => {
+			_cachedViewNames.value = [];
+		},
+		addExclude: (name) => {
+			if (name && !_excludedViewNames.value.includes(name)) _excludedViewNames.value = [..._excludedViewNames.value, name];
+		},
+		removeExclude: (name) => {
+			_excludedViewNames.value = _excludedViewNames.value.filter((n) => n !== name);
+		},
+		hasExclude: (name) => _excludedViewNames.value.includes(name),
+		clearExclude: () => {
+			_excludedViewNames.value = [];
+		}
+	};
+}
+/** Enable keep-alive caching for a specific page (by route name). */
+function enablePageCache(name) {
+	if (name && !_cachedViewNames.value.includes(name)) _cachedViewNames.value = [..._cachedViewNames.value, name];
+}
+/** Disable keep-alive caching for a specific page (by route name). */
+function disablePageCache(name) {
+	_cachedViewNames.value = _cachedViewNames.value.filter((n) => n !== name);
+}
+/**
+* Temporarily exclude a page from keep-alive (forces its cached instance
+* to be pruned on next render). Pair with `includePageCache()` to restore.
+*
+* Useful for the "reload current page" pattern: push the route name into
+* the exclude list, wait a tick, then remove it — the cached instance is
+* pruned and the page remounts fresh on next render.
+*/
+function excludePageCache(name) {
+	if (name && !_excludedViewNames.value.includes(name)) _excludedViewNames.value = [..._excludedViewNames.value, name];
+}
+/** Remove a route name from the cache exclude list (restores caching). */
+function includePageCache(name) {
+	_excludedViewNames.value = _excludedViewNames.value.filter((n) => n !== name);
+}
+/** Whether a specific page is currently excluded from cache. */
+function isPageExcluded(name) {
+	return _excludedViewNames.value.includes(name);
+}
+/**
+* Reload a cached page by pruning its keep-alive instance.
+*
+* Semantics (mirrors `routeStore.resetRouteCache` in soybean-unify):
+*   1. Remove the route name from the include list — the cached instance is
+*      pruned immediately, and when the user navigates away the instance is
+*      destroyed instead of being re-cached.
+*   2. The original `meta.cache` declaration is restored automatically on the
+*      next navigation away from the page (hooked by `createUbeanRouter`'s
+*      `afterEach`), so the NEXT visit mounts a fresh instance which is
+*      cached again as declared.
+*
+* Note: pruning cannot take effect while the user stays on the page —
+* `<KeepAlive>` re-caches the active instance on every render while its name
+* is in the include list. To force an in-place remount of the current page,
+* use `reloadPage(name)` instead (bumps the render key).
+*
+* @param name Route name. If omitted, this is a no-op.
+* @param delay Ignored — kept for signature compatibility with the previous
+*              exclude→include implementation.
+*/
+async function resetRouteCache(name, _delay) {
+	const target = name;
+	if (!target) return;
+	if (!_cachedViewNames.value.includes(target)) return;
+	disablePageCache(target);
+	_pendingReincludes.add(target);
+}
+/**
+* Route names whose cache declaration should be restored once the user has
+* navigated away from the page (populated by `resetRouteCache`).
+*/
+const _pendingReincludes = /* @__PURE__ */ new Set();
+/**
+* Restore cache declarations for pages whose cache was reset via
+* `resetRouteCache` once they are no longer the active page.
+*
+* @internal — called from `createUbeanRouter`'s `afterEach` hook.
+*/
+function _flushPendingReincludes(currentPageName) {
+	if (_pendingReincludes.size === 0) return;
+	for (const name of _pendingReincludes) if (name !== currentPageName) {
+		enablePageCache(name);
+		_pendingReincludes.delete(name);
+	}
+}
+/**
+* Invalidate cached page instance(s).
+*
+* - With a `name`: removes that page from the cache (its instance is pruned
+*   on next navigation).
+* - Without a `name`: clears all cached pages.
+*
+* Note: the page will be re-cached on next visit if its `definePage({ cache: true })`
+* is still in effect or `enablePageCache(name)` is called again.
+*/
+function invalidatePageCache(name) {
+	if (name) disablePageCache(name);
+	else _cachedViewNames.value = [];
+}
+/** Whether a specific page is currently cached. */
+function isPageCached(name) {
+	return _cachedViewNames.value.includes(name);
+}
+/** Whether page caching is globally enabled. */
+function isCacheEnabled() {
+	return _cacheEnabled.value;
+}
+/** Reactive ref of cached route names — for advanced use cases. */
+function getCachedViewNames() {
+	return _cachedViewNames;
+}
+/** Reactive ref of excluded route names — for advanced use cases. */
+function getExcludedViewNames() {
+	return _excludedViewNames;
+}
+/** Reactive ref of the global cache-enabled flag. */
+function getCacheEnabled() {
+	return _cacheEnabled;
+}
+/**
+* Seed the cache include list from route metadata.
+*
+* Called once during app bootstrap (`createUbeanClientApp`) to honor pages that
+* declared `definePage({ cache: true })`. Routes without `meta.cache` are
+* left untouched so runtime toggling remains possible.
+*/
+function initCachedViewsFromRoutes(routes) {
+	const initial = [];
+	for (const route of routes) if (route.meta?.cache === true && typeof route.name === "string" && route.name) {
+		if (!initial.includes(route.name)) initial.push(route.name);
+	}
+	if (initial.length > 0) {
+		const existing = new Set(_cachedViewNames.value);
+		for (const name of initial) if (!existing.has(name)) existing.add(name);
+		_cachedViewNames.value = [...existing];
+	}
+}
+/**
+* Get or create a named wrapper component for a page.
+*
+* The wrapper carries the route name as its component `name`, which is what
+* `<keep-alive :include>` matches against. The original page component is
+* rendered inside the wrapper. When the original changes (HMR in dev), the
+* wrapper is rebuilt so the new component takes effect.
+*
+* @internal — used by `createLayoutWrapper` in `app.ts`.
+*/
+function getNamedPageWrapper(routeName, original) {
+	const cached = _wrapperRegistry.get(routeName);
+	if (cached && cached.original === original) return cached.wrapper;
+	const wrapper = defineComponent({
+		name: routeName,
+		setup() {
+			return () => h(original);
+		}
+	});
+	_wrapperRegistry.set(routeName, {
+		wrapper,
+		original
+	});
+	return wrapper;
+}
+/**
+* Clear the wrapper registry. Mainly useful in tests or when the entire
+* route table is rebuilt.
+*
+* @internal
+*/
+function resetNamedPageWrappers() {
+	_wrapperRegistry.clear();
+}
+//#endregion
+//#region src/page-runtime.ts
+/**
+* Global page runtime config — animation mode + reload signal.
+*
+* These module-level singletons mirror the patterns found in soybean-unify's
+* `themeStore.pageAnimateMode` and `appStore.reloadSignal`:
+*
+*   - `pageAnimateMode` is a global transition name applied to every
+*     `<PageView />` unless overridden by the `transition` prop or
+*     `route.meta.transition`. Set to `'none'` (or empty string) to disable
+*     transitions globally.
+*
+*   - `reloadSignal` is a counter that increments each time `reloadPage()` is
+*     called. `<PageView />` watches this counter (via `:key`) and remounts
+*     the current page when it changes — for cached pages the keep-alive
+*     instance is pruned and rebuilt around the remount so it is fresh.
+*
+* These are intentionally framework-provided singletons (not pinia stores)
+* because ubean ships without a state management library and the values are
+* globally unique by nature.
+*/
+const _g = globalThis;
+const _pageTransitionName = _g.__ubeanPageTransitionName ??= ref("");
+const _reloadCounter = _g.__ubeanReloadCounter ??= ref(0);
+/**
+* Composable for reactive access to the global page transition name.
+*
+* Used by `<PageView />` as the fallback transition name when neither the
+* `transition` prop nor `route.meta.transition` is set.
+*
+* Layout components can also read this to display a settings UI:
+*
+* ```ts
+* const transition = usePageTransition();
+* // transition.name.value === 'fade-slide'
+* transition.set('zoom-fadein');
+* transition.clear();
+* ```
+*/
+function usePageTransition() {
+	return {
+		name: computed(() => _pageTransitionName.value),
+		set: (name) => {
+			_pageTransitionName.value = name === "none" ? "" : name;
+		},
+		clear: () => {
+			_pageTransitionName.value = "";
+		},
+		enabled: computed(() => _pageTransitionName.value !== "")
+	};
+}
+/** Imperatively set the global page transition name. */
+function setPageTransition(name) {
+	_pageTransitionName.value = name === "none" ? "" : name;
+}
+/** Imperatively clear the global page transition name (disables transitions). */
+function clearPageTransition() {
+	_pageTransitionName.value = "";
+}
+/** Reactive ref of the global transition name — for advanced use cases. */
+function getPageTransitionName() {
+	return _pageTransitionName;
+}
+/**
+* Composable for reactive access to the page reload signal.
+*
+* `<PageView />` uses the returned `counter` as part of its render key, so
+* each `reload()` call forces the current page to remount. For cached pages
+* the stale keep-alive instance is pruned around the remount (see
+* `_remountWithFreshCache`), so the remount is fresh while the cache
+* declaration stays in effect — equivalent to the
+* `v-if="appStore.reloadSignal"` pattern in soybean-unify's layout-content.
+*
+* Usage from any component:
+*
+* ```ts
+* const { reload } = useReloadSignal();
+* async function onReloadClick() {
+*   await reload(); // reloads the current page
+* }
+* ```
+*
+* @param routeNameGetter Optional function returning the current route name.
+*                        If provided (and `reload()` is called without an
+*                        explicit name), used to prune/rebuild that page's
+*                        cache around the remount. If omitted, `reload()`
+*                        only bumps the counter.
+*/
+/**
+* Internal flag — while `true`, `<PageView>` forces its `<Transition>` mode
+* to `'default'` (defensive: the reload sequence below never enters the
+* leave path, but if a stray re-render does, 'default' mode produces no
+* hollow placeholders).
+*
+* @internal — consumed by `components.ts` (same package).
+*/
+const _reloading = _g.__ubeanReloading ??= ref(false);
+/**
+* Internal blank flag — while `true`, `<PageView>`'s `<KeepAlive>` slot
+* renders a comment vnode instead of the page. Drives the reload sequence
+* in `_remountWithFreshCache`.
+*
+* @internal — consumed by `components.ts` (same package).
+*/
+const _reloadBlank = _g.__ubeanReloadBlank ??= ref(false);
+/**
+* Per-page reload counts — ONLY the reloaded page's key changes, so other
+* pages' KeepAlive cache entries (keyed by vnode key) stay valid across an
+* unrelated page's reload. (A global counter in the key would invalidate
+* every page's cache on any reload.)
+*
+* @internal — consumed by `components.ts` (same package).
+*/
+const _pageReloadCounts = _g.__ubeanPageReloadCounts ??= reactive(/* @__PURE__ */ new Map());
+/**
+* Internal reload driver — remounts the current page fresh via a brief
+* blank window (the `v-if="reloadSignal"` pattern from soybean-unify):
+*
+*   1. Enter reload mode (Transition falls back to 'default' mode).
+*   2. Blank the KeepAlive slot — the old page instance deactivates
+*      (cached) or unmounts; KeepAlive renders a comment. A comment inner
+*      child makes `<Transition>` skip its leave branch entirely, so Vue
+*      never produces an `emptyPlaceholder` hollow KeepAlive (children=null)
+*      whose patch crashes `updateSlots` (`Cannot read properties of null
+*      (reading '_')` — vue@3.5.41, same family as vuejs/core#10771).
+*   3. Prune the stale old-key cache entry via an include toggle
+*      (disable→enable) — safe while the KeepAlive child is blank: include
+*      changes only affect the cache set, never a hollow-vnode patch.
+*   4. Bump the page's reload count (new key) and un-blank in the same
+*      flush — the fresh page mounts; the enter transition plays. The
+*      global counter also bumps so `useReloadSignal().counter` consumers
+*      stay in sync.
+*   5. Leave reload mode.
+*
+* Without a `name` there is no way to target a page's key, so the call is
+* signal-only (global counter bump, no remount).
+*/
+async function _remountWithFreshCache(name) {
+	if (!name) {
+		_reloadCounter.value++;
+		return;
+	}
+	_reloading.value = true;
+	_reloadBlank.value = true;
+	await nextTick();
+	if (isPageCached(name)) {
+		disablePageCache(name);
+		await nextTick();
+		enablePageCache(name);
+		await nextTick();
+	}
+	_pageReloadCounts.set(name, (_pageReloadCounts.get(name) ?? 0) + 1);
+	_reloadCounter.value++;
+	_reloadBlank.value = false;
+	await nextTick();
+	_reloading.value = false;
+}
+function useReloadSignal(routeNameGetter) {
+	return {
+		counter: computed(() => _reloadCounter.value),
+		reloading: computed(() => _reloading.value),
+		reload: async (routeName, duration = 300) => {
+			_reloading.value = true;
+			try {
+				await _remountWithFreshCache(routeName ?? routeNameGetter?.());
+				await new Promise((resolve) => setTimeout(resolve, duration));
+			} finally {
+				_reloading.value = false;
+			}
+		}
+	};
+}
+/**
+* Imperatively trigger a page reload.
+*
+* - `name`: route name to reload (REQUIRED for an actual remount). The page
+*   is blanked, its stale keep-alive entry pruned, and a fresh instance
+*   mounts under a new key — while its cache declaration stays in effect.
+*   Only THIS page's key changes: other pages' keep-alive entries survive.
+*   If omitted, the call is signal-only (the global counter bumps for
+*   `useReloadSignal().counter` consumers; nothing remounts).
+* - `duration`: milliseconds to wait for transition/cleanup. Defaults to 300.
+*/
+async function reloadPage(name, duration = 300) {
+	_reloading.value = true;
+	try {
+		await _remountWithFreshCache(name);
+		await new Promise((resolve) => setTimeout(resolve, duration));
+	} finally {
+		_reloading.value = false;
+	}
+}
+/** Reactive ref of the reload counter — for advanced use cases. */
+function getReloadCounter() {
+	return _reloadCounter;
+}
+/** Whether a reload is currently in progress. */
+function isReloading() {
+	return _reloading.value;
+}
+//#endregion
+//#region src/view-transitions.ts
+const _global = globalThis;
+let _typesSupported = null;
+function supportsTransitionTypes() {
+	if (_typesSupported !== null) return _typesSupported;
+	if (!supportsViewTransitions()) {
+		_typesSupported = false;
+		return false;
+	}
+	try {
+		let calledWithObject = false;
+		const doc = _global.document;
+		const orig = doc.startViewTransition;
+		doc.startViewTransition = function(opts) {
+			if (opts && typeof opts === "object" && "update" in opts) calledWithObject = true;
+			return {
+				finished: Promise.resolve(),
+				ready: Promise.resolve(),
+				updateCallbackDone: Promise.resolve(),
+				skipTransition() {}
+			};
+		};
+		try {
+			doc.startViewTransition({
+				update: () => {},
+				types: ["test"]
+			});
+		} catch {}
+		doc.startViewTransition = orig;
+		_typesSupported = calledWithObject;
+	} catch {
+		_typesSupported = false;
+	}
+	return _typesSupported;
+}
+function supportsViewTransitions() {
+	if (typeof _global.document === "undefined") return false;
+	return typeof _global.document.startViewTransition === "function";
+}
+async function withViewTransition(callback, options = {}) {
+	const { enabled = true, types } = options;
+	if (!enabled || !supportsViewTransitions()) return callback();
+	const doc = _global.document;
+	const useTypesApi = types && types.length > 0 && supportsTransitionTypes();
+	let result;
+	let callbackError;
+	let callbackFailed = false;
+	const updateCallback = async () => {
+		try {
+			result = await callback();
+		} catch (e) {
+			callbackFailed = true;
+			callbackError = e;
+			throw e;
+		}
+	};
+	let transition;
+	if (useTypesApi) transition = doc.startViewTransition({
+		update: updateCallback,
+		types
+	});
+	else transition = doc.startViewTransition(updateCallback);
+	try {
+		await transition.finished;
+	} catch (err) {
+		if (callbackFailed) throw callbackError;
+		throw err;
+	}
+	if (callbackFailed) throw callbackError;
+	return result;
+}
+function getNavigationType() {
+	try {
+		const nav = _global.navigation;
+		if (nav?.currentEntry && nav?.transitionType) return nav.transitionType;
+	} catch {}
+	return "push";
+}
+function useViewTransitionState(name) {
+	return { style: `view-transition-name: ${name};` };
+}
+//#endregion
+//#region src/components.ts
+/**
+* @ubean/vue — lean components & plugin.
+*
+* Hard boundary of this module (and the whole package):
+*  - dependencies are `vue` + `vue-router` ONLY — no `@ubean/*`, no `node:*`,
+*    no `@unhead/vue`
+*  - no i18n: `Link` renders paths verbatim unless a localizer is provided
+*    via `LOCALIZE_PATH_KEY` (the framework runtime `@ubean/client` provides
+*    the reactive `localizePath`; lean SPAs simply don't)
+*  - no islands directive: the `v-client` directive is a framework concern
+*    (`@ubean/client` registers it inside its app factories)
+*/
+/**
+* Injection keys (exported for advanced use cases — e.g. testing utilities
+* that need to provide the page/transition context outside the plugin).
+*/
+const PAGE_KEY = Symbol("ubean-page");
+const TRANSITION_KEY = Symbol("ubean-transition");
+const SSR_KEY = Symbol("ubean-ssr");
+const LOADING_KEY = Symbol("ubean-loading");
+const ERROR_KEY = Symbol("ubean-error");
+/**
+* Module-level reload placeholder — a single comment vnode reused across
+* renders while `_reloadBlank` is active (see the KeepAlive slot in
+* `PageView` for why it must be a comment, not null).
+*/
+const _reloadPlaceholder = createCommentVNode("ubean-reload");
+/** Dev-only one-shot flag for the out-in degradation warning. */
+let _warnedOutIn = false;
+/**
+* Injectable path localizer (optional i18n bridge). The framework runtime
+* (`@ubean/client`) provides the reactive `localizePath`; when absent,
+* `Link` renders paths verbatim — this package never imports i18n itself.
+*/
+const LOCALIZE_PATH_KEY = Symbol("ubean-localize-path");
+const LAYOUT_CHAIN_KEY = Symbol("ubean-layout-chain");
+/**
+* LayoutChainRenderer — recursively renders a chain of nested layout
+* components (framework factories build the chain; lean SPAs may use it
+* directly for nested layouts via render functions).
+*/
+const LayoutChainRenderer = defineComponent({
+	name: "UbeanLayoutChain",
+	props: {
+		components: {
+			type: Array,
+			required: true
+		},
+		depth: {
+			type: Number,
+			default: 0
+		}
+	},
+	setup(props) {
+		provide(LAYOUT_CHAIN_KEY, {
+			get components() {
+				return props.components;
+			},
+			get depth() {
+				return props.depth;
+			}
+		});
+		return () => {
+			const comp = props.components[props.depth];
+			if (!comp) return h(PageView);
+			return h(comp);
+		};
+	}
+});
+/**
+* ErrorBoundary — catches rendering, async resolution, and setup errors
+* from descendant components. When an error is caught, renders the
+* configured `errorComponent` instead of the slot content. The error state
+* resets automatically on route change.
+*/
+const ErrorBoundary = defineComponent({
+	name: "UbeanErrorBoundary",
+	props: { component: {
+		type: [Object, Function],
+		default: null
+	} },
+	setup(props, { slots }) {
+		const error = shallowRef(null);
+		const route = useRoute();
+		watch(() => route.fullPath, () => {
+			error.value = null;
+		});
+		onErrorCaptured((err) => {
+			error.value = err;
+			return false;
+		});
+		return () => {
+			if (error.value && props.component) return h(props.component, { error: error.value });
+			return slots.default?.();
+		};
+	}
+});
+/**
+* PageView — renders the matched route page wrapped with `<Transition>` and
+* `<KeepAlive>`. Layouts use `<PageView />` (instead of `<slot />`) as the
+* page outlet.
+*
+* Equivalents of soybean-unify's layout-content pattern:
+*   - `pageAnimateMode` → `transition` prop + `route.meta.transition` + global `usePageTransition()`
+*   - `cachedRoutes` / `excludeCachedRoutes` → `useCacheViews().cachedViews` / `excludedViews`
+*   - `reloadSignal` → `useReloadSignal().counter` (incremented by `reloadPage()`)
+*
+* Props:
+* - `transition`: transition name (string) or `false` to disable.
+*   Priority: prop > `route.meta.transition` > global `usePageTransition()`.
+* - `reloadKey`: a reactive key — changing it forces remount (reload).
+*   When omitted, falls back to `route.fullPath` + per-page reload count.
+* - `mode`: Vue `<Transition>` mode. Defaults to `'default'` (cross-fade —
+*   old page plays its leave while the new one enters, both driven through
+*   KeepAlive's delayLeave). `'out-in'` is DEGRADED to `'default'` with a
+*   dev warning: vue@3.5.41's `out-in` renders an `emptyPlaceholder` hollow
+*   KeepAlive on page swaps, which crashes hand-written render chains
+*   (`updateSlots` reading `children._`) and corrupts keep-alive cache
+*   state on compiled chains (vuejs/core#10771 family). Revisit when the
+*   upstream fix lands.
+*
+* On SSR (via `SSR_KEY`), KeepAlive/Transition/Suspense/ErrorBoundary are
+* skipped (client-only concepts).
+*/
+const PageView = defineComponent({
+	name: "PageView",
+	props: {
+		transition: {
+			type: [String, Boolean],
+			default: void 0
+		},
+		reloadKey: {
+			type: [String, Number],
+			default: void 0
+		},
+		mode: {
+			type: String,
+			default: "default"
+		}
+	},
+	setup(props) {
+		const { cachedViews, excludedViews } = useCacheViews();
+		const globalTransition = usePageTransition();
+		const ssr = inject(SSR_KEY, false);
+		const loadingComp = inject(LOADING_KEY, null);
+		const errorComp = inject(ERROR_KEY, null);
+		const layoutChain = inject(LAYOUT_CHAIN_KEY, null);
+		const route = useRoute();
+		watch(() => route.fullPath, () => {
+			_flushPendingReincludes(route.meta?.pageName ?? (typeof route.name === "string" ? route.name : void 0));
+		}, { flush: "post" });
+		return () => {
+			if (layoutChain && layoutChain.depth < layoutChain.components.length - 1) return h(LayoutChainRenderer, {
+				components: layoutChain.components,
+				depth: layoutChain.depth + 1
+			});
+			return h(RouterView, null, { default: ({ Component, route: $route }) => {
+				if (!Component) return null;
+				if (ssr) return Component;
+				const rawComp = Component.type;
+				const pageName = $route.meta?.pageName;
+				const comp = pageName ? getNamedPageWrapper(pageName, rawComp) : rawComp;
+				const componentProps = Component.props || {};
+				const routeTransition = $route.meta?.transition;
+				const transitionName = props.transition === false ? void 0 : props.transition || routeTransition || globalTransition.name.value || void 0;
+				const pageReloadCount = pageName ? _pageReloadCounts.get(pageName) ?? 0 : 0;
+				const pageVNode = h(comp, {
+					...componentProps,
+					key: props.reloadKey ?? `${$route.fullPath}#${pageReloadCount}`
+				});
+				const keepAliveProps = { include: cachedViews.value };
+				if (excludedViews.value.length > 0) keepAliveProps.exclude = excludedViews.value;
+				const keepAliveVNode = h(KeepAlive, keepAliveProps, { default: () => _reloadBlank.value ? _reloadPlaceholder : pageVNode });
+				const contentVNode = !ssr && loadingComp ? h(Suspense, null, {
+					default: () => keepAliveVNode,
+					fallback: () => h(loadingComp)
+				}) : keepAliveVNode;
+				const transitionVNode = h(Transition, {
+					name: transitionName ?? "",
+					mode: _reloading.value || props.mode === "out-in" ? "default" : props.mode,
+					appear: !!transitionName
+				}, { default: () => contentVNode });
+				if (props.mode === "out-in" && import.meta.env?.DEV && !_warnedOutIn) {
+					_warnedOutIn = true;
+					console.warn("[PageView] mode=\"out-in\" is degraded to \"default\": vue@3.5.41 out-in + KeepAlive trips emptyPlaceholder bugs (updateSlots crash on hand-written chains, cache corruption on compiled chains). Using cross-fade instead.");
+				}
+				if (!ssr && errorComp) return h(ErrorBoundary, { component: errorComp }, { default: () => transitionVNode });
+				return transitionVNode;
+			} });
+		};
+	}
+});
+/**
+* SlotView — renders a named parallel route slot. Parallel routes are
+* registered as Vue Router named views on the matched route record;
+* `<SlotView name="analytics" />` resolves the slot component from the
+* current route (deepest matched record exposing the slot wins).
+*
+* Resolution is independent of RouterView depth chaining, so SlotView works
+* both as a sibling of `<PageView />` and inside the default view page
+* component (a nested `<RouterView>` there would look at depth + 1 and
+* never find the named view).
+*/
+const SlotView = defineComponent({
+	name: "SlotView",
+	props: { name: {
+		type: String,
+		required: true
+	} },
+	setup(props) {
+		const route = useRoute();
+		const asyncWrappers = /* @__PURE__ */ new Map();
+		const resolveSlot = () => {
+			for (let i = route.matched.length - 1; i >= 0; i--) {
+				const components = route.matched[i].components;
+				if (components && props.name in components) return components[props.name];
+			}
+			return null;
+		};
+		return () => {
+			const comp = resolveSlot();
+			if (!comp) return createCommentVNode(`slot-view:${props.name}`);
+			const fn = comp;
+			if (typeof comp === "function" && !fn.render && !fn.setup) {
+				let wrapper = asyncWrappers.get(props.name);
+				if (!wrapper) {
+					wrapper = defineAsyncComponent(() => comp());
+					asyncWrappers.set(props.name, wrapper);
+				}
+				return h(wrapper);
+			}
+			return h(comp);
+		};
+	}
+});
+/**
+* Link — internal links render via RouterLink; external links (`http*`,
+* `//`, `#`) render as native `<a target="_blank" rel="noopener noreferrer">`.
+*
+* Path localization is opt-in via `LOCALIZE_PATH_KEY` (provided by the
+* framework runtime); lean SPAs render paths verbatim.
+*/
+const Link = defineComponent({
+	name: "Link",
+	props: {
+		to: {
+			type: [String, Object],
+			default: void 0
+		},
+		href: {
+			type: String,
+			default: void 0
+		},
+		replace: {
+			type: Boolean,
+			default: false
+		},
+		prefetch: {
+			type: Boolean,
+			default: false
+		},
+		activeClass: {
+			type: String,
+			default: "router-link-active"
+		},
+		exactActiveClass: {
+			type: String,
+			default: "router-link-exact-active"
+		},
+		noActiveClass: {
+			type: Boolean,
+			default: false
+		}
+	},
+	setup(props, { slots, attrs }) {
+		const localize = inject(LOCALIZE_PATH_KEY, null);
+		const resolvedTo = computed(() => {
+			const path = props.to ?? props.href ?? "";
+			if (typeof path === "string" && (path.startsWith("http") || path.startsWith("//") || path.startsWith("#"))) return path;
+			return localize ? localize(path) : path;
+		});
+		const isExternal = computed(() => {
+			const path = String(resolvedTo.value);
+			return path.startsWith("http") || path.startsWith("//") || path.startsWith("#");
+		});
+		return () => {
+			if (isExternal.value) return h("a", {
+				...attrs,
+				href: resolvedTo.value,
+				target: "_blank",
+				rel: "noopener noreferrer"
+			}, slots.default ? slots.default() : void 0);
+			return h(RouterLink, {
+				...attrs,
+				to: resolvedTo.value,
+				replace: props.replace,
+				activeClass: props.noActiveClass ? "" : props.activeClass,
+				exactActiveClass: props.noActiveClass ? "" : props.exactActiveClass
+			}, slots.default);
+		};
+	}
+});
+const _EMPTY_PAGE_DATA = {};
+/**
+* `usePage()` — 读取 `PAGE_KEY` 注入的页面数据(精简版:仅 pageData)。
+*
+* 路由驱动的 url/params/query 请使用 vue-router 的 `useRoute()`;
+* 导航请使用 vue-router 的 `useRouter()`(push/replace 自带
+* RouteNamedMap 泛型推导)。
+*
+* 未提供 `PAGE_KEY` 时返回共享的空对象(字段均为 undefined)。
+*/
+function usePage() {
+	return inject(PAGE_KEY, null) ?? _EMPTY_PAGE_DATA;
+}
+/** `useViewTransition()` — whether native View Transitions are available/enabled. */
+function useViewTransition() {
+	const opts = inject(TRANSITION_KEY, { enabled: true });
+	return {
+		enabled: opts.enabled !== false && supportsViewTransitions(),
+		supports: supportsViewTransitions(),
+		options: opts
+	};
+}
+const ubeanVue = { install(app, options) {
+	app.component("Link", Link);
+	app.component("PageView", PageView);
+	app.component("SlotView", SlotView);
+	if (options?.routes) initCachedViewsFromRoutes(options.routes);
+} };
+//#endregion
+//#region src/define-page.ts
+/**
+* Macro to declare a client page.
+*
+* used in `<script setup>` of SFC.
+*
+* @param options Page options.
+*
+* @example
+* ```ts
+* definePage({
+*   name: 'UserProfile',
+*   path: '/u/:id',
+*   cache: true,
+*   transition: 'fade',
+*   layout: 'admin',
+*   requiresAuth: true,
+*   meta: { custom: 'any' }
+* });
+* ```
+*/
+function definePage(options) {}
+//#endregion
+//#region src/router-location.ts
+function resolveRoute(to, routeMap) {
+	if (typeof to === "string") {
+		if (to.startsWith("/") || to.startsWith("http") || to.startsWith("#")) return to;
+		return `/${to.replace(/^\//, "")}`;
+	}
+	let path = to.path || "/";
+	if (to.name && routeMap) {
+		const route = routeMap[to.name];
+		if (route) path = route.route;
+	}
+	if (to.params) for (const [key, value] of Object.entries(to.params)) path = path.replace(`:${key}`, String(value));
+	if (to.query) {
+		const qs = Object.entries(to.query).filter(([, v]) => v !== void 0 && v !== null).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+		if (qs) path += (path.includes("?") ? "&" : "?") + qs;
+	}
+	if (to.hash) path += to.hash.startsWith("#") ? to.hash : `#${to.hash}`;
+	return path;
+}
+function isActiveRoute(currentPath, targetHref, exact = false) {
+	if (targetHref === "/" || targetHref === "") return currentPath === "/";
+	if (exact) return currentPath === targetHref || currentPath === `${targetHref}/`;
+	return currentPath === targetHref || currentPath.startsWith(`${targetHref}/`) || currentPath.startsWith(`${targetHref}?`);
+}
+//#endregion
+//#region src/matchers.ts
+/**
+* 全局 matcher 注册表(进程单例)。
+*
+* server / client 运行时各自维护一份;dev 模式下 HMR 不会自动清理注册表,
+* 但 `defineMatcher` 同名覆盖,因此重新加载 matcher 文件会自动更新函数引用。
+*/
+const matcherRegistry = /* @__PURE__ */ new Map();
+/**
+* 定义并注册一个命名 route matcher。
+*
+* @param name matcher 名称,对应 `[paramName=name]` 中的 `name`
+* @param fn   matcher 函数,接收参数字符串值,返回 falsy 表示不匹配
+* @returns 传入的 `fn`,便于链式/导出使用
+*
+* @example
+* ```ts
+* // src/matchers/numeric.ts
+* import { defineMatcher } from '@ubean/vue';
+* export default defineMatcher('numeric', (value) => /^\d+$/.test(value));
+* ```
+*/
+function defineMatcher(name, fn) {
+	if (typeof name !== "string" || name.length === 0) throw new TypeError(`[ubean] defineMatcher: name must be a non-empty string, got: ${typeof name}`);
+	if (typeof fn !== "function") throw new TypeError(`[ubean] defineMatcher: fn must be a function, got: ${typeof fn}`);
+	matcherRegistry.set(name, fn);
+	return fn;
+}
+/**
+* 按名称获取已注册的 matcher。未注册时返回 `undefined`。
+*/
+function getMatcher(name) {
+	return matcherRegistry.get(name);
+}
+/**
+* 判断指定名称的 matcher 是否已注册。
+*/
+function hasMatcher(name) {
+	return matcherRegistry.has(name);
+}
+/**
+* 获取所有已注册 matcher 的名称列表(主要用于调试 / DevTools)。
+*/
+function listMatcherNames() {
+	return [...matcherRegistry.keys()];
+}
+/**
+* 清空所有已注册的 matcher。
+*
+* **仅供测试使用** —— 应用代码不应调用,避免误删其他模块注册的 matcher。
+*/
+function clearMatchers() {
+	matcherRegistry.clear();
+}
+/**
+* 校验一组路由参数是否通过对应的 matcher。
+*
+* @param matchers  `ScannedPage.matchers` —— `{ paramName: matcherName }` 映射
+* @param params    当前请求解析出的 `{ paramName: value }`
+* @returns         `true` 表示所有 matcher 通过(或无 matcher 需要校验);
+*                  `false` 表示至少一个 matcher 拒绝,该路由不应匹配
+*
+* 行为细节:
+* - 若 `matchers` 为空 / undefined,直接返回 `true`(无校验需求)
+* - 若 matcher 名对应的函数未注册,**返回 `false`**(保守策略)
+* - 若参数不存在于 `params` 中,视为校验失败返回 `false`
+* - matcher 函数抛异常时,捕获并视为不匹配
+*/
+function validateParams(matchers, params) {
+	if (!matchers || Object.keys(matchers).length === 0) return true;
+	for (const [paramName, matcherName] of Object.entries(matchers)) {
+		const value = params[paramName];
+		if (value === void 0 || value === null) return false;
+		const values = Array.isArray(value) ? value : [value];
+		const matcherFn = getMatcher(matcherName);
+		if (!matcherFn) return false;
+		for (const v of values) try {
+			if (!matcherFn(v)) return false;
+		} catch {
+			return false;
+		}
+	}
+	return true;
+}
+/**
+* 创建 Vue Router `beforeEach` 导航守卫,用于客户端校验动态路由 matchers。
+*
+* 路由记录的 `meta.matchers` 字段(由 route generator 自动注入)记录了
+* `{ paramName: matcherName }` 映射。守卫读取该字段,调用 `validateParams`
+* 校验 `to.params`;失败时跳转到 404 路由(若存在)或取消导航。
+*
+* **用法**:
+*
+* ```ts
+* import { createMatcherGuard } from '@ubean/vue';
+*
+* const router = createRouter({ history: createWebHistory(), routes });
+* router.beforeEach(createMatcherGuard());
+* ```
+*
+* **设计说明**:
+* - 守卫是**可选的**:不调用 `createMatcherGuard()` 时,客户端不做 matcher
+*   校验,完全依赖服务端 Hono 中间件拦截(适用于 SSR 应用)。
+* - 对于纯 SPA 应用(`ssr: false`),强烈建议注册此守卫,否则客户端导航到
+*   `/users/abc`(应当被 `[id=numeric]` 拒绝)会渲染页面而非 404。
+*/
+function createMatcherGuard(options = {}) {
+	const notFoundRouteName = options.notFoundRouteName ?? "NotFound";
+	const onReject = options.onReject;
+	return (to) => {
+		const matchers = to.meta?.matchers;
+		if (!matchers || Object.keys(matchers).length === 0) return;
+		const params = to.params;
+		if (!validateParams(matchers, params)) {
+			onReject?.({
+				path: to.path,
+				params: to.params,
+				matchers
+			});
+			return { name: notFoundRouteName };
+		}
+	};
+}
+//#endregion
+//#region src/head.ts
+/**
+* 将静态 `PageHead` push 进 head 实例(falsy 字段自动跳过)。
+* 与 SSR 侧 `pushPageHead`(@ubean/ssr)语义一致,保证双端同构。
+*/
+function pushPageHead(head, pageHead) {
+	const input = {};
+	if (pageHead.title !== void 0) input.title = pageHead.title;
+	if (pageHead.meta !== void 0) input.meta = pageHead.meta;
+	if (pageHead.link !== void 0) input.link = pageHead.link;
+	if (pageHead.script !== void 0) input.script = pageHead.script;
+	if (pageHead.htmlAttrs !== void 0) input.htmlAttrs = pageHead.htmlAttrs;
+	if (pageHead.bodyAttrs !== void 0) input.bodyAttrs = pageHead.bodyAttrs;
+	head.push(input);
+}
+/**
+* SPA 页面级 head 守卫:导航完成后读取 `route.meta.head` 并 push 进 head 实例。
+*
+* ```ts
+* import { createRouter, createWebHistory } from 'vue-router';
+* import { setupPageHeadGuard, createPageHead } from '@ubean/vue';
+*
+* const head = await createPageHead();          // 按需加载 @unhead/vue
+* const router = createRouter({ history: createWebHistory(), routes });
+* setupPageHeadGuard(router, head);             // 也可传任何已有 unhead 实例
+* ```
+*
+* 初始导航同样触发(vue-router 首次导航完成后 afterEach 执行)。
+*/
+function setupPageHeadGuard(router, head) {
+	router.afterEach((to) => {
+		const pageHead = to.meta.head;
+		if (pageHead) pushPageHead(head, pageHead);
+	});
+}
+/**
+* 按需创建 head 实例(懒加载 `@unhead/vue`,optional peer dependency)。
+*
+* 项目已自带 unhead 实例时无需调用 —— 直接把实例传给
+* `setupPageHeadGuard` 即可,零额外加载。
+*/
+async function createPageHead() {
+	try {
+		const mod = await import("@unhead/vue");
+		if (typeof mod.createHead === "function") return mod.createHead();
+	} catch {}
+	throw new Error("[ubean/vue] createPageHead() requires `@unhead/vue` to be installed (optional peer dependency)");
+}
+//#endregion
+export { ERROR_KEY, ErrorBoundary, LAYOUT_CHAIN_KEY, LOADING_KEY, LOCALIZE_PATH_KEY, LayoutChainRenderer, Link, PAGE_KEY, PageView, SSR_KEY, SlotView, TRANSITION_KEY, clearMatchers, clearPageTransition, createMatcherGuard, createPageHead, ubeanVue as default, ubeanVue, defineMatcher, definePage, disablePageCache, enablePageCache, excludePageCache, getCacheEnabled, getCachedViewNames, getExcludedViewNames, getMatcher, getNamedPageWrapper, getNavigationType, getPageTransitionName, getReloadCounter, hasMatcher, includePageCache, initCachedViewsFromRoutes, invalidatePageCache, isActiveRoute, isCacheEnabled, isPageCached, isPageExcluded, isReloading, listMatcherNames, pushPageHead, reloadPage, resetNamedPageWrappers, resetRouteCache, resolveRoute, setPageTransition, setupPageHeadGuard, supportsViewTransitions, useCacheViews, usePage, usePageTransition, useReloadSignal, useViewTransition, useViewTransitionState, validateParams, withViewTransition };