@lytjs/ssr 6.8.0 → 6.9.1

package/dist/index.d.cts

@@ -0,0 +1,612 @@
+import { VNode } from '@lytjs/vdom';
+import * as _lytjs_component from '@lytjs/component';
+
+/**
+ * @lytjs/ssr - 服务端渲染
+ *
+ * 将 VNode 渲染为 HTML 字符串
+ */
+
+/**
+ * 渲染 VNode 为 HTML 字符串
+ */
+declare function renderToString(vnode: VNode | VNode[] | string | number | null | undefined): string;
+/**
+ * 渲染完整的 HTML 页面
+ */
+declare function renderToHtml(vnode: VNode | VNode[], options?: {
+    title?: string;
+    lang?: string;
+    head?: string;
+    bodyAttrs?: Record<string, string>;
+}): string;
+declare const _default: {
+    renderToString: typeof renderToString;
+    renderToHtml: typeof renderToHtml;
+};
+
+/**
+ * @lytjs/ssr - 虚拟列表组件
+ *
+ * 高性能大数据列表渲染
+ */
+declare const VirtualList: _lytjs_component.ComponentOptions<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>>;
+
+/**
+ * @lytjs/ssr - 流式服务端渲染
+ *
+ * 将 VNode 渲染为 ReadableStream，支持分块发送和 Suspense 边界
+ */
+
+/** 流式渲染配置选项 */
+interface StreamRenderOptions {
+    /** 每个分块的最大字节数，默认 4096 */
+    chunkSize?: number;
+    /** Shell 就绪回调（Suspense 边界之前的初始内容已发送） */
+    onShellReady?: () => void;
+    /** 错误回调 */
+    onError?: (error: Error) => void;
+    /** 流式渲染超时时间（毫秒），默认 30000 */
+    timeout?: number;
+    /** 当渲染超时时的回退 HTML 内容 */
+    fallbackHtml?: string;
+    /** 流控制：每秒最大字节数，用于防止突发流量 */
+    maxBytesPerSecond?: number;
+    /** 是否启用错误恢复模式，默认 true */
+    errorRecovery?: boolean;
+    /** 单个组件渲染超时（毫秒），默认 5000 */
+    componentTimeout?: number;
+}
+/** 异步数据预取上下文 */
+interface DataPrefetchContext {
+    /** 路由路径 */
+    path?: string;
+    /** 路由参数 */
+    params?: Record<string, string>;
+    /** 查询参数 */
+    query?: Record<string, string>;
+}
+/** 异步数据预取结果 */
+interface PrefetchResult {
+    /** 预取的数据 */
+    data: Record<string, unknown>;
+    /** 数据过期时间（毫秒） */
+    ttl?: number;
+}
+/** 支持数据预取的组件接口 */
+interface PrefetchableComponent {
+    /** 预取数据方法 */
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+}
+/** 流式渲染增强选项 */
+interface EnhancedStreamRenderOptions extends StreamRenderOptions {
+    /** 数据预取上下文 */
+    prefetchContext?: DataPrefetchContext;
+    /** 数据预取完成回调 */
+    onDataPrefetched?: (data: Record<string, unknown>) => void;
+    /** 是否启用渐进式水合 */
+    progressiveHydration?: boolean;
+}
+/**
+ * 将 VNode 渲染为 ReadableStream（流式服务端渲染）
+ *
+ * @description
+ * 将 VNode 树渲染为 HTML 并通过 ReadableStream 分块发送。
+ * 支持以下特性：
+ * - 按组件边界拆分 HTML 分块
+ * - 支持 Suspense 边界（先发送 shell，再发送异步内容）
+ * - 使用 TextEncoder 编码为 Uint8Array
+ * - 可配置分块大小和回调
+ * - 超时控制和错误恢复
+ * - 流速率控制
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 流式渲染配置选项
+ * @returns ReadableStream<Uint8Array>
+ *
+ * @example
+ * ```typescript
+ * const stream = renderToStream(vnode, {
+ *   chunkSize: 2048,
+ *   onShellReady: () => console.log('Shell 已发送'),
+ *   onError: (err) => console.error(err),
+ *   timeout: 30000,
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   response.write(chunk);
+ * }
+ * ```
+ */
+declare function renderToStream(vnode: VNode, options?: StreamRenderOptions): ReadableStream<Uint8Array>;
+/**
+ * 将 VNode 渲染为异步 ReadableStream（支持异步组件和数据预取）
+ *
+ * @description
+ * 与 renderToStream 类似，但支持异步组件和数据预取。
+ * 遇到返回 Promise 的组件时先发送占位内容，等 Promise 解析后再发送实际内容。
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 流式渲染配置选项
+ * @returns ReadableStream<Uint8Array>
+ */
+declare function renderToStreamAsync(vnode: VNode, options?: EnhancedStreamRenderOptions): ReadableStream<Uint8Array>;
+/**
+ * 增强型流式渲染（包含数据预取和渐进式水合）
+ *
+ * @description
+ * 完整的流式渲染解决方案，包含数据预取、渐进式水合等高级特性。
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 增强型流式渲染配置
+ * @returns Promise<{ stream: ReadableStream<Uint8Array>; dehydratedState: Record<string, any> }>
+ */
+declare function renderToStreamEnhanced(vnode: VNode, options?: EnhancedStreamRenderOptions): Promise<{
+    stream: ReadableStream<Uint8Array>;
+    dehydratedState: Record<string, unknown>;
+}>;
+
+/**
+ * @lytjs/ssr - 静态站点生成（SSG）
+ *
+ * 预渲染页面配置为静态 HTML 文件
+ */
+
+/** SSG 页面配置 */
+interface SSGPage {
+    /** 页面路径，如 '/' 或 '/about' */
+    path: string;
+    /** 页面组件 VNode */
+    component: VNode;
+    /** 可选布局组件 */
+    layout?: VNode;
+    /** 页面头部信息 */
+    head?: {
+        /** 页面标题 */
+        title?: string;
+        /** 元信息键值对 */
+        meta?: Record<string, string>;
+    };
+    /** 额外的脚本标签 */
+    scripts?: string[];
+    /** 额外的样式标签 */
+    styles?: string[];
+}
+/** SSG 生成选项 */
+interface SSGOptions {
+    /** 站点基础 URL，默认 '/' */
+    baseUrl?: string;
+    /** 输出目录，默认 'dist' */
+    outDir?: string;
+    /** 默认页面标题 */
+    defaultTitle?: string;
+    /** 默认语言 */
+    lang?: string;
+    /** 是否生成 sitemap */
+    generateSitemap?: boolean;
+    /** 站点名称（用于 sitemap） */
+    siteName?: string;
+    /** 是否使用哈希路由 */
+    hashMode?: boolean;
+    /** 全局额外脚本 */
+    globalScripts?: string[];
+    /** 全局额外样式 */
+    globalStyles?: string[];
+    /** ISR 配置（增量静态再生成） */
+    isr?: {
+        /** 重新验证间隔（秒），0 表示按需重新验证 */
+        revalidate?: number;
+        /** 是否启用增量静态再生成 */
+        enabled?: boolean;
+        /** 预渲染 fallback 页面 */
+        fallback?: 'blocking' | boolean;
+    };
+}
+/**
+ * 将生成的 HTML 写入文件系统
+ *
+ * @description
+ * 将 generateStaticPages 生成的结果写入到指定的输出目录。
+ * 会自动创建所需的目录结构。
+ *
+ * @param pages - 页面配置数组
+ * @param options - SSG 选项
+ * @returns Promise<void>
+ *
+ * @example
+ * ```typescript
+ * await writeStaticFiles(pages, { outDir: 'build' });
+ * ```
+ */
+declare function writeStaticFiles(pages: SSGPage[], options?: SSGOptions): Promise<void>;
+/**
+ * 预渲染页面配置数组为静态 HTML
+ *
+ * @description
+ * 接受页面配置数组，为每个页面生成完整的 HTML 内容。
+ * 返回一个 Map，键为文件路径，值为 HTML 内容。
+ *
+ * @param pages - 页面配置数组
+ * @param options - SSG 生成选项
+ * @returns Map<string, string> 文件路径 -> HTML 内容
+ *
+ * @example
+ * ```typescript
+ * const pages: SSGPage[] = [
+ *   {
+ *     path: '/',
+ *     component: h('div', {}, 'Home'),
+ *     head: { title: '首页', meta: { description: '欢迎' } },
+ *   },
+ *   {
+ *     path: '/about',
+ *     component: h('div', {}, 'About'),
+ *   },
+ * ];
+ *
+ * const results = generateStaticPages(pages, {
+ *   baseUrl: 'https://example.com',
+ *   defaultTitle: 'My Site',
+ * });
+ *
+ * for (const [filePath, html] of results) {
+ *   console.log(filePath, html);
+ * }
+ * ```
+ */
+declare function generateStaticPages(pages: SSGPage[], options?: SSGOptions): Map<string, string>;
+/**
+ * 生成页面路由清单
+ *
+ * @description
+ * 根据页面配置生成一个 JSON 格式的路由清单，
+ * 可用于客户端路由注册或构建分析。
+ *
+ * @param pages - 页面配置数组
+ * @param baseUrl - 站点基础 URL
+ * @returns 路由信息数组
+ */
+declare function generateRouteManifest(pages: SSGPage[], baseUrl?: string): Array<{
+    path: string;
+    filePath: string;
+    title?: string;
+}>;
+/**
+ * 验证页面配置数组的合法性
+ *
+ * @description
+ * 检查每个页面配置是否包含必要的字段（path 和 component），
+ * 以及路径是否合法。返回错误信息数组。
+ *
+ * @param pages - 页面配置数组
+ * @returns 错误信息数组，空数组表示全部合法
+ */
+declare function validatePages(pages: SSGPage[]): string[];
+/**
+ * 创建 ISR 中间件
+ *
+ * @description
+ * 创建用于 Express/Fastify 等框架的 ISR 中间件，
+ * 支持增量静态再生成和背景重新验证。
+ *
+ * @param options - ISR 选项
+ * @returns 中间件函数
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createISRMiddleware, generateStaticPages } from '@lytjs/ssr';
+ *
+ * const app = express();
+ *
+ * // 预生成的页面
+ * const pages = [
+ *   { path: '/', component: homeComponent },
+ * ];
+ *
+ * const staticPages = generateStaticPages(pages);
+ *
+ * app.use(createISRMiddleware({
+ *   staticPages,
+ *   revalidate: 60, // 60秒后重新验证
+ *   async regenerate(path) {
+ *     const page = pages.find(p => p.path === path);
+ *     if (page) {
+ *       return generateStaticPages([page]).get('/index.html')!;
+ *     }
+ *     throw new Error('Page not found');
+ *   }
+ * }));
+ * ```
+ */
+declare function createISRMiddleware(options: {
+    /** 预生成的静态页面 */
+    staticPages: Map<string, string>;
+    /** 重新验证间隔（秒） */
+    revalidate?: number;
+    /** 是否启用 ISR */
+    enabled?: boolean;
+    /** 重新生成页面的函数 */
+    regenerate?: (path: string) => Promise<string>;
+}): (req: any, res: any, next: any) => Promise<any>;
+/**
+ * 触发按需重新验证
+ *
+ * @description
+ * 手动触发特定路径的重新验证，适合于内容更新后调用。
+ *
+ * @param path - 要重新验证的路径
+ * @param regenerate - 重新生成页面的函数
+ * @returns Promise<string> 新生成的 HTML
+ *
+ * @example
+ * ```typescript
+ * // 当博客文章更新时
+ * await revalidateOnDemand(
+ *   '/blog/my-post',
+ *   async () => generatePostHTML('my-post')
+ * );
+ * ```
+ */
+declare function revalidateOnDemand(path: string, regenerate: () => Promise<string>): Promise<string>;
+/**
+ * 获取 ISR 缓存统计信息
+ *
+ * @description
+ * 获取当前 ISR 缓存的统计信息，用于监控和调试。
+ *
+ * @returns 缓存统计信息
+ */
+declare function getISRCacheStats(): {
+    total: number;
+    paths: string[];
+};
+/**
+ * 清除 ISR 缓存
+ *
+ * @description
+ * 清除指定路径或所有过期的缓存。
+ *
+ * @param path - 可选，要清除的特定路径
+ * @param maxAge - 可选，清除超过指定秒数的缓存
+ */
+declare function clearISRCache(path?: string, maxAge?: number): void;
+
+/**
+ * @lytjs/ssr - 服务端组件完善
+ *
+ * 提供服务端组件生命周期管理、数据预取优化、状态序列化等功能
+ */
+
+/** 服务端组件生命周期钩子类型 */
+type ServerLifecycleHook = (context: ServerComponentContext) => Promise<void> | void;
+/** 服务端组件上下文 */
+interface ServerComponentContext {
+    /** 组件唯一 ID */
+    componentId: string;
+    /** 路由信息 */
+    route?: {
+        path: string;
+        params: Record<string, string>;
+        query: Record<string, string>;
+    };
+    /** 请求上下文 */
+    request?: {
+        headers: Record<string, string | undefined>;
+        cookies: Record<string, string>;
+    };
+}
+/** 服务端组件注册信息 */
+interface ServerComponentRegistration {
+    /** 组件名称 */
+    name: string;
+    /** 组件渲染函数 */
+    render: () => VNode;
+    /** 服务端初始化钩子 */
+    onServerInit?: ServerLifecycleHook;
+    /** 数据预取钩子 */
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    /** 服务端清理钩子 */
+    onServerCleanup?: ServerLifecycleHook;
+}
+/** 服务端组件状态管理器 */
+declare class ServerComponentStateManager {
+    /** 注册的组件 */
+    private registrations;
+    /** 正在执行的预取请求 */
+    private pendingPrefetches;
+    /** 组件初始化状态 */
+    private initializationStates;
+    /**
+     * 注册服务端组件
+     */
+    register(name: string, registration: ServerComponentRegistration): void;
+    /**
+     * 取消注册服务端组件
+     */
+    unregister(name: string): void;
+    /**
+     * 获取已注册的组件
+     */
+    getRegistration(name: string): ServerComponentRegistration | undefined;
+    /**
+     * 初始化服务端组件
+     */
+    initializeComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 清理服务端组件
+     */
+    cleanupComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 预取组件数据（带缓存）
+     */
+    prefetchComponentData(name: string, context: DataPrefetchContext, cacheKey?: string): Promise<PrefetchResult>;
+    /**
+     * 清除所有缓存
+     */
+    clearAll(): void;
+}
+/** 全局状态管理器实例 */
+declare const stateManager: ServerComponentStateManager;
+/**
+ * 注册服务端组件
+ */
+declare function registerServerComponent(name: string, registration: ServerComponentRegistration): void;
+/**
+ * 取消注册服务端组件
+ */
+declare function unregisterServerComponent(name: string): void;
+/**
+ * 从 VNode 树中收集需要预取数据的组件
+ */
+declare function collectPrefetchComponents(vnode: VNode | VNode[] | string | number | null | undefined): string[];
+/**
+ * 并发预取多个组件的数据
+ */
+declare function prefetchAllComponents(components: string[], context: DataPrefetchContext): Promise<Record<string, PrefetchResult>>;
+/**
+ * 安全的状态序列化
+ * 处理循环引用、日期、正则表达式等特殊类型
+ */
+declare function safeSerializeState(state: unknown): string;
+/**
+ * 安全的状态反序列化
+ * 恢复特殊类型
+ */
+declare function safeDeserializeState(serialized: string): unknown;
+/**
+ * 创建组件脱水状态
+ */
+interface ComponentDehydratedState {
+    /** 组件名称 */
+    componentName: string;
+    /** 组件 Props */
+    props: Record<string, unknown>;
+    /** 预取的数据 */
+    data?: Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 构建完整的脱水状态
+ */
+declare function buildDehydratedState(prefetchResults: Record<string, PrefetchResult>): Record<string, ComponentDehydratedState>;
+/**
+ * 服务端组件管理器装饰器
+ */
+declare function ServerComponent(options: {
+    name: string;
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    onInit?: ServerLifecycleHook;
+    onCleanup?: ServerLifecycleHook;
+}): (target: {
+    name?: string;
+    render?: () => VNode;
+}) => void;
+
+/**
+ * @lytjs/ssr - 组件级水合提示
+ *
+ * 提供水合标记、策略检测和状态序列化等辅助函数，
+ * 用于 SSR 输出中嵌入客户端水合所需的信息
+ */
+
+/** 水合策略类型 */
+type HydrationStrategy = 'lazy' | 'eager' | 'idle';
+/** 水合提示信息 */
+interface HydrationHints {
+    /** 组件唯一标识 */
+    componentId: string;
+    /** 水合策略 */
+    strategy: HydrationStrategy;
+    /** 组件 props 快照 */
+    props: Record<string, unknown>;
+}
+/** 水合状态数据结构 */
+interface HydrationState {
+    /** 组件水合提示列表 */
+    hints: HydrationHints[];
+    /** 全局初始状态 */
+    initialState?: Record<string, unknown>;
+}
+/**
+ * 重置组件 ID 计数器（仅用于测试）
+ */
+declare function resetComponentIdCounter(): void;
+/**
+ * 为 VNode 树添加水合标记
+ *
+ * @description
+ * 递归遍历 VNode 树，为每个元素节点添加 data-hydrate 属性，
+ * 用于客户端水合时识别对应的 SSR 输出节点。
+ * 同时根据 props 中的 hydrateStrategy 设置 data-hydrate-strategy 属性。
+ *
+ * @param vnode - 原始 VNode
+ * @returns 添加了水合标记的新 VNode（浅拷贝）
+ *
+ * @example
+ * ```typescript
+ * const marked = createHydrationMarkers(vnode);
+ * // marked 的每个元素节点都带有 data-hydrate="lyt-hydrate-1" 等属性
+ * ```
+ */
+declare function createHydrationMarkers(vnode: VNode): VNode;
+/**
+ * 获取组件的水合策略
+ *
+ * @description
+ * 从 VNode 的 props 中读取 hydrateStrategy 字段，
+ * 返回对应的水合策略。如果未设置，默认返回 'eager'。
+ *
+ * @param vnode - 目标 VNode
+ * @returns 水合策略（lazy / eager / idle）
+ *
+ * @example
+ * ```typescript
+ * const strategy = getHydrationStrategy(vnode);
+ * // 'eager' | 'lazy' | 'idle'
+ * ```
+ */
+declare function getHydrationStrategy(vnode: VNode): HydrationStrategy;
+/**
+ * 序列化客户端水合所需的初始状态
+ *
+ * @description
+ * 将任意状态对象序列化为可安全嵌入 HTML 的 JSON 字符串。
+ * 处理特殊值（undefined、函数、Symbol 等）以确保 JSON 安全。
+ *
+ * @param state - 要序列化的状态对象
+ * @returns JSON 字符串
+ *
+ * @example
+ * ```typescript
+ * const serialized = serializeHydrationState({
+ *   user: { name: 'Alice', age: 30 },
+ *   items: [1, 2, 3],
+ * });
+ * // '{"user":{"name":"Alice","age":30},"items":[1,2,3]}'
+ * ```
+ */
+declare function serializeHydrationState(state: unknown): string;
+/**
+ * 创建脱水状态（SSR 时序列化到 HTML 中的状态）
+ *
+ * @description
+ * 从 VNode 树中提取水合所需的信息，生成一段可嵌入 HTML 的 script 标签内容。
+ * 客户端加载时读取此状态进行水合。
+ *
+ * @param vnode - VNode 节点
+ * @param initialState - 可选的全局初始状态
+ * @returns 可嵌入 HTML 的 script 标签字符串
+ *
+ * @example
+ * ```typescript
+ * const script = createDehydratedState(vnode, {
+ *   user: { name: 'Alice' },
+ * });
+ * // <script id="__LYT_DEHYDRATED_STATE__" type="application/json">...</script>
+ * ```
+ */
+declare function createDehydratedState(vnode: VNode, initialState?: Record<string, unknown>): string;
+
+export { type ComponentDehydratedState, type DataPrefetchContext, type EnhancedStreamRenderOptions, type HydrationHints, type HydrationState, type HydrationStrategy, type PrefetchResult, type PrefetchableComponent, type SSGOptions, type SSGPage, ServerComponent, type ServerComponentContext, type ServerComponentRegistration, type ServerLifecycleHook, type StreamRenderOptions, VirtualList, buildDehydratedState, clearISRCache, collectPrefetchComponents, createDehydratedState, createHydrationMarkers, createISRMiddleware, _default as default, generateRouteManifest, generateStaticPages, getHydrationStrategy, getISRCacheStats, prefetchAllComponents, registerServerComponent, renderToHtml, renderToStream, renderToStreamAsync, renderToStreamEnhanced, renderToString, resetComponentIdCounter, revalidateOnDemand, safeDeserializeState, safeSerializeState, serializeHydrationState, stateManager, unregisterServerComponent, validatePages, writeStaticFiles };

package/dist/index.d.ts

@@ -0,0 +1,612 @@
+import { VNode } from '@lytjs/vdom';
+import * as _lytjs_component from '@lytjs/component';
+
+/**
+ * @lytjs/ssr - 服务端渲染
+ *
+ * 将 VNode 渲染为 HTML 字符串
+ */
+
+/**
+ * 渲染 VNode 为 HTML 字符串
+ */
+declare function renderToString(vnode: VNode | VNode[] | string | number | null | undefined): string;
+/**
+ * 渲染完整的 HTML 页面
+ */
+declare function renderToHtml(vnode: VNode | VNode[], options?: {
+    title?: string;
+    lang?: string;
+    head?: string;
+    bodyAttrs?: Record<string, string>;
+}): string;
+declare const _default: {
+    renderToString: typeof renderToString;
+    renderToHtml: typeof renderToHtml;
+};
+
+/**
+ * @lytjs/ssr - 虚拟列表组件
+ *
+ * 高性能大数据列表渲染
+ */
+declare const VirtualList: _lytjs_component.ComponentOptions<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>>;
+
+/**
+ * @lytjs/ssr - 流式服务端渲染
+ *
+ * 将 VNode 渲染为 ReadableStream，支持分块发送和 Suspense 边界
+ */
+
+/** 流式渲染配置选项 */
+interface StreamRenderOptions {
+    /** 每个分块的最大字节数，默认 4096 */
+    chunkSize?: number;
+    /** Shell 就绪回调（Suspense 边界之前的初始内容已发送） */
+    onShellReady?: () => void;
+    /** 错误回调 */
+    onError?: (error: Error) => void;
+    /** 流式渲染超时时间（毫秒），默认 30000 */
+    timeout?: number;
+    /** 当渲染超时时的回退 HTML 内容 */
+    fallbackHtml?: string;
+    /** 流控制：每秒最大字节数，用于防止突发流量 */
+    maxBytesPerSecond?: number;
+    /** 是否启用错误恢复模式，默认 true */
+    errorRecovery?: boolean;
+    /** 单个组件渲染超时（毫秒），默认 5000 */
+    componentTimeout?: number;
+}
+/** 异步数据预取上下文 */
+interface DataPrefetchContext {
+    /** 路由路径 */
+    path?: string;
+    /** 路由参数 */
+    params?: Record<string, string>;
+    /** 查询参数 */
+    query?: Record<string, string>;
+}
+/** 异步数据预取结果 */
+interface PrefetchResult {
+    /** 预取的数据 */
+    data: Record<string, unknown>;
+    /** 数据过期时间（毫秒） */
+    ttl?: number;
+}
+/** 支持数据预取的组件接口 */
+interface PrefetchableComponent {
+    /** 预取数据方法 */
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+}
+/** 流式渲染增强选项 */
+interface EnhancedStreamRenderOptions extends StreamRenderOptions {
+    /** 数据预取上下文 */
+    prefetchContext?: DataPrefetchContext;
+    /** 数据预取完成回调 */
+    onDataPrefetched?: (data: Record<string, unknown>) => void;
+    /** 是否启用渐进式水合 */
+    progressiveHydration?: boolean;
+}
+/**
+ * 将 VNode 渲染为 ReadableStream（流式服务端渲染）
+ *
+ * @description
+ * 将 VNode 树渲染为 HTML 并通过 ReadableStream 分块发送。
+ * 支持以下特性：
+ * - 按组件边界拆分 HTML 分块
+ * - 支持 Suspense 边界（先发送 shell，再发送异步内容）
+ * - 使用 TextEncoder 编码为 Uint8Array
+ * - 可配置分块大小和回调
+ * - 超时控制和错误恢复
+ * - 流速率控制
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 流式渲染配置选项
+ * @returns ReadableStream<Uint8Array>
+ *
+ * @example
+ * ```typescript
+ * const stream = renderToStream(vnode, {
+ *   chunkSize: 2048,
+ *   onShellReady: () => console.log('Shell 已发送'),
+ *   onError: (err) => console.error(err),
+ *   timeout: 30000,
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   response.write(chunk);
+ * }
+ * ```
+ */
+declare function renderToStream(vnode: VNode, options?: StreamRenderOptions): ReadableStream<Uint8Array>;
+/**
+ * 将 VNode 渲染为异步 ReadableStream（支持异步组件和数据预取）
+ *
+ * @description
+ * 与 renderToStream 类似，但支持异步组件和数据预取。
+ * 遇到返回 Promise 的组件时先发送占位内容，等 Promise 解析后再发送实际内容。
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 流式渲染配置选项
+ * @returns ReadableStream<Uint8Array>
+ */
+declare function renderToStreamAsync(vnode: VNode, options?: EnhancedStreamRenderOptions): ReadableStream<Uint8Array>;
+/**
+ * 增强型流式渲染（包含数据预取和渐进式水合）
+ *
+ * @description
+ * 完整的流式渲染解决方案，包含数据预取、渐进式水合等高级特性。
+ *
+ * @param vnode - 要渲染的 VNode
+ * @param options - 增强型流式渲染配置
+ * @returns Promise<{ stream: ReadableStream<Uint8Array>; dehydratedState: Record<string, any> }>
+ */
+declare function renderToStreamEnhanced(vnode: VNode, options?: EnhancedStreamRenderOptions): Promise<{
+    stream: ReadableStream<Uint8Array>;
+    dehydratedState: Record<string, unknown>;
+}>;
+
+/**
+ * @lytjs/ssr - 静态站点生成（SSG）
+ *
+ * 预渲染页面配置为静态 HTML 文件
+ */
+
+/** SSG 页面配置 */
+interface SSGPage {
+    /** 页面路径，如 '/' 或 '/about' */
+    path: string;
+    /** 页面组件 VNode */
+    component: VNode;
+    /** 可选布局组件 */
+    layout?: VNode;
+    /** 页面头部信息 */
+    head?: {
+        /** 页面标题 */
+        title?: string;
+        /** 元信息键值对 */
+        meta?: Record<string, string>;
+    };
+    /** 额外的脚本标签 */
+    scripts?: string[];
+    /** 额外的样式标签 */
+    styles?: string[];
+}
+/** SSG 生成选项 */
+interface SSGOptions {
+    /** 站点基础 URL，默认 '/' */
+    baseUrl?: string;
+    /** 输出目录，默认 'dist' */
+    outDir?: string;
+    /** 默认页面标题 */
+    defaultTitle?: string;
+    /** 默认语言 */
+    lang?: string;
+    /** 是否生成 sitemap */
+    generateSitemap?: boolean;
+    /** 站点名称（用于 sitemap） */
+    siteName?: string;
+    /** 是否使用哈希路由 */
+    hashMode?: boolean;
+    /** 全局额外脚本 */
+    globalScripts?: string[];
+    /** 全局额外样式 */
+    globalStyles?: string[];
+    /** ISR 配置（增量静态再生成） */
+    isr?: {
+        /** 重新验证间隔（秒），0 表示按需重新验证 */
+        revalidate?: number;
+        /** 是否启用增量静态再生成 */
+        enabled?: boolean;
+        /** 预渲染 fallback 页面 */
+        fallback?: 'blocking' | boolean;
+    };
+}
+/**
+ * 将生成的 HTML 写入文件系统
+ *
+ * @description
+ * 将 generateStaticPages 生成的结果写入到指定的输出目录。
+ * 会自动创建所需的目录结构。
+ *
+ * @param pages - 页面配置数组
+ * @param options - SSG 选项
+ * @returns Promise<void>
+ *
+ * @example
+ * ```typescript
+ * await writeStaticFiles(pages, { outDir: 'build' });
+ * ```
+ */
+declare function writeStaticFiles(pages: SSGPage[], options?: SSGOptions): Promise<void>;
+/**
+ * 预渲染页面配置数组为静态 HTML
+ *
+ * @description
+ * 接受页面配置数组，为每个页面生成完整的 HTML 内容。
+ * 返回一个 Map，键为文件路径，值为 HTML 内容。
+ *
+ * @param pages - 页面配置数组
+ * @param options - SSG 生成选项
+ * @returns Map<string, string> 文件路径 -> HTML 内容
+ *
+ * @example
+ * ```typescript
+ * const pages: SSGPage[] = [
+ *   {
+ *     path: '/',
+ *     component: h('div', {}, 'Home'),
+ *     head: { title: '首页', meta: { description: '欢迎' } },
+ *   },
+ *   {
+ *     path: '/about',
+ *     component: h('div', {}, 'About'),
+ *   },
+ * ];
+ *
+ * const results = generateStaticPages(pages, {
+ *   baseUrl: 'https://example.com',
+ *   defaultTitle: 'My Site',
+ * });
+ *
+ * for (const [filePath, html] of results) {
+ *   console.log(filePath, html);
+ * }
+ * ```
+ */
+declare function generateStaticPages(pages: SSGPage[], options?: SSGOptions): Map<string, string>;
+/**
+ * 生成页面路由清单
+ *
+ * @description
+ * 根据页面配置生成一个 JSON 格式的路由清单，
+ * 可用于客户端路由注册或构建分析。
+ *
+ * @param pages - 页面配置数组
+ * @param baseUrl - 站点基础 URL
+ * @returns 路由信息数组
+ */
+declare function generateRouteManifest(pages: SSGPage[], baseUrl?: string): Array<{
+    path: string;
+    filePath: string;
+    title?: string;
+}>;
+/**
+ * 验证页面配置数组的合法性
+ *
+ * @description
+ * 检查每个页面配置是否包含必要的字段（path 和 component），
+ * 以及路径是否合法。返回错误信息数组。
+ *
+ * @param pages - 页面配置数组
+ * @returns 错误信息数组，空数组表示全部合法
+ */
+declare function validatePages(pages: SSGPage[]): string[];
+/**
+ * 创建 ISR 中间件
+ *
+ * @description
+ * 创建用于 Express/Fastify 等框架的 ISR 中间件，
+ * 支持增量静态再生成和背景重新验证。
+ *
+ * @param options - ISR 选项
+ * @returns 中间件函数
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createISRMiddleware, generateStaticPages } from '@lytjs/ssr';
+ *
+ * const app = express();
+ *
+ * // 预生成的页面
+ * const pages = [
+ *   { path: '/', component: homeComponent },
+ * ];
+ *
+ * const staticPages = generateStaticPages(pages);
+ *
+ * app.use(createISRMiddleware({
+ *   staticPages,
+ *   revalidate: 60, // 60秒后重新验证
+ *   async regenerate(path) {
+ *     const page = pages.find(p => p.path === path);
+ *     if (page) {
+ *       return generateStaticPages([page]).get('/index.html')!;
+ *     }
+ *     throw new Error('Page not found');
+ *   }
+ * }));
+ * ```
+ */
+declare function createISRMiddleware(options: {
+    /** 预生成的静态页面 */
+    staticPages: Map<string, string>;
+    /** 重新验证间隔（秒） */
+    revalidate?: number;
+    /** 是否启用 ISR */
+    enabled?: boolean;
+    /** 重新生成页面的函数 */
+    regenerate?: (path: string) => Promise<string>;
+}): (req: any, res: any, next: any) => Promise<any>;
+/**
+ * 触发按需重新验证
+ *
+ * @description
+ * 手动触发特定路径的重新验证，适合于内容更新后调用。
+ *
+ * @param path - 要重新验证的路径
+ * @param regenerate - 重新生成页面的函数
+ * @returns Promise<string> 新生成的 HTML
+ *
+ * @example
+ * ```typescript
+ * // 当博客文章更新时
+ * await revalidateOnDemand(
+ *   '/blog/my-post',
+ *   async () => generatePostHTML('my-post')
+ * );
+ * ```
+ */
+declare function revalidateOnDemand(path: string, regenerate: () => Promise<string>): Promise<string>;
+/**
+ * 获取 ISR 缓存统计信息
+ *
+ * @description
+ * 获取当前 ISR 缓存的统计信息，用于监控和调试。
+ *
+ * @returns 缓存统计信息
+ */
+declare function getISRCacheStats(): {
+    total: number;
+    paths: string[];
+};
+/**
+ * 清除 ISR 缓存
+ *
+ * @description
+ * 清除指定路径或所有过期的缓存。
+ *
+ * @param path - 可选，要清除的特定路径
+ * @param maxAge - 可选，清除超过指定秒数的缓存
+ */
+declare function clearISRCache(path?: string, maxAge?: number): void;
+
+/**
+ * @lytjs/ssr - 服务端组件完善
+ *
+ * 提供服务端组件生命周期管理、数据预取优化、状态序列化等功能
+ */
+
+/** 服务端组件生命周期钩子类型 */
+type ServerLifecycleHook = (context: ServerComponentContext) => Promise<void> | void;
+/** 服务端组件上下文 */
+interface ServerComponentContext {
+    /** 组件唯一 ID */
+    componentId: string;
+    /** 路由信息 */
+    route?: {
+        path: string;
+        params: Record<string, string>;
+        query: Record<string, string>;
+    };
+    /** 请求上下文 */
+    request?: {
+        headers: Record<string, string | undefined>;
+        cookies: Record<string, string>;
+    };
+}
+/** 服务端组件注册信息 */
+interface ServerComponentRegistration {
+    /** 组件名称 */
+    name: string;
+    /** 组件渲染函数 */
+    render: () => VNode;
+    /** 服务端初始化钩子 */
+    onServerInit?: ServerLifecycleHook;
+    /** 数据预取钩子 */
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    /** 服务端清理钩子 */
+    onServerCleanup?: ServerLifecycleHook;
+}
+/** 服务端组件状态管理器 */
+declare class ServerComponentStateManager {
+    /** 注册的组件 */
+    private registrations;
+    /** 正在执行的预取请求 */
+    private pendingPrefetches;
+    /** 组件初始化状态 */
+    private initializationStates;
+    /**
+     * 注册服务端组件
+     */
+    register(name: string, registration: ServerComponentRegistration): void;
+    /**
+     * 取消注册服务端组件
+     */
+    unregister(name: string): void;
+    /**
+     * 获取已注册的组件
+     */
+    getRegistration(name: string): ServerComponentRegistration | undefined;
+    /**
+     * 初始化服务端组件
+     */
+    initializeComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 清理服务端组件
+     */
+    cleanupComponent(name: string, context: ServerComponentContext): Promise<void>;
+    /**
+     * 预取组件数据（带缓存）
+     */
+    prefetchComponentData(name: string, context: DataPrefetchContext, cacheKey?: string): Promise<PrefetchResult>;
+    /**
+     * 清除所有缓存
+     */
+    clearAll(): void;
+}
+/** 全局状态管理器实例 */
+declare const stateManager: ServerComponentStateManager;
+/**
+ * 注册服务端组件
+ */
+declare function registerServerComponent(name: string, registration: ServerComponentRegistration): void;
+/**
+ * 取消注册服务端组件
+ */
+declare function unregisterServerComponent(name: string): void;
+/**
+ * 从 VNode 树中收集需要预取数据的组件
+ */
+declare function collectPrefetchComponents(vnode: VNode | VNode[] | string | number | null | undefined): string[];
+/**
+ * 并发预取多个组件的数据
+ */
+declare function prefetchAllComponents(components: string[], context: DataPrefetchContext): Promise<Record<string, PrefetchResult>>;
+/**
+ * 安全的状态序列化
+ * 处理循环引用、日期、正则表达式等特殊类型
+ */
+declare function safeSerializeState(state: unknown): string;
+/**
+ * 安全的状态反序列化
+ * 恢复特殊类型
+ */
+declare function safeDeserializeState(serialized: string): unknown;
+/**
+ * 创建组件脱水状态
+ */
+interface ComponentDehydratedState {
+    /** 组件名称 */
+    componentName: string;
+    /** 组件 Props */
+    props: Record<string, unknown>;
+    /** 预取的数据 */
+    data?: Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 构建完整的脱水状态
+ */
+declare function buildDehydratedState(prefetchResults: Record<string, PrefetchResult>): Record<string, ComponentDehydratedState>;
+/**
+ * 服务端组件管理器装饰器
+ */
+declare function ServerComponent(options: {
+    name: string;
+    prefetch?: (context: DataPrefetchContext) => Promise<PrefetchResult>;
+    onInit?: ServerLifecycleHook;
+    onCleanup?: ServerLifecycleHook;
+}): (target: {
+    name?: string;
+    render?: () => VNode;
+}) => void;
+
+/**
+ * @lytjs/ssr - 组件级水合提示
+ *
+ * 提供水合标记、策略检测和状态序列化等辅助函数，
+ * 用于 SSR 输出中嵌入客户端水合所需的信息
+ */
+
+/** 水合策略类型 */
+type HydrationStrategy = 'lazy' | 'eager' | 'idle';
+/** 水合提示信息 */
+interface HydrationHints {
+    /** 组件唯一标识 */
+    componentId: string;
+    /** 水合策略 */
+    strategy: HydrationStrategy;
+    /** 组件 props 快照 */
+    props: Record<string, unknown>;
+}
+/** 水合状态数据结构 */
+interface HydrationState {
+    /** 组件水合提示列表 */
+    hints: HydrationHints[];
+    /** 全局初始状态 */
+    initialState?: Record<string, unknown>;
+}
+/**
+ * 重置组件 ID 计数器（仅用于测试）
+ */
+declare function resetComponentIdCounter(): void;
+/**
+ * 为 VNode 树添加水合标记
+ *
+ * @description
+ * 递归遍历 VNode 树，为每个元素节点添加 data-hydrate 属性，
+ * 用于客户端水合时识别对应的 SSR 输出节点。
+ * 同时根据 props 中的 hydrateStrategy 设置 data-hydrate-strategy 属性。
+ *
+ * @param vnode - 原始 VNode
+ * @returns 添加了水合标记的新 VNode（浅拷贝）
+ *
+ * @example
+ * ```typescript
+ * const marked = createHydrationMarkers(vnode);
+ * // marked 的每个元素节点都带有 data-hydrate="lyt-hydrate-1" 等属性
+ * ```
+ */
+declare function createHydrationMarkers(vnode: VNode): VNode;
+/**
+ * 获取组件的水合策略
+ *
+ * @description
+ * 从 VNode 的 props 中读取 hydrateStrategy 字段，
+ * 返回对应的水合策略。如果未设置，默认返回 'eager'。
+ *
+ * @param vnode - 目标 VNode
+ * @returns 水合策略（lazy / eager / idle）
+ *
+ * @example
+ * ```typescript
+ * const strategy = getHydrationStrategy(vnode);
+ * // 'eager' | 'lazy' | 'idle'
+ * ```
+ */
+declare function getHydrationStrategy(vnode: VNode): HydrationStrategy;
+/**
+ * 序列化客户端水合所需的初始状态
+ *
+ * @description
+ * 将任意状态对象序列化为可安全嵌入 HTML 的 JSON 字符串。
+ * 处理特殊值（undefined、函数、Symbol 等）以确保 JSON 安全。
+ *
+ * @param state - 要序列化的状态对象
+ * @returns JSON 字符串
+ *
+ * @example
+ * ```typescript
+ * const serialized = serializeHydrationState({
+ *   user: { name: 'Alice', age: 30 },
+ *   items: [1, 2, 3],
+ * });
+ * // '{"user":{"name":"Alice","age":30},"items":[1,2,3]}'
+ * ```
+ */
+declare function serializeHydrationState(state: unknown): string;
+/**
+ * 创建脱水状态（SSR 时序列化到 HTML 中的状态）
+ *
+ * @description
+ * 从 VNode 树中提取水合所需的信息，生成一段可嵌入 HTML 的 script 标签内容。
+ * 客户端加载时读取此状态进行水合。
+ *
+ * @param vnode - VNode 节点
+ * @param initialState - 可选的全局初始状态
+ * @returns 可嵌入 HTML 的 script 标签字符串
+ *
+ * @example
+ * ```typescript
+ * const script = createDehydratedState(vnode, {
+ *   user: { name: 'Alice' },
+ * });
+ * // <script id="__LYT_DEHYDRATED_STATE__" type="application/json">...</script>
+ * ```
+ */
+declare function createDehydratedState(vnode: VNode, initialState?: Record<string, unknown>): string;
+
+export { type ComponentDehydratedState, type DataPrefetchContext, type EnhancedStreamRenderOptions, type HydrationHints, type HydrationState, type HydrationStrategy, type PrefetchResult, type PrefetchableComponent, type SSGOptions, type SSGPage, ServerComponent, type ServerComponentContext, type ServerComponentRegistration, type ServerLifecycleHook, type StreamRenderOptions, VirtualList, buildDehydratedState, clearISRCache, collectPrefetchComponents, createDehydratedState, createHydrationMarkers, createISRMiddleware, _default as default, generateRouteManifest, generateStaticPages, getHydrationStrategy, getISRCacheStats, prefetchAllComponents, registerServerComponent, renderToHtml, renderToStream, renderToStreamAsync, renderToStreamEnhanced, renderToString, resetComponentIdCounter, revalidateOnDemand, safeDeserializeState, safeSerializeState, serializeHydrationState, stateManager, unregisterServerComponent, validatePages, writeStaticFiles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lytjs/ssr",
-  "version": "6.8.0",
+  "version": "6.9.1",
   "description": "LytJS Server-Side Rendering support",
   "type": "module",
   "main": "./dist/index.cjs",