@ubean/runtime 0.1.7 → 0.1.8

package/dist/define-app.d.ts

@@ -60,6 +60,50 @@ interface DefineAppOptions {
   errorComponent?: Component;
   loadingComponent?: Component;
   viewTransitions?: boolean | ViewTransitionOptions;
+  /**
+   * SSR 专用:在 `renderToString(app)` 完成后调用,从 app 实例提取需要
+   * 序列化到客户端的状态(如 Pinia 的 `pinia.state.value`)。
+   *
+   * 返回的对象会被 `safeJsonStringify` 序列化并注入到 HTML 的
+   * `__UBEAN_STATE__` script 标签中。
+   *
+   * 仅在 server mode 下生效;client mode 下被忽略。
+   *
+   * @example
+   * ```ts
+   * import { createPinia } from 'pinia';
+   * defineApp({
+   *   plugins: [createPinia()],
+   *   serializeState: (app) => ({
+   *     pinia: app.config.globalProperties.$pinia.state.value
+   *   })
+   * });
+   * ```
+   */
+  serializeState?: (app: App) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /**
+   * Client 专用:在 `applyAppConfig`(注册插件/provide)之后、`app.mount()` 之前调用,
+   * 用于从 `__UBEAN_STATE__` 反序列化的状态回填到 app(如 Pinia 的水合)。
+   *
+   * `state` 即 `serializeState` 在服务端返回的对象;若服务端未配置 `serializeState`
+   * 或返回空,`state` 为 `null`。
+   *
+   * 仅在 client mode 下生效;server mode 下被忽略。
+   *
+   * @example
+   * ```ts
+   * import { createPinia } from 'pinia';
+   * defineApp({
+   *   plugins: [createPinia()],
+   *   hydrateState: (app, state) => {
+   *     if (state?.pinia) {
+   *       app.config.globalProperties.$pinia.state.value = state.pinia;
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  hydrateState?: (app: App, state: Record<string, unknown> | null) => void;
 }
 interface ResolvedAppConfig {
   plugins: AppPluginConfig[];
@@ -74,9 +118,21 @@ interface ResolvedAppConfig {
   errorComponent?: Component;
   loadingComponent?: Component;
   viewTransitions?: boolean | ViewTransitionOptions;
+  serializeState?: (app: App) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  hydrateState?: (app: App, state: Record<string, unknown> | null) => void;
 }
 declare function defineApp(options: DefineAppOptions): ResolvedAppConfig;
 declare function applyAppConfig(app: App, config: ResolvedAppConfig, mode: 'client' | 'server'): void;
 declare function createDefaultAppConfig(): ResolvedAppConfig;
+/**
+ * 从多个 `ResolvedAppConfig` 合并出一个最终配置(shared + client/server)。
+ *
+ * `serializeState` 与 `hydrateState` 的合并语义:server 配置的 `serializeState` 优先,
+ * client 配置的 `hydrateState` 优先;shared 配置作为默认值。
+ *
+ * 这个函数在 `virtual:ubean-app` 虚拟模块中以 JS 字符串形式重新实现
+ * (`_mergeAppConfig`),保持两者语义一致。
+ */
+declare function mergeAppConfig(base: ResolvedAppConfig, ...configs: (ResolvedAppConfig | null | undefined)[]): ResolvedAppConfig;
 //#endregion
-export { AppPluginConfig, DefineAppOptions, ResolvedAppConfig, RouterConfig, applyAppConfig, createDefaultAppConfig, defineApp };
+export { AppPluginConfig, DefineAppOptions, ResolvedAppConfig, RouterConfig, applyAppConfig, createDefaultAppConfig, defineApp, mergeAppConfig };

package/dist/define-app.js

@@ -22,7 +22,9 @@ function defineApp(options) {
 		onClientReady: options.onClientReady,
 		errorComponent: options.errorComponent,
 		loadingComponent: options.loadingComponent,
-		viewTransitions: options.viewTransitions
+		viewTransitions: options.viewTransitions,
+		serializeState: options.serializeState,
+		hydrateState: options.hydrateState
 	};
 }
 function applyAppConfig(app, config, mode) {
@@ -40,5 +42,54 @@ function createDefaultAppConfig() {
 		rootAttrs: {}
 	};
 }
+/**
+* 从多个 `ResolvedAppConfig` 合并出一个最终配置(shared + client/server)。
+*
+* `serializeState` 与 `hydrateState` 的合并语义:server 配置的 `serializeState` 优先,
+* client 配置的 `hydrateState` 优先;shared 配置作为默认值。
+*
+* 这个函数在 `virtual:ubean-app` 虚拟模块中以 JS 字符串形式重新实现
+* (`_mergeAppConfig`),保持两者语义一致。
+*/
+function mergeAppConfig(base, ...configs) {
+	const result = { ...base };
+	for (const cfg of configs) {
+		if (!cfg) continue;
+		if (cfg.plugins) result.plugins = [...result.plugins || [], ...cfg.plugins];
+		if (cfg.globalComponents) result.globalComponents = {
+			...result.globalComponents,
+			...cfg.globalComponents
+		};
+		if (cfg.provides) result.provides = {
+			...result.provides,
+			...cfg.provides
+		};
+		if (cfg.head) result.head = {
+			...result.head,
+			...cfg.head
+		};
+		if (cfg.rootId) result.rootId = cfg.rootId;
+		if (cfg.rootAttrs) result.rootAttrs = {
+			...result.rootAttrs,
+			...cfg.rootAttrs
+		};
+		if (cfg.onAppCreated) result.onAppCreated = cfg.onAppCreated;
+		if (cfg.onClientReady) result.onClientReady = cfg.onClientReady;
+		if (cfg.errorComponent) result.errorComponent = cfg.errorComponent;
+		if (cfg.loadingComponent) result.loadingComponent = cfg.loadingComponent;
+		if (cfg.viewTransitions !== void 0) result.viewTransitions = cfg.viewTransitions;
+		if (cfg.serializeState) result.serializeState = cfg.serializeState;
+		if (cfg.hydrateState) result.hydrateState = cfg.hydrateState;
+		if (cfg.router?.setup) {
+			const prevSetup = result.router?.setup;
+			if (prevSetup) result.router = { setup: (router) => {
+				prevSetup(router);
+				cfg.router.setup(router);
+			} };
+			else result.router = { setup: cfg.router.setup };
+		}
+	}
+	return result;
+}
 //#endregion
-export { applyAppConfig, createDefaultAppConfig, defineApp };
+export { applyAppConfig, createDefaultAppConfig, defineApp, mergeAppConfig };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { a as UbeanAppOptions, c as createUbeanApp, d as useRouter, f as useSeoMeta, g as createUbeanRouter, h as CreateUbeanRouterOptions, i as UbeanAppInstance, l as createUbeanSSRApp, m as useViewTransition, n as Link, p as useUnheadHead, r as PageView, s as VueHeadClient$1, t as Head, u as usePage } from "./app-CDOvFfdJ.js";
 import { a as withViewTransition, i as useViewTransitionState, n as getNavigationType, r as supportsViewTransitions, t as ViewTransitionOptions } from "./view-transitions-DRrLaRHL.js";
-import { AppPluginConfig, DefineAppOptions, ResolvedAppConfig, applyAppConfig, createDefaultAppConfig, defineApp } from "./define-app.js";
+import { AppPluginConfig, DefineAppOptions, ResolvedAppConfig, applyAppConfig, createDefaultAppConfig, defineApp, mergeAppConfig } from "./define-app.js";
 import { VueHeadClient, injectHead } from "@unhead/vue";
 import { createHead as createClientHead } from "@unhead/vue/client";
 import { createHead as createServerHead } from "@unhead/vue/server";
@@ -12,6 +12,17 @@ import { DefineMetaResult, PageMeta } from "@ubean/routing";
 import { LinkTag, MetaTag, SeoMetadata } from "@ubean/seo";
 //#region src/client.d.ts
 declare function getInitialPageData<T = Record<string, unknown>>(): PageObject<T> | null;
+/**
+ * 从 DOM 中的 `<script id="__UBEAN_STATE__">` 读取 SSR 序列化的状态。
+ *
+ * 该状态由服务端 `defineApp({ serializeState })` 产生,用于在客户端 mount 前
+ * 水合到对应的库实例(如 Pinia 的 `pinia.state.value`)。
+ *
+ * 必须在 `app.mount()` 之前调用(在 `defineApp({ hydrateState })` 内部使用)。
+ *
+ * @returns 解析后的状态对象,或 `null`(无状态 / 解析失败 / 非 DOM 环境)
+ */
+declare function getInitialState(): Record<string, unknown> | null;
 //#endregion
 //#region src/head.d.ts
 declare function useHeadInstance(): import("@unhead/vue").VueHeadClient;
@@ -390,4 +401,4 @@ declare module 'vue-router' {
   }
 }
 //#endregion
-export { type AppPluginConfig, type CreateUbeanRouterOptions, type DataCacheStore, type DefineAppOptions, Head, type VueHeadClient as HeadClient, type HydrateIslandsOptions, type IslandHydrateOptions, type IslandRecord, Link, type LinkProps, type LinkTag, type MetaTag, PageView, type ResolvedAppConfig, type RouteLocation, type RouteLocationRaw, type SeoMetadata, type TypedLinkProps, type UbeanAppInstance, type UbeanAppOptions, type UbeanVueContext, type UseAsyncDataOptions, type UseAsyncDataReturn, type UseCacheViewsReturn, type UsePageTransitionReturn, type UseReloadSignalReturn, type ViewTransitionOptions, type VueHeadClient$1 as VueHeadClient, type VueI18nInstance, addLocale, applyAppConfig, clearCache, clearLocales, clearPageTransition, collectIslands, createClientHead, createDataCacheStore, createDefaultAppConfig, createLinkHandler, createServerHead, createUbeanApp, createUbeanRouter, createUbeanSSRApp, createUseAsyncData, defineApp, defineDataKey, defineLocale, defineMeta, defineMiddleware, definePage, detectBrowserLocale, detectLocale, disablePageCache, enablePageCache, excludePageCache, extractLocaleFromPath, extractPageData, getCacheEnabled, getCachedViewNames, getDefaultLocale, getExcludedViewNames, getI18nConfig, getInitialPageData, getInvalidatedKeysForAction, getLocale, getLocaleDir, getLocaleName, getNavigationType, getPageTransitionName, getRegisteredLocales, getReloadCounter, hydrateIsland, hydrateIslands, includePageCache, initCachedViewsFromRoutes, injectHead, invalidateCache, invalidatePageCache, isActiveRoute, isCacheEnabled, isPageCached, isPageExcluded, isReloading, localizePath, mergeLocale, onLocaleChange, reloadPage, resetRouteCache, resolveRoute, setI18nConfig, setLocale, setPageTransition, supportsViewTransitions, switchLocalePath, t, useCacheViews, useUnheadHead as useHead, useHeadInstance, useI18n, useLocalePath, usePage, usePageTransition, useReloadSignal, useRouter, useSeoMeta, useServerData, useSwitchLocalePath, useViewTransition, useViewTransitionState, withViewTransition };
+export { type AppPluginConfig, type CreateUbeanRouterOptions, type DataCacheStore, type DefineAppOptions, Head, type VueHeadClient as HeadClient, type HydrateIslandsOptions, type IslandHydrateOptions, type IslandRecord, Link, type LinkProps, type LinkTag, type MetaTag, PageView, type ResolvedAppConfig, type RouteLocation, type RouteLocationRaw, type SeoMetadata, type TypedLinkProps, type UbeanAppInstance, type UbeanAppOptions, type UbeanVueContext, type UseAsyncDataOptions, type UseAsyncDataReturn, type UseCacheViewsReturn, type UsePageTransitionReturn, type UseReloadSignalReturn, type ViewTransitionOptions, type VueHeadClient$1 as VueHeadClient, type VueI18nInstance, addLocale, applyAppConfig, clearCache, clearLocales, clearPageTransition, collectIslands, createClientHead, createDataCacheStore, createDefaultAppConfig, createLinkHandler, createServerHead, createUbeanApp, createUbeanRouter, createUbeanSSRApp, createUseAsyncData, defineApp, defineDataKey, defineLocale, defineMeta, defineMiddleware, definePage, detectBrowserLocale, detectLocale, disablePageCache, enablePageCache, excludePageCache, extractLocaleFromPath, extractPageData, getCacheEnabled, getCachedViewNames, getDefaultLocale, getExcludedViewNames, getI18nConfig, getInitialPageData, getInitialState, getInvalidatedKeysForAction, getLocale, getLocaleDir, getLocaleName, getNavigationType, getPageTransitionName, getRegisteredLocales, getReloadCounter, hydrateIsland, hydrateIslands, includePageCache, initCachedViewsFromRoutes, injectHead, invalidateCache, invalidatePageCache, isActiveRoute, isCacheEnabled, isPageCached, isPageExcluded, isReloading, localizePath, mergeAppConfig, mergeLocale, onLocaleChange, reloadPage, resetRouteCache, resolveRoute, setI18nConfig, setLocale, setPageTransition, supportsViewTransitions, switchLocalePath, t, useCacheViews, useUnheadHead as useHead, useHeadInstance, useI18n, useLocalePath, usePage, usePageTransition, useReloadSignal, useRouter, useSeoMeta, useServerData, useSwitchLocalePath, useViewTransition, useViewTransitionState, withViewTransition };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { $ as setI18nConfig, A as initCachedViewsFromRoutes, B as defineLocale, C as disablePageCache, D as getCachedViewNames, E as getCacheEnabled, F as resetRouteCache, G as getI18nConfig, H as detectLocale, I as useCacheViews, J as getLocaleName, K as getLocale, L as createUbeanRouter, M as isCacheEnabled, N as isPageCached, O as getExcludedViewNames, P as isPageExcluded, Q as onLocaleChange, R as addLocale, S as useReloadSignal, T as excludePageCache, U as extractLocaleFromPath, V as detectBrowserLocale, W as getDefaultLocale, X as localizePath, Y as getRegisteredLocales, Z as mergeLocale, _ as getReloadCounter, a as createUbeanSSRApp, at as useSwitchLocalePath, b as setPageTransition, c as useSeoMeta, d as getNavigationType, et as setLocale, f as supportsViewTransitions, g as getPageTransitionName, h as clearPageTransition, i as createUbeanApp, it as useLocalePath, j as invalidatePageCache, k as includePageCache, l as useUnheadHead, m as withViewTransition, n as Link, nt as t, o as usePage, p as useViewTransitionState, q as getLocaleDir, r as PageView, rt as useI18n, s as useRouter, t as Head, tt as switchLocalePath, u as useViewTransition, v as isReloading, w as enablePageCache, x as usePageTransition, y as reloadPage, z as clearLocales } from "./app-dx92OPRP.js";
-import { applyAppConfig, createDefaultAppConfig, defineApp } from "./define-app.js";
+import { applyAppConfig, createDefaultAppConfig, defineApp, mergeAppConfig } from "./define-app.js";
 import { injectHead, injectHead as injectHead$1 } from "@unhead/vue";
 import { createHead as createClientHead } from "@unhead/vue/client";
 import { createHead as createServerHead } from "@unhead/vue/server";
@@ -17,6 +17,28 @@ function getInitialPageData() {
 		return null;
 	}
 }
+/**
+* 从 DOM 中的 `<script id="__UBEAN_STATE__">` 读取 SSR 序列化的状态。
+*
+* 该状态由服务端 `defineApp({ serializeState })` 产生,用于在客户端 mount 前
+* 水合到对应的库实例(如 Pinia 的 `pinia.state.value`)。
+*
+* 必须在 `app.mount()` 之前调用(在 `defineApp({ hydrateState })` 内部使用)。
+*
+* @returns 解析后的状态对象,或 `null`(无状态 / 解析失败 / 非 DOM 环境)
+*/
+function getInitialState() {
+	if (typeof _global$2.document === "undefined") return null;
+	const el = _global$2.document.getElementById("__UBEAN_STATE__");
+	if (!el) return _global$2.__UBEAN_STATE__ ?? null;
+	try {
+		const text = el.textContent || "";
+		if (!text.trim()) return null;
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
 //#endregion
 //#region src/head.ts
 function useHeadInstance() {
@@ -361,4 +383,4 @@ function resolveComponent(name, components, getComponent) {
 	return null;
 }
 //#endregion
-export { Head, Link, PageView, addLocale, applyAppConfig, clearCache, clearLocales, clearPageTransition, collectIslands, createClientHead, createDataCacheStore, createDefaultAppConfig, createLinkHandler, createServerHead, createUbeanApp, createUbeanRouter, createUbeanSSRApp, createUseAsyncData, defineApp, defineDataKey, defineLocale, defineMeta, defineMiddleware, definePage, detectBrowserLocale, detectLocale, disablePageCache, enablePageCache, excludePageCache, extractLocaleFromPath, extractPageData, getCacheEnabled, getCachedViewNames, getDefaultLocale, getExcludedViewNames, getI18nConfig, getInitialPageData, getInvalidatedKeysForAction, getLocale, getLocaleDir, getLocaleName, getNavigationType, getPageTransitionName, getRegisteredLocales, getReloadCounter, hydrateIsland, hydrateIslands, includePageCache, initCachedViewsFromRoutes, injectHead, invalidateCache, invalidatePageCache, isActiveRoute, isCacheEnabled, isPageCached, isPageExcluded, isReloading, localizePath, mergeLocale, onLocaleChange, reloadPage, resetRouteCache, resolveRoute, setI18nConfig, setLocale, setPageTransition, supportsViewTransitions, switchLocalePath, t, useCacheViews, useUnheadHead as useHead, useHeadInstance, useI18n, useLocalePath, usePage, usePageTransition, useReloadSignal, useRouter, useSeoMeta, useServerData, useSwitchLocalePath, useViewTransition, useViewTransitionState, withViewTransition };
+export { Head, Link, PageView, addLocale, applyAppConfig, clearCache, clearLocales, clearPageTransition, collectIslands, createClientHead, createDataCacheStore, createDefaultAppConfig, createLinkHandler, createServerHead, createUbeanApp, createUbeanRouter, createUbeanSSRApp, createUseAsyncData, defineApp, defineDataKey, defineLocale, defineMeta, defineMiddleware, definePage, detectBrowserLocale, detectLocale, disablePageCache, enablePageCache, excludePageCache, extractLocaleFromPath, extractPageData, getCacheEnabled, getCachedViewNames, getDefaultLocale, getExcludedViewNames, getI18nConfig, getInitialPageData, getInitialState, getInvalidatedKeysForAction, getLocale, getLocaleDir, getLocaleName, getNavigationType, getPageTransitionName, getRegisteredLocales, getReloadCounter, hydrateIsland, hydrateIslands, includePageCache, initCachedViewsFromRoutes, injectHead, invalidateCache, invalidatePageCache, isActiveRoute, isCacheEnabled, isPageCached, isPageExcluded, isReloading, localizePath, mergeAppConfig, mergeLocale, onLocaleChange, reloadPage, resetRouteCache, resolveRoute, setI18nConfig, setLocale, setPageTransition, supportsViewTransitions, switchLocalePath, t, useCacheViews, useUnheadHead as useHead, useHeadInstance, useI18n, useLocalePath, usePage, usePageTransition, useReloadSignal, useRouter, useSeoMeta, useServerData, useSwitchLocalePath, useViewTransition, useViewTransitionState, withViewTransition };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/runtime",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Vue client runtime for ubean (createUbeanApp, useRouter, useHead, Link, Head, PageView, composables, view-transitions, cache-views, islands hydrate)",
   "files": [
     "dist"
@@ -27,18 +27,18 @@
     "@unhead/vue": "^3.2.3",
     "vue": "^3.5.40",
     "vue-router": "^5.2.0",
-    "@ubean/i18n": "0.1.7",
-    "@ubean/pages": "0.1.7",
-    "@ubean/types": "0.1.7"
+    "@ubean/i18n": "0.1.8",
+    "@ubean/types": "0.1.8",
+    "@ubean/pages": "0.1.8"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
-    "typescript": "6.0.3",
+    "@types/node": "^26.1.2",
+    "typescript": "7.0.2",
     "vite-plus": "0.2.6"
   },
   "peerDependencies": {
-    "@ubean/routing": "0.1.7",
-    "@ubean/seo": "0.1.7"
+    "@ubean/routing": "0.1.8",
+    "@ubean/seo": "0.1.8"
   },
   "peerDependenciesMeta": {
     "@ubean/seo": {