request-iframe 0.1.0 → 0.2.0

package/QUICKSTART.CN.md

@@ -220,9 +220,11 @@ server.on('/api/users/:id', (req, res) => {
 开启 trace 模式查看详细日志：
 
 ```typescript
+import { LogLevel } from 'request-iframe';
+
 const client = requestIframeClient(iframe, { 
   secretKey: 'my-app',
-  trace: true  // 开启调试日志
+  trace: LogLevel.INFO  // 输出 info/warn/error（也可以用 true 开启 TRACE）
 });
 
 const server = requestIframeServer({ 
@@ -293,4 +295,4 @@ console.log(response.data.name); // TypeScript 知道这是 string
 
 - 查看 [README.CN.md](./README.CN.md) 了解完整 API（中文）
 - 查看 [README.md](./README.md) 了解完整 API（English）
-- 查看 [src/__tests__](./src/__tests__) 目录下的测试用例获取更多示例
+- 查看 [`__tests__/`](./__tests__) 与 [`react/__tests__/`](./react/__tests__) 下的测试用例获取更多示例

package/QUICKSTART.md

@@ -220,9 +220,11 @@ server.on('/api/users/:id', (req, res) => {
 Enable trace mode to view detailed logs:
 
 ```typescript
+import { LogLevel } from 'request-iframe';
+
 const client = requestIframeClient(iframe, { 
   secretKey: 'my-app',
-  trace: true  // Enable debug logs
+  trace: LogLevel.INFO  // Enable info/warn/error logs (or use true for TRACE)
 });
 
 const server = requestIframeServer({ 
@@ -293,4 +295,4 @@ console.log(response.data.name); // TypeScript knows this is string
 
 - View [README.md](./README.md) for complete API documentation (English)
 - View [README.CN.md](./README.CN.md) for complete API documentation (中文)
-- Check [src/__tests__](./src/__tests__) directory for more examples from test cases
+- Check [`__tests__/`](./__tests__) and [`react/__tests__/`](./react/__tests__) for more examples from test cases

package/README.CN.md

@@ -1,6 +1,6 @@
 # request-iframe
 
-像发送 HTTP 请求一样与 iframe 通信！基于 `postMessage` 实现的 iframe 跨域通信库。
+像发送 HTTP 请求一样与 iframe / Window 通信！基于 `postMessage` 实现的浏览器跨页面通信库。
 
 > 🌐 **Languages**: [English](./README.md) | [中文](./README.CN.md)
 
@@ -8,7 +8,7 @@
   <img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript Ready">
   <img src="https://img.shields.io/badge/API-Express%20Like-green" alt="Express Like API">
   <img src="https://img.shields.io/badge/License-MIT-yellow" alt="MIT License">
-  <img src="https://img.shields.io/badge/Test%20Coverage-76%25-brightgreen" alt="Test Coverage">
+  <img src="https://coveralls.io/repos/github/gxlmyacc/request-iframe/badge.svg?branch=main" alt="Coverage Status">
 </p>
 
 ## 📑 目录
@@ -48,7 +48,7 @@
 
 ## 为什么选择 request-iframe？
 
-在微前端、iframe 嵌套等场景下，父子页面通信是常见需求。传统的 `postMessage` 通信存在以下痛点：
+在微前端、iframe 嵌套、弹窗（window.open）等场景下，跨页面通信是常见需求。传统的 `postMessage` 通信存在以下痛点：
 
 | 痛点 | 传统方式 | request-iframe |
 |------|----------|----------------|
@@ -74,8 +74,9 @@
 - ⏱️ **智能超时** - 三阶段超时（连接/同步/异步），自动识别长任务
 - 📦 **TypeScript** - 完整的类型定义和智能提示
 - 🔒 **消息隔离** - secretKey 机制避免多实例消息串线
-- 📁 **文件传输** - 支持文件通过流方式传输（Client→Server）
+- 📁 **文件传输** - 支持文件通过流方式传输（Client↔Server）
 - 🌊 **流式传输** - 支持大文件分块传输，支持异步迭代器
+- 🧾 **分级日志** - 默认只输出 warn/error，可通过 `trace` 设置日志等级与调试日志
 - 🌍 **多语言** - 错误消息可自定义，便于国际化
 - ✅ **协议版本** - 内置版本控制，便于升级兼容
 
@@ -93,6 +94,32 @@ pnpm add request-iframe
 
 **TypeScript**: 内置完整类型定义，无需安装 `@types/request-iframe`
 
+## CDN（UMD bundle）
+
+本项目也支持构建 **可直接用 `<script>` 引入的 UMD bundle**（核心 + React hooks），方便放到 CDN 上。
+
+- 核心 bundle 输出：`cdn/request-iframe.umd(.min).js` → 全局变量 `RequestIframe`
+- React bundle 输出：`cdn/request-iframe-react.umd(.min).js` → 全局变量 `RequestIframeReact`
+  - 依赖 `React` 全局变量（即 `react` 的 UMD 版本）
+  - 依赖 `RequestIframe` 全局变量（先加载核心 bundle）
+
+示例（使用 unpkg）：
+
+```html
+<!-- 核心 -->
+<script src="https://unpkg.com/request-iframe@latest/cdn/request-iframe.umd.min.js"></script>
+
+<!-- React（可选） -->
+<script src="https://unpkg.com/react@latest/umd/react.production.min.js"></script>
+<script src="https://unpkg.com/request-iframe@latest/cdn/request-iframe-react.umd.min.js"></script>
+
+<script>
+  const { requestIframeClient, requestIframeServer, requestIframeEndpoint } = RequestIframe;
+  // React hooks 在 RequestIframeReact 上（例如 RequestIframeReact.useClient）
+  console.log(!!requestIframeClient, !!requestIframeServer, !!requestIframeEndpoint);
+<\/script>
+```
+
 ## 快速开始
 
 ### 1. 父页面（Client 端）
@@ -130,6 +157,11 @@ server.on('/api/getUserInfo', (req, res) => {
 
 > 💡 **提示**: 更多快速上手指南请查看 [QUICKSTART.CN.md](./QUICKSTART.CN.md) 或 [QUICKSTART.md](./QUICKSTART.md) (English)
 
+## 该用哪个 API？
+
+- **优先使用 `requestIframeClient()` + `requestIframeServer()`**：适用于主要是单向通信（父页 → iframe），并且你希望把“发送请求”和“处理请求”职责明确分开。
+- **优先使用 `requestIframeEndpoint()`**：适用于需要 **双向通信**（双方都需要 `send()` + `on()/use()/map()`），或者你希望用一个门面对象更方便地串起全链路做调试。
+
 ---
 
 ## 实现原理
@@ -151,7 +183,7 @@ request-iframe 在 `postMessage` 基础上实现了一套类 HTTP 的通信协
        │                                            │
        │  <──── RESPONSE ────────────────────────  │  返回结果
        │                                            │
-       │  ──── RECEIVED (可选) ──────────────────>  │  确认收到响应
+       │  ──── ACK (可选) ───────────────────────>  │  确认收到响应
        │                                            │
 ```
 
@@ -160,11 +192,10 @@ request-iframe 在 `postMessage` 基础上实现了一套类 HTTP 的通信协
 | 类型 | 方向 | 说明 |
 |------|------|------|
 | `request` | Client → Server | 客户端发起请求 |
-| `ack` | Server → Client | 服务端确认收到请求（当请求 `requireAck` 开启时） |
+| `ack` | 接收方 → 发送方 | 回执确认（当消息 `requireAck: true` 且被接管/处理时发送；ACK-only） |
 | `async` | Server → Client | 通知客户端这是异步任务（handler 返回 Promise 时发送） |
 | `response` | Server → Client | 返回响应数据 |
 | `error` | Server → Client | 返回错误信息 |
-| `received` | Client → Server | 客户端确认收到响应/错误（可选，由响应的 `requireAck` 控制） |
 | `ping` | Client → Server | 连接检测（`isConnect()`；可使用 `requireAck` 确认投递） |
 | `pong` | Server → Client | 连接检测响应 |
 
@@ -286,6 +317,29 @@ server.on('/event', (req, res) => {
 });
 ```
 
+### 弹窗 / 新标签页（Window 通信）
+
+`request-iframe` 不仅可以与 iframe 通信，也可以把 `target` 直接传 `Window`（例如弹窗/新标签页）。
+
+**重要前提**：你必须拿到对方页面的 `Window` 引用（例如 `window.open()` 的返回值，或通过 `window.opener` / `MessageEvent.source` 获取）。**无法**通过 URL 给“任意标签页”发消息。
+
+```typescript
+// 父页面：打开新标签页/弹窗
+const child = window.open('https://child.example.com/page.html', '_blank');
+if (!child) throw new Error('弹窗被拦截');
+
+// 父 -> 子
+const client = requestIframeClient(child, {
+  secretKey: 'popup-demo',
+  targetOrigin: 'https://child.example.com' // 强烈建议不要用 '*'
+});
+await client.send('/api/ping', { from: 'parent' });
+
+// 子页面：创建 server
+const server = requestIframeServer({ secretKey: 'popup-demo' });
+server.on('/api/ping', (req, res) => res.send({ ok: true, echo: req.body }));
+```
+
 ### 跨域数据获取
 
 当 iframe 与父页面不同域时，使用 request-iframe 安全地获取数据：
@@ -583,6 +637,8 @@ server.on('/api/data', (req, res) => {
 
 ### 文件传输
 
+> 说明：文件传输（无论 Client→Server 还是 Server→Client）底层都会通过 stream 协议承载；你只需要使用 `client.sendFile()` / `res.sendFile()` 这一层 API 即可。
+
 ```typescript
 // Server 端发送文件
 server.on('/api/download', async (req, res) => {
@@ -615,7 +671,7 @@ if (response.data instanceof File || response.data instanceof Blob) {
 
 #### Client → Server（Client 向 Server 发送文件）
 
-Client 端发送文件**仅走流式**。使用 `sendFile()`（或直接 `send(path, file)`）；Server 端在 `autoResolve: true`（默认）时会把文件自动解析成 `File/Blob` 放到 `req.body`，当 `autoResolve: false` 时则通过 `req.stream` / `req.body` 暴露为 `IframeFileReadableStream`。
+Client 端发送文件使用 `sendFile()`（或直接 `send(path, file)`）；Server 端在 `autoResolve: true`（默认）时会把文件自动解析成 `File/Blob` 放到 `req.body`，当 `autoResolve: false` 时则通过 `req.stream` / `req.body` 暴露为 `IframeFileReadableStream`。
 
 ```typescript
 // Client 端：发送文件（stream，autoResolve 默认 true）
@@ -639,14 +695,74 @@ server.on('/api/upload', async (req, res) => {
 });
 ```
 
-**提示**：当 `client.send()` 的 `body` 是 `File/Blob` 时，会自动分发到 `client.sendFile()`（走流式）。`autoResolve` 为 true（默认）时 Server 拿到 `req.body`（File/Blob），为 false 时拿到 `req.stream` / `req.body`（`IframeFileReadableStream`）。
+**提示**：当 `client.send()` 的 `body` 是 `File/Blob` 时，会自动分发到 `client.sendFile()`。`autoResolve` 为 true（默认）时 Server 拿到 `req.body`（File/Blob），为 false 时拿到 `req.stream` / `req.body`（`IframeFileReadableStream`）。
 
 ### 流式传输（Stream）
 
-对于大文件或需要分块传输的场景，可以使用流式传输：
+Stream 除了用于大文件/分块传输，也可以用于“长连接 / 订阅式交互”（类似 SSE / WebSocket，但基于 `postMessage`）。常见用法有两类：
+
+- **长连接/订阅**：Client 发起一次请求拿到 `response.stream`，然后用 `for await` 持续消费事件；需要结束时调用 `stream.cancel()`。
+- **分块/文件流**：按 chunk 传输数据或文件（下方示例）。
+
+> 长连接注意事项：
+> - `IframeWritableStream` 默认会使用 `asyncTimeout` 作为 `expireTimeout`（避免泄露）。如果你的订阅需要更久，请显式设置更大的 `expireTimeout`，或设置 `expireTimeout: 0` 关闭自动过期（建议配合业务侧取消/重连，避免泄露）。
+> - Server 端的 `res.sendStream(stream)` 会一直等待到流结束；如果你需要在后续主动 `write()` 推送数据，请不要直接 `await` 它，可以用 `void res.sendStream(stream)` 或保存返回的 Promise。
+> - 如果启用了 `maxConcurrentRequestsPerClient`，一个长连接 stream 会占用一个并发槽，需要按业务场景调整。
+> - **事件订阅**：stream 支持 `stream.on(event, listener)`（返回取消订阅函数），可用于埋点/进度/调试（如监听 `start/data/read/write/cancel/end/error/timeout/expired`）。主消费仍建议使用 `for await`。
+
+#### 长连接 / 订阅式交互（push 模式示例）
 
 ```typescript
-import { 
+/**
+ * Server 端：订阅（长连接）
+ * - mode: 'push'：由写侧主动 write()
+ * - expireTimeout: 0：关闭自动过期（谨慎使用，建议结合业务取消/重连）
+ */
+server.on('/api/subscribe', (req, res) => {
+  const stream = new IframeWritableStream({
+    type: 'data',
+    chunked: true,
+    mode: 'push',
+    expireTimeout: 0,
+    /** 可选：写侧空闲检测（等待 pull/ack 太久会做心跳并失败） */
+    streamTimeout: 15000
+  });
+
+  /** 注意：不要 await，否则会一直等到流结束 */
+  void res.sendStream(stream);
+
+  const timer = setInterval(() => {
+    try {
+      stream.write({ type: 'tick', ts: Date.now() });
+    } catch {
+      clearInterval(timer);
+    }
+  }, 1000);
+});
+
+/**
+ * Client 端：持续读取（长连接建议用 for await，而不是 readAll()）
+ */
+const resp = await client.send('/api/subscribe', {});
+if (isIframeReadableStream(resp.stream)) {
+  /** 事件订阅示例（可选） */
+  const off = resp.stream.on(StreamEvent.ERROR, ({ error }) => {
+    console.error('stream error:', error);
+  });
+
+  for await (const evt of resp.stream) {
+    console.log('event:', evt);
+  }
+
+  off();
+}
+```
+
+#### 分块 / 文件流示例
+
+```typescript
+import {
+  StreamEvent,
   IframeWritableStream, 
   IframeFileWritableStream,
   isIframeReadableStream,
@@ -757,10 +873,10 @@ if (isIframeFileReadableStream(fileResponse.stream)) {
 
 | 类型 | 说明 |
 |------|------|
-| `IframeWritableStream` | 服务端可写流，用于发送普通数据 |
-| `IframeFileWritableStream` | 服务端文件可写流（文件流） |
-| `IframeReadableStream` | 客户端可读流，用于接收普通数据 |
-| `IframeFileReadableStream` | 客户端文件可读流（文件流） |
+| `IframeWritableStream` | 写侧（生产者）流：**谁要发送 stream，谁就创建它**；可用于 Server→Client 的响应流，也可用于 Client→Server 的请求流 |
+| `IframeFileWritableStream` | 文件写侧（生产者）流：用于发送文件（底层会做 Base64 编码） |
+| `IframeReadableStream` | 读侧（消费者）流：用于接收普通数据（无论来自 Server 还是 Client） |
+| `IframeFileReadableStream` | 文件读侧（消费者）流：用于接收文件（底层会做 Base64 解码） |
 
 > **注意**：文件流内部会进行 Base64 编/解码。Base64 会带来约 33% 的体积膨胀，并且在超大文件场景下可能会有较高的内存/CPU 开销。大文件建议使用 **分块** 文件流（`chunked: true`），并控制 chunk 大小（例如 256KB–1MB）。
 
@@ -775,18 +891,22 @@ interface WritableStreamOptions {
   streamTimeout?: number;     // 写侧空闲超时（ms，可选）：长时间未收到对端 pull/ack 时会做心跳确认并失败
   iterator?: () => AsyncGenerator;  // 数据生成迭代器
   next?: () => Promise<{ data: any; done: boolean }>;  // 数据生成函数
+  maxPendingChunks?: number;  // 写侧待发送缓冲上限（可选；push/长连接场景建议配置，避免 pendingQueue 无限增长）
+  maxPendingBytes?: number;   // 写侧待发送字节上限（可选；避免单次 write 超大 chunk 导致内存暴涨）
   metadata?: Record<string, any>;   // 自定义元数据
 }
 ```
 
 **流超时/保活：**
-- `streamTimeout`（请求参数）：读侧空闲超时（ms，可选）。消费 `response.stream` 时超过该时间未收到新的 chunk，会先做一次心跳确认，失败则认为流已断开并报错。
-- `streamTimeout`（流参数）：写侧空闲超时（ms，可选）。写侧在 pull/ack 协议下，若长时间未收到对端 `pull/ack`，会做心跳确认并失败（避免长时间无效占用）。
+- `streamTimeout`（请求参数）：读侧空闲超时（ms，可选）。消费 `response.stream` 时超过该时间未收到新的 chunk，会先做一次心跳确认（默认使用 `client.isConnect()`），失败则认为流已断开并报错。
+- `streamTimeout`（流参数）：写侧空闲超时（ms，可选）。写侧在 pull 协议下，若长时间未收到对端 `pull`，会做心跳确认并失败（避免长时间无效占用）。
 - `expireTimeout`（流参数）：写侧有效期；过期后会发送 `stream_error`，读侧会收到明确的“已过期”错误。
+- `maxPendingChunks`（流参数）：写侧待发送缓冲上限（可选）。对 `push` / 长连接场景很重要：当对端停止 pull 时，继续 `write()` 会在写侧积压，建议设置上限防止内存无限增长。
+- `maxPendingBytes`（流参数）：写侧待发送字节上限（可选）。用于防止单次写入超大 chunk（例如大字符串/大 Blob 包装）导致内存占用过高。
 
 **pull/ack 协议（新增，默认启用）：**
-- 读侧会自动发送 `stream_pull` 请求更多 chunk，并对每个收到的 chunk 自动发送 `stream_ack`。
-- 写侧只会在收到 `stream_pull` 后才继续发送 `stream_data`，实现真正的背压（按需拉取）。
+- 读侧会自动发送 `stream_pull` 请求更多 chunk；写侧只会在收到 `stream_pull` 后才继续发送 `stream_data`，实现真正的背压（按需拉取）。
+  - 断连检测不依赖“逐帧确认专用消息类型”，而是通过 `streamTimeout + 心跳(isConnect)` 来实现。
 
 **consume 默认行为（变更）：**
 - `for await (const chunk of stream)` 默认会 **消费并丢弃已迭代过的 chunk**（`consume: true`），避免长流场景内存无限增长。
@@ -811,9 +931,9 @@ Server 可以要求 Client 确认收到响应：
 ```typescript
 server.on('/api/important', async (req, res) => {
   // requireAck: true 表示需要客户端确认
-  const received = await res.send(data, { requireAck: true });
+  const acked = await res.send(data, { requireAck: true });
   
-  if (received) {
+  if (acked) {
     console.log('客户端已确认收到');
   } else {
     console.log('客户端未确认（超时）');
@@ -821,21 +941,25 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
-> **说明**：当响应/错误被客户端“接管”（即存在对应的 pending request）时，库会自动发送 `received`，无需业务侧手动发送。
+> **说明**：当响应/错误被客户端“接管”（即存在对应的 pending request）时，库会自动发送 `ack`，无需业务侧手动发送。
 
 ### 追踪模式
 
-开启追踪模式可以在控制台查看详细的通信日志：
+默认情况下，request-iframe 只会输出 **warn/error** 日志（避免生产环境控制台过于吵闹）。
+
+开启追踪模式（或设置日志等级）可以在控制台查看更详细的通信日志：
 
 ```typescript
+import { LogLevel } from 'request-iframe';
+
 const client = requestIframeClient(iframe, { 
   secretKey: 'demo',
-  trace: true 
+  trace: true // 等价于 LogLevel.TRACE
 });
 
 const server = requestIframeServer({ 
   secretKey: 'demo',
-  trace: true 
+  trace: LogLevel.INFO // 输出 info/warn/error（比 trace 更克制）
 });
 
 // 控制台输出：
@@ -844,6 +968,14 @@ const server = requestIframeServer({
 // [request-iframe] [INFO] ✅ Request Success { status: 200, data: {...} }
 ```
 
+`trace` 支持：
+- `true` / `false`
+- `'trace' | 'info' | 'warn' | 'error' | 'silent'`（或 `LogLevel.*`）
+
+说明：
+- 当 `trace` 为 `LogLevel.TRACE` / `LogLevel.INFO` 时，库会额外挂载内置的调试拦截器/监听器，以输出更丰富的 request/response 日志。
+- 当 `trace` 为 `LogLevel.WARN` / `LogLevel.ERROR` / `LogLevel.SILENT` 时，只影响日志输出等级（不会额外挂载调试拦截器）。
+
 ### 多语言支持
 
 ```typescript
@@ -874,7 +1006,7 @@ setMessages({
 |------|------|------|
 | `target` | `HTMLIFrameElement \| Window` | 目标 iframe 元素或 window 对象 |
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
-| `options.trace` | `boolean` | 是否开启追踪模式（可选） |
+| `options.trace` | `boolean \| 'trace' \| 'info' \| 'warn' \| 'error' \| 'silent'` | trace/日志等级（可选）。默认只输出 warn/error |
 | `options.targetOrigin` | `string` | 覆盖 postMessage 的 targetOrigin（可选）。当 `target` 是 `Window` 时默认 `*`；当 `target` 是 iframe 时默认取 `iframe.src` 的 origin。 |
 | `options.ackTimeout` | `number` | 全局默认 ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 全局默认请求超时（ms），默认 5000 |
@@ -886,6 +1018,70 @@ setMessages({
 
 **返回值：** `RequestIframeClient`
 
+**关于 `target: Window` 的说明：**
+- **必须持有对方页面的 `Window` 引用**（例如 `window.open()` 返回值、`window.opener`、或 `MessageEvent.source`）。
+- **无法**通过 URL 给“任意标签页”发消息。
+- 安全起见，建议显式设置 `targetOrigin`，并配置 `allowedOrigins` / `validateOrigin`。
+
+**生产环境推荐配置（模板）：**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * 建议：明确限定 3 件事
+ * - secretKey：隔离不同业务/不同实例，避免消息串线
+ * - targetOrigin：发送时的 targetOrigin（Window 场景强烈建议不要用 '*'）
+ * - allowedOrigins / validateOrigin：接收时的 origin 白名单校验
+ */
+const secretKey = 'my-app';
+const targetOrigin = 'https://child.example.com';
+const allowedOrigins = [targetOrigin];
+
+// Client（父页）
+const client = requestIframeClient(window.open(targetOrigin)!, {
+  secretKey,
+  targetOrigin,
+  allowedOrigins
+});
+
+// Server（子页/iframe 内）
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins,
+  // 防止异常/攻击导致消息爆炸（按需设置）
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
+**生产环境推荐配置（iframe 场景模板）：**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * iframe 场景通常可以从 iframe.src 推导 targetOrigin，并用它作为 allowedOrigins 白名单。
+ */
+const iframe = document.querySelector('iframe')!;
+const targetOrigin = new URL(iframe.src).origin;
+const secretKey = 'my-app';
+
+// Client（父页）
+const client = requestIframeClient(iframe, {
+  secretKey,
+  // 可显式写出来（即使库内部也会默认推导），便于审计/避免误用 '*'
+  targetOrigin,
+  allowedOrigins: [targetOrigin]
+});
+
+// Server（iframe 内）
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins: [targetOrigin],
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
 **示例：**
 
 ```typescript
@@ -912,7 +1108,7 @@ await client.send('/api/longTask', {}, {
 | 参数 | 类型 | 说明 |
 |------|------|------|
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
-| `options.trace` | `boolean` | 是否开启追踪模式（可选） |
+| `options.trace` | `boolean \| 'trace' \| 'info' \| 'warn' \| 'error' \| 'silent'` | trace/日志等级（可选）。默认只输出 warn/error |
 | `options.ackTimeout` | `number` | 等待客户端确认超时（ms），默认 1000 |
 | `options.maxConcurrentRequestsPerClient` | `number` | 每个客户端的最大并发 in-flight 请求数（按 origin + creatorId 维度），默认 Infinity |
 | `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | 接收消息的 origin 白名单（可选，生产环境强烈建议配置） |
@@ -920,6 +1116,65 @@ await client.send('/api/longTask', {}, {
 
 **返回值：** `RequestIframeServer`
 
+### requestIframeEndpoint(target, options?)
+
+创建一个 **endpoint 门面**（client + server）并绑定到某个对端窗口/iframe。
+
+它可以：
+- **向对端发送请求**：`endpoint.send(...)`
+- **处理对端发来的请求**：`endpoint.on(...)` / `endpoint.use(...)` / `endpoint.map(...)`
+
+说明：
+- 内部的 client/server 是 **懒创建** 的（只有首次使用发送/注册 handler 等能力时才会创建）。
+- 如果传了 `options.id`，它会作为 client+server 的共享 id；不传则会自动生成一个。
+- `options.trace` 与 client/server 一致，推荐用 `LogLevel.*` 来配置日志等级。
+
+示例（使用 endpoint 做双向通信，推荐）：
+
+```typescript
+import { requestIframeEndpoint, LogLevel } from 'request-iframe';
+
+// 父页面（持有 iframe 元素）
+const iframe = document.querySelector('iframe')!;
+const parentEndpoint = requestIframeEndpoint(iframe, {
+  secretKey: 'demo',
+  trace: LogLevel.INFO
+});
+parentEndpoint.on('/notify', (req, res) => res.send({ ok: true, echo: req.body }));
+
+// iframe 页面（持有 window.parent）
+const iframeEndpoint = requestIframeEndpoint(window.parent, {
+  secretKey: 'demo',
+  targetOrigin: 'https://parent.example.com',
+  trace: true
+});
+iframeEndpoint.on('/api/ping', (req, res) => res.send({ ok: true }));
+
+// 任意一侧都可以 send + handle
+await parentEndpoint.send('/api/ping', { from: 'parent' });
+await iframeEndpoint.send('/notify', { from: 'iframe' });
+```
+
+生产环境推荐配置（模板）：
+
+```typescript
+import { requestIframeEndpoint, LogLevel } from 'request-iframe';
+
+const secretKey = 'my-app';
+const iframe = document.querySelector('iframe')!;
+const targetOrigin = new URL(iframe.src).origin;
+
+const endpoint = requestIframeEndpoint(iframe, {
+  secretKey,
+  targetOrigin,
+  allowedOrigins: [targetOrigin],
+  // 防止异常/攻击导致消息爆炸（按需设置）
+  maxConcurrentRequestsPerClient: 50,
+  // 日志：默认只输出 warn/error；调试时可切到 LogLevel.INFO / LogLevel.TRACE
+  trace: LogLevel.WARN
+});
+```
+
 ### Client API
 
 #### client.send(path, body?, options?)
@@ -1520,7 +1775,10 @@ import {
   // 多语言消息
   Messages,
   setMessages,
-  formatMessage
+  formatMessage,
+
+  // 日志等级
+  LogLevel
 } from 'request-iframe';
 ```
 
@@ -1611,7 +1869,11 @@ const server = requestIframeServer();
 
 ### 4. Server 可以主动推送消息吗？
 
-request-iframe 是请求-响应模式，Server 不能主动推送。如需双向通信，可以让 iframe 内也创建 Client：
+request-iframe 是请求-响应模式，Server 本身不能“主动推送”。
+
+如需双向通信，有两种做法：
+- iframe 内创建一个反向的 Client（传统做法）
+- 双方都使用 `requestIframeEndpoint()`（推荐），一个对象同时具备 **send + handle**
 
 ```typescript
 // iframe 内
@@ -1624,10 +1886,11 @@ await client.send('/notify', { event: 'data-changed' });
 
 ### 5. 如何调试通信问题？
 
-1. **开启 trace 模式**：查看详细的通信日志
-2. **检查 secretKey**：确保 Client 和 Server 使用相同的 secretKey
+1. **按日志等级开启输出**：默认只输出 warn/error；建议设置 `trace: LogLevel.INFO`（或 `trace: true`）来输出更详细的通信日志
+2. **检查 secretKey**：确保双方使用相同的 `secretKey`
 3. **检查 iframe 加载**：确保 iframe 已完全加载
-4. **检查控制台**：查看是否有跨域错误
+4. **检查 origin 约束**：尽量设置严格的 `targetOrigin`，并配置 `allowedOrigins` / `validateOrigin`，避免因为校验失败导致消息被忽略
+5. **考虑使用 `requestIframeEndpoint()`**：把双向（send + handle）能力合在一个对象里，更容易串起完整链路做排查
 
 ### 6. 支持哪些浏览器？
 
@@ -1681,27 +1944,10 @@ client.interceptors.response.use(
 );
 ```
 
-### 9. 如何调试通信问题？
-
-1. **开启 trace 模式**：在创建 client/server 时设置 `trace: true`
-2. **检查控制台**：查看详细的通信日志
-3. **验证 secretKey**：确保 client 和 server 使用相同的 secretKey
-4. **检查 iframe 加载**：确保 iframe 已完全加载后再发送请求
-5. **使用 `isConnect()`**：先检测连接是否正常
-
-```typescript
-// 开启调试模式
-const client = requestIframeClient(iframe, { 
-  secretKey: 'my-app',
-  trace: true  // 开启详细日志
-});
+### 9. trace/日志等级怎么用？
 
-// 检测连接
-const connected = await client.isConnect();
-if (!connected) {
-  console.error('无法连接到 iframe');
-}
-```
+- 推荐优先使用常量：`trace: LogLevel.INFO` / `trace: LogLevel.TRACE`
+- 如果你在做双向排查，推荐使用 `requestIframeEndpoint()` 并把 trace 打开（这样 send/handle 都在同一对象上更直观）
 
 ### 10. 性能如何？
 
@@ -1775,14 +2021,16 @@ yarn build
 request-iframe/
 ├── src/
 │   ├── api/              # 对外 API（client.ts, server.ts）
-│   ├── core/             # 核心实现（client, server, request, response）
+│   ├── impl/             # 实现层（client, server, request, response）
+│   ├── endpoint/         # endpoint 基础设施（hub/inbox/outbox + stream/heartbeat 等）
 │   ├── message/          # 消息通信层（channel, dispatcher）
 │   ├── stream/           # 流式传输实现
 │   ├── interceptors/    # 拦截器实现
 │   ├── utils/            # 工具函数
 │   ├── constants/        # 常量定义
 │   ├── types/            # TypeScript 类型定义
-│   └── __tests__/        # 测试文件
+├── __tests__/             # 测试文件（Jest）
+├── react/__tests__/       # React hooks 测试
 ├── library/              # 构建输出
 ├── coverage/             # 测试覆盖率报告
 ├── jest.config.js        # Jest 配置