@ubean/vue 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,782 @@
+import { a as ScannedLayout, i as ScanPagesResult, n as PageMeta, o as ScannedPage, r as ScanPagesOptions, t as PageHead } from "./types-VHF1RJu2.js";
+import { Component, ComputedRef, InjectionKey, Plugin, PropType, Ref, VNode } from "vue";
+import { NavigationGuard, RouteMeta, Router } from "vue-router";
+//#region src/view-transitions.d.ts
+interface ViewTransitionOptions {
+  enabled?: boolean;
+  fallback?: 'none' | 'crossfade';
+  types?: string[];
+}
+declare function supportsViewTransitions(): boolean;
+declare function withViewTransition<T>(callback: () => Promise<T> | T, options?: ViewTransitionOptions): Promise<T>;
+declare function getNavigationType(): 'traverse' | 'push' | 'replace' | 'reload';
+declare function useViewTransitionState(name: string): Record<string, string>;
+//#endregion
+//#region src/components.d.ts
+/**
+ * Injection keys (exported for advanced use cases — e.g. testing utilities
+ * that need to provide the page/transition context outside the plugin).
+ */
+declare const PAGE_KEY: unique symbol;
+declare const TRANSITION_KEY: unique symbol;
+declare const SSR_KEY: InjectionKey<boolean>;
+declare const LOADING_KEY: InjectionKey<Component | null>;
+declare const ERROR_KEY: InjectionKey<Component | null>;
+/**
+ * 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.
+ */
+declare const LOCALIZE_PATH_KEY: InjectionKey<(path: string) => string>;
+/**
+ * Layout chain context — provided by `LayoutChainRenderer` so that `<PageView />`
+ * inside a layout knows whether to render the next nested layout or the actual
+ * page. When `depth < components.length - 1`, `PageView` renders the next
+ * `LayoutChainRenderer`; otherwise it renders the matched page via `<RouterView>`.
+ */
+interface LayoutChainContext {
+  components: Array<Component | null>;
+  depth: number;
+}
+declare const LAYOUT_CHAIN_KEY: InjectionKey<LayoutChainContext | null>;
+/**
+ * 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).
+ */
+declare const LayoutChainRenderer: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  components: {
+    type: PropType<Array<Component | null>>;
+    required: true;
+  };
+  depth: {
+    type: NumberConstructor;
+    default: number;
+  };
+}>, () => VNode, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  components: {
+    type: PropType<Array<Component | null>>;
+    required: true;
+  };
+  depth: {
+    type: NumberConstructor;
+    default: number;
+  };
+}>> & Readonly<{}>, {
+  depth: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * 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.
+ */
+declare const ErrorBoundary: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  component: {
+    type: PropType<Component | null>;
+    default: null;
+  };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}> | VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  component: {
+    type: PropType<Component | null>;
+    default: null;
+  };
+}>> & Readonly<{}>, {
+  component: Component | null;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * 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).
+ */
+declare const PageView: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  transition: {
+    type: (BooleanConstructor | StringConstructor)[];
+    default: undefined;
+  };
+  reloadKey: {
+    type: (NumberConstructor | StringConstructor)[];
+    default: undefined;
+  };
+  mode: {
+    type: PropType<"out-in" | "in-out" | "default">;
+    default: string;
+  };
+}>, () => VNode, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  transition: {
+    type: (BooleanConstructor | StringConstructor)[];
+    default: undefined;
+  };
+  reloadKey: {
+    type: (NumberConstructor | StringConstructor)[];
+    default: undefined;
+  };
+  mode: {
+    type: PropType<"out-in" | "in-out" | "default">;
+    default: string;
+  };
+}>> & Readonly<{}>, {
+  mode: "default" | "in-out" | "out-in";
+  transition: string | boolean;
+  reloadKey: string | number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * 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).
+ */
+declare const SlotView: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  name: {
+    type: StringConstructor;
+    required: true;
+  };
+}>, () => VNode, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  name: {
+    type: StringConstructor;
+    required: true;
+  };
+}>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * 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.
+ */
+declare const Link: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  to: {
+    type: PropType<string | Record<string, unknown>>;
+    default: undefined;
+  };
+  href: {
+    type: StringConstructor;
+    default: undefined;
+  };
+  replace: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  prefetch: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  activeClass: {
+    type: StringConstructor;
+    default: string;
+  };
+  exactActiveClass: {
+    type: StringConstructor;
+    default: string;
+  };
+  noActiveClass: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  to: {
+    type: PropType<string | Record<string, unknown>>;
+    default: undefined;
+  };
+  href: {
+    type: StringConstructor;
+    default: undefined;
+  };
+  replace: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  prefetch: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  activeClass: {
+    type: StringConstructor;
+    default: string;
+  };
+  exactActiveClass: {
+    type: StringConstructor;
+    default: string;
+  };
+  noActiveClass: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+}>> & Readonly<{}>, {
+  to: string | Record<string, unknown>;
+  href: string;
+  replace: boolean;
+  prefetch: boolean;
+  activeClass: string;
+  exactActiveClass: string;
+  noActiveClass: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * `PAGE_KEY` 注入的页面数据形状(框架工厂 / SSR 链路提供;精简 SPA
+ * 通常不提供,`usePage()` 返回空对象)。
+ *
+ * 路由态(url/params/query/meta)不在此处 —— 直接用 vue-router 的
+ * `useRoute()`;导航(push/replace 带类型推导)直接用 vue-router 的
+ * `useRouter()`。本包不再包装二者,避免丢失 vue-router 的泛型能力。
+ */
+interface UbeanVuePageData<TProps = Record<string, unknown>> {
+  /** 工厂/SSR 注入的页面 props(框架数据协议)。 */
+  props?: Record<string, TProps>;
+  /** 页面组件标识(框架 SSR 数据)。 */
+  component?: string;
+  /** 校验错误映射(表单/服务端校验协议)。 */
+  errors?: Record<string, string> | null;
+}
+/**
+ * `usePage()` — 读取 `PAGE_KEY` 注入的页面数据(精简版:仅 pageData)。
+ *
+ * 路由驱动的 url/params/query 请使用 vue-router 的 `useRoute()`;
+ * 导航请使用 vue-router 的 `useRouter()`(push/replace 自带
+ * RouteNamedMap 泛型推导)。
+ *
+ * 未提供 `PAGE_KEY` 时返回共享的空对象(字段均为 undefined)。
+ */
+declare function usePage<TProps = Record<string, unknown>>(): UbeanVuePageData<TProps>;
+/** `useViewTransition()` — whether native View Transitions are available/enabled. */
+declare function useViewTransition(): {
+  enabled: boolean;
+  supports: boolean;
+  options: ViewTransitionOptions;
+};
+/**
+ * `ubeanVue` — the plugin exposing the lean kernel. This is the ONLY wiring
+ * entry of `@ubean/vue` (no app factory, no router factory):
+ *
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { createRouter, createWebHistory } from 'vue-router';
+ * import { ubeanVue } from '@ubean/vue';
+ * import { routes } from 'virtual:ubean-vue-routes'; // @ubean/vue/vite
+ *
+ * const router = createRouter({ history: createWebHistory(), routes });
+ * const app = createApp(App);
+ * app.use(router);
+ * app.use(ubeanVue, { routes }); // Link/PageView/SlotView + cache seeding
+ * app.mount('#app');
+ * ```
+ */
+interface UbeanVueOptions {
+  /**
+   * Route records — seeds the keep-alive include list from `meta.cache: true`
+   * declarations (the lean equivalent of the framework's
+   * `definePage({ cache: true })` macro).
+   */
+  routes?: Array<{
+    name?: string | symbol;
+    meta?: {
+      cache?: boolean;
+    };
+  }>;
+}
+declare const ubeanVue: Plugin<UbeanVueOptions>;
+//#endregion
+//#region src/cache-views.d.ts
+interface UseCacheViewsReturn {
+  /** Reactive list of cached route names — pass to `<keep-alive :include>`. */
+  cachedViews: ComputedRef<string[]>;
+  /** Reactive list of route names explicitly added to the cache. */
+  cachedViewNames: ComputedRef<string[]>;
+  /** Reactive list of route names excluded from cache — pass to `<keep-alive :exclude>`. */
+  excludedViews: ComputedRef<string[]>;
+  /** Whether page caching is globally enabled. */
+  enabled: ComputedRef<boolean>;
+  /** Enable page caching globally. */
+  enable: () => void;
+  /** Disable page caching globally (purges keep-alive immediately). */
+  disable: () => void;
+  /** Add a route name to the cache include list. */
+  add: (name: string) => void;
+  /** Remove a route name from the cache include list (prunes its instance). */
+  remove: (name: string) => void;
+  /** Whether a route name is currently in the cache include list. */
+  has: (name: string) => boolean;
+  /** Remove all route names from the cache include list. */
+  clear: () => void;
+  /** Add a route name to the cache exclude list (forces prune on next render). */
+  addExclude: (name: string) => void;
+  /** Remove a route name from the cache exclude list. */
+  removeExclude: (name: string) => void;
+  /** Whether a route name is currently in the cache exclude list. */
+  hasExclude: (name: string) => boolean;
+  /** Clear the cache exclude list. */
+  clearExclude: () => void;
+}
+/**
+ * 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.
+ */
+declare function useCacheViews(): UseCacheViewsReturn;
+/** Enable keep-alive caching for a specific page (by route name). */
+declare function enablePageCache(name: string): void;
+/** Disable keep-alive caching for a specific page (by route name). */
+declare function disablePageCache(name: string): void;
+/**
+ * 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.
+ */
+declare function excludePageCache(name: string): void;
+/** Remove a route name from the cache exclude list (restores caching). */
+declare function includePageCache(name: string): void;
+/** Whether a specific page is currently excluded from cache. */
+declare function isPageExcluded(name: string): boolean;
+/**
+ * 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.
+ */
+declare function resetRouteCache(name?: string, _delay?: number): Promise<void>;
+/**
+ * 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.
+ */
+declare function invalidatePageCache(name?: string): void;
+/** Whether a specific page is currently cached. */
+declare function isPageCached(name: string): boolean;
+/** Whether page caching is globally enabled. */
+declare function isCacheEnabled(): boolean;
+/** Reactive ref of cached route names — for advanced use cases. */
+declare function getCachedViewNames(): Ref<string[]>;
+/** Reactive ref of excluded route names — for advanced use cases. */
+declare function getExcludedViewNames(): Ref<string[]>;
+/** Reactive ref of the global cache-enabled flag. */
+declare function getCacheEnabled(): Ref<boolean>;
+/**
+ * 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.
+ */
+declare function initCachedViewsFromRoutes(routes: Array<{
+  name?: string | symbol;
+  meta?: {
+    cache?: boolean;
+  };
+}>): void;
+/**
+ * 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`.
+ */
+declare function getNamedPageWrapper(routeName: string, original: Component): Component;
+/**
+ * Clear the wrapper registry. Mainly useful in tests or when the entire
+ * route table is rebuilt.
+ *
+ * @internal
+ */
+declare function resetNamedPageWrappers(): void;
+//#endregion
+//#region src/page-runtime.d.ts
+interface UsePageTransitionReturn {
+  /** Reactive transition name. Empty string means "no transition". */
+  name: ComputedRef<string>;
+  /** Set the global transition name. Use '' or 'none' to disable. */
+  set: (name: string) => void;
+  /** Clear the global transition name (disables transitions). */
+  clear: () => void;
+  /** Whether a transition is currently configured. */
+  enabled: ComputedRef<boolean>;
+}
+/**
+ * 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();
+ * ```
+ */
+declare function usePageTransition(): UsePageTransitionReturn;
+/** Imperatively set the global page transition name. */
+declare function setPageTransition(name: string): void;
+/** Imperatively clear the global page transition name (disables transitions). */
+declare function clearPageTransition(): void;
+/** Reactive ref of the global transition name — for advanced use cases. */
+declare function getPageTransitionName(): Ref<string>;
+interface UseReloadSignalReturn {
+  /** Reactive counter that increments on each `reloadPage()` call. */
+  counter: ComputedRef<number>;
+  /** Whether a reload is currently in progress. */
+  reloading: ComputedRef<boolean>;
+  /** Trigger a reload of the current page. */
+  reload: (routeName?: string, duration?: number) => Promise<void>;
+}
+declare function useReloadSignal(routeNameGetter?: () => string | undefined | null): UseReloadSignalReturn;
+/**
+ * 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.
+ */
+declare function reloadPage(name?: string, duration?: number): Promise<void>;
+/** Reactive ref of the reload counter — for advanced use cases. */
+declare function getReloadCounter(): Ref<number>;
+/** Whether a reload is currently in progress. */
+declare function isReloading(): boolean;
+//#endregion
+//#region src/define-page.d.ts
+/**
+ * `definePage` —— 客户端页面声明宏(纯客户端能力子集)。
+ *
+ * 在 SFC 的 `<script setup>` 顶层调用,声明本页的路由元信息:
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * import { definePage } from '@ubean/vue';
+ *
+ * definePage({
+ *   name: 'UserProfile',           // 覆盖文件派生的路由名
+ *   path: '/u/:id',                // 覆盖文件派生的路径
+ *   cache: true,                   // keep-alive 页面缓存
+ *   transition: 'fade',            // 页面级过渡名(PageView)
+ *   layout: 'admin',               // 布局标记(由宿主布局层消费)
+ *   requiresAuth: true,            // 鉴权标记(由导航守卫消费)
+ *   head: { title: '用户主页' },    // 页面级 head(需 /vite 插件 head: true)
+ *   meta: { custom: 'any' }        // 任意扩展 meta(RouteMeta)
+ * });
+ * </script>
+ * ```
+ *
+ * 双重语义:
+ * - **构建期**(推荐):`@ubean/vue/vite` 插件在编译时提取参数对象,合并进
+ *   `virtual:ubean-vue-routes` 生成的路由表,并把调用从产物中剥除
+ *   (零运行时开销)。
+ * - **运行时兜底**:无插件环境下本函数是 no-op —— 不报错、不产生副作用,
+ *   页面仍以文件派生的路径/名称注册。`cache` 等声明可通过
+ *   `enablePageCache(name)` 运行时补齐。
+ *
+ * 与全栈版 `definePage`(`@ubean/pages` 协议)的差异:此处保留客户端字段
+ * (`head` 为 opt-in,需 `/vite` 插件开启);`middleware` 已移除 —— 此前
+ * 该字段从未被任何运行时消费,按路由声明守卫请用 `meta` 透传。
+ */
+interface DefineClientPageOptions {
+  /** 覆盖文件派生的路由名(同时作为 keep-alive 匹配的 pageName)。 */
+  name?: string;
+  /** 覆盖文件派生的路由路径(需以 `/` 开头,支持 `:param` 动态段)。 */
+  path?: string;
+  /**
+   * 布局标记:布局名、外→内嵌套布局名数组,或 `false` 禁用。
+   * 精简内核只把该值写入 `route.meta.layout`,渲染由宿主的布局层
+   * (`LayoutChainRenderer` / 框架运行时)消费。
+   */
+  layout?: string | string[] | false;
+  /** 声明式开启 keep-alive 页面缓存(等价于运行时 `enablePageCache(name)`)。 */
+  cache?: boolean;
+  /** 页面级过渡名,`<PageView>` 渲染 `<Transition :name>`;空串禁用本页过渡。 */
+  transition?: string;
+  /** 鉴权标记,写入 `route.meta.requiresAuth`,由用户导航守卫消费。 */
+  requiresAuth?: boolean;
+  /**
+   * reuse 路由目标页名(仅 `.reuse.ts` / `.reuse.js` 元数据文件使用):
+   * 本路由复用目标页的组件实现,仅注入独立的路由元数据(路径/名称等)。
+   */
+  reuse?: string;
+  /**
+   * 页面级静态 head(SEO title/meta 等)。仅当 `/vite` 插件 `head: true`
+   * (默认 false)时写入 `route.meta.head`;SPA 端配合
+   * `setupPageHeadGuard()` 应用,SSR 链路经服务端扫描结果消费。
+   */
+  head?: PageHead;
+  /** 任意扩展 meta,浅合并进 `route.meta`(类型上扩展 vue-router RouteMeta)。 */
+  meta?: RouteMeta;
+}
+/**
+ * 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' }
+ * });
+ * ```
+ */
+declare function definePage(options?: DefineClientPageOptions): void;
+//#endregion
+//#region src/router-location.d.ts
+interface RouteLocationRaw {
+  name?: string;
+  path?: string;
+  params?: Record<string, string | number>;
+  query?: Record<string, string | number | boolean | undefined | null>;
+  hash?: string;
+}
+type RouteLocation = string | RouteLocationRaw;
+declare function resolveRoute(to: RouteLocation, routeMap?: Record<string, {
+  path: string;
+  route: string;
+}>): string;
+type TypedLinkProps = {
+  to?: RouteLocation;
+  href?: string;
+  replace?: boolean;
+  prefetch?: boolean;
+  as?: string;
+  activeClass?: string;
+  exactActiveClass?: string;
+};
+declare function isActiveRoute(currentPath: string, targetHref: string, exact?: boolean): boolean;
+//#endregion
+//#region src/matchers.d.ts
+/**
+ * Matcher 函数签名。接收 URL 中的原始字符串参数,返回 falsy 表示不匹配。
+ *
+ * @example
+ * defineMatcher('numeric', (value) => /^\d+$/.test(value));
+ * defineMatcher('slug', (value) => /^[a-z0-9-]+$/.test(value));
+ */
+type MatcherFunction = (value: string) => boolean | null | undefined;
+/**
+ * 定义并注册一个命名 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));
+ * ```
+ */
+declare function defineMatcher(name: string, fn: MatcherFunction): MatcherFunction;
+/**
+ * 按名称获取已注册的 matcher。未注册时返回 `undefined`。
+ */
+declare function getMatcher(name: string): MatcherFunction | undefined;
+/**
+ * 判断指定名称的 matcher 是否已注册。
+ */
+declare function hasMatcher(name: string): boolean;
+/**
+ * 获取所有已注册 matcher 的名称列表(主要用于调试 / DevTools)。
+ */
+declare function listMatcherNames(): string[];
+/**
+ * 清空所有已注册的 matcher。
+ *
+ * **仅供测试使用** —— 应用代码不应调用,避免误删其他模块注册的 matcher。
+ */
+declare function clearMatchers(): void;
+/**
+ * 校验一组路由参数是否通过对应的 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 函数抛异常时,捕获并视为不匹配
+ */
+declare function validateParams(matchers: Record<string, string> | undefined, params: Record<string, string | string[] | undefined>): boolean;
+interface MatcherGuardOptions {
+  /**
+   * matcher 校验失败时跳转的路由名。默认 `'NotFound'`。
+   *
+   * 若该路由不存在,守卫返回 `false`(取消导航),用户停留在当前页面。
+   */
+  notFoundRouteName?: string;
+  /**
+   * 自定义拒绝回调,在跳转 404 之前调用。可用于日志、监控、自定义错误页等。
+   */
+  onReject?: (to: {
+    path: string;
+    params: Record<string, unknown>;
+    matchers: Record<string, string>;
+  }) => void;
+}
+/**
+ * 创建 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。
+ */
+declare function createMatcherGuard(options?: MatcherGuardOptions): NavigationGuard;
+//#endregion
+//#region src/head.d.ts
+/**
+ * 页面级 head 的客户端接通(零依赖核心 + 按需加载)。
+ *
+ * 设计:
+ * - 核心路径零第三方依赖:`PageHeadClient` 是结构化类型(`{ push }`),
+ *   任何 unhead 实例(或测试替身)都可直接传入。
+ * - 无实例时通过 `createPageHead()` 按需加载 `@unhead/vue`(optional peer),
+ *   未安装时报清晰错误。
+ * - 构建期 `/vite` 插件 `head: true`(默认 false)时,`definePage({ head })`
+ *   与 markdown frontmatter `head` 才写入 `route.meta.head`;SSR 链路不受
+ *   影响(服务端从扫描结果的 `pageMeta.head` 读取)。
+ */
+/** 结构化 head 客户端 —— 与 `@unhead/vue` 的 head 实例兼容。 */
+interface PageHeadClient {
+  push(input: unknown): unknown;
+}
+/**
+ * 将静态 `PageHead` push 进 head 实例(falsy 字段自动跳过)。
+ * 与 SSR 侧 `pushPageHead`(@ubean/ssr)语义一致,保证双端同构。
+ */
+declare function pushPageHead(head: PageHeadClient, pageHead: PageHead): void;
+/**
+ * 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 执行)。
+ */
+declare function setupPageHeadGuard(router: Router, head: PageHeadClient): void;
+/**
+ * 按需创建 head 实例(懒加载 `@unhead/vue`,optional peer dependency)。
+ *
+ * 项目已自带 unhead 实例时无需调用 —— 直接把实例传给
+ * `setupPageHeadGuard` 即可,零额外加载。
+ */
+declare function createPageHead(): Promise<PageHeadClient>;
+//#endregion
+//#region src/index.d.ts
+declare module 'vue-router' {
+  interface RouteMeta {
+    /** Whether this page is kept-alive (lean: route `meta: { cache: true }`). */
+    cache?: boolean;
+    /** The page route name (used by KeepAlive include matching). */
+    pageName?: string;
+    /** Layout name(s) or `false` to disable (consumed by framework factories). */
+    layout?: string | string[] | false;
+    /** Whether authentication is required for this route. */
+    requiresAuth?: boolean;
+    /**
+     * Page transition name (used by `<PageView>`). Falls back to the global
+     * `usePageTransition()` ref when not set. Empty string disables
+     * transitions for this specific page.
+     */
+    transition?: string;
+    /**
+     * Static page-level head (`definePage({ head })` / markdown frontmatter).
+     * Only populated when the `/vite` plugin runs with `head: true`; apply
+     * via `setupPageHeadGuard()` (SPA) or the SSR pipeline.
+     */
+    head?: PageHead;
+    /** `[param=matcher]` mapping consumed by `createMatcherGuard()`. */
+    matchers?: Record<string, string>;
+  }
+}
+//#endregion
+export { type DefineClientPageOptions, ERROR_KEY, ErrorBoundary, LAYOUT_CHAIN_KEY, LOADING_KEY, LOCALIZE_PATH_KEY, type LayoutChainContext, LayoutChainRenderer, Link, type MatcherFunction, type MatcherGuardOptions, PAGE_KEY, type PageHead, type PageHeadClient, type PageMeta, PageView, type RouteLocation, type RouteLocationRaw, SSR_KEY, type ScanPagesOptions, type ScanPagesResult, type ScannedLayout, type ScannedPage, SlotView, TRANSITION_KEY, type TypedLinkProps, type UbeanVueOptions, type UbeanVuePageData, type UseCacheViewsReturn, type UsePageTransitionReturn, type UseReloadSignalReturn, type ViewTransitionOptions, 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 };