npm package: @kg-ui/widget-runtime
Description: 智星 Widget 运行时 - iframe 沙盒和生命周期管理
Latest version: 1.0.0

# @zhixing/widget-runtime

智星运行时 Widget 管理包 - 提供安全的 iframe 沙盒和生命周期管理功能。

## 📋 功能特性

- **安全沙盒**: 基于 iframe 的安全执行环境
- **生命周期管理**: 完整的 Widget 生命周期控制
- **Bridge 通信**: 安全的父子窗口通信机制
- **状态管理**: 双向状态同步和更新
- **错误处理**: 完善的错误恢复机制
- **资源管理**: 自动资源清理和内存管理

## 🏗️ 核心组件

### Runtime 运行时
- `mount.ts` - Widget 挂载和实例管理
- `lifecycle.ts` - 生命周期事件处理
- `createIframe.ts` - 安全 iframe 创建

### Bridge 通信桥接
- `openaiBridge.ts` - 父子窗口通信核心
- 详细架构说明: [OpenAI Bridge 架构详解](../../docs/openai-bridge-architecture.md)

### Security 安全机制
- `networkControl.ts` - 网络访问控制
- `storageIsolation.ts` - 存储沙盒隔离
- `threatDetection.ts` - 安全威胁检测

### Types 类型定义
- `widget.ts` - Widget 相关类型定义

### Errors 错误处理
- `LifecycleError.ts` - 生命周期相关错误
- `SecurityError.ts` - 安全相关错误

## 🚀 快速开始

### 安装
```bash
pnpm add @zhixing/widget-runtime
```

### 基本使用
```typescript
import { DefaultMountManager } from '@zhixing/widget-runtime';

// 创建挂载管理器
const mountManager = new DefaultMountManager();

// 挂载 Widget
const widgetInstance = await mountManager.mount(container, {
  srcdoc: '<html>...</html>',
  initialState: { initialized: true },
  toolOutput: {
    structuredContent: { /* ... */ },
    metadata: { timestamp: Date.now() }
  }
});

// 更新 Widget
await mountManager.updateWidget(widgetInstance, {
  widgetState: { currentPage: 2 }
});

// 卸载 Widget
await mountManager.unmount(widgetInstance);
```

## 📡 Bridge 通信机制

Widget 运行时使用 OpenAI Bridge 实现安全的父子窗口通信：

### Widget 内部 API
```javascript
// 访问工具输出数据
const data = window.openai.toolOutput.structuredContent;

// 更新 Widget 状态
window.openai.setWidgetState({
  currentPage: 2,
  selectedItems: ['item1', 'item2']
});

// 监听 Bridge 就绪事件
window.addEventListener('openai-bridge-ready', (event) => {
  console.log('Bridge 已就绪:', event.detail.openai);
  initializeWidget();
});
```

### 父窗口管理
```typescript
import { DefaultBridgeManager } from '@zhixing/widget-runtime';

const bridgeManager = new DefaultBridgeManager();

// 注入 Bridge 到 iframe
await bridgeManager.injectBridge(
  iframe, 
  toolOutput, 
  (patch) => {
    // 处理状态更新
    console.log('Widget 状态更新:', patch);
  }
);
```

## 🛡️ 安全特性

### 沙盒隔离
- iframe sandbox 属性限制
- CSP (Content Security Policy) 保护
- 网络访问控制
- 存储隔离机制

### 数据保护
- 深度只读代理保护传入数据
- 状态更新验证和过滤
- 函数注入防护
- 消息来源严格验证

### 错误恢复
- 超时机制 (15秒)
- 自动重试和降级
- 资源清理和内存管理
- 详细错误日志

## 🔄 生命周期管理

Widget 支持完整的生命周期事件：

```typescript
// 生命周期事件
await lifecycleManager.onInit(widget);    // 初始化
await lifecycleManager.onRender(widget);  // 渲染
await lifecycleManager.onUpdate(widget, updates); // 更新
await lifecycleManager.onDestroy(widget); // 销毁
```

### 生命周期状态
- `CREATED` - 已创建
- `INITIALIZING` - 初始化中
- `INITIALIZED` - 已初始化
- `RENDERING` - 渲染中
- `RENDERED` - 已渲染
- `UPDATING` - 更新中
- `DESTROYING` - 销毁中
- `DESTROYED` - 已销毁

## 📊 实例管理

### 创建和管理实例
```typescript
// 获取活跃实例
const activeInstances = mountManager.getActiveInstances();

// 获取特定实例
const instance = mountManager.getInstance('widget-id');

// 检查实例隔离状态
const isIsolated = mountManager.isInstanceIsolated('widget-id');

// 清理所有实例
await mountManager.cleanup_all();
```

### 实例操作
```typescript
// Widget 实例方法
await widgetInstance.update({
  widgetState: { newData: 'value' }
});

await widgetInstance.destroy();

const currentState = widgetInstance.getState();
```

## 🔧 配置选项

### Widget 配置
```typescript
interface WidgetConfig {
  src?: string;           // iframe src URL
  srcdoc?: string;        // iframe srcdoc 内容
  initialState?: any;     // 初始状态
  toolOutput?: WidgetInput; // 工具输出数据
}
```

### iframe 配置
```typescript
interface IframeConfig {
  sandbox: string[];      // 沙盒权限
  csp: string;           // 内容安全策略
  src?: string;          // 源 URL
  srcdoc?: string;       // 内联内容
}
```

## 📝 开发指南

### 创建自定义 Widget
1. 实现 Widget HTML 内容
2. 添加 Bridge 通信逻辑
3. 处理生命周期事件
4. 实现状态管理

### 调试技巧
- 启用详细日志记录
- 使用浏览器开发者工具
- 检查 iframe 沙盒设置
- 监控消息传递过程

### 性能优化
- 合理设置超时时间
- 及时清理不需要的资源
- 使用高效的状态更新策略
- 避免频繁的 DOM 操作

## 🧪 测试

```bash
# 运行单元测试
pnpm test

# 运行监听模式测试
pnpm test --watch

# 生成覆盖率报告
pnpm test --coverage
```

## 📚 相关文档

- [OpenAI Bridge 架构详解](../../docs/openai-bridge-architecture.md)
- [Widget 开发指南](../../docs/widget-development-guide.md)
- [安全最佳实践](../../docs/security-best-practices.md)
- [故障排除指南](../../docs/troubleshooting-guide.md)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个包。

## 📄 许可证

MIT License