request-iframe 0.1.0 → 0.1.1

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,7 +74,7 @@
 - ⏱️ **智能超时** - 三阶段超时（连接/同步/异步），自动识别长任务
 - 📦 **TypeScript** - 完整的类型定义和智能提示
 - 🔒 **消息隔离** - secretKey 机制避免多实例消息串线
-- 📁 **文件传输** - 支持文件通过流方式传输（Client→Server）
+- 📁 **文件传输** - 支持文件通过流方式传输（Client↔Server）
 - 🌊 **流式传输** - 支持大文件分块传输，支持异步迭代器
 - 🌍 **多语言** - 错误消息可自定义，便于国际化
 - ✅ **协议版本** - 内置版本控制，便于升级兼容
@@ -151,7 +151,7 @@ request-iframe 在 `postMessage` 基础上实现了一套类 HTTP 的通信协
        │                                            │
        │  <──── RESPONSE ────────────────────────  │  返回结果
        │                                            │
-       │  ──── RECEIVED (可选) ──────────────────>  │  确认收到响应
+       │  ──── ACK (可选) ───────────────────────>  │  确认收到响应
        │                                            │
 ```
 
@@ -160,11 +160,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 +285,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 +605,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 +639,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 +663,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 +841,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 +859,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`，实现真正的背压（按需拉取）。
+  - 断连检测不依赖 `stream_ack`，而是通过 `streamTimeout + 心跳(isConnect)` 来实现。
 
 **consume 默认行为（变更）：**
 - `for await (const chunk of stream)` 默认会 **消费并丢弃已迭代过的 chunk**（`consume: true`），避免长流场景内存无限增长。
@@ -811,9 +899,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,7 +909,7 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
-> **说明**：当响应/错误被客户端“接管”（即存在对应的 pending request）时，库会自动发送 `received`，无需业务侧手动发送。
+> **说明**：当响应/错误被客户端“接管”（即存在对应的 pending request）时，库会自动发送 `ack`，无需业务侧手动发送。
 
 ### 追踪模式
 
@@ -886,6 +974,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

package/README.md

@@ -1,6 +1,6 @@
 # request-iframe
 
-Communicate with iframes like sending HTTP requests! A cross-origin iframe communication library based on `postMessage`.
+Communicate with iframes/windows like sending HTTP requests! A cross-origin browser communication library based on `postMessage`.
 
 > 🌐 **Languages**: [English](./README.md) | [中文](./README.CN.md)
 
@@ -8,7 +8,7 @@ Communicate with iframes like sending HTTP requests! A cross-origin iframe commu
   <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>
 
 ## 📑 Table of Contents
@@ -48,7 +48,7 @@ Communicate with iframes like sending HTTP requests! A cross-origin iframe commu
 
 ## Why request-iframe?
 
-In micro-frontend and iframe nesting scenarios, parent-child page communication is a common requirement. Traditional `postMessage` communication has the following pain points:
+In micro-frontend, iframe nesting, and popup window scenarios, cross-page communication is a common requirement. Traditional `postMessage` communication has the following pain points:
 
 | Pain Point | Traditional Way | request-iframe |
 |------------|----------------|----------------|
@@ -74,7 +74,7 @@ In micro-frontend and iframe nesting scenarios, parent-child page communication
 - ⏱️ **Smart Timeout** - Three-stage timeout (connection/sync/async), automatically detects long tasks
 - 📦 **TypeScript** - Complete type definitions and IntelliSense
 - 🔒 **Message Isolation** - secretKey mechanism prevents message cross-talk between multiple instances
-- 📁 **File Transfer** - Support for file sending via stream (client→server)
+- 📁 **File Transfer** - File transfer via streams (client↔server)
 - 🌊 **Streaming** - Support for large file chunked transfer, supports async iterators
 - 🌍 **Internationalization** - Error messages can be customized for i18n
 - ✅ **Protocol Versioning** - Built-in version control for upgrade compatibility
@@ -172,6 +172,29 @@ server.on('/event', (req, res) => {
 });
 ```
 
+### Popup / New Window (Window Communication)
+
+`request-iframe` also works with a `Window` target (not only an iframe).
+
+**Important**: you must have a real `Window` reference (e.g. returned by `window.open()`, or available via `window.opener` / `event.source`). You cannot send to an arbitrary browser tab by URL.
+
+```typescript
+// Parent page: open a new tab/window
+const child = window.open('https://child.example.com/page.html', '_blank');
+if (!child) throw new Error('Popup blocked');
+
+// Parent -> child
+const client = requestIframeClient(child, {
+  secretKey: 'popup-demo',
+  targetOrigin: 'https://child.example.com' // strongly recommended (avoid '*')
+});
+await client.send('/api/ping', { from: 'parent' });
+
+// Child page: create server
+const server = requestIframeServer({ secretKey: 'popup-demo' });
+server.on('/api/ping', (req, res) => res.send({ ok: true, echo: req.body }));
+```
+
 ### Cross-Origin Data Fetching
 
 When iframe and parent page are on different origins, use request-iframe to securely fetch data:
@@ -237,7 +260,7 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
        │                                          │
        │  <──── RESPONSE ──────────────────────  │  Return result
        │                                          │
-       │  ──── RECEIVED (optional) ────────────>  │  Acknowledge receipt of response/error (controlled by response `requireAck`)
+       │  ──── ACK (optional) ─────────────────>  │  Acknowledge receipt of response/error (ACK-only requireAck)
        │                                          │
 ```
 
@@ -246,15 +269,13 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
 | Type | Direction | Description |
 |------|-----------|-------------|
 | `request` | Client → Server | Client initiates request |
-| `ack` | Server → Client | Server acknowledges receipt of request (when request `requireAck` is enabled) |
+| `ack` | Receiver → Sender | Acknowledgment when `requireAck: true` and the message is accepted/handled (ACK-only) |
 | `async` | Server → Client | Notifies client this is an async task (sent when handler returns Promise) |
 | `response` | Server → Client | Returns response data |
 | `error` | Server → Client | Returns error information |
-| `received` | Client → Server | Client acknowledges receipt of response/error (optional, controlled by response `requireAck`) |
 | `ping` | Client → Server | Connection detection (`isConnect()` method, may use `requireAck` to confirm delivery) |
 | `pong` | Server → Client | Connection detection response |
 | `stream_pull` | Receiver → Sender | Stream pull: receiver requests next chunks (pull/ack protocol) |
-| `stream_ack` | Receiver → Sender | Stream ack: receiver acknowledges a chunk (pull/ack protocol) |
 
 ### Timeout Mechanism
 
@@ -558,6 +579,8 @@ server.on('/api/data', (req, res) => {
 
 ### File Transfer
 
+> Note: File transfer (both Client→Server and Server→Client) is carried by the stream protocol under the hood. You normally only need to use `client.sendFile()` / `res.sendFile()`.
+
 #### Server → Client (Server sends file to client)
 
 ```typescript
@@ -592,7 +615,7 @@ if (response.data instanceof File || response.data instanceof Blob) {
 
 #### Client → Server (Client sends file to server)
 
-Client sends file via stream only. Use `sendFile()` (or `send(path, file)`); server receives either `req.body` as File/Blob when `autoResolve: true` (default), or `req.stream` as `IframeFileReadableStream` when `autoResolve: false`.
+Client sends file using `sendFile()` (or `send(path, file)`); server receives either `req.body` as File/Blob when `autoResolve: true` (default), or `req.stream` as `IframeFileReadableStream` when `autoResolve: false`.
 
 ```typescript
 // Client side: Send file (stream, autoResolve defaults to true)
@@ -616,16 +639,71 @@ server.on('/api/upload', async (req, res) => {
 });
 ```
 
-**Note:** When using `client.send()` with a `File` or `Blob`, it automatically dispatches to `client.sendFile()`, which sends the file via stream. Server gets `req.body` as File/Blob when `autoResolve` is true (default), or `req.stream` / `req.body` as `IframeFileReadableStream` when `autoResolve` is false.
+**Note:** When using `client.send()` with a `File` or `Blob`, it automatically dispatches to `client.sendFile()`. Server gets `req.body` as File/Blob when `autoResolve` is true (default), or `req.stream` / `req.body` as `IframeFileReadableStream` when `autoResolve` is false.
 
 ### Streaming
 
-For large files or scenarios requiring chunked transfer, you can use streaming:
+Streaming is not only for large/chunked transfers, but also works well for **long-lived subscription-style interactions** (similar to SSE/WebSocket, but built on top of `postMessage`).
+
+#### Long-lived subscription (push mode)
+
+> Notes:
+> - `IframeWritableStream` defaults `expireTimeout` to `asyncTimeout` to avoid leaking long-lived streams. For real subscriptions, set a larger `expireTimeout`, or set `expireTimeout: 0` to disable auto-expire (use with care and pair with cancel/reconnect).
+> - `res.sendStream(stream)` waits until the stream ends. If you want to keep pushing via `write()`, **do not** `await` it; use `void res.sendStream(stream)` or keep the returned Promise.
+> - If `maxConcurrentRequestsPerClient` is enabled, a long-lived stream occupies one in-flight request slot.
+> - **Event subscription**: streams support `stream.on(event, listener)` (returns an unsubscribe function) for observability (e.g. `start/data/read/write/cancel/end/error/timeout/expired`). For consuming data, prefer `for await`.
+
+```typescript
+/**
+ * Server side: subscribe (long-lived)
+ * - mode: 'push': writer calls write()
+ * - expireTimeout: 0: disable auto-expire (use with care)
+ */
+server.on('/api/subscribe', (req, res) => {
+  const stream = new IframeWritableStream({
+    type: 'data',
+    chunked: true,
+    mode: 'push',
+    expireTimeout: 0,
+    /** optional: writer-side idle timeout while waiting for pull/ack */
+    streamTimeout: 15000
+  });
+
+  /** do not await, otherwise it blocks until stream ends */
+  void res.sendStream(stream);
+
+  const timer = setInterval(() => {
+    try {
+      stream.write({ type: 'tick', ts: Date.now() });
+    } catch {
+      clearInterval(timer);
+    }
+  }, 1000);
+});
+
+/**
+ * Client side: consume continuously (prefer for-await for long-lived streams)
+ */
+const resp = await client.send('/api/subscribe', {});
+if (isIframeReadableStream(resp.stream)) {
+  /** Optional: observe events */
+  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();
+}
+```
 
 #### Server → Client (Server sends stream to client)
 
 ```typescript
-import { 
+import {
+  StreamEvent,
   IframeWritableStream, 
   IframeFileWritableStream,
   isIframeReadableStream,
@@ -740,21 +818,23 @@ server.on('/api/uploadStream', async (req, res) => {
 
 | Type | Description |
 |------|-------------|
-| `IframeWritableStream` | Server-side writable stream for sending regular data |
-| `IframeFileWritableStream` | Server-side file writable stream, automatically handles base64 encoding |
-| `IframeReadableStream` | Client-side readable stream for receiving regular data |
-| `IframeFileReadableStream` | Client-side file readable stream, automatically handles base64 decoding |
+| `IframeWritableStream` | Writer/producer stream: **created by whichever side is sending the stream** (server→client response stream, or client→server request stream) |
+| `IframeFileWritableStream` | File writer/producer stream (base64-encodes internally) |
+| `IframeReadableStream` | Reader/consumer stream for receiving regular data (regardless of which side sent it) |
+| `IframeFileReadableStream` | File reader/consumer stream (base64-decodes internally) |
 
 > **Note**: File streams are base64-encoded internally. Base64 introduces ~33% size overhead and can be memory/CPU heavy for very large files. For large files, prefer **chunked** file streams (`chunked: true`) and keep chunk sizes moderate (e.g. 256KB–1MB).
 
 **Stream timeouts:**
-- `options.streamTimeout` (request option): client-side stream idle timeout while consuming `response.stream` (data/file streams). When triggered, the client will attempt a heartbeat check and fail the stream if the connection is not alive.
+- `options.streamTimeout` (request option): client-side stream idle timeout while consuming `response.stream` (data/file streams). When triggered, the client performs a heartbeat check (by default `client.isConnect()`); if not alive, the stream fails as disconnected.
 - `expireTimeout` (writable stream option): writer-side stream lifetime. When expired, the writer sends `stream_error` and the reader will fail the stream with `STREAM_EXPIRED`.
-- `streamTimeout` (writable stream option): writer-side idle timeout. If the writer does not receive `stream_pull/stream_ack` for a long time, it will heartbeat-check and fail to avoid wasting resources.
+- `streamTimeout` (writable stream option): writer-side idle timeout. If the writer does not receive `stream_pull` for a long time, it will heartbeat-check and fail to avoid wasting resources.
+- `maxPendingChunks` (writable stream option): max number of pending (unsent) chunks kept in memory on the writer side (optional). Important for long-lived `push` streams: if the receiver stops pulling, continued `write()` calls will accumulate in the writer queue.
+- `maxPendingBytes` (writable stream option): max bytes of pending (unsent) chunks kept in memory on the writer side (optional). Useful when a single `write()` may enqueue a very large chunk.
 
 **Pull/Ack protocol (default):**
-- Reader automatically sends `stream_pull` to request chunks and sends `stream_ack` for each received chunk.
 - Writer only sends `stream_data` when it has received `stream_pull`, enabling real backpressure.
+  - Disconnect detection does not rely on `stream_ack`, but uses `streamTimeout + heartbeat(isConnect)`.
 
 **consume default change:**
 - `for await (const chunk of response.stream)` defaults to **consume and drop** already iterated chunks (`consume: true`) to prevent unbounded memory growth for long streams.
@@ -778,9 +858,9 @@ Server can require Client to acknowledge receipt of response:
 ```typescript
 server.on('/api/important', async (req, res) => {
   // requireAck: true means client needs to acknowledge
-  const received = await res.send(data, { requireAck: true });
+  const acked = await res.send(data, { requireAck: true });
   
-  if (received) {
+  if (acked) {
     console.log('Client acknowledged receipt');
   } else {
     console.log('Client did not acknowledge (timeout)');
@@ -788,7 +868,7 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
-> **Note**: Client acknowledgment (`received`) is sent automatically by the library when the response/error is accepted by the client (i.e., there is a matching pending request). You don't need to manually send `received`.
+> **Note**: Client acknowledgment (`ack`) is sent automatically by the library when the response/error is accepted by the client (i.e., there is a matching pending request). You don't need to manually send `ack`.
 
 ### Trace Mode
 
@@ -853,6 +933,70 @@ Create a Client instance.
 
 **Returns:** `RequestIframeClient`
 
+**Notes about `target: Window`:**
+- **You must have a `Window` reference** (e.g. from `window.open()`, `window.opener`, or `MessageEvent.source`).
+- You **cannot** communicate with an arbitrary browser tab by URL.
+- For security, prefer setting a strict `targetOrigin` and configure `allowedOrigins` / `validateOrigin`.
+
+**Production configuration template:**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * Recommended: explicitly constrain 3 things
+ * - secretKey: isolate different apps/instances (avoid cross-talk)
+ * - targetOrigin: postMessage targetOrigin (strongly avoid '*' for Window targets)
+ * - allowedOrigins / validateOrigin: incoming origin allowlist validation
+ */
+const secretKey = 'my-app';
+const targetOrigin = 'https://child.example.com';
+const allowedOrigins = [targetOrigin];
+
+// Client (parent)
+const client = requestIframeClient(window.open(targetOrigin)!, {
+  secretKey,
+  targetOrigin,
+  allowedOrigins
+});
+
+// Server (child/iframe)
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins,
+  // Mitigate message explosion (tune as needed)
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
+**Production configuration template (iframe target):**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * For iframe targets, you can derive targetOrigin from iframe.src, and use it as the allowedOrigins allowlist.
+ */
+const iframe = document.querySelector('iframe')!;
+const targetOrigin = new URL(iframe.src).origin;
+const secretKey = 'my-app';
+
+// Client (parent)
+const client = requestIframeClient(iframe, {
+  secretKey,
+  // Explicitly set it (even though the library can derive it) to avoid accidentally using '*'
+  targetOrigin,
+  allowedOrigins: [targetOrigin]
+});
+
+// Server (inside iframe)
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins: [targetOrigin],
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
 ### requestIframeServer(options?)
 
 Create a Server instance.

package/esm/api/client.js

@@ -2,7 +2,7 @@ import { getIframeTargetOrigin, generateInstanceId } from '../utils';
 import { RequestIframeClientServer } from '../core/client-server';
 import { RequestIframeClientImpl } from '../core/client';
 import { setupClientDebugInterceptors } from '../utils/debug';
-import { Messages, ErrorCode } from '../constants';
+import { Messages, ErrorCode, OriginConstant } from '../constants';
 
 /**
  * Create a client (for sending requests)
@@ -14,7 +14,7 @@ import { Messages, ErrorCode } from '../constants';
  */
 export function requestIframeClient(target, options) {
   var targetWindow = null;
-  var targetOrigin = '*';
+  var targetOrigin = OriginConstant.ANY;
   if (target.tagName === 'IFRAME') {
     var iframe = target;
     targetWindow = iframe.contentWindow;
@@ -27,7 +27,7 @@ export function requestIframeClient(target, options) {
     }
   } else {
     targetWindow = target;
-    targetOrigin = '*';
+    targetOrigin = OriginConstant.ANY;
   }
 
   // Allow user to override targetOrigin explicitly
@@ -44,8 +44,9 @@ export function requestIframeClient(target, options) {
   // Create ClientServer (internally obtains or creates a shared MessageChannel)
   var server = new RequestIframeClientServer({
     secretKey,
-    ackTimeout: options === null || options === void 0 ? void 0 : options.ackTimeout,
-    autoOpen: options === null || options === void 0 ? void 0 : options.autoOpen
+    autoOpen: options === null || options === void 0 ? void 0 : options.autoOpen,
+    autoAckMaxMetaLength: options === null || options === void 0 ? void 0 : options.autoAckMaxMetaLength,
+    autoAckMaxIdLength: options === null || options === void 0 ? void 0 : options.autoAckMaxIdLength
   }, instanceId);
 
   // Create client instance