@ubean/pages 0.1.13 → 0.2.1

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { PageHead, PageHead as PageHead$1, PageHead as PageHeadMeta } from "@ubean/types";
+import { Ref, ShallowRef } from "vue";
+import { PageHead, PageHead as PageHead$1, PageHead as PageHeadMeta } from "@ubean/shared";
 //#region src/protocol.d.ts
 interface PageObject<Props = Record<string, unknown>> {
   component: string;
@@ -45,8 +46,19 @@ type PageRenderResult = string | {
   state?: Record<string, unknown>;
 };
 type PageRenderFn = (pageObj: PageObject, shellHtml: string, assetTags: PageAssetTags, renderContext?: PageRenderContext) => PageRenderResult | Promise<PageRenderResult>;
+/**
+ * 流式渲染函数:返回一个 `ReadableStream<Uint8Array>`,将完整 HTML 文档
+ * 分块流式输出(头部先发送,app HTML 边渲染边输出,state 在尾部注入)。
+ *
+ * 由 `@ubean/ssr` 的 `createVueRenderer` 实现。当 renderer 提供此方法且
+ * 应用配置启用了 `streaming` 时,页面处理器会优先使用流式渲染,显著改善
+ * TTFB/LCP(浏览器可在 app 渲染期间提前加载 CSS/JS)。
+ */
+type PageStreamRenderFn = (pageObj: PageObject, shellHtml: string, assetTags: PageAssetTags, renderContext?: PageRenderContext) => ReadableStream<Uint8Array>;
 interface PageRenderer {
   render: PageRenderFn;
+  /** 流式渲染(可选)。提供时优先于 `render` 用于流式 SSR 响应。 */
+  renderToStream?: PageStreamRenderFn;
   preambleScript?: string;
 }
 declare const PAGE_DATA_ID = "__UBEAN_PAGE_DATA__";
@@ -64,6 +76,11 @@ declare function isPagesRequest(c: {
 declare function safeJsonStringify(value: unknown): string;
 declare function serializePageData(pageObj: PageObject): string;
 declare function pageJsonResponse(pageObj: PageObject, headers?: Record<string, string>): Response;
+/**
+ * 生成 favicon `<link>` 标签字符串。
+ * 当 `favicon` 为空/未设置时返回空字符串。
+ */
+declare function renderFaviconLink(favicon?: string): string;
 declare function buildPageShell(pageObj: PageObject, assetTags: PageAssetTags, preambleScript?: string, appId?: string, renderContext?: PageRenderContext): string;
 declare function insertSsrContent(shell: string, appHtml: string): string;
 /**
@@ -78,6 +95,17 @@ declare function insertSsrContent(shell: string, appHtml: string): string;
 declare function insertStateContent(shell: string, stateJson: string | null): string;
 declare function buildClientOnlyShell(pageObj: PageObject, assetTags: PageAssetTags, preambleScript?: string, appId?: string, renderContext?: PageRenderContext): string;
 declare function renderPage(pageObj: PageObject, assetTags: PageAssetTags, renderer: PageRenderer | null, appId?: string, renderContext?: PageRenderContext): Promise<string>;
+/**
+ * 流式渲染页面:当 renderer 提供 `renderToStream` 时,返回一个
+ * `ReadableStream<Uint8Array>`,将完整 HTML 文档分块流式输出。
+ *
+ * 当 renderer 不支持流式(无 `renderToStream`)时,回退到缓冲式 `renderPage`,
+ * 返回一个包含完整 HTML 的单块流(保持调用方接口一致)。
+ *
+ * 调用方应使用 `c.body(stream, { headers: { 'Content-Type': 'text/html; charset=utf-8' } })`
+ * 将流作为 HTTP 响应返回。
+ */
+declare function renderPageToStream(pageObj: PageObject, assetTags: PageAssetTags, renderer: PageRenderer | null, appId?: string, renderContext?: PageRenderContext): ReadableStream<Uint8Array>;
 //#endregion
 //#region src/data.d.ts
 type DataKey = string | symbol;
@@ -90,24 +118,110 @@ interface DataCacheEntry<T = unknown> {
 }
 type DataFetcher<T> = () => T | Promise<T>;
 declare function defineDataKey(key: string): symbol;
+/**
+ * `__UBEAN_DATA__` script 标签 ID — SSR 渲染时,useData 解析的数据以 JSON 形式
+ * 注入到此标签中,客户端水合时读取,避免二次请求。
+ *
+ * 与 `__UBEAN_DEFERRED__`(非关键延迟数据)和 `__UBEAN_STATE__`(用户状态如 Pinia)
+ * 分离,职责单一,便于 SSG payload 提取(roadmap Task 3)。
+ */
+declare const DATA_PAYLOAD_ID = "__UBEAN_DATA__";
+/**
+ * SSR payload 条目:记录 useData 解析结果,序列化到 `__UBEAN_DATA__`。
+ * `error` 以字符串形式存储(可序列化),客户端水合时重建为 Error。
+ */
+interface DataPayloadEntry {
+  data: unknown;
+  error: string | null;
+  timestamp: number;
+}
+/**
+ * SSR 内部:注册一个 useData 解析结果到 payload。
+ *
+ * 在 `useData` 的 SSR 分支中调用。每次渲染前应调用 `__clearDataPayload()`。
+ * 仅 string key 可注册(symbol 无法序列化)。
+ */
+declare function __registerDataPayload(key: string, entry: DataPayloadEntry): void;
+/**
+ * SSR 内部:返回所有已注册的 payload 条目,用于序列化到 `__UBEAN_DATA__`。
+ */
+declare function __resolveDataPayload(): Record<string, DataPayloadEntry>;
+/**
+ * SSR 内部:清空 payload 注册表 + 全局 inflight。每次渲染前调用,
+ * 避免上一个请求的残留。
+ */
+declare function __clearDataPayload(): void;
+/**
+ * SSR 内部:将 data payload 序列化为 `<script>` 标签字符串。
+ * 无数据时返回空字符串(不注入标签)。
+ */
+declare function __serializeDataPayload(data: Record<string, DataPayloadEntry>): string;
+/**
+ * 重置客户端 payload 缓存(测试用)。
+ */
+declare function __resetDataPayloadCache(): void;
 interface UseDataOptions<T> {
   key?: DataKey;
   tags?: string[];
   ttl?: number;
   staleWhileRevalidate?: boolean;
   fetcher: DataFetcher<T>;
+  /**
+   * Dedupe in-flight requests with the same key (default: `true`).
+   * When enabled, concurrent calls within the same request cycle share a
+   * single Promise, preventing duplicate fetcher invocations.
+   */
+  dedupe?: boolean;
 }
+type DataStatus = 'idle' | 'pending' | 'success' | 'error';
 interface DataResult<T> {
   data: T | undefined;
   error: Error | null;
   loading: boolean;
+  /** Alias for `!loading` (Nuxt `useAsyncData` compat). */
+  pending: boolean;
+  /** Current fetch status. */
+  status: DataStatus;
   timestamp: number | undefined;
   invalidate: () => void;
+  /**
+   * Force re-fetch, bypassing cache and dedupe.
+   * Mutates this result object in place and resolves when done.
+   */
+  refresh: () => Promise<void>;
 }
 declare function useData<T>(options: UseDataOptions<T>, context?: object): Promise<DataResult<T>>;
+/**
+ * `useAsyncData` 选项:Nuxt 风格的 `useAsyncData(key, fn, options)` 第三参数。
+ *
+ * 是 `UseDataOptions` 的子集(去掉 `key`/`fetcher`,改用位置参数)。
+ */
+interface UseAsyncDataOptions {
+  tags?: string[];
+  ttl?: number;
+  staleWhileRevalidate?: boolean;
+  /** Dedupe in-flight requests (default: `true`). */
+  dedupe?: boolean;
+}
+/**
+ * Nuxt 风格的 `useAsyncData(key, fn, options)`,作为 `useData` 的超集/别名。
+ *
+ * 与 `useData` 的区别仅在于调用签名:位置参数 `(key, fn, options)` vs
+ * 选项对象 `{ key, fetcher, ... }`。返回值与 `useData` 完全一致。
+ *
+ * @example
+ * ```ts
+ * const { data, pending, error, refresh } = await useAsyncData(
+ *   'posts',
+ *   () => fetch('/api/posts').then(r => r.json()),
+ *   { ttl: 60_000 }
+ * );
+ * ```
+ */
+declare function useAsyncData<T>(key: string, fn: DataFetcher<T>, options?: UseAsyncDataOptions, context?: object): Promise<DataResult<T>>;
 declare function invalidateData(keyOrTag: DataKey | string, context?: object): number;
 declare function invalidateAll(context?: object): void;
-declare function clearDataCache(context?: object): void;
+declare function clearPageData(context?: object): void;
 declare function hasData(key: DataKey, context?: object): boolean;
 interface DependencyDeclaration {
   keys: DataKey[];
@@ -138,4 +252,102 @@ interface StreamHelper {
 declare function createStreamResponse(init?: ResponseInit, onStart?: (stream: StreamHelper) => void | Promise<void>): Response;
 declare function createSseStream(onStart?: (stream: StreamHelper) => void | Promise<void>): Response;
 //#endregion
-export { type DataCacheEntry, type DataKey, type DataResult, type DependencyDeclaration, type InternalFetchOptions, LOCALE_DATA_ID, type LocaleMetaInfo, PAGE_DATA_ID, PAGE_REQUEST_HEADER, type PageAssetTags, type PageHead, type PageHeadMeta, type PageObject, type PageRenderContext, type PageRenderFn, type PageRenderResult, type PageRenderer, SSR_CONTENT_MARKER, STATE_DATA_ID, STATE_MARKER, type StreamHelper, type UseDataOptions, buildClientOnlyShell, buildPageShell, clearDataCache, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, insertStateContent, invalidateAll, invalidateData, isPagesRequest, pageJsonResponse, renderPage, safeJsonStringify, serializePageData, useData, withDependencies };
+//#region src/defer.d.ts
+/**
+ * `__UBEAN_DEFERRED__` script 标签 ID — SSR 流式渲染完成后,延迟数据
+ * 以 JSON 形式注入到此标签中,客户端水合时读取。
+ */
+declare const DEFERRED_DATA_ID = "__UBEAN_DEFERRED__";
+/**
+ * 延迟值:包装一个 factory 函数,标记为"非关键数据"。
+ *
+ * SSR 时不阻塞初始渲染,数据在主内容之后流式注入。
+ */
+interface DeferredValue<T> {
+  readonly __isDeferred: true;
+  readonly factory: () => Promise<T>;
+}
+/**
+ * 标记一个 Promise 为可延迟的(非关键数据)。
+ *
+ * 在 SSR 流式渲染中,`defer()` 包装的 Promise 不会阻塞初始 HTML 输出。
+ * 主内容渲染完成后,延迟数据解析结果作为 `<script>` 标签流式注入,
+ * 客户端水合后立即可用。
+ *
+ * @example
+ * ```ts
+ * // 阻塞初始渲染(关键数据)
+ * const critical = await fetchCritical();
+ * // 不阻塞,流式输出(非关键数据)
+ * const nonCritical = defer(() => fetchNonCritical());
+ * ```
+ */
+declare function defer<T>(factory: (() => Promise<T>) | Promise<T>): DeferredValue<T>;
+/**
+ * 判断值是否为 DeferredValue(类型守卫)。
+ */
+declare function isDeferredValue<T>(value: unknown): value is DeferredValue<T>;
+/**
+ * SSR 内部:注册一个 deferred promise,在流式渲染后统一解析。
+ *
+ * 在 `useDeferredData` 的 SSR 分支中调用。每次渲染前应调用 `__clearDeferred()`。
+ */
+declare function __registerDeferred(key: string, promise: Promise<unknown>): void;
+/**
+ * SSR 内部:解析所有已注册的 deferred promise,返回 key → data 映射。
+ *
+ * 失败的 promise 以 `{ __deferredError: message }` 形式包含在结果中,
+ * 不影响其他 promise 的解析。
+ */
+declare function __resolveDeferred(): Promise<Record<string, unknown>>;
+/**
+ * SSR 内部:清空注册表。每次渲染前调用,避免上一个请求的残留。
+ */
+declare function __clearDeferred(): void;
+/**
+ * SSR 内部:将 deferred 数据序列化为 `<script>` 标签字符串。
+ *
+ * 无数据时返回空字符串(不注入标签)。
+ */
+declare function __serializeDeferred(data: Record<string, unknown>): string;
+/**
+ * 重置客户端缓存(测试用)。
+ */
+declare function __resetDeferredCache(): void;
+interface UseDeferredDataResult<T> {
+  /** 延迟数据(初始为 undefined,解析后更新) */
+  data: ShallowRef<T | undefined>;
+  /** 是否正在获取 */
+  pending: Ref<boolean>;
+  /** 错误信息(获取失败时设置) */
+  error: ShallowRef<Error | null>;
+}
+/**
+ * 在组件中使用延迟数据。
+ *
+ * - **SSR**: 注册 promise 但不阻塞渲染,组件渲染 fallback;渲染完成后数据流式注入
+ * - **客户端水合**: 从 `__UBEAN_DEFERRED__` 读取已解析数据,立即显示(无闪烁)
+ * - **客户端导航**: 调用 factory 获取数据,显示 pending → resolved
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { defer, useDeferredData } from 'ubean';
+ *
+ * const { data: comments, pending } = useDeferredData(
+ *   'comments',
+ *   defer(() => fetch('/api/comments').then(r => r.json()))
+ * );
+ * </script>
+ *
+ * <template>
+ *   <div v-if="pending">Loading comments...</div>
+ *   <ul v-else>
+ *     <li v-for="c in comments" :key="c.id">{{ c.text }}</li>
+ *   </ul>
+ * </template>
+ * ```
+ */
+declare function useDeferredData<T>(key: string, deferred: DeferredValue<T>): UseDeferredDataResult<T>;
+//#endregion
+export { DATA_PAYLOAD_ID, DEFERRED_DATA_ID, type DataCacheEntry, type DataKey, type DataPayloadEntry, type DataResult, type DataStatus, type DeferredValue, type DependencyDeclaration, type InternalFetchOptions, LOCALE_DATA_ID, type LocaleMetaInfo, PAGE_DATA_ID, PAGE_REQUEST_HEADER, type PageAssetTags, type PageHead, type PageHeadMeta, type PageObject, type PageRenderContext, type PageRenderFn, type PageRenderResult, type PageRenderer, type PageStreamRenderFn, SSR_CONTENT_MARKER, STATE_DATA_ID, STATE_MARKER, type StreamHelper, type UseAsyncDataOptions, type UseDataOptions, type UseDeferredDataResult, __clearDataPayload, __clearDeferred, __registerDataPayload, __registerDeferred, __resetDataPayloadCache, __resetDeferredCache, __resolveDataPayload, __resolveDeferred, __serializeDataPayload, __serializeDeferred, buildClientOnlyShell, buildPageShell, clearPageData, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defer, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, insertStateContent, invalidateAll, invalidateData, isDeferredValue, isPagesRequest, pageJsonResponse, renderFaviconLink, renderPage, renderPageToStream, safeJsonStringify, serializePageData, useAsyncData, useData, useDeferredData, withDependencies };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { ref, shallowRef } from "vue";
 //#region src/protocol.ts
 const PAGE_DATA_ID = "__UBEAN_PAGE_DATA__";
 const LOCALE_DATA_ID = "__UBEAN_LOCALE__";
@@ -189,12 +190,35 @@ async function renderPage(pageObj, assetTags, renderer, appId = "app", renderCon
 	else finalHtml = insertStateContent(finalHtml, "");
 	return finalHtml;
 }
+/**
+* 流式渲染页面:当 renderer 提供 `renderToStream` 时,返回一个
+* `ReadableStream<Uint8Array>`,将完整 HTML 文档分块流式输出。
+*
+* 当 renderer 不支持流式(无 `renderToStream`)时,回退到缓冲式 `renderPage`,
+* 返回一个包含完整 HTML 的单块流(保持调用方接口一致)。
+*
+* 调用方应使用 `c.body(stream, { headers: { 'Content-Type': 'text/html; charset=utf-8' } })`
+* 将流作为 HTTP 响应返回。
+*/
+function renderPageToStream(pageObj, assetTags, renderer, appId = "app", renderContext) {
+	if (!renderer || !renderer.renderToStream) {
+		const encoder = new TextEncoder();
+		return new ReadableStream({ async start(controller) {
+			const html = await renderPage(pageObj, assetTags, renderer, appId, renderContext);
+			controller.enqueue(encoder.encode(html));
+			controller.close();
+		} });
+	}
+	const shell = buildPageShell(pageObj, assetTags, renderer.preambleScript ?? "", appId, renderContext);
+	return renderer.renderToStream(pageObj, shell, assetTags, renderContext);
+}
 //#endregion
 //#region src/data.ts
 function createRegistry() {
 	return {
 		entries: /* @__PURE__ */ new Map(),
-		tagIndex: /* @__PURE__ */ new Map()
+		tagIndex: /* @__PURE__ */ new Map(),
+		inflight: /* @__PURE__ */ new Map()
 	};
 }
 const globalRegistry = createRegistry();
@@ -213,24 +237,171 @@ function getRegistry(context) {
 function defineDataKey(key) {
 	return Symbol.for(`ubean:data:${key}`);
 }
-async function useData(options, context) {
-	const registry = getRegistry(context);
-	const key = options.key || Symbol();
-	const invalidate = () => {
-		invalidateData(key, context);
-	};
+/**
+* `__UBEAN_DATA__` script 标签 ID — SSR 渲染时,useData 解析的数据以 JSON 形式
+* 注入到此标签中,客户端水合时读取,避免二次请求。
+*
+* 与 `__UBEAN_DEFERRED__`(非关键延迟数据)和 `__UBEAN_STATE__`(用户状态如 Pinia)
+* 分离,职责单一,便于 SSG payload 提取(roadmap Task 3)。
+*/
+const DATA_PAYLOAD_ID = "__UBEAN_DATA__";
+const ssrPayload = /* @__PURE__ */ new Map();
+/**
+* SSR 内部:注册一个 useData 解析结果到 payload。
+*
+* 在 `useData` 的 SSR 分支中调用。每次渲染前应调用 `__clearDataPayload()`。
+* 仅 string key 可注册(symbol 无法序列化)。
+*/
+function __registerDataPayload(key, entry) {
+	ssrPayload.set(key, entry);
+}
+/**
+* SSR 内部:返回所有已注册的 payload 条目,用于序列化到 `__UBEAN_DATA__`。
+*/
+function __resolveDataPayload() {
+	return Object.fromEntries(ssrPayload);
+}
+/**
+* SSR 内部:清空 payload 注册表 + 全局 inflight。每次渲染前调用,
+* 避免上一个请求的残留。
+*/
+function __clearDataPayload() {
+	ssrPayload.clear();
+	globalRegistry.inflight.clear();
+}
+/**
+* SSR 内部:将 data payload 序列化为 `<script>` 标签字符串。
+* 无数据时返回空字符串(不注入标签)。
+*/
+function __serializeDataPayload(data) {
+	if (Object.keys(data).length === 0) return "";
+	return `<script id="${DATA_PAYLOAD_ID}" type="application/json">${safeJsonStringify(data)}<\/script>`;
+}
+let clientPayloadCache;
+/**
+* 客户端:实际执行 payload 解析。
+*
+* 优先级:
+* 1. `globalThis.__UBEAN_DATA_PAYLOAD__`(SSG 模式注入,可能是 Promise / 对象 / null)
+*    - Promise → await,解析失败返回 null
+*    - 对象 → 直接使用
+*    - null/undefined → 降级到 DOM 路径
+* 2. DOM 读取 `__UBEAN_DATA__` script 标签(SSR/无 SSG 提取场景)
+*
+* SSR 环境(无 document)返回 `null`。
+*/
+async function computeClientPayload() {
+	const injected = globalThis.__UBEAN_DATA_PAYLOAD__;
+	if (injected !== void 0) try {
+		const value = injected instanceof Promise ? await injected : injected;
+		if (value && typeof value === "object") return value;
+		return null;
+	} catch {
+		return null;
+	}
+	if (typeof document === "undefined") return null;
+	const el = document.getElementById(DATA_PAYLOAD_ID);
+	if (!el?.textContent) return null;
 	try {
-		const cached = registry.entries.get(key);
-		if (cached) {
-			if (!(cached.ttl !== void 0 && Date.now() - cached.timestamp > cached.ttl)) return {
-				data: cached.data,
-				error: null,
-				loading: false,
-				timestamp: cached.timestamp,
-				invalidate
+		return JSON.parse(el.textContent);
+	} catch {
+		return null;
+	}
+}
+/**
+* 客户端:读取 payload,带 in-flight 去重缓存。
+*
+* 首次调用启动计算并存 Promise 到缓存(去重并发调用);解析后用结果替换 Promise,
+* 后续调用直接命中同步缓存。
+* SSR 环境返回 `null`。
+*/
+function readClientPayload() {
+	const cached = clientPayloadCache;
+	if (cached !== void 0) return Promise.resolve(cached);
+	const promise = computeClientPayload();
+	clientPayloadCache = promise;
+	return promise.then((value) => {
+		clientPayloadCache = value;
+		return value;
+	}, () => {
+		clientPayloadCache = null;
+		return null;
+	});
+}
+/**
+* 重置客户端 payload 缓存(测试用)。
+*/
+function __resetDataPayloadCache() {
+	clientPayloadCache = void 0;
+}
+/**
+* 客户端水合:从 payload 缓存中读取指定 key 的初始数据,注入到 data registry。
+*
+* 在 `useData` 的客户端分支中调用:若 payload 命中,将数据写入 registry,
+* 后续逻辑直接走缓存命中路径,避免二次请求。
+* 仅处理 string key,且仅当 registry 中尚无该 key 时注入(不覆盖已有缓存)。
+*
+* @returns true 表示 payload 命中并已注入
+*/
+async function hydrateFromPayload(key, registry) {
+	if (typeof key !== "string") return false;
+	if (registry.entries.has(key)) return false;
+	const payload = await readClientPayload();
+	if (!payload) return false;
+	const entry = payload[key];
+	if (!entry) return false;
+	if (entry.error !== null) return false;
+	registry.entries.set(key, {
+		key,
+		data: entry.data,
+		timestamp: entry.timestamp,
+		tags: void 0
+	});
+	return true;
+}
+/**
+* 判断当前是否为 SSR 环境(无 `window`)。
+* 与 `defer.ts` 保持一致的环境检测方式。
+*/
+function isSSR() {
+	return typeof window === "undefined";
+}
+/**
+* 将解析结果注册到 SSR payload(仅 string key + SSR 环境)。
+*/
+function registerSSRPayload(key, data, error) {
+	if (!isSSR()) return;
+	if (typeof key !== "string") return;
+	__registerDataPayload(key, {
+		data: error ? void 0 : data,
+		error: error ? error instanceof Error ? error.message : String(error) : null,
+		timestamp: Date.now()
+	});
+}
+/**
+* 执行 fetcher,管理 inflight 注册 + cache 写入 + tag 索引 + SSR payload 注册。
+* dedupe 决定是否复用同 key 的 in-flight Promise。
+*/
+async function executeFetch(options, key, registry, _context) {
+	const dedupe = options.dedupe !== false;
+	if (dedupe) {
+		const existing = registry.inflight.get(key);
+		if (existing) try {
+			return {
+				data: await existing,
+				error: null
+			};
+		} catch (err) {
+			return {
+				data: void 0,
+				error: err instanceof Error ? err : new Error(String(err))
 			};
 		}
-		const data = await options.fetcher();
+	}
+	const promise = Promise.resolve(options.fetcher());
+	if (dedupe) registry.inflight.set(key, promise);
+	try {
+		const data = await promise;
 		const entry = {
 			key,
 			data,
@@ -247,22 +418,99 @@ async function useData(options, context) {
 			}
 			tagSet.add(key);
 		}
+		registerSSRPayload(key, data, null);
 		return {
 			data,
-			error: null,
-			loading: false,
-			timestamp: entry.timestamp,
-			invalidate
+			error: null
 		};
 	} catch (err) {
+		const error = err instanceof Error ? err : new Error(String(err));
+		registerSSRPayload(key, void 0, error);
 		return {
 			data: void 0,
-			error: err instanceof Error ? err : new Error(String(err)),
-			loading: false,
-			timestamp: void 0,
-			invalidate
+			error
 		};
+	} finally {
+		if (dedupe) registry.inflight.delete(key);
+	}
+}
+async function useData(options, context) {
+	const registry = getRegistry(context);
+	const key = options.key || Symbol();
+	const invalidate = () => {
+		invalidateData(key, context);
+	};
+	if (!isSSR()) await hydrateFromPayload(key, registry);
+	const result = {
+		data: void 0,
+		error: null,
+		loading: false,
+		pending: false,
+		status: "idle",
+		timestamp: void 0,
+		invalidate,
+		refresh: async () => {
+			invalidateData(key, context);
+			result.loading = true;
+			result.pending = true;
+			result.status = "pending";
+			const { data, error } = await executeFetch(options, key, registry, context);
+			result.data = data;
+			result.error = error;
+			result.loading = false;
+			result.pending = false;
+			result.status = error ? "error" : "success";
+			result.timestamp = registry.entries.get(key)?.timestamp;
+		}
+	};
+	const cached = registry.entries.get(key);
+	if (cached) {
+		if (!(cached.ttl !== void 0 && Date.now() - cached.timestamp > cached.ttl)) {
+			result.data = cached.data;
+			result.error = null;
+			result.loading = false;
+			result.pending = false;
+			result.status = "success";
+			result.timestamp = cached.timestamp;
+			return result;
+		}
 	}
+	result.loading = true;
+	result.pending = true;
+	result.status = "pending";
+	const { data, error } = await executeFetch(options, key, registry, context);
+	result.data = data;
+	result.error = error;
+	result.loading = false;
+	result.pending = false;
+	result.status = error ? "error" : "success";
+	result.timestamp = registry.entries.get(key)?.timestamp;
+	return result;
+}
+/**
+* Nuxt 风格的 `useAsyncData(key, fn, options)`,作为 `useData` 的超集/别名。
+*
+* 与 `useData` 的区别仅在于调用签名:位置参数 `(key, fn, options)` vs
+* 选项对象 `{ key, fetcher, ... }`。返回值与 `useData` 完全一致。
+*
+* @example
+* ```ts
+* const { data, pending, error, refresh } = await useAsyncData(
+*   'posts',
+*   () => fetch('/api/posts').then(r => r.json()),
+*   { ttl: 60_000 }
+* );
+* ```
+*/
+async function useAsyncData(key, fn, options, context) {
+	return useData({
+		key,
+		fetcher: fn,
+		tags: options?.tags,
+		ttl: options?.ttl,
+		staleWhileRevalidate: options?.staleWhileRevalidate,
+		dedupe: options?.dedupe
+	}, context);
 }
 function invalidateData(keyOrTag, context) {
 	const registry = getRegistry(context);
@@ -300,8 +548,9 @@ function invalidateAll(context) {
 	const registry = getRegistry(context);
 	registry.entries.clear();
 	registry.tagIndex.clear();
+	registry.inflight.clear();
 }
-function clearDataCache(context) {
+function clearPageData(context) {
 	invalidateAll(context);
 }
 function hasData(key, context) {
@@ -426,4 +675,169 @@ function createSseStream(onStart) {
 	} });
 }
 //#endregion
-export { LOCALE_DATA_ID, PAGE_DATA_ID, PAGE_REQUEST_HEADER, SSR_CONTENT_MARKER, STATE_DATA_ID, STATE_MARKER, buildClientOnlyShell, buildPageShell, clearDataCache, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, insertStateContent, invalidateAll, invalidateData, isPagesRequest, pageJsonResponse, renderPage, safeJsonStringify, serializePageData, useData, withDependencies };
+//#region src/defer.ts
+/**
+* `__UBEAN_DEFERRED__` script 标签 ID — SSR 流式渲染完成后,延迟数据
+* 以 JSON 形式注入到此标签中,客户端水合时读取。
+*/
+const DEFERRED_DATA_ID = "__UBEAN_DEFERRED__";
+/**
+* 标记一个 Promise 为可延迟的(非关键数据)。
+*
+* 在 SSR 流式渲染中,`defer()` 包装的 Promise 不会阻塞初始 HTML 输出。
+* 主内容渲染完成后,延迟数据解析结果作为 `<script>` 标签流式注入,
+* 客户端水合后立即可用。
+*
+* @example
+* ```ts
+* // 阻塞初始渲染(关键数据)
+* const critical = await fetchCritical();
+* // 不阻塞,流式输出(非关键数据)
+* const nonCritical = defer(() => fetchNonCritical());
+* ```
+*/
+function defer(factory) {
+	return {
+		__isDeferred: true,
+		factory: typeof factory === "function" ? factory : () => factory
+	};
+}
+/**
+* 判断值是否为 DeferredValue(类型守卫)。
+*/
+function isDeferredValue(value) {
+	return value !== null && typeof value === "object" && value.__isDeferred === true;
+}
+const entries = [];
+/**
+* SSR 内部:注册一个 deferred promise,在流式渲染后统一解析。
+*
+* 在 `useDeferredData` 的 SSR 分支中调用。每次渲染前应调用 `__clearDeferred()`。
+*/
+function __registerDeferred(key, promise) {
+	entries.push({
+		key,
+		promise
+	});
+}
+/**
+* SSR 内部:解析所有已注册的 deferred promise,返回 key → data 映射。
+*
+* 失败的 promise 以 `{ __deferredError: message }` 形式包含在结果中,
+* 不影响其他 promise 的解析。
+*/
+async function __resolveDeferred() {
+	if (entries.length === 0) return {};
+	const results = {};
+	await Promise.allSettled(entries.map(async (entry) => {
+		try {
+			results[entry.key] = await entry.promise;
+		} catch (err) {
+			results[entry.key] = { __deferredError: err instanceof Error ? err.message : String(err) };
+		}
+	}));
+	return results;
+}
+/**
+* SSR 内部:清空注册表。每次渲染前调用,避免上一个请求的残留。
+*/
+function __clearDeferred() {
+	entries.length = 0;
+}
+/**
+* SSR 内部:将 deferred 数据序列化为 `<script>` 标签字符串。
+*
+* 无数据时返回空字符串(不注入标签)。
+*/
+function __serializeDeferred(data) {
+	if (Object.keys(data).length === 0) return "";
+	return `<script id="${DEFERRED_DATA_ID}" type="application/json">${safeJsonStringify(data)}<\/script>`;
+}
+let clientCache;
+/**
+* 客户端:从 DOM 读取 `__UBEAN_DEFERRED__` script 标签内容。
+*
+* 首次调用后缓存结果,后续调用直接返回缓存。
+* SSR 环境返回 `null`。
+*/
+function readClientCache() {
+	const cached = clientCache;
+	if (cached !== void 0) return cached;
+	let result;
+	if (typeof document === "undefined") result = null;
+	else {
+		const el = document.getElementById(DEFERRED_DATA_ID);
+		if (!el?.textContent) result = {};
+		else try {
+			result = JSON.parse(el.textContent);
+		} catch {
+			result = {};
+		}
+	}
+	clientCache = result;
+	return result;
+}
+/**
+* 重置客户端缓存(测试用)。
+*/
+function __resetDeferredCache() {
+	clientCache = void 0;
+}
+/**
+* 在组件中使用延迟数据。
+*
+* - **SSR**: 注册 promise 但不阻塞渲染,组件渲染 fallback;渲染完成后数据流式注入
+* - **客户端水合**: 从 `__UBEAN_DEFERRED__` 读取已解析数据,立即显示(无闪烁)
+* - **客户端导航**: 调用 factory 获取数据,显示 pending → resolved
+*
+* @example
+* ```vue
+* <script setup>
+* import { defer, useDeferredData } from 'ubean';
+*
+* const { data: comments, pending } = useDeferredData(
+*   'comments',
+*   defer(() => fetch('/api/comments').then(r => r.json()))
+* );
+* <\/script>
+*
+* <template>
+*   <div v-if="pending">Loading comments...</div>
+*   <ul v-else>
+*     <li v-for="c in comments" :key="c.id">{{ c.text }}</li>
+*   </ul>
+* </template>
+* ```
+*/
+function useDeferredData(key, deferred) {
+	const data = shallowRef(void 0);
+	const pending = ref(true);
+	const error = shallowRef(null);
+	if (typeof window === "undefined") {
+		__registerDeferred(key, deferred.factory());
+		pending.value = true;
+	} else {
+		const cached = readClientCache()?.[key];
+		if (cached !== void 0) {
+			if (cached !== null && typeof cached === "object" && "__deferredError" in cached) error.value = new Error(String(cached.__deferredError));
+			else data.value = cached;
+			pending.value = false;
+		} else {
+			pending.value = true;
+			deferred.factory().then((result) => {
+				data.value = result;
+				pending.value = false;
+			}).catch((err) => {
+				error.value = err instanceof Error ? err : new Error(String(err));
+				pending.value = false;
+			});
+		}
+	}
+	return {
+		data,
+		pending,
+		error
+	};
+}
+//#endregion
+export { DATA_PAYLOAD_ID, DEFERRED_DATA_ID, LOCALE_DATA_ID, PAGE_DATA_ID, PAGE_REQUEST_HEADER, SSR_CONTENT_MARKER, STATE_DATA_ID, STATE_MARKER, __clearDataPayload, __clearDeferred, __registerDataPayload, __registerDeferred, __resetDataPayloadCache, __resetDeferredCache, __resolveDataPayload, __resolveDeferred, __serializeDataPayload, __serializeDeferred, buildClientOnlyShell, buildPageShell, clearPageData, createInternalFetch, createSseStream, createStreamResponse, declareDependencies, defer, defineDataKey, getInvalidatedKeysForAction, hasData, insertSsrContent, insertStateContent, invalidateAll, invalidateData, isDeferredValue, isPagesRequest, pageJsonResponse, renderFaviconLink, renderPage, renderPageToStream, safeJsonStringify, serializePageData, useAsyncData, useData, useDeferredData, withDependencies };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/pages",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "description": "Page data protocol and isomorphic data layer for ubean (PageObject, useData, invalidateData)",
   "files": [
     "dist"
@@ -16,12 +16,15 @@
     }
   },
   "dependencies": {
-    "@ubean/types": "0.1.13"
+    "@ubean/shared": "0.2.1"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "typescript": "7.0.2",
-    "vite-plus": "0.2.6"
+    "vite-plus": "0.2.9"
+  },
+  "peerDependencies": {
+    "vue": ">=3.4.0"
   },
   "scripts": {
     "build": "vp pack",