@ubean/vue 0.4.5 → 0.4.6

package/README.md

@@ -15,7 +15,7 @@ import { routes } from 'virtual:ubean-vue-routes'; // generated by @ubean/vue/vi
 const router = createRouter({ history: createWebHistory(), routes });
 const app = createApp(App);
 app.use(router);
-app.use(ubeanVue, { routes }); // registers Link/PageView/SlotView + seeds page cache
+app.use(ubeanVue, { routes }); // registers Link/PageView/SlotView/ClientOnly + seeds page cache
 app.mount('#app');
 ```
 
@@ -61,7 +61,7 @@ app.mount('#app');
 **Included:**
 
 - `ubeanVue` Vue plugin (the only wiring entry — plugin-first, no factory)
-- `<PageView>` / `<Link>` / `<SlotView>` / `<LayoutChainRenderer>` / `<ErrorBoundary>`
+- `<PageView>` / `<Link>` / `<SlotView>` / `<LayoutChainRenderer>` / `<ErrorBoundary>` / `<ClientOnly>`
 - Page cache (keep-alive) store with imperative + declarative APIs
 - Page transitions & reload signal (per-page remount with fresh cache)
 - View Transitions helpers (feature detection + wrapper)
@@ -345,7 +345,7 @@ The `RouteFileGenerator` class is also exported for incremental use (`new RouteF
 app.use(ubeanVue, { routes });
 ```
 
-Registers `Link` / `PageView` / `SlotView` as global components and seeds the keep-alive include list from `meta.cache: true` declarations (`initCachedViewsFromRoutes`). This is the **only** wiring entry of the package (main subpath — distinct from the same-named Vite plugin in the `/vite` subpath).
+Registers `Link` / `PageView` / `SlotView` / `ClientOnly` as global components and seeds the keep-alive include list from `meta.cache: true` declarations (`initCachedViewsFromRoutes`). This is the **only** wiring entry of the package (main subpath — distinct from the same-named Vite plugin in the `/vite` subpath).
 
 ## Components
 
@@ -379,6 +379,43 @@ Recursively renders a chain of nested layout components (framework factories bui
 
 Catches render/async/setup errors from descendants and renders the configured error component; resets on route change.
 
+### `<ClientOnly>`
+
+Renders its content ONLY on the client, after hydration. Useful for browser-only markup or template fragments (the islands `v-client.*` transform only applies to capitalized component tags).
+
+```vue
+<template>
+  <!-- string fallback prop -->
+  <ClientOnly fallback="loading…">
+    <BrowserChart />
+  </ClientOnly>
+
+  <!-- fallback slot (reserve space to avoid CLS) -->
+  <ClientOnly>
+    <template #fallback>
+      <div class="skeleton" />
+    </template>
+    <BrowserMap />
+  </ClientOnly>
+
+  <!-- plain fragments work too -->
+  <ClientOnly>Window width: {{ width }}px</ClientOnly>
+</template>
+```
+
+**Hydration safety:** the placeholder (fallback / nothing) is rendered during SSR AND during the client's hydration render; the real content is patched in right after mount. There is no `typeof window` branching, so no hydration mismatch warnings.
+
+**When to use what:**
+
+| Scenario                                                             | Use                                                         |
+| -------------------------------------------------------------------- | ----------------------------------------------------------- |
+| Template fragments / plain HTML, same-tree rendering, fallback slots | `<ClientOnly>`                                              |
+| Component-level deferred hydration strategies (idle/visible/media)   | islands `v-client.*`                                        |
+| Programmatic islands / client-only wrappers                          | `defineIsland` / `defineClientComponent` (`@ubean/islands`) |
+| File-level server/client split                                       | `.server.vue` / `.client.vue`                               |
+
+> Notes: default-slot content is absent from the SSR HTML — don't use `<ClientOnly>` for SEO-critical content. `<ClientOnly>` inside an island placeholder's children is wiped when the island hydrates (islands hydrate via a separate app).
+
 ## Composables
 
 - **`usePage<T>()`** — lean page-data access: returns the `PAGE_KEY` injected data (`props` / `component` / `errors`) as-is, or a shared empty object when nothing was provided. Route state (`url` / `params` / `query` / `meta`) is NOT included — use vue-router's `useRoute()` directly. The framework runtime (`@ubean/client`) layers its own route-aware `usePage` on top for the full PageObject protocol.

package/README.zh-CN.md

@@ -15,7 +15,7 @@ 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 + 播种页面缓存
+app.use(ubeanVue, { routes }); // 注册 Link/PageView/SlotView/ClientOnly + 播种页面缓存
 app.mount('#app');
 ```
 
@@ -45,6 +45,7 @@ app.mount('#app');
     - [`<SlotView>`](#slotview)
     - [`<LayoutChainRenderer>`](#layoutchainrenderer)
     - [`<ErrorBoundary>`](#errorboundary)
+    - [`<ClientOnly>`](#clientonly)
   - [组合式函数](#组合式函数)
   - [页面缓存（keep-alive）](#页面缓存keep-alive)
   - [页面过渡与重载](#页面过渡与重载)
@@ -68,7 +69,7 @@ app.mount('#app');
 **包含：**
 
 - `ubeanVue` Vue 插件（唯一接线入口 —— 插件优先，无工厂）
-- `<PageView>` / `<Link>` / `<SlotView>` / `<LayoutChainRenderer>` / `<ErrorBoundary>`
+- `<PageView>` / `<Link>` / `<SlotView>` / `<LayoutChainRenderer>` / `<ErrorBoundary>` / `<ClientOnly>`
 - 页面缓存（keep-alive）store：命令式 + 声明式 API
 - 页面过渡与重载信号（按页重载 + 缓存新鲜重建）
 - View Transitions 工具（特性检测 + 包装器）
@@ -352,7 +353,7 @@ const result = await generateRouteFiles(
 app.use(ubeanVue, { routes });
 ```
 
-注册 `Link` / `PageView` / `SlotView` 全局组件，并从 `meta.cache: true` 声明播种 keep-alive include 列表（`initCachedViewsFromRoutes`）。这是本包主入口**唯一**的接线入口（与 `/vite` 子路径的同名 Vite 插件是两个不同入口）。
+注册 `Link` / `PageView` / `SlotView` / `ClientOnly` 全局组件，并从 `meta.cache: true` 声明播种 keep-alive include 列表（`initCachedViewsFromRoutes`）。这是本包主入口**唯一**的接线入口（与 `/vite` 子路径的同名 Vite 插件是两个不同入口）。
 
 ## 组件
 
@@ -386,6 +387,43 @@ Props：`to`（字符串或位置对象）、`href`、`replace`、`activeClass`
 
 捕获后代组件的渲染/异步/setup 错误并渲染配置的错误组件；路由变更时自动重置。
 
+### `<ClientOnly>`
+
+内容仅在客户端、水合之后渲染。适合浏览器态内容与模板片段（islands 的 `v-client.*` 编译转换只作用于大写开头的组件标签）。
+
+```vue
+<template>
+  <!-- 字符串 fallback prop -->
+  <ClientOnly fallback="加载中…">
+    <BrowserChart />
+  </ClientOnly>
+
+  <!-- #fallback slot（预留空间避免 CLS） -->
+  <ClientOnly>
+    <template #fallback>
+      <div class="skeleton" />
+    </template>
+    <BrowserMap />
+  </ClientOnly>
+
+  <!-- 裸模板片段也可以 -->
+  <ClientOnly>窗口宽度：{{ width }}px</ClientOnly>
+</template>
+```
+
+**水合安全**：占位内容（fallback / 空）在 SSR 与客户端水合首帧渲染**完全一致**，真实内容在挂载后 patch 进来。实现不做 `typeof window` 分支，因此不会产生水合 mismatch 警告。
+
+**场景选择**：
+
+| 场景                                                          | 用法                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------ |
+| 模板片段 / 裸 HTML、同树渲染（完整应用上下文）、fallback slot | `<ClientOnly>`                                               |
+| 组件级延迟水合策略（idle/visible/media）                      | islands `v-client.*`                                         |
+| 编程式 island / 客户端组件包装                                | `defineIsland` / `defineClientComponent`（`@ubean/islands`） |
+| 文件级 server/client 拆分                                     | `.server.vue` / `.client.vue`                                |
+
+> 注意：默认 slot 内容不进 SSR HTML —— SEO 关键内容不要用 `<ClientOnly>`。出现在 island 占位元素子内容中的 `<ClientOnly>` 会在 island 水合时一并被覆盖（islands 通过独立 app 水合）。
+
 ## 组合式函数
 
 - **`usePage<T>()`** —— 精简版页面数据访问：原样返回 `PAGE_KEY` 注入的数据（`props` / `component` / `errors`），未注入时返回共享空对象。**不含**路由态（`url` / `params` / `query` / `meta`）—— 请直接用 vue-router 的 `useRoute()`。框架运行时（`@ubean/client`）在其上叠加自己的路由感知 `usePage` 提供完整 PageObject 协议。

package/dist/generator.d.ts

@@ -17,7 +17,7 @@ import { a as ScannedLayout, o as ScannedPage } from "./types-CeX4SJit.js";
  * `ScanPagesResult`(`@ubean/vue/vite` 的 `scanPages` 返回值)与聚合层的
  * `ScanResult`(`@ubean/scan` 的 `scanProject`)都结构性满足本接口。
  */
-interface GeneratorScanInput {
+export interface GeneratorScanInput {
   pages: ScannedPage[];
   layouts: ScannedLayout[];
 }
@@ -41,7 +41,7 @@ interface GeneratorScanInput {
  * 在 `@ubean/vue` 不改变产物契约。精简 SPA 用虚拟模式的 `typed-router.d.ts`
  * (`@ubean/vue/vite` 的 `generateTypedRouter`),不经过本生成器。
  */
-interface GeneratorOptions {
+export interface GeneratorOptions {
   /** Project root directory (absolute). */
   cwd: string;
   /**
@@ -93,16 +93,16 @@ interface GeneratorOptions {
    */
   headerComment?: string;
 }
-interface GeneratorResult {
+export interface GeneratorResult {
   routesPath?: string;
   importsPath?: string;
   dtsPath?: string;
   routeCount: number;
   layoutCount: number;
 }
-declare const DEFAULT_HEADER_COMMENT: string;
-declare function generateRouteFiles(scan: GeneratorScanInput, options: GeneratorOptions): Promise<GeneratorResult>;
-declare class RouteFileGenerator {
+export declare const DEFAULT_HEADER_COMMENT: string;
+export declare function generateRouteFiles(scan: GeneratorScanInput, options: GeneratorOptions): Promise<GeneratorResult>;
+export declare class RouteFileGenerator {
   private readonly opts;
   constructor(options: GeneratorOptions);
   generate(scan: GeneratorScanInput): Promise<GeneratorResult>;
@@ -127,5 +127,4 @@ declare class RouteFileGenerator {
    */
   private renderRouteRecordInfo;
 }
-//#endregion
-export { DEFAULT_HEADER_COMMENT, GeneratorOptions, GeneratorResult, GeneratorScanInput, RouteFileGenerator, generateRouteFiles };
+//#endregion

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { a as ScannedLayout, i as ScanPagesResult, n as PageMeta, o as ScannedPage, r as ScanPagesOptions, t as PageHead } from "./types-CeX4SJit.js";
-import { Component, ComputedRef, InjectionKey, Plugin, PropType, Ref, VNode } from "vue";
+import { Component, ComputedRef, InjectionKey, Plugin, PropType, Ref, SlotsType, VNode } from "vue";
 import { NavigationGuard, RouteMeta, Router } from "vue-router";
 //#region src/view-transitions.d.ts
 interface ViewTransitionOptions {
@@ -7,10 +7,10 @@ interface ViewTransitionOptions {
   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>;
+export declare function supportsViewTransitions(): boolean;
+export declare function withViewTransition<T>(callback: () => Promise<T> | T, options?: ViewTransitionOptions): Promise<T>;
+export declare function getNavigationType(): 'traverse' | 'push' | 'replace' | 'reload';
+export declare function useViewTransitionState(name: string): Record<string, string>;
 //#endregion
 //#region src/components.d.ts
 /**
@@ -25,17 +25,17 @@ declare function useViewTransitionState(name: string): Record<string, string>;
  * hydration href mismatch). Registered keys are shared globally, so every
  * copy resolves to the same Symbol.
  */
-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>;
+export declare const PAGE_KEY: unique symbol;
+export declare const TRANSITION_KEY: unique symbol;
+export declare const SSR_KEY: InjectionKey<boolean>;
+export declare const LOADING_KEY: InjectionKey<Component | null>;
+export 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, locale?: string) => string>;
+export declare const LOCALIZE_PATH_KEY: InjectionKey<(path: string, locale?: 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
@@ -46,13 +46,13 @@ interface LayoutChainContext {
   components: Array<Component | null>;
   depth: number;
 }
-declare const LAYOUT_CHAIN_KEY: InjectionKey<LayoutChainContext | null>;
+export 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<{
+export declare const LayoutChainRenderer: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
   components: {
     type: PropType<Array<Component | null>>;
     required: true;
@@ -79,7 +79,7 @@ declare const LayoutChainRenderer: import("vue").DefineComponent<import("vue").E
  * configured `errorComponent` instead of the slot content. The error state
  * resets automatically on route change.
  */
-declare const ErrorBoundary: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+export declare const ErrorBoundary: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
   component: {
     type: PropType<Component | null>;
     default: null;
@@ -96,6 +96,56 @@ declare const ErrorBoundary: import("vue").DefineComponent<import("vue").Extract
 }>> & Readonly<{}>, {
   component: Component | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+interface ClientOnlyProps {
+  /** Placeholder text rendered during SSR and client hydration render. */
+  fallback?: string;
+}
+interface ClientOnlySlots {
+  /** Content rendered only on the client, after hydration. */
+  default?: () => VNode[];
+  /** Placeholder rendered during SSR and the client's hydration render. */
+  fallback?: () => VNode[];
+}
+/**
+ * ClientOnly — renders its default slot ONLY on the client, after hydration.
+ *
+ * ## Hydration-safety contract
+ *
+ * The implementation must NEVER branch on `typeof window` (that renders
+ * different trees on server vs client first paint → hydration mismatch).
+ * Instead it follows the same pattern as the islands runtime's
+ * `defineClientComponent`: the placeholder (fallback) is rendered during SSR
+ * AND during the client's hydration render, then `onMounted` flips
+ * `mounted` and Vue patches in the real content.
+ *
+ * ## Output shape
+ *
+ * - Default (no fallback): renders a comment vnode on BOTH server and client
+ *   first paint — no wrapper element, no layout pollution.
+ * - `fallback` prop: renders the string as a text node.
+ * - `#fallback` slot: renders arbitrary placeholder content (reserve space to
+ *   avoid CLS — the default slot content is absent from the SSR HTML).
+ *
+ * ## Typing
+ *
+ * Props and slots are fully typed (`ClientOnlyProps` / `ClientOnlySlots`) so
+ * templates get `#fallback` autocompletion and vue-tsc rejects unknown slots.
+ * Uses the function-style `defineComponent<Props, E, S>` overload — the
+ * object-style overload cannot carry slot types.
+ *
+ * ## When to use what (vs islands)
+ *
+ * - `<ClientOnly>` — template fragments / browser-only markup, same-tree
+ *   rendering (full app context), works on plain HTML (the islands
+ *   `v-client.*` transform only matches capitalized component tags).
+ * - `v-client.only` — islands architecture: registry-driven, hydrated via a
+ *   separate app by `hydrateIslands()` (content inside an island placeholder
+ *   is replaced on hydration, so `<ClientOnly>` inside island children is
+ *   wiped with it).
+ * - `defineClientComponent` — programmatic wrapper (always renders a
+ *   `<div data-client-only>` wrapper element).
+ */
+export declare const ClientOnly: import("vue").DefineSetupFnComponent<ClientOnlyProps, {}, SlotsType<ClientOnlySlots>, ClientOnlyProps & {}, import("vue").PublicProps>;
 /**
  * PageView — renders the matched route page wrapped with `<Transition>` and
  * `<KeepAlive>`. Layouts use `<PageView />` (instead of `<slot />`) as the
@@ -123,7 +173,7 @@ declare const ErrorBoundary: import("vue").DefineComponent<import("vue").Extract
  * On SSR (via `SSR_KEY`), KeepAlive/Transition/Suspense/ErrorBoundary are
  * skipped (client-only concepts).
  */
-declare const PageView: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+export declare const PageView: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
   transition: {
     type: (BooleanConstructor | StringConstructor)[];
     default: undefined;
@@ -165,7 +215,7 @@ declare const PageView: import("vue").DefineComponent<import("vue").ExtractPropT
  * 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<{
+export declare const SlotView: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
   name: {
     type: StringConstructor;
     required: true;
@@ -183,7 +233,7 @@ declare const SlotView: import("vue").DefineComponent<import("vue").ExtractPropT
  * 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<{
+export declare const Link: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
   to: {
     type: PropType<string | Record<string, unknown>>;
     default: undefined;
@@ -288,9 +338,9 @@ interface UbeanVuePageData<TProps = Record<string, unknown>> {
  *
  * 未提供 `PAGE_KEY` 时返回共享的空对象(字段均为 undefined)。
  */
-declare function usePage<TProps = Record<string, unknown>>(): UbeanVuePageData<TProps>;
+export declare function usePage<TProps = Record<string, unknown>>(): UbeanVuePageData<TProps>;
 /** `useViewTransition()` — whether native View Transitions are available/enabled. */
-declare function useViewTransition(): {
+export declare function useViewTransition(): {
   enabled: boolean;
   supports: boolean;
   options: ViewTransitionOptions;
@@ -308,7 +358,7 @@ declare function useViewTransition(): {
  * const router = createRouter({ history: createWebHistory(), routes });
  * const app = createApp(App);
  * app.use(router);
- * app.use(ubeanVue, { routes }); // Link/PageView/SlotView + cache seeding
+ * app.use(ubeanVue, { routes }); // Link/PageView/SlotView/ClientOnly + cache seeding
  * app.mount('#app');
  * ```
  */
@@ -325,7 +375,7 @@ interface UbeanVueOptions {
     };
   }>;
 }
-declare const ubeanVue: Plugin<UbeanVueOptions>;
+export declare const ubeanVue: Plugin<UbeanVueOptions>;
 //#endregion
 //#region src/cache-views.d.ts
 interface UseCacheViewsReturn {
@@ -364,11 +414,11 @@ interface UseCacheViewsReturn {
  * 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;
+export declare function useCacheViews(): UseCacheViewsReturn;
 /** Enable keep-alive caching for a specific page (by route name). */
-declare function enablePageCache(name: string): void;
+export declare function enablePageCache(name: string): void;
 /** Disable keep-alive caching for a specific page (by route name). */
-declare function disablePageCache(name: string): void;
+export 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.
@@ -377,11 +427,11 @@ declare function disablePageCache(name: string): void;
  * 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;
+export declare function excludePageCache(name: string): void;
 /** Remove a route name from the cache exclude list (restores caching). */
-declare function includePageCache(name: string): void;
+export declare function includePageCache(name: string): void;
 /** Whether a specific page is currently excluded from cache. */
-declare function isPageExcluded(name: string): boolean;
+export declare function isPageExcluded(name: string): boolean;
 /**
  * Reload a cached page by pruning its keep-alive instance.
  *
@@ -403,7 +453,7 @@ declare function isPageExcluded(name: string): boolean;
  * @param delay Ignored — kept for signature compatibility with the previous
  *              exclude→include implementation.
  */
-declare function resetRouteCache(name?: string, _delay?: number): Promise<void>;
+export declare function resetRouteCache(name?: string, _delay?: number): Promise<void>;
 /**
  * Invalidate cached page instance(s).
  *
@@ -414,17 +464,17 @@ declare function resetRouteCache(name?: string, _delay?: number): Promise<void>;
  * 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;
+export declare function invalidatePageCache(name?: string): void;
 /** Whether a specific page is currently cached. */
-declare function isPageCached(name: string): boolean;
+export declare function isPageCached(name: string): boolean;
 /** Whether page caching is globally enabled. */
-declare function isCacheEnabled(): boolean;
+export declare function isCacheEnabled(): boolean;
 /** Reactive ref of cached route names — for advanced use cases. */
-declare function getCachedViewNames(): Ref<string[]>;
+export declare function getCachedViewNames(): Ref<string[]>;
 /** Reactive ref of excluded route names — for advanced use cases. */
-declare function getExcludedViewNames(): Ref<string[]>;
+export declare function getExcludedViewNames(): Ref<string[]>;
 /** Reactive ref of the global cache-enabled flag. */
-declare function getCacheEnabled(): Ref<boolean>;
+export declare function getCacheEnabled(): Ref<boolean>;
 /**
  * Seed the cache include list from route metadata.
  *
@@ -432,7 +482,7 @@ declare function getCacheEnabled(): Ref<boolean>;
  * declared `definePage({ cache: true })`. Routes without `meta.cache` are
  * left untouched so runtime toggling remains possible.
  */
-declare function initCachedViewsFromRoutes(routes: Array<{
+export declare function initCachedViewsFromRoutes(routes: Array<{
   name?: string | symbol;
   meta?: {
     cache?: boolean;
@@ -448,14 +498,14 @@ declare function initCachedViewsFromRoutes(routes: Array<{
  *
  * @internal — used by `createLayoutWrapper` in `app.ts`.
  */
-declare function getNamedPageWrapper(routeName: string, original: Component): Component;
+export 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;
+export declare function resetNamedPageWrappers(): void;
 //#endregion
 //#region src/page-runtime.d.ts
 interface UsePageTransitionReturn {
@@ -483,13 +533,13 @@ interface UsePageTransitionReturn {
  * transition.clear();
  * ```
  */
-declare function usePageTransition(): UsePageTransitionReturn;
+export declare function usePageTransition(): UsePageTransitionReturn;
 /** Imperatively set the global page transition name. */
-declare function setPageTransition(name: string): void;
+export declare function setPageTransition(name: string): void;
 /** Imperatively clear the global page transition name (disables transitions). */
-declare function clearPageTransition(): void;
+export declare function clearPageTransition(): void;
 /** Reactive ref of the global transition name — for advanced use cases. */
-declare function getPageTransitionName(): Ref<string>;
+export declare function getPageTransitionName(): Ref<string>;
 interface UseReloadSignalReturn {
   /** Reactive counter that increments on each `reloadPage()` call. */
   counter: ComputedRef<number>;
@@ -498,7 +548,7 @@ interface UseReloadSignalReturn {
   /** Trigger a reload of the current page. */
   reload: (routeName?: string, duration?: number) => Promise<void>;
 }
-declare function useReloadSignal(routeNameGetter?: () => string | undefined | null): UseReloadSignalReturn;
+export declare function useReloadSignal(routeNameGetter?: () => string | undefined | null): UseReloadSignalReturn;
 /**
  * Imperatively trigger a page reload.
  *
@@ -510,11 +560,11 @@ declare function useReloadSignal(routeNameGetter?: () => string | undefined | nu
  *   `useReloadSignal().counter` consumers; nothing remounts).
  * - `duration`: milliseconds to wait for transition/cleanup. Defaults to 300.
  */
-declare function reloadPage(name?: string, duration?: number): Promise<void>;
+export declare function reloadPage(name?: string, duration?: number): Promise<void>;
 /** Reactive ref of the reload counter — for advanced use cases. */
-declare function getReloadCounter(): Ref<number>;
+export declare function getReloadCounter(): Ref<number>;
 /** Whether a reload is currently in progress. */
-declare function isReloading(): boolean;
+export declare function isReloading(): boolean;
 //#endregion
 //#region src/define-page.d.ts
 /**
@@ -607,7 +657,7 @@ interface DefineClientPageOptions {
  * });
  * ```
  */
-declare function definePage(options?: DefineClientPageOptions): void;
+export declare function definePage(options?: DefineClientPageOptions): void;
 //#endregion
 //#region src/router-location.d.ts
 interface RouteLocationRaw {
@@ -618,7 +668,7 @@ interface RouteLocationRaw {
   hash?: string;
 }
 type RouteLocation = string | RouteLocationRaw;
-declare function resolveRoute(to: RouteLocation, routeMap?: Record<string, {
+export declare function resolveRoute(to: RouteLocation, routeMap?: Record<string, {
   path: string;
   route: string;
 }>): string;
@@ -631,7 +681,7 @@ type TypedLinkProps = {
   activeClass?: string;
   exactActiveClass?: string;
 };
-declare function isActiveRoute(currentPath: string, targetHref: string, exact?: boolean): boolean;
+export declare function isActiveRoute(currentPath: string, targetHref: string, exact?: boolean): boolean;
 //#endregion
 //#region src/matchers.d.ts
 /**
@@ -656,25 +706,25 @@ type MatcherFunction = (value: string) => boolean | null | undefined;
  * export default defineMatcher('numeric', (value) => /^\d+$/.test(value));
  * ```
  */
-declare function defineMatcher(name: string, fn: MatcherFunction): MatcherFunction;
+export declare function defineMatcher(name: string, fn: MatcherFunction): MatcherFunction;
 /**
  * 按名称获取已注册的 matcher。未注册时返回 `undefined`。
  */
-declare function getMatcher(name: string): MatcherFunction | undefined;
+export declare function getMatcher(name: string): MatcherFunction | undefined;
 /**
  * 判断指定名称的 matcher 是否已注册。
  */
-declare function hasMatcher(name: string): boolean;
+export declare function hasMatcher(name: string): boolean;
 /**
  * 获取所有已注册 matcher 的名称列表(主要用于调试 / DevTools)。
  */
-declare function listMatcherNames(): string[];
+export declare function listMatcherNames(): string[];
 /**
  * 清空所有已注册的 matcher。
  *
  * **仅供测试使用** —— 应用代码不应调用,避免误删其他模块注册的 matcher。
  */
-declare function clearMatchers(): void;
+export declare function clearMatchers(): void;
 /**
  * 校验一组路由参数是否通过对应的 matcher。
  *
@@ -689,7 +739,7 @@ declare function clearMatchers(): void;
  * - 若参数不存在于 `params` 中,视为校验失败返回 `false`
  * - matcher 函数抛异常时,捕获并视为不匹配
  */
-declare function validateParams(matchers: Record<string, string> | undefined, params: Record<string, string | string[] | undefined>): boolean;
+export declare function validateParams(matchers: Record<string, string> | undefined, params: Record<string, string | string[] | undefined>): boolean;
 interface MatcherGuardOptions {
   /**
    * matcher 校验失败时跳转的路由名。默认 `'NotFound'`。
@@ -728,7 +778,7 @@ interface MatcherGuardOptions {
  * - 对于纯 SPA 应用(`ssr: false`),强烈建议注册此守卫,否则客户端导航到
  *   `/users/abc`(应当被 `[id=numeric]` 拒绝)会渲染页面而非 404。
  */
-declare function createMatcherGuard(options?: MatcherGuardOptions): NavigationGuard;
+export declare function createMatcherGuard(options?: MatcherGuardOptions): NavigationGuard;
 //#endregion
 //#region src/head.d.ts
 /**
@@ -751,7 +801,7 @@ interface PageHeadClient {
  * 将静态 `PageHead` push 进 head 实例(falsy 字段自动跳过)。
  * 与 SSR 侧 `pushPageHead`(@ubean/client/ssr)语义一致,保证双端同构。
  */
-declare function pushPageHead(head: PageHeadClient, pageHead: PageHead): void;
+export declare function pushPageHead(head: PageHeadClient, pageHead: PageHead): void;
 /**
  * SPA 页面级 head 守卫:导航完成后读取 `route.meta.head` 并 push 进 head 实例。
  *
@@ -766,14 +816,14 @@ declare function pushPageHead(head: PageHeadClient, pageHead: PageHead): void;
  *
  * 初始导航同样触发(vue-router 首次导航完成后 afterEach 执行)。
  */
-declare function setupPageHeadGuard(router: Router, head: PageHeadClient): void;
+export declare function setupPageHeadGuard(router: Router, head: PageHeadClient): void;
 /**
  * 按需创建 head 实例(懒加载 `@unhead/vue`,optional peer dependency)。
  *
  * 项目已自带 unhead 实例时无需调用 —— 直接把实例传给
  * `setupPageHeadGuard` 即可,零额外加载。
  */
-declare function createPageHead(): Promise<PageHeadClient>;
+export declare function createPageHead(): Promise<PageHeadClient>;
 //#endregion
 //#region src/index.d.ts
 declare module 'vue-router' {
@@ -805,4 +855,4 @@ declare module 'vue-router' {
   }
 }
 //#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 };
+export { type ClientOnlyProps, type ClientOnlySlots, type DefineClientPageOptions, type LayoutChainContext, type MatcherFunction, type MatcherGuardOptions, type PageHead, type PageHeadClient, type PageMeta, type RouteLocation, type RouteLocationRaw, type ScanPagesOptions, type ScanPagesResult, type ScannedLayout, type ScannedPage, type TypedLinkProps, type UbeanVueOptions, type UbeanVuePageData, type UseCacheViewsReturn, type UsePageTransitionReturn, type UseReloadSignalReturn, type ViewTransitionOptions, ubeanVue as default };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { KeepAlive, Suspense, Transition, computed, createCommentVNode, defineAsyncComponent, defineComponent, h, inject, nextTick, onErrorCaptured, provide, reactive, ref, shallowRef, watch } from "vue";
+import { KeepAlive, Suspense, Transition, computed, createCommentVNode, createTextVNode, defineAsyncComponent, defineComponent, h, inject, nextTick, onErrorCaptured, onMounted, provide, reactive, ref, shallowRef, watch } from "vue";
 import { RouterLink, RouterView, useRoute } from "vue-router";
 //#region src/cache-views.ts
 /**
@@ -624,6 +624,61 @@ const ErrorBoundary = defineComponent({
 	}
 });
 /**
+* ClientOnly — renders its default slot ONLY on the client, after hydration.
+*
+* ## Hydration-safety contract
+*
+* The implementation must NEVER branch on `typeof window` (that renders
+* different trees on server vs client first paint → hydration mismatch).
+* Instead it follows the same pattern as the islands runtime's
+* `defineClientComponent`: the placeholder (fallback) is rendered during SSR
+* AND during the client's hydration render, then `onMounted` flips
+* `mounted` and Vue patches in the real content.
+*
+* ## Output shape
+*
+* - Default (no fallback): renders a comment vnode on BOTH server and client
+*   first paint — no wrapper element, no layout pollution.
+* - `fallback` prop: renders the string as a text node.
+* - `#fallback` slot: renders arbitrary placeholder content (reserve space to
+*   avoid CLS — the default slot content is absent from the SSR HTML).
+*
+* ## Typing
+*
+* Props and slots are fully typed (`ClientOnlyProps` / `ClientOnlySlots`) so
+* templates get `#fallback` autocompletion and vue-tsc rejects unknown slots.
+* Uses the function-style `defineComponent<Props, E, S>` overload — the
+* object-style overload cannot carry slot types.
+*
+* ## When to use what (vs islands)
+*
+* - `<ClientOnly>` — template fragments / browser-only markup, same-tree
+*   rendering (full app context), works on plain HTML (the islands
+*   `v-client.*` transform only matches capitalized component tags).
+* - `v-client.only` — islands architecture: registry-driven, hydrated via a
+*   separate app by `hydrateIslands()` (content inside an island placeholder
+*   is replaced on hydration, so `<ClientOnly>` inside island children is
+*   wiped with it).
+* - `defineClientComponent` — programmatic wrapper (always renders a
+*   `<div data-client-only>` wrapper element).
+*/
+const ClientOnly = defineComponent((props, { slots }) => {
+	const mounted = ref(false);
+	onMounted(() => {
+		mounted.value = true;
+	});
+	return () => {
+		if (mounted.value) return slots.default?.() ?? null;
+		if (slots.fallback) return slots.fallback();
+		if (props.fallback !== void 0) return createTextVNode(props.fallback);
+		return createCommentVNode("client-only");
+	};
+}, {
+	name: "ClientOnly",
+	inheritAttrs: false,
+	props: ["fallback"]
+});
+/**
 * PageView — renders the matched route page wrapped with `<Transition>` and
 * `<KeepAlive>`. Layouts use `<PageView />` (instead of `<slot />`) as the
 * page outlet.
@@ -868,6 +923,7 @@ const ubeanVue = { install(app, options) {
 	app.component("Link", Link);
 	app.component("PageView", PageView);
 	app.component("SlotView", SlotView);
+	app.component("ClientOnly", ClientOnly);
 	if (options?.routes) initCachedViewsFromRoutes(options.routes);
 } };
 //#endregion
@@ -1092,4 +1148,4 @@ async function createPageHead() {
 	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 };
+export { ClientOnly, 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 };

package/dist/vite.d.ts

@@ -10,13 +10,13 @@ import { Plugin } from "vite";
  *   `(.)target/page.vue`   → intercept from same level, target = 'target'
  *   `(...)target/page.vue` → intercept from root, target = 'target'
  */
-declare function extractSlotAndIntercept(fileBase: string): {
+export declare function extractSlotAndIntercept(fileBase: string): {
   cleanedBase: string;
   slot?: string;
   interceptFrom?: string;
   interceptTarget?: string;
 };
-declare function scanPages(options: ScanPagesOptions): Promise<ScanPagesResult>;
+export declare function scanPages(options: ScanPagesOptions): Promise<ScanPagesResult>;
 //#endregion
 //#region src/virtual-pages.d.ts
 type PagesModuleInput = Pick<ScanPagesResult, 'pages' | 'layouts' | 'notFoundPage' | 'loadingPage' | 'errorPage'>;
@@ -28,7 +28,7 @@ interface LocaleRouteCompileOptions {
   vueParam?: string;
 }
 /** Generate the virtual module source(plain JS — no TS syntax, SSR-safe)。 */
-declare function generatePagesModuleSource(input: PagesModuleInput, locale?: LocaleRouteCompileOptions): string;
+export declare function generatePagesModuleSource(input: PagesModuleInput, locale?: LocaleRouteCompileOptions): string;
 /**
  * Generate the ambient module declaration d.ts for the virtual module.
  *
@@ -36,7 +36,7 @@ declare function generatePagesModuleSource(input: PagesModuleInput, locale?: Loc
  * script 上下文中才注册「环境模块声明」;在 module 文件中会被当作模块增强,
  * 对不存在的模块无法生效。由 `/vite` 插件写入 `<root>/ubean-vue-routes.d.ts`。
  */
-declare function generateVirtualModuleDts(input: PagesModuleInput, moduleId?: string): string;
+export declare function generateVirtualModuleDts(input: PagesModuleInput, moduleId?: string): string;
 /**
  * Generate `typed-router.d.ts` content for the virtual module.
  *
@@ -48,10 +48,10 @@ declare function generateVirtualModuleDts(input: PagesModuleInput, moduleId?: st
  * 若以 script 形式输出,同名环境模块声明会整体遮蔽真实包的类型。
  * 虚拟模块自身的环境声明见 `generateVirtualModuleDts`。
  */
-declare function generateTypedRouter(input: PagesModuleInput, _moduleId?: string): string;
+export declare function generateTypedRouter(input: PagesModuleInput, _moduleId?: string): string;
 //#endregion
 //#region src/route-path.d.ts
-declare function stripRouteGroups(path: string): string;
+export declare function stripRouteGroups(path: string): string;
 interface ParsedRoutePath {
   route: string;
   method?: string;
@@ -78,11 +78,11 @@ interface ParsedRoutePath {
  * parseMatchers('blog/[...slug=any]') → { cleaned: 'blog/[...slug]', matchers: { slug: 'any' } }
  * parseMatchers('users/[id]')         → { cleaned: 'users/[id]', matchers: undefined }
  */
-declare function parseMatchers(filePath: string): {
+export declare function parseMatchers(filePath: string): {
   cleaned: string;
   matchers?: Record<string, string>;
 };
-declare function filePathToRoute(filePath: string, prefix?: string): ParsedRoutePath;
+export declare function filePathToRoute(filePath: string, prefix?: string): ParsedRoutePath;
 //#endregion
 //#region src/route-name.d.ts
 /**
@@ -90,8 +90,8 @@ declare function filePathToRoute(filePath: string, prefix?: string): ParsedRoute
  * `@ubean/scan` 聚合层 re-export 保持向后兼容;服务端专用的
  * `generateApiRouteId` 保留在 `@ubean/scan`。
  */
-declare function generateRouteName(routePath: string): string;
-declare function generateLayoutName(layoutPath: string): string;
+export declare function generateRouteName(routePath: string): string;
+export declare function generateLayoutName(layoutPath: string): string;
 //#endregion
 //#region src/extract-page.d.ts
 /**
@@ -99,7 +99,7 @@ declare function generateLayoutName(layoutPath: string): string;
  * 对象字面量参数。供本包的 `definePage` 提取与 `@ubean/scan` 的
  * `defineHandlerMeta` 提取共用(单一解析器实现)。
  */
-declare function extractCallObject(code: string, funcName: string): Record<string, unknown> | null;
+export declare function extractCallObject(code: string, funcName: string): Record<string, unknown> | null;
 /**
  * Normalize a parsed `head` value into a `PageHead` object。
  *
@@ -107,8 +107,8 @@ declare function extractCallObject(code: string, funcName: string): Record<strin
  * `definePage`) and Markdown pages (via frontmatter) share the same rules.
  */
 declare function normalizePageHead(raw: unknown): PageHead | undefined;
-declare function extractDefinePageFromCode(code: string): PageMeta | null;
-declare function extractDefinePage(filePath: string): Promise<PageMeta | null>;
+export declare function extractDefinePageFromCode(code: string): PageMeta | null;
+export declare function extractDefinePage(filePath: string): Promise<PageMeta | null>;
 //#endregion
 //#region src/vite.d.ts
 /**
@@ -125,8 +125,8 @@ declare function extractDefinePage(filePath: string): Promise<PageMeta | null>;
  * 框架层(`@ubean/vite`)通过 `generatePagesModuleSource` /
  * `scanPages` / `generateTypedRouter` 复用同一套生成器。
  */
-declare const VUE_ROUTES_MODULE_ID = "virtual:ubean-vue-routes";
-interface UbeanVueViteOptions {
+export declare const VUE_ROUTES_MODULE_ID = "virtual:ubean-vue-routes";
+export interface UbeanVueViteOptions {
   /** 页面目录(相对项目根或绝对),支持多目录。默认 `'src/pages'`。 */
   pagesDir?: string | string[];
   /** 布局目录(相对项目根或绝对),支持多目录。默认 `'src/layouts'`。 */
@@ -161,11 +161,11 @@ interface UbeanVueViteOptions {
   head?: boolean;
 }
 /** 剥离 `definePage({...})` 宏调用(构建期,扫描后源码中不再需要)。 */
-declare function stripDefinePageCalls(code: string): string;
+export declare function stripDefinePageCalls(code: string): string;
 /**
  * 扫描客户端页面/布局(对外工具函数,`root` 为项目根)。
  */
-declare function scanClientPages(root: string, options?: UbeanVueViteOptions): Promise<ScanPagesResult>;
-declare function ubeanVueVite(options?: UbeanVueViteOptions): Plugin;
+export declare function scanClientPages(root: string, options?: UbeanVueViteOptions): Promise<ScanPagesResult>;
+export declare function ubeanVueVite(options?: UbeanVueViteOptions): Plugin;
 //#endregion
-export { type LocaleRouteCompileOptions, type PagesModuleInput, type ParsedRoutePath, UbeanVueViteOptions, VUE_ROUTES_MODULE_ID, ubeanVueVite as default, ubeanVueVite, extractCallObject, extractDefinePage, extractDefinePageFromCode, extractSlotAndIntercept, filePathToRoute, generateLayoutName, generatePagesModuleSource, generateRouteName, generateTypedRouter, generateVirtualModuleDts, normalizePageHead, parseMatchers, scanClientPages, scanPages, stripDefinePageCalls, stripRouteGroups };
+export { type LocaleRouteCompileOptions, type PagesModuleInput, type ParsedRoutePath, ubeanVueVite as default, normalizePageHead };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/vue",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Lean Vue client kernel & page-routing owner for ubean — plugin-first page routing outlet, page cache (keep-alive), transitions, reload signal, definePage macro + file-routing Vite plugin (/vite: multi-dir scan, reuse routes, markdown & page-head opt-in). Runtime deps: vue + vue-router only.",
   "files": [
     "dist"
@@ -33,13 +33,13 @@
   },
   "devDependencies": {
     "@types/node": "^26.5.0",
-    "@ubean/markdown": "0.4.5",
+    "@ubean/markdown": "0.4.6",
     "@unhead/vue": "^3.4.0",
     "@vue/server-renderer": "^3.5.42",
     "happy-dom": "^20.14.0",
-    "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
-    "vite-plus": "0.3.0",
+    "typescript": "npm:typescript-native-bridge@latest",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.1",
+    "vite-plus": "0.3.1",
     "vitest": "5.0.0"
   },
   "peerDependencies": {