@rtc-agent/component 0.2.7-rc.3 → 0.2.7-rc.4

package/dist/utils/skeleton-tracker.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Skeleton Tracker - 骨架屏生命周期统一管理
+ *
+ * 替代原有分散的状态管理：
+ * - _placeholderItemIds: Set<string>
+ * - _placeholderPositions: Array<{itemId: string; y: number}>
+ * - _placeholderIndexMap: Map<string, number>
+ * - _pendingRestorationIds: Set<string>
+ *
+ * 统一管理骨架屏的创建、追踪、恢复，提供清晰的 API。
+ */
+/**
+ * 骨架屏信息
+ */
+export interface SkeletonInfo {
+    /** 元素 ID */
+    itemId: string;
+    /** 在 _items 中的索引 */
+    index: number;
+    /** 绝对 Y 坐标（相对于滚动内容） */
+    y: number;
+    /** DOM 元素引用 */
+    element: HTMLElement;
+    /** 是否在待恢复队列中 */
+    isPendingRestoration: boolean;
+}
+/**
+ * 骨架屏追踪器
+ *
+ * 职责：
+ * 1. 追踪所有骨架屏的状态（位置、DOM 引用、恢复状态）
+ * 2. 提供高效的查询 API（按范围、按 ID）
+ * 3. 支持批量操作（重建位置、清空）
+ *
+ * 使用方式：
+ * ```typescript
+ * const tracker = new SkeletonTracker();
+ *
+ * // 添加骨架屏
+ * tracker.add(itemId, index, y, element);
+ *
+ * // 查询范围内的骨架屏
+ * const skeletons = tracker.getSkeletonsInRange(top, bottom);
+ *
+ * // 重建所有位置（布局变化后）
+ * tracker.rebuildPositions(scrollContainer, elementMap);
+ *
+ * // 移除已恢复的骨架屏
+ * tracker.remove(itemId);
+ * ```
+ */
+export declare class SkeletonTracker {
+    /** 骨架屏信息映射：itemId → SkeletonInfo */
+    private _skeletons;
+    /**
+     * 添加骨架屏
+     *
+     * @param itemId 元素 ID
+     * @param index 在 _items 中的索引
+     * @param y 绝对 Y 坐标
+     * @param element DOM 元素引用
+     */
+    add(itemId: string, index: number, y: number, element: HTMLElement): void;
+    /**
+     * 移除骨架屏
+     *
+     * @param itemId 元素 ID
+     */
+    remove(itemId: string): void;
+    /**
+     * 获取骨架屏信息
+     *
+     * @param itemId 元素 ID
+     * @returns 骨架屏信息，不存在返回 undefined
+     */
+    get(itemId: string): SkeletonInfo | undefined;
+    /**
+     * 检查是否是骨架屏
+     *
+     * @param itemId 元素 ID
+     * @returns 是否是骨架屏
+     */
+    has(itemId: string): boolean;
+    /**
+     * 获取指定 Y 范围内的骨架屏
+     *
+     * 检查骨架屏的任意部分是否在范围内（顶部、底部或完全包含）。
+     *
+     * @param yMin 范围上界
+     * @param yMax 范围下界
+     * @returns 范围内的骨架屏数组
+     */
+    getInRange(yMin: number, yMax: number): SkeletonInfo[];
+    /**
+     * 标记骨架屏为待恢复状态
+     *
+     * @param itemId 元素 ID
+     */
+    markPending(itemId: string): void;
+    /**
+     * 清除待恢复标记
+     *
+     * @param itemId 元素 ID
+     */
+    clearPending(itemId: string): void;
+    /**
+     * 重建所有骨架屏的 Y 位置
+     *
+     * 当布局发生变化（容器 resize、元素插入等）后调用，
+     * 基于当前 DOM 状态重新计算所有骨架屏的绝对 Y 坐标。
+     *
+     * @param scrollContainer 滚动容器
+     * @param elementMap 索引 → DOM 元素映射
+     */
+    rebuildPositions(scrollContainer: HTMLElement, elementMap: Map<number, HTMLElement>): void;
+    /**
+     * 更新骨架屏的索引
+     *
+     * 当 _items 数组变化（prepend、splice 等）后调用，
+     * 更新所有骨架屏的索引以匹配新的 _items 数组。
+     *
+     * @param indexMap 旧索引 → 新索引映射
+     */
+    updateIndices(indexMap: Map<number, number>): void;
+    /**
+     * 清空所有骨架屏
+     */
+    clear(): void;
+    /**
+     * 获取所有骨架屏
+     *
+     * @returns 所有骨架屏数组
+     */
+    getAll(): SkeletonInfo[];
+    /**
+     * 获取骨架屏数量
+     */
+    get size(): number;
+    /**
+     * 获取待恢复的骨架屏数量
+     */
+    get pendingCount(): number;
+}
+//# sourceMappingURL=skeleton-tracker.d.ts.map

package/dist/utils/skeleton-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skeleton-tracker.d.ts","sourceRoot":"","sources":["../../src/utils/skeleton-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,YAAY;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,eAAe;IACf,OAAO,EAAE,WAAW,CAAC;IACrB,gBAAgB;IAChB,oBAAoB,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,eAAe;IACxB,oCAAoC;IACpC,OAAO,CAAC,UAAU,CAAwC;IAE1D;;;;;;;OAOG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAgBzE;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO5B;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI7C;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE;IAiCtD;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOjC;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOlC;;;;;;;;OAQG;IACH,gBAAgB,CAAC,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI;IAiB1F;;;;;;;OAOG;IACH,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IASlD;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,MAAM,IAAI,YAAY,EAAE;IAIxB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAQzB;CACJ"}

package/dist/utils/visibility-manager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Visibility Manager - 可见性状态机
+ *
+ * 管理虚拟滚动的可见性状态，确保在不可见时暂停操作，
+ * 恢复到可见时同步重建状态。
+ *
+ * 解决的问题：
+ * - Tab 切换（visibility: hidden）时虚拟滚动仍在执行操作
+ * - 浏览器窗口失焦（document.hidden）时的状态不一致
+ * - 从不可见恢复到可见时骨架屏无法恢复
+ */
+/**
+ * 可见性状态
+ */
+export declare enum VisibilityState {
+    /** 可见且活跃 */
+    VISIBLE = "visible",
+    /** 不可见（Tab 切换或窗口失焦） */
+    HIDDEN = "hidden",
+    /** 正在转换（从 hidden 到 visible 的过渡期） */
+    TRANSITIONING = "transitioning"
+}
+/**
+ * 可见性状态变化监听器
+ */
+export type VisibilityChangeListener = (state: VisibilityState) => void;
+/**
+ * 可见性管理器
+ *
+ * 职责：
+ * 1. 维护可见性状态机（VISIBLE ↔ HIDDEN ↔ TRANSITIONING）
+ * 2. 通知监听器状态变化
+ * 3. 提供操作许可检查（shouldPerformOperations）
+ *
+ * 使用方式：
+ * ```typescript
+ * const manager = new VisibilityManager();
+ *
+ * // 监听状态变化
+ * manager.onStateChange(state => {
+ *     console.log('Visibility changed:', state);
+ * });
+ *
+ * // 更新可见性（由外部调用）
+ * manager.update(true);  // 变为可见
+ * manager.update(false); // 变为不可见
+ *
+ * // 检查是否应该执行操作
+ * if (manager.shouldPerformOperations()) {
+ *     // 执行虚拟滚动操作
+ * }
+ * ```
+ */
+export declare class VisibilityManager {
+    private _state;
+    private _listeners;
+    /**
+     * 获取当前状态
+     */
+    get state(): VisibilityState;
+    /**
+     * 更新可见性状态
+     *
+     * 状态转换规则：
+     * - VISIBLE → HIDDEN: 直接转换
+     * - HIDDEN → VISIBLE: 经过 TRANSITIONING 过渡状态
+     * - TRANSITIONING → VISIBLE: 自动转换（在一帧后）
+     *
+     * @param isVisible 是否可见
+     */
+    update(isVisible: boolean): void;
+    /**
+     * 转换到指定状态并通知监听器
+     */
+    private _transitionTo;
+    /**
+     * 注册状态变化监听器
+     *
+     * @param listener 监听器函数
+     * @returns 取消注册的函数
+     */
+    onStateChange(listener: VisibilityChangeListener): () => void;
+    /**
+     * 检查当前是否应该执行虚拟滚动操作
+     *
+     * 只有在 VISIBLE 状态下才允许执行操作（skeletonize、restore 等）。
+     * HIDDEN 和 TRANSITIONING 状态下应该暂停所有操作。
+     *
+     * @returns 是否应该执行操作
+     */
+    shouldPerformOperations(): boolean;
+    /**
+     * 检查当前是否可见
+     *
+     * @returns 是否可见（VISIBLE 或 TRANSITIONING）
+     */
+    isVisible(): boolean;
+    /**
+     * 清空所有监听器（用于 dispose）
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=visibility-manager.d.ts.map

package/dist/utils/visibility-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-manager.d.ts","sourceRoot":"","sources":["../../src/utils/visibility-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,oBAAY,eAAe;IACvB,YAAY;IACZ,OAAO,YAAY;IACnB,uBAAuB;IACvB,MAAM,WAAW;IACjB,oCAAoC;IACpC,aAAa,kBAAkB;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,MAAM,CAA4C;IAC1D,OAAO,CAAC,UAAU,CAA4C;IAE9D;;OAEG;IACH,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAyBhC;;OAEG;IACH,OAAO,CAAC,aAAa;IAoBrB;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI;IAQ7D;;;;;;;OAOG;IACH,uBAAuB,IAAI,OAAO;IAIlC;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAKpB;;OAEG;IACH,OAAO,IAAI,IAAI;CAIlB"}

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+export declare function generateUUID(): string;
+export declare function escapeHtml(text: string): string;
+export declare function formatDate(dateStr: string): string;
+export declare function showToast(message: string, type?: 'info' | 'success' | 'error'): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AASA,wBAAgB,YAAY,IAAI,MAAM,CAWrC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,SAAS,GAAG,OAAgB,GAAG,IAAI,CAY5F"}

package/dist/validation/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 运行时参数校验模块
+ *
+ * 提供统一的参数校验入口，支持 Zod schema 和 OpenAPI Schema
+ * 校验失败返回友好错误，引导 Agent 读取 /functions/INDEX.md
+ */
+import { z, type ZodType } from 'zod';
+import type { ParameterDef } from '../types/skill.js';
+/** 校验错误信息 */
+export interface ValidationError {
+    field: string;
+    message: string;
+    code?: string;
+}
+/** 校验结果 */
+export interface ValidationResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    errors?: ValidationError[];
+}
+/**
+ * 用 Zod schema 校验参数
+ *
+ * @param schema Zod schema
+ * @param params 待校验的参数
+ */
+export declare function validateParams<T extends ZodType>(schema: T, params: Record<string, unknown>): ValidationResult<z.infer<T>>;
+/**
+ * 格式化校验错误为 Agent 友好的消息
+ */
+export declare function formatValidationError(groupName: string, functionName: string, errors: ValidationError[]): string;
+/**
+ * 构建校验器
+ *
+ * 优先使用 zodSchema，否则从 parameters 生成
+ *
+ * @param zodSchema 可选的 Zod schema
+ * @param parameters OpenAPI 格式的参数定义
+ * @returns Zod schema 用于校验
+ */
+export declare function buildValidator(zodSchema: ZodType | undefined, parameters: ParameterDef[] | undefined): ZodType | null;
+/**
+ * 带校验的 handler 包装器
+ *
+ * 用于 FunctionDef.handler 的包装，自动进行参数校验
+ */
+export declare function withValidation<TParams extends ZodType, TResult>(groupName: string, functionName: string, schema: TParams, handler: (params: z.infer<TParams>) => Promise<TResult> | TResult): (params: Record<string, unknown>) => Promise<TResult | {
+    error: string;
+}>;
+export { z } from 'zod';
+export { zodToParams, withMeta } from './zod-to-openapi.js';
+export { openApiToZod } from './openapi-to-zod.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAKtD,aAAa;AACb,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,WAAW;AACX,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;CAC5B;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC9C,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAc9B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,eAAe,EAAE,GACxB,MAAM,CAMR;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,UAAU,EAAE,YAAY,EAAE,GAAG,SAAS,GACrC,OAAO,GAAG,IAAI,CAWhB;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,OAAO,EAAE,OAAO,EAC7D,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GAChE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB3E;AAID,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/validation/openapi-to-zod.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OpenAPI Schema → Zod Schema 转换
+ *
+ * 将 OpenAPI Schema 转换为 Zod schema，用于向后兼容现有 OpenAPI Schema 注册方式
+ */
+import { type ZodType } from 'zod';
+import type { ParameterDef } from '../types/skill.js';
+/**
+ * 从 OpenAPI parameters 生成 ZodObject schema
+ *
+ * @param parameters OpenAPI 格式的参数定义数组
+ * @returns ZodObject schema，可用于运行时校验
+ */
+export declare function openApiToZod(parameters: ParameterDef[]): ZodType;
+//# sourceMappingURL=openapi-to-zod.d.ts.map

package/dist/validation/openapi-to-zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-to-zod.d.ts","sourceRoot":"","sources":["../../src/validation/openapi-to-zod.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAK,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAoBhE"}

package/dist/validation/zod-to-openapi.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Zod Schema → OpenAPI Schema 转换
+ *
+ * 将 Zod schema 转换为 OpenAPI Schema 格式，用于生成 Agent 文档
+ *
+ * 迁移自 peep/src/lib/rtc-agent-validation.ts
+ *
+ * 支持的 Zod 功能：
+ * - .describe() → description（参数描述）
+ * - .optional() → required: false
+ * - .default() → default + required: false
+ * - .min()/.max() → minimum/maximum
+ * - .minLength()/.maxLength() → minLength/maxLength
+ * - .regex() → pattern
+ * - .enum() → enum
+ * - z.array() → array + items
+ *
+ * 扩展功能（通过 meta 方法）：
+ * - .meta({ example: ... }) → example（示例值）
+ */
+import type { ZodType } from 'zod';
+import type { ParameterDef } from '../types/skill.js';
+/**
+ * Zod metadata 扩展接口
+ *
+ * 用于存储示例值等 OpenAPI 特有信息
+ */
+interface ZodMeta {
+    example?: unknown;
+    examples?: unknown[];
+    format?: string;
+}
+/**
+ * 从 Zod schema 生成 OpenAPI parameters
+ *
+ * @param shape ZodObject schema
+ * @param descriptions 可选的参数描述覆盖
+ */
+export declare function zodToParams<T extends ZodType>(shape: T, descriptions?: Record<string, string>): ParameterDef[];
+/**
+ * 为 Zod schema 添加 metadata（示例值等）
+ *
+ * 用法：
+ * ```ts
+ * import { z } from 'zod';
+ * import { withMeta } from '@rtc-agent/component';
+ *
+ * const schema = z.object({
+ *   name: withMeta(z.string(), { example: 'John Doe' }),
+ *   age: withMeta(z.number().int(), { example: 30 }),
+ * });
+ * ```
+ */
+export declare function withMeta<T extends ZodType>(schema: T, meta: ZodMeta): T;
+export {};
+//# sourceMappingURL=zod-to-openapi.d.ts.map

package/dist/validation/zod-to-openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-openapi.d.ts","sourceRoot":"","sources":["../../src/validation/zod-to-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE;;;;GAIG;AACH,UAAU,OAAO;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAC3C,KAAK,EAAE,CAAC,EACR,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,YAAY,EAAE,CAkDhB;AA2KD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC,CAMvE"}

package/dist/worker-bridge.d.ts

@@ -0,0 +1,141 @@
+/**
+ * WorkerBridge — Comlink bridge between the main thread and a SharedWorker.
+ *
+ * Responsibilities:
+ * 1. Create a SharedWorker instance.
+ * 2. Use Comlink.wrap() to obtain a WorkerPersistenceCore proxy.
+ * 3. Register callback: Worker's UIUpdateEvent -> main-thread UIUpdateBus.publish().
+ * 4. Register callback: Worker's token request -> AuthController.getAccessToken() (with dedup).
+ * 5. Register callback: Worker's connection state change -> main-thread listeners.
+ *
+ * Design notes:
+ * - The main thread retains the UIUpdateBus singleton (existing UI code continues to subscribe).
+ * - When the Worker broadcasts events, WorkerBridge re-publishes them on the main-thread UIUpdateBus.
+ * - Only one SharedWorker instance per page (multi-tab sharing managed by the browser).
+ * - Token request dedup: concurrent requests share the same Promise.
+ */
+import { type Remote } from 'comlink';
+import type { PersistenceConfig } from '@rtc-agent/persistence';
+import type { ConnectionState, ConnectionStateEvent } from '@rtc-agent/client';
+import type { WorkerPersistenceCore } from '@rtc-agent/worker';
+import type { AuthController } from './controllers/auth.controller.js';
+export interface WorkerBridgeConfig {
+    /**
+     * Custom SharedWorker URL.
+     *
+     * When not provided, uses Vite's factory function to determine the worker URL.
+     * This is useful when the component is loaded from NPM and the worker file
+     * needs to be served from a different location (e.g., /rtc-agent/shared-worker.js).
+     *
+     * @example
+     * ```ts
+     * new WorkerBridge(authController, {
+     *   workerUrl: '/rtc-agent/shared-worker.js'
+     * });
+     * ```
+     */
+    workerUrl?: string;
+}
+export declare class WorkerBridge {
+    private readonly _auth;
+    private _worker;
+    private _core;
+    private _callbacks;
+    /** Comlink-proxied callbacks (for cross-Worker transfer). */
+    private _proxiedCallbacks;
+    private _initialized;
+    private _config;
+    /** Connection state listeners (main-thread side). */
+    private _connectionListeners;
+    private static readonly MAX_INIT_RETRIES;
+    private static readonly INIT_RETRY_DELAY_MS;
+    /** Timeout for worker liveness verification (ping/pong). */
+    private static readonly VERIFICATION_TIMEOUT_MS;
+    constructor(_auth: AuthController, config?: WorkerBridgeConfig);
+    /**
+     * Asynchronously create a SharedWorker instance.
+     *
+     * Flow:
+     * 1. Extract the worker chunk's relative path from the Vite factory function.
+     * 2. Resolve the absolute CDN URL and fetch the compiled worker script (requires CORS).
+     * 3. Create a same-origin blob: URL via Blob + createObjectURL.
+     * 4. Construct SharedWorker with the blob: URL -> inherits page origin.
+     * 5. Verify the Worker started successfully (via ping test).
+     *
+     * Must be called before init().
+     * Supports retry: on failure, automatically retries up to MAX_INIT_RETRIES times.
+     */
+    initWorker(): Promise<void>;
+    /**
+     * Single Worker initialization attempt.
+     */
+    private _initWorkerOnce;
+    /**
+     * Verify the Worker actually started and can respond.
+     *
+     * Calls a lightweight method (ping) to verify the Worker is alive.
+     * ping() does not require init() and is suitable for startup verification.
+     * If the Worker failed to start or crashed immediately, this call will time out or throw.
+     */
+    private _verifyWorkerAlive;
+    /**
+     * Clean up a failed Worker instance.
+     */
+    private _cleanupFailedWorker;
+    /**
+     * Delay for the specified number of milliseconds.
+     */
+    private _delay;
+    /**
+     * Get the Comlink-proxied WorkerPersistenceCore.
+     *
+     * All method calls are forwarded to the Worker via postMessage.
+     * The returned object has the same interface as WorkerPersistenceCore.
+     *
+     * Must be accessed after initWorker().
+     */
+    get core(): Remote<WorkerPersistenceCore>;
+    /**
+     * Initialize the bridge.
+     *
+     * 1. Call Worker's core.init() to initialize shared state.
+     * 2. Register this tab's callbacks (onUIUpdate + requestToken + onConnectionStateChange).
+     * 3. Open the port to start communication.
+     *
+     * Idempotent: only the first call takes effect.
+     * Must call initWorker() first.
+     */
+    init(config: PersistenceConfig): Promise<void>;
+    /**
+     * Destroy the bridge.
+     *
+     * 1. Unregister callbacks.
+     * 2. Close the port.
+     * 3. Terminate the Worker (note: SharedWorker only terminates after all ports are closed).
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get the current connection state of RTCAgentClient in the Worker.
+     *
+     * Calls the Worker's getConnectionState() via Comlink.
+     */
+    getConnectionState(): Promise<ConnectionState>;
+    /**
+     * Listen for connection state changes.
+     *
+     * Returns an unsubscribe function.
+     */
+    onConnectionStateChange(listener: (event: ConnectionStateEvent) => void): () => void;
+    /**
+     * Replace the main-thread's virtualFS singleton methods with Comlink proxies.
+     *
+     * The main thread cannot directly access IndexedDB.
+     * After replacement, all operations via virtualFS (tool execution, script reading,
+     * function-registry doc writing, scenario-loader, etc.) are automatically routed
+     * to the Worker.
+     *
+     * Note: virtualFS is a module-level singleton; the replacement is global.
+     */
+    installVirtualFSProxy(): void;
+}
+//# sourceMappingURL=worker-bridge.d.ts.map

package/dist/worker-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-bridge.d.ts","sourceRoot":"","sources":["../src/worker-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAc,KAAK,MAAM,EAAC,MAAM,SAAS,CAAC;AAEjD,OAAO,KAAK,EAAC,iBAAiB,EAA4C,MAAM,wBAAwB,CAAC;AACzG,OAAO,KAAK,EAAC,eAAe,EAAE,oBAAoB,EAAC,MAAM,mBAAmB,CAAC;AAE7E,OAAO,KAAK,EAAC,qBAAqB,EAAkB,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,kCAAkC,CAAC;AAmErE,MAAM,WAAW,kBAAkB;IAC/B;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAY;IAkBjB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAjB1B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,UAAU,CAAkB;IACpC,6DAA6D;IAC7D,OAAO,CAAC,iBAAiB,CAAkB;IAC3C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAqB;IAEpC,qDAAqD;IACrD,OAAO,CAAC,oBAAoB,CAAoD;IAEhF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAK;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAQ;IACnD,4DAA4D;IAC5D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;gBAGlC,KAAK,EAAE,cAAc,EACtC,MAAM,GAAE,kBAAuB;IAuDnC;;;;;;;;;;;;OAYG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BjC;;OAEG;YACW,eAAe;IAgG7B;;;;;;OAMG;YACW,kBAAkB;IAkChC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;;;;;;OAOG;IACH,IAAI,IAAI,IAAI,MAAM,CAAC,qBAAqB,CAAC,CAExC;IAED;;;;;;;;;OASG;IACG,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBpD;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB9B;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAIpD;;;;OAIG;IACH,uBAAuB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IASpF;;;;;;;;;OASG;IACH,qBAAqB,IAAI,IAAI;CAyChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtc-agent/component",
-  "version": "0.2.7-rc.3",
+  "version": "0.2.7-rc.4",
   "description": "RTC Agent Web Components（基于 Lit）",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,10 +32,10 @@
     "lit": "^3.1.0",
     "marked": "^18.0.11",
     "zod": "^3.23.8",
-    "@rtc-agent/protocol": "0.2.7-rc.3",
-    "@rtc-agent/client": "0.2.7-rc.3",
-    "@rtc-agent/persistence": "0.2.7-rc.3",
-    "@rtc-agent/worker": "0.2.7-rc.3"
+    "@rtc-agent/client": "0.2.7-rc.4",
+    "@rtc-agent/persistence": "0.2.7-rc.4",
+    "@rtc-agent/protocol": "0.2.7-rc.4",
+    "@rtc-agent/worker": "0.2.7-rc.4"
   },
   "devDependencies": {
     "@lit/localize-tools": "^0.8.2",
@@ -50,7 +50,7 @@
     "vitest": "^2.0.0"
   },
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && tsc --emitDeclarationOnly --declaration --declarationMap",
     "prebuild": "lit-localize build",
     "dev": "vite",
     "predev": "lit-localize build",