crx-rpc 1.0.7 → 2.0.0

package/README.md

@@ -157,21 +157,86 @@ async function calculate() {
 
 ## Architecture
 
-### Hybrid Mode (Both Bridge + Direct)
-```
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Web Page      │    │ Content Script  │    │ Background      │
-│                 │    │ (Bridge+Client) │    │ Script          │
-├─────────────────┤    ├─────────────────┤    ├─────────────────┤
-│ WebRPCClient    │    │   ContentRPC    │    │ BackgroundRPC   │
-│                 │    │      +          │    │                 │
-│ mathService ────┼───▶│ContentRPCClient │◄──▶│ MathService     │
-│ .add(1,2)       │◄───│                 │    │ UserService     │
-│                 │    │ userService     │    │                 │
-│                 │    │ .getUser() ─────┼───▶│                 │
-└─────────────────┘    └─────────────────┘◄───└─────────────────┘
+### Complete Communication Topology
+
+```mermaid
+graph TB
+    subgraph WebPage["Web Page Context"]
+        WC[WebRPCClient]
+        WO[WebObservable]
+    end
+    
+    subgraph ContentScript["Content Script Context"]
+        CR[ContentRPC<br/>Bridge Mode]
+        CC[ContentRPCClient<br/>Direct Mode]
+        CO[ContentObservable]
+    end
+    
+    subgraph Background["Background Script Context"]
+        BR[BackgroundRPC]
+        MS[MathService]
+        US[UserService]
+        RS[RemoteSubject]
+        RSM[RemoteSubjectManager]
+    end
+    
+    subgraph ExtPage["Extension Page Context<br/>(Popup/Options/Sidepanel)"]
+        EC[ExtPageRPCClient]
+        EO[ExtPageObservable]
+    end
+    
+    subgraph TabContext["Tab-specific Access"]
+        TC[TabRPCClient]
+    end
+    
+    %% RPC Calls
+    WC -->|"CustomEvent<br/>.add(1,2)"| CR
+    CR -->|"chrome.runtime<br/>Forward"| BR
+    CC -->|"chrome.runtime<br/>.multiply(2,3)"| BR
+    EC -->|"chrome.runtime<br/>.divide(10,2)"| BR
+    TC -->|"chrome.tabs<br/>Access Content Service"| CC
+    
+    BR -->|Response| CR
+    CR -->|CustomEvent| WC
+    BR -->|Response| CC
+    BR -->|Response| EC
+    
+    BR -.->|Manages| MS
+    BR -.->|Manages| US
+    
+    %% Observable Streams
+    WO -.->|Subscribe| CR
+    CR -.->|Forward| RSM
+    CO -.->|Subscribe| RSM
+    EO -.->|Subscribe| RSM
+    RSM -.->|Broadcast| RS
+    RS -.->|Updates| CR
+    CR -.->|Updates| WO
+    RS -.->|Updates| CO
+    RS -.->|Updates| EO
+    
+    style WC fill:#e1f5ff
+    style CC fill:#e1f5ff
+    style EC fill:#e1f5ff
+    style TC fill:#e1f5ff
+    style BR fill:#fff4e6
+    style MS fill:#f0f0f0
+    style US fill:#f0f0f0
+    style RS fill:#ffe6f0
+    style RSM fill:#ffe6f0
+    style CR fill:#e8f5e9
 ```
 
+### Communication Paths
+
+| Path | Method | Description |
+|------|--------|-------------|
+| **Web Page → Background** | CustomEvent + chrome.runtime | Through ContentRPC bridge |
+| **Content Script → Background** | chrome.runtime | Direct communication |
+| **Extension Page → Background** | chrome.runtime | Direct communication |
+| **Extension Page → Content Script** | chrome.tabs + TabRPCClient | Tab-specific access |
+| **Background → All Contexts** | RemoteSubject broadcast | Real-time data streaming |
+
 ### Key Components
 
 - **WebRPCClient**: Client for web pages using window events
@@ -201,31 +266,12 @@ const rpc = new BackgroundRPC(true); // Enable logging
 
 ### Log Output
 
-When logging is enabled, the following information is logged with **color-coded formatting**:
-
-- **Function Calls**: `[RPC] Call: Service.Method [ID]` with colored components
-- **Success Responses**: `[RPC] Success: Service.Method [ID]` with green success indicator
-- **Error Responses**: `[RPC] Error: Service.Method [ID]` with red error indicator
-- **Unknown Services/Methods**: `[RPC] Unknown service/method: Service.Method [ID]` with orange warnings
-
-### Color Scheme
-
-- 🟣 **Purple**: `[RPC]` prefix and request IDs
-- 🟢 **Green**: Service names and success indicators
-- 🔴 **Red**: Method names and error indicators
-- 🟠 **Orange**: Warning messages
-- ⚫ **Gray**: Separators and structural elements
+When logging is enabled, the following information is logged:
 
-### Example Output
-
-```
-[RPC] Call: MathService.add [rpc-123]
-[RPC] Success: MathService.add [rpc-123]
-[RPC] Error: MathService.divide [rpc-124]
-[RPC] Unknown service: InvalidService [rpc-125]
-```
-
-*Note: Colors are visible in browser developer console, not in plain text.*
+- **Function Calls**: Service name, method name, arguments, sender ID, and timestamp
+- **Success Responses**: Service name, method name, result, and timestamp  
+- **Error Responses**: Service name, method name, error message, and timestamp
+- **Unknown Services/Methods**: Warnings for invalid service or method calls
 
 ### Use Cases
 
@@ -361,6 +407,34 @@ const observable = new ContentObservable(
 // observable.dispose();
 ```
 
+### Subscribing from Extension Page
+
+```typescript
+// popup.ts / options.ts
+import { ExtPageObservable, createIdentifier } from 'crx-rpc';
+
+interface ICounterObservable {
+    value: number;
+}
+
+const ICounterObservable = createIdentifier<ICounterObservable>('Counter');
+
+// Extension page can subscribe to background observables
+const observable = new ExtPageObservable(
+    ICounterObservable,
+    'main',
+    (value) => {
+        console.log('Counter from extension page:', value.value);
+        document.getElementById('counter').textContent = value.value.toString();
+    }
+);
+
+// Cleanup when done
+window.addEventListener('unload', () => {
+    observable.dispose();
+});
+```
+
 ### Observable Communication Patterns
 
 The Observable system supports multiple communication patterns with centralized management:
@@ -413,6 +487,94 @@ if (!client.isDisposed()) {
 }
 ```
 
+### Extension Page Accessing Content Script Services
+
+Extension pages can access content script services using `TabRPCClient` by specifying the target tab ID:
+
+```typescript
+// popup.ts
+import { TabRPCClient } from 'crx-rpc';
+import { IContentService } from './services';
+
+// Get current active tab
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+
+if (tab.id) {
+    // Create RPC client for specific tab
+    const tabClient = new TabRPCClient(tab.id);
+    
+    // Access content script services in that tab
+    const contentService = tabClient.createWebRPCService(IContentService);
+    
+    // Call content script methods
+    const result = await contentService.getDOMInfo();
+    console.log('DOM info from content script:', result);
+    
+    // Cleanup when done
+    window.addEventListener('unload', () => {
+        tabClient.dispose();
+    });
+}
+```
+
+#### Use Cases for Extension Page → Content Script Communication:
+
+1. **DOM Inspection**: Popup queries content script for page information
+2. **User Actions**: Options page triggers content script actions on specific tabs
+3. **Multi-tab Management**: Sidepanel coordinates actions across multiple tabs
+4. **Live Preview**: Extension page gets real-time updates from content script
+
+#### Complete Example: Popup with Tab-specific Services
+
+```typescript
+// content.ts - Register services in content script
+import { ContentRPCHost } from 'crx-rpc';
+import { IPageService } from './services';
+
+class PageService implements IPageService {
+    async getTitle(): Promise<string> {
+        return document.title;
+    }
+    
+    async getSelection(): Promise<string> {
+        return window.getSelection()?.toString() || '';
+    }
+    
+    async highlightText(text: string): Promise<void> {
+        // Highlight logic...
+    }
+}
+
+const contentHost = new ContentRPCHost();
+contentHost.register(IPageService, new PageService());
+
+// popup.ts - Access content script from popup
+import { TabRPCClient, ExtPageRPCClient } from 'crx-rpc';
+import { IPageService, IMathService } from './services';
+
+// Access background services
+const bgClient = new ExtPageRPCClient();
+const mathService = bgClient.createWebRPCService(IMathService);
+
+// Access content script services in active tab
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+if (tab.id) {
+    const tabClient = new TabRPCClient(tab.id);
+    const pageService = tabClient.createWebRPCService(IPageService);
+    
+    // Get page info from content script
+    const title = await pageService.getTitle();
+    const selection = await pageService.getSelection();
+    
+    // Process with background service
+    const result = await mathService.calculate(selection.length);
+    
+    // Update popup UI
+    document.getElementById('title').textContent = title;
+    document.getElementById('result').textContent = result.toString();
+}
+```
+
 ## Usage Scenarios
 
 ### Scenario 1: Web Page Only

package/README.zh-CN.md

@@ -155,25 +155,118 @@ async function calculate() {
 }
 ```
 
+### 5. 使用客户端(扩展页面)
+
+```typescript
+// popup.ts / options.ts / sidepanel.ts
+import { ExtPageRPCClient } from 'crx-rpc';
+import { IMathService } from './services/math';
+
+async function calculate() {
+    // 创建扩展页面RPC客户端
+    const client = new ExtPageRPCClient();
+
+    // 创建类型安全的服务代理
+    const mathService = client.createWebRPCService(IMathService);
+
+    // 直接调用background服务
+    const sum = await mathService.add(1, 2);
+    const difference = await mathService.subtract(10, 5);
+    const product = await mathService.multiply(3, 4);
+    const quotient = await mathService.divide(15, 3);
+
+    console.log('结果:', { sum, difference, product, quotient });
+
+    // 页面关闭时自动清理
+    window.addEventListener('unload', () => {
+        client.dispose();
+    });
+}
+```
+
 ## 架构
 
+### 完整通信拓扑图
+
+```mermaid
+graph TB
+    subgraph WebPage["网页上下文"]
+        WC[WebRPCClient]
+        WO[WebObservable]
+    end
+    
+    subgraph ContentScript["内容脚本上下文"]
+        CR[ContentRPC<br/>桥接模式]
+        CC[ContentRPCClient<br/>直接模式]
+        CO[ContentObservable]
+    end
+    
+    subgraph Background["背景脚本上下文"]
+        BR[BackgroundRPC]
+        MS[MathService]
+        US[UserService]
+        RS[RemoteSubject]
+        RSM[RemoteSubjectManager]
+    end
+    
+    subgraph ExtPage["扩展页面上下文<br/>(Popup/Options/Sidepanel)"]
+        EC[ExtPageRPCClient]
+        EO[ExtPageObservable]
+    end
+    
+    subgraph TabContext["标签页特定访问"]
+        TC[TabRPCClient]
+    end
+    
+    %% RPC 调用
+    WC -->|"CustomEvent<br/>.add(1,2)"| CR
+    CR -->|"chrome.runtime<br/>转发"| BR
+    CC -->|"chrome.runtime<br/>.multiply(2,3)"| BR
+    EC -->|"chrome.runtime<br/>.divide(10,2)"| BR
+    TC -->|"chrome.tabs<br/>访问内容服务"| CC
+    
+    BR -->|响应| CR
+    CR -->|CustomEvent| WC
+    BR -->|响应| CC
+    BR -->|响应| EC
+    
+    BR -.->|管理| MS
+    BR -.->|管理| US
+    
+    %% Observable 数据流
+    WO -.->|订阅| CR
+    CR -.->|转发| RSM
+    CO -.->|订阅| RSM
+    EO -.->|订阅| RSM
+    RSM -.->|广播| RS
+    RS -.->|更新| CR
+    CR -.->|更新| WO
+    RS -.->|更新| CO
+    RS -.->|更新| EO
+    
+    style WC fill:#e1f5ff
+    style CC fill:#e1f5ff
+    style EC fill:#e1f5ff
+    style TC fill:#e1f5ff
+    style BR fill:#fff4e6
+    style MS fill:#f0f0f0
+    style US fill:#f0f0f0
+    style RS fill:#ffe6f0
+    style RSM fill:#ffe6f0
+    style CR fill:#e8f5e9
 ```
-网页               内容脚本            背景脚本
-┌─────────────┐   ┌─────────────────┐   ┌─────────────────┐
-│ WebRPCClient│──▶│   ContentRPC    │──▶│  BackgroundRPC  │
-│             │   │   (桥接器)      │   │                 │
-│ 代理        │   │                 │   │ 服务            │
-│ 服务        │   │ MessageAdapter  │   │ 注册表          │
-│ .add(1, 2)  │   │                 │   │                 │
-└─────────────┘   └─────────────────┘   └─────────────────┘
-        │                  │                       ▲
-        │  CustomEvent     │  chrome.runtime      │
-        │                  │  Messages            │
-        └──────────────────┴──────────────────────┘
-                           │
-                    ┌─────────────────┐
-                    │ContentRPCClient │
-                    │   (直接)        │
+
+### 通信路径
+
+| 路径 | 方式 | 描述 |
+|------|------|------|
+| **网页 → 背景脚本** | CustomEvent + chrome.runtime | 通过 ContentRPC 桥接 |
+| **内容脚本 → 背景脚本** | chrome.runtime | 直接通信 |
+| **扩展页面 → 背景脚本** | chrome.runtime | 直接通信 |
+| **扩展页面 → 内容脚本** | chrome.tabs + TabRPCClient | 标签页特定访问 |
+| **背景脚本 → 所有上下文** | RemoteSubject 广播 | 实时数据流 |
+
+### 核心组件
                     │                 │
                     │ 代理服务        │
                     │ .subtract(5,2)  │
@@ -187,12 +280,14 @@ async function calculate() {
 3. **背景脚本 → 内容脚本**: 使用 `chrome.tabs.sendMessage`
 4. **内容脚本 → 网页**: 使用 `window.dispatchEvent` 和 `CustomEvent`
 5. **内容脚本直接**: 直接使用 `chrome.runtime.sendMessage` (ContentRPCClient)
+6. **扩展页面 ↔ 背景脚本**: 直接使用 `chrome.runtime.sendMessage/onMessage` (ExtPageRPCClient)
 
 ### 核心组件
 
-- **WebRPCClient**: 用于网页的客户端，使用window事件
+- **WebRPCClient**: 用于网页的客户端,使用window事件
 - **ContentRPC**: 在网页和背景脚本间转发消息的桥接器
-- **ContentRPCClient**: 内容脚本的直接RPC客户端（绕过桥接器）
+- **ContentRPCClient**: 内容脚本的直接RPC客户端(绕过桥接器)
+- **ExtPageRPCClient**: 用于扩展页面(popup/options/sidepanel)的直接RPC客户端
 - **BackgroundRPC**: 背景脚本中的服务注册表和处理器
 - **RPCClient**: 具有服务代理生成功能的基础客户端
 
@@ -217,31 +312,12 @@ const rpc = new BackgroundRPC(true); // 启用日志
 
 ### 日志输出
 
-启用日志时，会记录以下信息并使用**彩色格式**：
-
-- **函数调用**: `[RPC] Call: Service.Method [ID]` 带有彩色组件
-- **成功响应**: `[RPC] Success: Service.Method [ID]` 带有绿色成功指示器
-- **错误响应**: `[RPC] Error: Service.Method [ID]` 带有红色错误指示器
-- **未知服务/方法**: `[RPC] Unknown service/method: Service.Method [ID]` 带有橙色警告
-
-### 颜色方案
-
-- 🟣 **紫色**: `[RPC]` 前缀和请求ID
-- 🟢 **绿色**: 服务名和成功指示器
-- 🔴 **红色**: 方法名和错误指示器
-- 🟠 **橙色**: 警告消息
-- ⚫ **灰色**: 分隔符和结构元素
+启用日志时，会记录以下信息：
 
-### 输出示例
-
-```
-[RPC] Call: MathService.add [rpc-123]
-[RPC] Success: MathService.add [rpc-123]
-[RPC] Error: MathService.divide [rpc-124]
-[RPC] Unknown service: InvalidService [rpc-125]
-```
-
-*注意：颜色在浏览器开发者控制台中可见，不在纯文本中显示。*
+- **函数调用**: 服务名、方法名、参数、发送者ID和时间戳
+- **成功响应**: 服务名、方法名、结果和时间戳  
+- **错误响应**: 服务名、方法名、错误消息和时间戳
+- **未知服务/方法**: 无效服务或方法调用的警告
 
 ### 使用场景
 
@@ -377,6 +453,35 @@ const observable = new ContentObservable(
 // observable.dispose();
 ```
 
+### 从扩展页面订阅
+
+```typescript
+// popup.ts / options.ts / sidepanel.ts
+import { ExtPageObservable, createIdentifier } from 'crx-rpc';
+
+interface ICounterObservable {
+    value: number;
+}
+
+const ICounterObservable = createIdentifier<ICounterObservable>('Counter');
+
+// 扩展页面可以订阅background的observables
+const observable = new ExtPageObservable(
+    ICounterObservable,
+    'main',
+    (value) => {
+        console.log('Popup计数器更新:', value.value);
+        // 更新popup UI
+        document.getElementById('counter').textContent = value.value.toString();
+    }
+);
+
+// 页面关闭时自动清理
+window.addEventListener('unload', () => {
+    observable.dispose();
+});
+```
+
 ### Observable通信模式
 
 Observable系统支持多种具有集中式管理的通信模式：
@@ -477,6 +582,150 @@ document.addEventListener('DOMContentLoaded', async () => {
 4. **桥接+客户端**: 既作为网页的桥接器又作为直接客户端
 5. **DOM操作**: 使用RPC数据修改页面内容
 
+### 扩展页面作为直接客户端
+
+扩展页面(popup、options、sidepanel等)可以直接与background通信,无需content script:
+
+```typescript
+// popup.ts
+import { ExtPageRPCClient, ExtPageObservable } from 'crx-rpc';
+import { IMathService, IUserService, ICounterObservable } from './services';
+
+const client = new ExtPageRPCClient();
+
+// 创建服务代理
+const mathService = client.createWebRPCService(IMathService);
+const userService = client.createWebRPCService(IUserService);
+
+// 直接调用背景服务
+const result = await mathService.add(5, 3);
+const user = await userService.getUser('123');
+
+// 扩展页面也可以订阅observables
+const counterObservable = new ExtPageObservable(
+    ICounterObservable,
+    'main',
+    (value) => {
+        // 实时更新popup UI
+        document.getElementById('counter').textContent = value.toString();
+    }
+);
+
+// 在popup中使用
+document.addEventListener('DOMContentLoaded', async () => {
+    const calculation = await mathService.multiply(2, 3);
+    document.getElementById('result').textContent = `结果: ${calculation}`;
+    
+    // 更新用户信息
+    const currentUser = await userService.getUser('me');
+    document.getElementById('username').textContent = currentUser.name;
+});
+
+// 页面关闭时清理
+window.addEventListener('unload', () => {
+    client.dispose();
+    counterObservable.dispose();
+});
+```
+
+### 扩展页面使用场景
+
+扩展页面在各种场景中使用RPC:
+
+1. **直接通信**: 与background service直接通信,无需content script
+2. **UI交互**: 根据background数据更新popup/options界面
+3. **实时更新**: 订阅observables获取实时数据推送
+4. **用户设置**: 在options页面中读取/保存配置
+5. **状态同步**: 与background保持状态同步
+
+### 扩展页面访问内容脚本服务
+
+扩展页面可以使用 `TabRPCClient` 通过指定 tab ID 来访问内容脚本的服务:
+
+```typescript
+// popup.ts
+import { TabRPCClient } from 'crx-rpc';
+import { IContentService } from './services';
+
+// 获取当前活动标签页
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+
+if (tab.id) {
+    // 为特定 tab 创建 RPC 客户端
+    const tabClient = new TabRPCClient(tab.id);
+    
+    // 访问该 tab 中的内容脚本服务
+    const contentService = tabClient.createWebRPCService(IContentService);
+    
+    // 调用内容脚本方法
+    const result = await contentService.getDOMInfo();
+    console.log('来自内容脚本的 DOM 信息:', result);
+    
+    // 完成时清理
+    window.addEventListener('unload', () => {
+        tabClient.dispose();
+    });
+}
+```
+
+#### 扩展页面 → 内容脚本通信的使用场景:
+
+1. **DOM 检查**: Popup 查询内容脚本获取页面信息
+2. **用户操作**: Options 页面触发特定标签页的内容脚本操作
+3. **多标签管理**: Sidepanel 协调多个标签页的操作
+4. **实时预览**: 扩展页面从内容脚本获取实时更新
+
+#### 完整示例: Popup 与标签页特定服务交互
+
+```typescript
+// content.ts - 在内容脚本中注册服务
+import { ContentRPCHost } from 'crx-rpc';
+import { IPageService } from './services';
+
+class PageService implements IPageService {
+    async getTitle(): Promise<string> {
+        return document.title;
+    }
+    
+    async getSelection(): Promise<string> {
+        return window.getSelection()?.toString() || '';
+    }
+    
+    async highlightText(text: string): Promise<void> {
+        // 高亮逻辑...
+    }
+}
+
+const contentHost = new ContentRPCHost();
+contentHost.register(IPageService, new PageService());
+
+// popup.ts - 从 popup 访问内容脚本
+import { TabRPCClient, ExtPageRPCClient } from 'crx-rpc';
+import { IPageService, IMathService } from './services';
+
+// 访问背景服务
+const bgClient = new ExtPageRPCClient();
+const mathService = bgClient.createWebRPCService(IMathService);
+
+// 访问活动标签页中的内容脚本服务
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+if (tab.id) {
+    const tabClient = new TabRPCClient(tab.id);
+    const pageService = tabClient.createWebRPCService(IPageService);
+    
+    // 从内容脚本获取页面信息
+    const title = await pageService.getTitle();
+    const selection = await pageService.getSelection();
+    
+    // 使用背景服务处理
+    const result = await mathService.calculate(selection.length);
+    
+    // 更新 popup UI
+    document.getElementById('title').textContent = title;
+    document.getElementById('result').textContent = result.toString();
+}
+```
+
 ### 复杂数据类型
 
 ```typescript
@@ -537,15 +786,20 @@ const [sum, user, file] = await Promise.all([
 
 ### 场景2: 仅内容脚本  
 - 内容脚本需要直接访问背景服务
-- 使用: 直接使用 `ContentRPCClient`（无需桥接器）
+- 使用: 直接使用 `ContentRPCClient`(无需桥接器)
 
 ### 场景3: 网页和内容脚本同时
 - 两个上下文都需要RPC访问
 - 使用: `ContentRPC` 桥接器 + `ContentRPCClient` 进行直接访问
 
-### 场景4: 实时数据流
+### 场景4: 扩展页面(Popup/Options/Sidepanel)
+- 扩展内置页面需要访问背景服务
+- 使用: 直接使用 `ExtPageRPCClient`
+- 特点: 不需要content script,直接与background通信
+
+### 场景5: 实时数据流
 - 背景脚本需要向多个上下文推送更新
-- 使用: `RemoteSubject` + `WebObservable`/`ContentObservable`
+- 使用: `RemoteSubject` + `WebObservable`/`ContentObservable`/`ExtPageObservable`
 
 ## API参考
 
@@ -555,6 +809,7 @@ const [sum, user, file] = await Promise.all([
 - **`ContentRPC`**: 网页和背景脚本间的消息桥接器
 - **`WebRPCClient`**: 网页的RPC客户端
 - **`ContentRPCClient`**: 内容脚本的直接RPC客户端
+- **`ExtPageRPCClient`**: 扩展页面(popup/options/sidepanel)的直接RPC客户端
 - **`RemoteSubjectManager`**: 集中式observable消息管理系统
 
 ### Observable类
@@ -563,6 +818,7 @@ const [sum, user, file] = await Promise.all([
 - **`RemoteSubject<T>`**: 与管理器配合进行纯状态管理的Observable subject
 - **`WebObservable<T>`**: 网页的Observable订阅者
 - **`ContentObservable<T>`**: 内容脚本的Observable订阅者
+- **`ExtPageObservable<T>`**: 扩展页面的Observable订阅者
 
 ### 工具函数