@lytjs/renderer 6.9.2 → 6.9.3

package/dist/index.d.ts

@@ -0,0 +1,965 @@
+import { Ref } from '@lytjs/reactivity';
+export { getSkippedTrackingCount, resetSkippedTrackingCount, shouldSkipTracking, withFirstRenderOptimization } from '@lytjs/reactivity';
+import { VaporComponentDefinition, VaporApp } from './vapor/vapor-app.js';
+export { VaporAppOptions, VaporComponentOptions, VaporContext, PropOptions as VaporPropOptions } from './vapor/vapor-app.js';
+import { VNode } from '@lytjs/vdom';
+export { RendererOptions, VNode, createRenderer } from '@lytjs/vdom';
+export { DOMRenderer, EventInvoker, HydrationRenderer, ParsedEvent, WebRendererHost, createDOMRenderer, createHydrationFunctions, createInvoker, createWebHost, getEventKey, normalizeEventName, parseEventModifier, patchAttr, patchClass, patchEvent, patchProp, patchStyle, removeAllEventListeners, wrapDOMEvent } from '@lytjs/adapter-web';
+export { isOn } from '@lytjs/common-events';
+export { HostEvent, HostEventHandler, HostEventOptions, HostRect, HostStyleDeclaration, RendererHost, TransitionDurationInfo } from '@lytjs/host-contract';
+export { SSRInput } from './ssr.js';
+export { escapeHtml, isBooleanAttr } from '@lytjs/common-string';
+
+/** 数据获取状态 */
+interface DataFetchState<T = unknown> {
+    /** 数据 */
+    data: T | undefined;
+    /** 是否正在加载 */
+    loading: boolean;
+    /** 错误信息 */
+    error: Error | null;
+    /** 是否来自缓存 */
+    fromCache: boolean;
+    /** 获取时间戳 */
+    timestamp: number | null;
+}
+/** 数据获取选项 */
+interface DataFetchOptions<T = unknown> {
+    /** 是否立即执行 */
+    immediate?: boolean;
+    /** 初始数据 */
+    initialData?: T;
+    /** 缓存键 */
+    cacheKey?: string | (() => string);
+    /** 缓存时间（毫秒） */
+    cacheTime?: number;
+    /** 是否服务端预取 */
+    serverPrefetch?: boolean;
+    /** 依赖项变化时重新获取 */
+    watch?: Ref<unknown>[];
+    /** 转换函数 */
+    transform?: (data: unknown) => T;
+    /** 错误处理 */
+    onError?: (error: Error) => void;
+    /** 成功处理 */
+    onSuccess?: (data: T) => void;
+    /** 重试次数 */
+    retry?: number;
+    /** 重试延迟（毫秒） */
+    retryDelay?: number;
+}
+/** 预取数据条目 */
+interface PrefetchDataEntry {
+    /** 缓存键 */
+    key: string;
+    /** 数据 */
+    data: unknown;
+    /** 时间戳 */
+    timestamp: number;
+    /** 过期时间 */
+    expiresAt: number;
+}
+/** 预取管理器 */
+interface PrefetchManager {
+    /** 预取数据 */
+    prefetch<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
+    /** 获取预取数据 */
+    getPrefetchedData<T>(key: string): T | undefined;
+    /** 序列化所有预取数据 */
+    serialize(): string;
+    /** 反序列化预取数据 */
+    deserialize(data: string): void;
+    /** 清除预取数据 */
+    clear(): void;
+}
+/**
+ * 序列化数据（支持特殊类型）
+ */
+declare function serializeData(data: unknown): string;
+/**
+ * 反序列化数据
+ */
+declare function deserializeData(json: string): unknown;
+/**
+ * 创建预取管理器
+ */
+declare function createPrefetchManager(): PrefetchManager;
+/**
+ * 组合式数据获取函数
+ *
+ * @example
+ * ```ts
+ * const { data, loading, error, refetch } = useFetch('/api/users', {
+ *   immediate: true,
+ *   cacheKey: 'users',
+ * });
+ * ```
+ */
+declare function useFetch<T extends string | number | boolean | object | null = object>(url: string | (() => string), options?: DataFetchOptions<T>): {
+    data: Ref<T | undefined>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    refetch: () => Promise<void>;
+};
+/**
+ * 异步数据获取（类似 Nuxt useAsyncData）
+ *
+ * @example
+ * ```ts
+ * const { data, pending, error } = useAsyncData('users', () =>
+ *   $fetch('/api/users')
+ * );
+ * ```
+ */
+declare function useAsyncData<T extends string | number | boolean | object | null = object>(key: string, fetcher: () => Promise<T>, options?: DataFetchOptions<T>): {
+    data: Ref<T | undefined>;
+    pending: Ref<boolean>;
+    error: Ref<Error | null>;
+    refresh: () => Promise<void>;
+};
+/**
+ * 注入服务端预取数据到 HTML
+ */
+declare function injectPrefetchData(): string;
+/**
+ * 从客户端读取预取数据
+ */
+declare function getPrefetchData<T = unknown>(key: string): T | undefined;
+
+/** Server Action 配置 */
+interface ServerActionConfig {
+    /** 服务端 action 端点 */
+    endpoint?: string;
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 错误处理 */
+    onError?: (error: Error) => void;
+}
+/**
+ * 配置 Server Action
+ */
+declare function configureServerAction(config: Partial<ServerActionConfig>): void;
+/**
+ * 调用服务端函数
+ *
+ * @example
+ * ```ts
+ * // 在客户端调用服务端函数
+ * const result = await callServer('ProductList', 'fetchProducts', { category: 'electronics' });
+ * ```
+ */
+declare function callServer<T = unknown>(componentName: string, functionName: string, ...args: unknown[]): Promise<T>;
+/**
+ * 创建服务端函数代理
+ *
+ * @example
+ * ```ts
+ * // 创建类型安全的服务端函数调用
+ * const fetchProducts = createServerFunction<Product[]>('ProductList', 'fetchProducts');
+ * const products = await fetchProducts({ category: 'electronics' });
+ * ```
+ */
+declare function createServerFunction<T>(componentName: string, functionName: string): (...args: unknown[]) => Promise<T>;
+/**
+ * 获取服务端预取的数据
+ */
+declare function getServerData<T = unknown>(key?: string): T | undefined;
+/**
+ * 检查是否有服务端数据
+ */
+declare function hasServerData(): boolean;
+/**
+ * 检查组件是否已 hydration
+ */
+declare function isHydrated(componentId: string): boolean;
+/**
+ * 标记组件为已 hydration
+ */
+declare function markHydrated(componentId: string): void;
+/**
+ * 获取 hydration 状态
+ */
+declare function getHydrationState(componentId: string): {
+    hydrated: boolean;
+    pending: boolean;
+    error: Error | null;
+};
+/**
+ * 自动 hydrate 所有 Server Components
+ */
+declare function autoHydrate(): Promise<void>;
+
+/** Server Component 定义 */
+interface ServerComponentDefinition {
+    /** 组件 ID */
+    id: string;
+    /** 组件名称 */
+    name: string;
+    /** 渲染函数 */
+    render: () => Promise<string>;
+    /** 数据获取函数 */
+    fetchData?: () => Promise<Record<string, unknown>>;
+    /** 序列化数据 */
+    serializeData?: () => string;
+}
+/** Server Action 请求 */
+interface ServerActionRequest {
+    /** 组件名称 */
+    componentName: string;
+    /** 函数名称 */
+    functionName: string;
+    /** 参数 */
+    args: unknown[];
+}
+/** Server Action 响应 */
+interface ServerActionResponse {
+    /** 是否成功 */
+    success: boolean;
+    /** 返回数据 */
+    data?: unknown;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 注册 Server Component
+ */
+declare function registerServerComponent(component: ServerComponentDefinition): void;
+/**
+ * 注册服务端函数
+ */
+declare function registerServerFunction(componentId: string, functionName: string, fn: (...args: unknown[]) => Promise<unknown>): void;
+/**
+ * 获取 Server Component
+ */
+declare function getServerComponent(id: string): ServerComponentDefinition | undefined;
+/**
+ * 获取服务端函数
+ */
+declare function getServerFunction(componentId: string, functionName: string): ((...args: unknown[]) => Promise<unknown>) | undefined;
+/**
+ * 处理 Server Action 请求
+ * 用于处理客户端对服务端函数的调用
+ */
+declare function handleServerAction(request: ServerActionRequest): Promise<ServerActionResponse>;
+/**
+ * 创建 Server Action 处理器
+ * 用于 Express/Fastify 等服务端框架
+ */
+declare function createServerActionHandler(): (req: any, res: any) => Promise<void>;
+/**
+ * 序列化 Server Component 数据
+ */
+declare function serializeServerData(data: unknown): string;
+/**
+ * 反序列化 Server Component 数据
+ */
+declare function deserializeServerData(json: string): unknown;
+/**
+ * 渲染 Server Component
+ */
+declare function renderServerComponent(componentId: string, _context?: Record<string, unknown>): Promise<string>;
+/**
+ * 定义 Server Component
+ *
+ * @example
+ * ```ts
+ * export default defineServerComponent({
+ *   id: 'product-list',
+ *   name: 'ProductList',
+ *   async fetchData() {
+ *     const products = await db.products.findMany();
+ *     return { products };
+ *   },
+ *   async render() {
+ *     return '<div class="product-list">...</div>';
+ *   }
+ * });
+ * ```
+ */
+declare function defineServerComponent(options: Omit<ServerComponentDefinition, 'serializeData'> & {
+    serializeData?: () => string;
+}): ServerComponentDefinition;
+
+/** HMR 更新类型 */
+type HMRUpdateType = 'template' | 'script' | 'style' | 'full';
+/** HMR 更新信息 */
+interface HMRUpdate {
+    type: HMRUpdateType;
+    componentId: string;
+    oldComponent: VaporComponentDefinition | null;
+    newComponent: VaporComponentDefinition;
+    timestamp: number;
+}
+/** HMR 状态保留策略 */
+interface HMRStatePreservation {
+    /** 是否保留 ref 状态 */
+    refs: boolean;
+    /** 是否保留 reactive 状态 */
+    reactive: boolean;
+    /** 是否保留 computed 缓存 */
+    computed: boolean;
+    /** 是否保留 watch 副作用 */
+    watches: boolean;
+}
+/** 默认状态保留策略 */
+declare const DEFAULT_STATE_PRESERVATION: HMRStatePreservation;
+/**
+ * 生成唯一的组件 ID
+ */
+declare function generateComponentId(): string;
+/**
+ * 注册组件实例
+ */
+declare function registerComponent(id: string, component: VaporComponentDefinition, container: Element): void;
+/**
+ * 注销组件实例
+ */
+declare function unregisterComponent(id: string): void;
+/** HMR 更新监听器 */
+type HMRUpdateListener = (update: HMRUpdate) => void;
+/**
+ * 添加 HMR 更新监听器
+ */
+declare function onHMRUpdate(listener: HMRUpdateListener): () => void;
+/**
+ * 处理组件更新
+ *
+ * @param componentId 组件 ID
+ * @param newComponent 新组件定义
+ * @param updateType 更新类型
+ * @param preservation 状态保留策略
+ * @returns 是否成功更新
+ */
+declare function handleComponentUpdate(componentId: string, newComponent: VaporComponentDefinition, updateType: HMRUpdateType, _preservation?: HMRStatePreservation): boolean;
+/**
+ * 创建 Vite HMR accept 处理器
+ *
+ * 用于在组件中调用：
+ * ```ts
+ * if (import.meta.hot) {
+ *   import.meta.hot.accept((newModule) => {
+ *     createVaporHMRHandler('my-component-id')(newModule);
+ *   });
+ * }
+ * ```
+ */
+declare function createVaporHMRHandler(componentId: string): (newModule: {
+    default: VaporComponentDefinition;
+} | null) => void;
+/**
+ * 检测是否支持 HMR
+ */
+declare function isHMRAvailable(): boolean;
+/**
+ * 手动触发组件重新渲染
+ */
+declare function forceRerender(componentId: string): boolean;
+/**
+ * 清理所有 HMR 状态
+ */
+declare function clearHMRState(): void;
+
+type App = unknown;
+type Component = unknown;
+/** Hydration 模式 */
+type HydrationMode = 'full' | 'selective' | 'lazy';
+/** Hydration 选项 */
+interface HydrationOptions {
+    /** Hydration 模式 */
+    mode?: HydrationMode;
+    /** 选择性 Hydration 选择器 */
+    selectors?: string[];
+    /** 懒加载阈值（毫秒） */
+    lazyThreshold?: number;
+    /** 是否在空闲时 Hydration */
+    idleCallback?: boolean;
+    /** 错误处理 */
+    onError?: (error: HydrationError) => void;
+    /** 不匹配处理 */
+    onMismatch?: (mismatch: HydrationMismatch) => void;
+    /** Hydration 完成回调 */
+    onComplete?: () => void;
+}
+/** Hydration 错误 */
+interface HydrationError {
+    /** 错误类型 */
+    type: 'mismatch' | 'missing' | 'invalid' | 'script';
+    /** 错误消息 */
+    message: string;
+    /** 相关节点 */
+    node?: Element;
+    /** 原始错误 */
+    error?: Error;
+}
+/** Hydration 不匹配 */
+interface HydrationMismatch {
+    /** 期望的 HTML */
+    expected: string;
+    /** 实际的 HTML */
+    actual: string;
+    /** 节点路径 */
+    path: string;
+    /** 恢复策略 */
+    recoveryStrategy: 'rerender' | 'keep-server' | 'keep-client';
+}
+/** Hydration 统计 */
+interface HydrationStats {
+    /** 总节点数 */
+    totalNodes: number;
+    /** 已 Hydration 节点数 */
+    hydratedNodes: number;
+    /** 跳过的节点数 */
+    skippedNodes: number;
+    /** 不匹配数 */
+    mismatches: number;
+    /** 错误数 */
+    errors: number;
+    /** Hydration 耗时（毫秒） */
+    duration: number;
+}
+/**
+ * 全应用 Hydration
+ *
+ * @example
+ * ```ts
+ * // 服务端渲染的 HTML
+ * const html = '<div id="app">...</div>';
+ *
+ * // 客户端 Hydration
+ * hydrateApp(App, '#app');
+ * ```
+ */
+declare function hydrateApp(component: Component, container: string | Element, options?: HydrationOptions): Promise<{
+    app: App;
+    stats: HydrationStats;
+}>;
+/**
+ * 选择性 Hydration
+ *
+ * @example
+ * ```ts
+ * // 只 Hydration 可见区域
+ * hydrateVisible(App, '#app');
+ *
+ * // 基于 IntersectionObserver
+ * hydrateOnVisible(App, '#app', {
+ *   rootMargin: '100px',
+ * });
+ * ```
+ */
+declare function hydrateVisible(component: Component, container: string | Element, options?: HydrationOptions): Promise<{
+    app: App;
+    stats: HydrationStats;
+}>;
+/**
+ * 延迟 Hydration
+ * 将 Hydration 任务加入队列，按优先级执行
+ */
+declare function queueHydration(element: Element, priority: 'high' | 'medium' | 'low', callback: () => Promise<void>): void;
+/**
+ * 水合错误恢复策略
+ */
+type RecoveryStrategy = 'rerender' | 'keep-server' | 'keep-client' | 'fallback';
+/**
+ * 水合错误处理器
+ */
+declare class HydrationErrorHandler {
+    private errors;
+    private mismatches;
+    private options;
+    constructor(options?: HydrationOptions);
+    /**
+     * 处理 Hydration 错误
+     */
+    handleError(error: HydrationError): RecoveryStrategy;
+    /**
+     * 处理不匹配错误
+     */
+    private handleMismatch;
+    /**
+     * 判断是否是轻微不匹配
+     */
+    private isMinorMismatch;
+    /**
+     * 判断是否是严重不匹配
+     */
+    private isCriticalMismatch;
+    /**
+     * 获取节点路径
+     */
+    private getNodePath;
+    /**
+     * 获取所有错误
+     */
+    getErrors(): HydrationError[];
+    /**
+     * 获取所有不匹配
+     */
+    getMismatches(): HydrationMismatch[];
+    /**
+     * 清除错误记录
+     */
+    clear(): void;
+}
+/**
+ * 创建错误处理器
+ */
+declare function createHydrationErrorHandler(options?: HydrationOptions): HydrationErrorHandler;
+/**
+ * 安全 Hydration
+ * 带错误恢复的 Hydration
+ */
+declare function safeHydrate(component: Component, container: string | Element, options?: HydrationOptions): Promise<{
+    app: App;
+    stats: HydrationStats;
+    errorHandler: HydrationErrorHandler;
+}>;
+
+/**
+ * @lytjs/renderer - SSR 流式渲染
+ * 使用 Web Streams API 进行服务端流式渲染
+ * FIX: P2-36 使用共享工具函数
+ */
+
+interface SSRStreamOptions {
+    /** 是否在块之间插入注释标记（用于调试） */
+    commentMarkers?: boolean;
+}
+
+/** 优化的流式渲染选项 */
+interface OptimizedStreamOptions {
+    /** 是否启用预加载提示 */
+    preloadHints?: boolean;
+    /** 是否启用 HTTP/2 Push */
+    http2Push?: boolean;
+    /** 关键 CSS 内联 */
+    criticalCSS?: string;
+    /** 延迟加载阈值（毫秒） */
+    deferThreshold?: number;
+    /** 是否启用压缩 */
+    compression?: boolean;
+    /** 缓冲区大小（字节） */
+    bufferSize?: number;
+    /** 是否启用 Early Flush */
+    earlyFlush?: boolean;
+}
+/** 预加载提示 */
+interface PreloadHint {
+    /** 资源类型 */
+    type: 'script' | 'style' | 'font' | 'image';
+    /** 资源 URL */
+    href: string;
+    /** 是否跨域 */
+    crossorigin?: boolean;
+    /** 优先级 */
+    importance?: 'high' | 'low' | 'auto';
+}
+/** 流式渲染统计 */
+interface StreamStats {
+    /** TTFB（首字节时间） */
+    ttfb: number;
+    /** 总渲染时间 */
+    totalTime: number;
+    /** 块数量 */
+    chunkCount: number;
+    /** 总字节数 */
+    totalBytes: number;
+    /** Suspense 边界数量 */
+    suspenseBoundaries: number;
+}
+/**
+ * 优化的 SSR 流式渲染器
+ *
+ * 特性：
+ * - Early Flush：尽早发送初始 HTML
+ * - 智能缓冲：自动管理缓冲区大小
+ * - 预加载提示：自动生成 Link 头
+ * - 优先级调度：关键内容优先发送
+ */
+declare class OptimizedSSRStream {
+    private controller;
+    private encoder;
+    private options;
+    private buffer;
+    private bufferSize;
+    private stats;
+    private startTime;
+    private flushedFirstChunk;
+    private preloadHints;
+    constructor(controller: ReadableStreamDefaultController<Uint8Array>, options?: OptimizedStreamOptions);
+    /**
+     * 推送 HTML 内容到流
+     */
+    push(html: string): void;
+    /**
+     * 刷新缓冲区到流
+     */
+    flush(): void;
+    /**
+     * 添加预加载提示
+     */
+    addPreloadHint(hint: PreloadHint): void;
+    /**
+     * 生成文档头部
+     */
+    generateDocumentHead(options: {
+        title?: string;
+        meta?: Record<string, string>[];
+        links?: Record<string, string>[];
+        styles?: string[];
+    }): string;
+    /**
+     * 生成文档尾部
+     */
+    generateDocumentFooter(options: {
+        scripts?: string[];
+        inlineScripts?: string[];
+    }): string;
+    /**
+     * 流式渲染 VNode
+     */
+    renderVNode(vnode: VNode): Promise<void>;
+    /**
+     * 获取渲染统计
+     */
+    getStats(): StreamStats;
+    /**
+     * 完成渲染
+     */
+    finish(): void;
+    private generateLinkHeader;
+    private streamVNode;
+    private streamFragment;
+    private streamElement;
+    private streamComponent;
+    private isComponentVNode;
+    private yieldToMicrotask;
+}
+
+/**
+ * @lytjs/renderer - SSR Island 架构
+ * 为 SSR 应用提供基于 Island 的选择性 hydration
+ */
+
+/**
+ * Island 组件的精简接口。
+ * 使用简化的结构以避免与完整的 ComponentOptions 紧耦合。
+ */
+interface ComponentOptions {
+    name?: string;
+    props?: Record<string, unknown>;
+    setup?: (props: Record<string, unknown>) => Record<string, unknown> | VNode | void;
+    render?: (ctx: Record<string, unknown>) => VNode;
+    data?: () => Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+interface SignalRenderer {
+    /** 将模板渲染到指定的容器元素或 CSS 选择器 */
+    render(container: Element | string): void;
+    /** 卸载渲染器，清理所有 effect 和 DOM */
+    unmount(): void;
+}
+
+/** Vapor SSR 渲染选项 */
+interface VaporSSROptions {
+    /** 是否包含数据预取脚本 */
+    includePrefetchScript?: boolean;
+    /** 是否启用流式渲染 */
+    streaming?: boolean;
+    /** 自定义序列化函数 */
+    serialize?: (data: unknown) => string;
+}
+/** Vapor SSR 渲染结果 */
+interface VaporSSRResult {
+    /** 渲染的 HTML 字符串 */
+    html: string;
+    /** 预取的数据（用于客户端 hydration） */
+    prefetchData?: Record<string, unknown>;
+    /** 需要注入的脚本 */
+    scripts?: string[];
+    /** 需要注入的样式 */
+    styles?: string[];
+}
+/** Vapor SSR 流式渲染结果 */
+interface VaporSSRStreamResult {
+    /** HTML 流 */
+    stream: ReadableStream<Uint8Array>;
+    /** 预取数据 Promise */
+    prefetchData: Promise<Record<string, unknown>>;
+}
+/**
+ * 定义数据预取函数
+ *
+ * @example
+ * ```ts
+ * const App = defineVaporComponent({
+ *   template: '<div>{{ data.message }}</div>',
+ *   setup() {
+ *     // 使用 definePrefetch 定义预取函数
+ *     const data = definePrefetch(async () => {
+ *       const res = await fetch('/api/data');
+ *       return res.json();
+ *     });
+ *     return { data };
+ *   }
+ * });
+ * ```
+ */
+declare function definePrefetch<T>(fetcher: () => Promise<T>): {
+    data: T | undefined;
+    __prefetchFn__: () => Promise<T>;
+};
+/**
+ * 在 setup 中使用预取数据
+ */
+declare function usePrefetchData<T>(key: string, _fetcher?: () => Promise<T>): {
+    data: T | undefined;
+    pending: boolean;
+    error: Error | null;
+};
+/**
+ * Vapor SSR Hydration 选项
+ */
+interface VaporHydrationOptions {
+    /** 是否启用选择性 hydration */
+    selective?: boolean;
+    /** Hydration 错误处理 */
+    onError?: (error: Error) => void;
+}
+
+/**
+ * @lytjs/renderer - Component Resource Cleanup
+ *
+ * 基于 WeakMap 的组件资源清理注册表。
+ * 组件卸载时自动清理所有注册的事件监听器、effect 订阅和 cleanup 钩子。
+ */
+/** 渲染器接口（仅需 removeEventListener 方法） */
+interface ResourceCleanupRenderer {
+    removeEventListener(el: unknown, event: string, handler: (...args: unknown[]) => void, options?: unknown): void;
+}
+/**
+ * 注册组件事件监听器。
+ * 组件卸载时将自动调用 renderer.removeEventListener 移除该监听器。
+ *
+ * @param component - 组件实例（作为 WeakMap key）
+ * @param el - 事件目标元素
+ * @param event - 事件名称
+ * @param handler - 事件处理函数
+ * @param options - 可选的 addEventListener 选项
+ */
+declare function registerComponentEventListener(component: object, el: unknown, event: string, handler: (...args: unknown[]) => void, options?: unknown): void;
+/**
+ * 注册 effect 订阅。
+ * 组件卸载时将自动调用 dispose 函数停止 effect。
+ *
+ * @param component - 组件实例（作为 WeakMap key）
+ * @param dispose - effect 的 dispose 回调函数
+ */
+declare function registerComponentEffectSubscription(component: object, dispose: () => void): void;
+/**
+ * 注册通用 cleanup 钩子。
+ * 组件卸载时将按注册顺序执行该回调。
+ *
+ * @param component - 组件实例（作为 WeakMap key）
+ * @param cleanup - 清理回调函数
+ */
+declare function registerComponentCleanup(component: object, cleanup: () => void): void;
+/**
+ * 统一清理组件所有注册资源。
+ *
+ * 清理顺序：
+ * 1. cleanup 钩子（可能依赖 effect 仍活跃）
+ * 2. effect 订阅（停止响应式追踪）
+ * 3. 事件监听器（DOM 操作，最后执行）
+ *
+ * 每个清理操作均通过 try-catch 保护，单个失败不影响其余流程。
+ *
+ * @param renderer - 渲染器实例，需提供 removeEventListener 方法
+ * @param component - 要清理资源的组件实例
+ */
+declare function cleanupComponentResources(renderer: ResourceCleanupRenderer, component: object): void;
+
+/**
+ * @lytjs/renderer - Shared utilities
+ *
+ * This module provides shared utility functions used across the renderer package,
+ * including HTML escaping, boolean attribute detection, and void element checks.
+ * It re-exports selected utilities from @lytjs/common-string for convenience.
+ */
+
+/**
+ * Check if a tag is a void (self-closing) element
+ */
+declare function isVoidElement(tag: string): boolean;
+
+/**
+ * 渲染器插件接口
+ * 插件可以挂载到渲染生命周期的各个阶段
+ */
+interface RendererPlugin {
+    /** 插件名称 */
+    name: string;
+    /** 插件安装时调用 */
+    install: (context: PluginContext) => void;
+    /** 可选：在 mount vnode 之前调用 */
+    beforeMount?: (vnode: VNode) => void;
+    /** 可选：在 mount vnode 之后调用 */
+    afterMount?: (vnode: VNode, container: unknown) => void;
+    /** 可选：在 patch vnode 之前调用 */
+    beforePatch?: (oldVNode: VNode, newVNode: VNode) => void;
+    /** 可选：在 patch vnode 之后调用 */
+    afterPatch?: (vnode: VNode) => void;
+    /** 可选：在 unmount vnode 之前调用 */
+    beforeUnmount?: (vnode: VNode) => void;
+    /** 可选：在 unmount vnode 之后调用 */
+    afterUnmount?: (vnode: VNode) => void;
+}
+/**
+ * 插件安装时传递的上下文
+ */
+interface PluginContext {
+    /** 为特定的生命周期事件注册钩子 */
+    on: (event: LifecycleEvent, handler: HookHandler) => void;
+    /** 移除已注册的钩子 */
+    off: (event: LifecycleEvent, handler: HookHandler) => void;
+}
+/** 插件可以挂载的生命周期事件 */
+type LifecycleEvent = 'beforeMount' | 'afterMount' | 'beforePatch' | 'afterPatch' | 'beforeUnmount' | 'afterUnmount';
+/** 钩子处理函数类型 */
+type HookHandler = (...args: unknown[]) => void;
+/**
+ * 安装渲染器插件。
+ * 插件可以通过挂载生命周期事件来扩展渲染器的功能。
+ *
+ * @example
+ * ```ts
+ * // 创建插件
+ * const myPlugin: RendererPlugin = {
+ *   name: 'MyPlugin',
+ *   install(context) {
+ *     context.on('beforeMount', (vnode) => {
+ *       console.log('Before mount:', vnode);
+ *     });
+ *   },
+ * };
+ *
+ * // 使用插件
+ * use(myPlugin);
+ * ```
+ */
+declare function use(plugin: RendererPlugin): void;
+/**
+ * 获取所有已安装的插件
+ */
+declare function getInstalledPlugins(): readonly RendererPlugin[];
+/**
+ * 检查插件是否已安装
+ */
+declare function isPluginInstalled(pluginName: string): boolean;
+/**
+ * 按名称移除插件
+ */
+declare function removePlugin(pluginName: string): boolean;
+/**
+ * 内部：执行生命周期事件的钩子
+ * 由渲染器在适当的生命周期节点调用
+ * FIX: P2-29 数组遍历优化 - 使用 for 循环替代 forEach
+ */
+declare function executeHooks(event: LifecycleEvent, ...args: unknown[]): void;
+
+/** Hydration 完善：全应用、选择性、错误恢复 */
+declare function getEnhancedHydrationFunctions(): Promise<{
+    hydrateApp: typeof hydrateApp;
+    hydrateVisible: typeof hydrateVisible;
+    queueHydration: typeof queueHydration;
+    safeHydrate: typeof safeHydrate;
+    createHydrationErrorHandler: typeof createHydrationErrorHandler;
+}>;
+
+/** 将组件渲染为字符串（SSR） */
+declare function renderToString(input: {
+    vnode: VNode;
+}): Promise<string>;
+
+/** 将 VNode 树流式渲染为 ReadableStream（SSR Streaming） */
+declare function renderToStream(input: {
+    vnode: unknown;
+}, options?: {
+    commentMarkers?: boolean;
+}): Promise<ReadableStream>;
+
+/** 优化的流式渲染 - TTFB 降低 50%+ */
+declare function createOptimizedStream(vnode: unknown, options?: unknown): Promise<ReadableStream>;
+declare function renderDocumentToStream(vnode: unknown, options?: unknown): Promise<ReadableStream>;
+
+declare function hydrateIsland(el: Element, component: ComponentOptions, props?: Record<string, unknown>): Promise<void>;
+declare function registerIslandComponent(name: string, component: ComponentOptions): Promise<void>;
+declare function createIslandSSRContent(name: string, props?: Record<string, unknown>): Promise<string>;
+
+/** 创建 Signal 模式渲染器（细粒度 DOM 更新） */
+declare function createSignalRenderer(template?: string, context?: Record<string, unknown>): Promise<SignalRenderer>;
+
+/** 创建 Vapor 模式渲染器（Signal 渲染器的别名） */
+declare function createVaporRenderer(template?: string, context?: Record<string, unknown>): Promise<SignalRenderer>;
+
+/** 定义 Vapor 模式组件 */
+declare function defineVaporComponent(options: unknown): Promise<VaporComponentDefinition>;
+declare function createVaporApp(rootComponent: unknown, props?: Record<string, unknown>): Promise<VaporApp>;
+
+/** Vapor 模式 HMR 支持 */
+declare function getVaporHMRFunctions(): Promise<{
+    generateComponentId: typeof generateComponentId;
+    registerComponent: typeof registerComponent;
+    unregisterComponent: typeof unregisterComponent;
+    handleComponentUpdate: typeof handleComponentUpdate;
+    createVaporHMRHandler: typeof createVaporHMRHandler;
+    isHMRAvailable: typeof isHMRAvailable;
+    forceRerender: typeof forceRerender;
+    clearHMRState: typeof clearHMRState;
+    onHMRUpdate: typeof onHMRUpdate;
+}>;
+
+/** Vapor 模式 SSR 支持 */
+declare function renderVaporToString(component: unknown, props?: Record<string, unknown>, options?: unknown): Promise<VaporSSRResult>;
+declare function renderVaporToStream(component: unknown, props?: Record<string, unknown>, options?: unknown): Promise<VaporSSRStreamResult>;
+declare function hydrateVaporComponent(container: Element | string, component: unknown, options?: unknown): Promise<void>;
+
+/** Server Components 服务端运行时 */
+declare function getServerComponentFunctions(): Promise<{
+    registerServerComponent: typeof registerServerComponent;
+    registerServerFunction: typeof registerServerFunction;
+    getServerComponent: typeof getServerComponent;
+    getServerFunction: typeof getServerFunction;
+    handleServerAction: typeof handleServerAction;
+    createServerActionHandler: typeof createServerActionHandler;
+    serializeServerData: typeof serializeServerData;
+    deserializeServerData: typeof deserializeServerData;
+    renderServerComponent: typeof renderServerComponent;
+    defineServerComponent: typeof defineServerComponent;
+}>;
+
+/** Server Components 客户端运行时 */
+declare function getServerComponentClientFunctions(): Promise<{
+    callServer: typeof callServer;
+    createServerFunction: typeof createServerFunction;
+    getServerData: typeof getServerData;
+    hasServerData: typeof hasServerData;
+    isHydrated: typeof isHydrated;
+    markHydrated: typeof markHydrated;
+    getHydrationState: typeof getHydrationState;
+    autoHydrate: typeof autoHydrate;
+    configureServerAction: typeof configureServerAction;
+}>;
+/** 数据获取集成 */
+declare function getDataFetchingFunctions(): Promise<{
+    serializeData: typeof serializeData;
+    deserializeData: typeof deserializeData;
+    createPrefetchManager: typeof createPrefetchManager;
+    useFetch: typeof useFetch;
+    useAsyncData: typeof useAsyncData;
+    injectPrefetchData: typeof injectPrefetchData;
+    getPrefetchData: typeof getPrefetchData;
+}>;
+
+export { DEFAULT_STATE_PRESERVATION, type DataFetchOptions, type DataFetchState, type HMRStatePreservation, type HMRUpdate, type HMRUpdateType, type HookHandler, type HydrationError, HydrationErrorHandler, type HydrationMismatch, type HydrationMode, type HydrationOptions, type HydrationStats, type ComponentOptions as IslandComponentOptions, type LifecycleEvent, OptimizedSSRStream, type OptimizedStreamOptions, type RendererPlugin as Plugin, type PluginContext, type PrefetchDataEntry, type PrefetchManager, type PreloadHint, type RecoveryStrategy, type RendererPlugin, type ResourceCleanupRenderer, type SSRStreamOptions, type ServerActionRequest, type ServerActionResponse, type ServerComponentDefinition, type SignalRenderer, type StreamStats, VaporApp, VaporComponentDefinition, type VaporHydrationOptions, type SignalRenderer as VaporRenderer, type VaporSSROptions, type VaporSSRResult, type VaporSSRStreamResult, cleanupComponentResources, createIslandSSRContent, createOptimizedStream, createSignalRenderer, createVaporApp, createVaporRenderer, definePrefetch, defineVaporComponent, executeHooks, getDataFetchingFunctions, getEnhancedHydrationFunctions, getInstalledPlugins, getServerComponentClientFunctions, getServerComponentFunctions, getVaporHMRFunctions, hydrateIsland, hydrateVaporComponent, isPluginInstalled, isVoidElement, registerComponentCleanup, registerComponentEffectSubscription, registerComponentEventListener, registerIslandComponent, removePlugin, renderDocumentToStream, renderToStream, renderToString, renderVaporToStream, renderVaporToString, use, usePrefetchData };