request-iframe 0.1.1 → 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

@@ -76,6 +76,7 @@
 - 🔒 **消息隔离** - secretKey 机制避免多实例消息串线
 - 📁 **文件传输** - 支持文件通过流方式传输（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()`），或者你希望用一个门面对象更方便地串起全链路做调试。
+
 ---
 
 ## 实现原理
@@ -874,7 +906,7 @@ interface WritableStreamOptions {
 
 **pull/ack 协议（新增，默认启用）：**
 - 读侧会自动发送 `stream_pull` 请求更多 chunk；写侧只会在收到 `stream_pull` 后才继续发送 `stream_data`，实现真正的背压（按需拉取）。
-  - 断连检测不依赖 `stream_ack`，而是通过 `streamTimeout + 心跳(isConnect)` 来实现。
+  - 断连检测不依赖“逐帧确认专用消息类型”，而是通过 `streamTimeout + 心跳(isConnect)` 来实现。
 
 **consume 默认行为（变更）：**
 - `for await (const chunk of stream)` 默认会 **消费并丢弃已迭代过的 chunk**（`consume: true`），避免长流场景内存无限增长。
@@ -913,17 +945,21 @@ server.on('/api/important', async (req, res) => {
 
 ### 追踪模式
 
-开启追踪模式可以在控制台查看详细的通信日志：
+默认情况下，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 更克制）
 });
 
 // 控制台输出：
@@ -932,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
@@ -962,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 |
@@ -1064,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 白名单（可选，生产环境强烈建议配置） |
@@ -1072,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?)
@@ -1672,7 +1775,10 @@ import {
   // 多语言消息
   Messages,
   setMessages,
-  formatMessage
+  formatMessage,
+
+  // 日志等级
+  LogLevel
 } from 'request-iframe';
 ```
 
@@ -1763,7 +1869,11 @@ const server = requestIframeServer();
 
 ### 4. Server 可以主动推送消息吗？
 
-request-iframe 是请求-响应模式，Server 不能主动推送。如需双向通信，可以让 iframe 内也创建 Client：
+request-iframe 是请求-响应模式，Server 本身不能“主动推送”。
+
+如需双向通信，有两种做法：
+- iframe 内创建一个反向的 Client（传统做法）
+- 双方都使用 `requestIframeEndpoint()`（推荐），一个对象同时具备 **send + handle**
 
 ```typescript
 // iframe 内
@@ -1776,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. 支持哪些浏览器？
 
@@ -1833,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()`**：先检测连接是否正常
+### 9. trace/日志等级怎么用？
 
-```typescript
-// 开启调试模式
-const client = requestIframeClient(iframe, { 
-  secretKey: 'my-app',
-  trace: true  // 开启详细日志
-});
-
-// 检测连接
-const connected = await client.isConnect();
-if (!connected) {
-  console.error('无法连接到 iframe');
-}
-```
+- 推荐优先使用常量：`trace: LogLevel.INFO` / `trace: LogLevel.TRACE`
+- 如果你在做双向排查，推荐使用 `requestIframeEndpoint()` 并把 trace 打开（这样 send/handle 都在同一对象上更直观）
 
 ### 10. 性能如何？
 
@@ -1927,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 配置

package/README.md

@@ -76,6 +76,7 @@ In micro-frontend, iframe nesting, and popup window scenarios, cross-page commun
 - 🔒 **Message Isolation** - secretKey mechanism prevents message cross-talk between multiple instances
 - 📁 **File Transfer** - File transfer via streams (client↔server)
 - 🌊 **Streaming** - Support for large file chunked transfer, supports async iterators
+- 🧾 **Leveled Logging** - Warn/Error logs enabled by default; can be configured via `trace` level
 - 🌍 **Internationalization** - Error messages can be customized for i18n
 - ✅ **Protocol Versioning** - Built-in version control for upgrade compatibility
 
@@ -93,6 +94,30 @@ pnpm add request-iframe
 
 **TypeScript**: Built-in complete type definitions, no need to install `@types/request-iframe`
 
+## CDN (UMD bundles)
+
+This repo also builds **script-tag friendly UMD bundles** (core + react hooks) that can be hosted on a CDN.
+
+- Core bundle output: `cdn/request-iframe.umd(.min).js` → global `RequestIframe`
+- React bundle output: `cdn/request-iframe-react.umd(.min).js` → global `RequestIframeReact` (requires `React` global and `RequestIframe` global)
+
+Example (using unpkg):
+
+```html
+<!-- Core -->
+<script src="https://unpkg.com/request-iframe@latest/cdn/request-iframe.umd.min.js"></script>
+
+<!-- React (optional) -->
+<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 are available on RequestIframeReact (e.g. RequestIframeReact.useClient)
+  console.log(!!requestIframeClient, !!requestIframeServer, !!requestIframeEndpoint);
+<\/script>
+```
+
 ## Quick Start
 
 ### 1. Parent Page (Client Side)
@@ -130,6 +155,11 @@ That's it! 🎉
 
 > 💡 **Tip**: For more quick start guides, see [QUICKSTART.md](./QUICKSTART.md) or [QUICKSTART.CN.md](./QUICKSTART.CN.md) (中文)
 
+## Which API should I use?
+
+- **Use `requestIframeClient()` + `requestIframeServer()`** when communication is mostly one-way (parent → iframe), and you prefer a clear separation between request sender and handler.
+- **Use `requestIframeEndpoint()`** when you need **bidirectional** communication (both sides need `send()` + `on()/use()/map()`), or when you want a single façade object to debug a full flow more easily.
+
 ---
 
 ## Use Cases
@@ -834,7 +864,7 @@ server.on('/api/uploadStream', async (req, res) => {
 
 **Pull/Ack protocol (default):**
 - 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)`.
+  - Disconnect detection does not rely on a dedicated per-frame ack message type, 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.
@@ -872,17 +902,21 @@ server.on('/api/important', async (req, res) => {
 
 ### Trace Mode
 
-Enable trace mode to view detailed communication logs in console:
+By default, request-iframe only prints **warn/error** logs (to avoid noisy console in production).
+
+Enable trace mode (or set a log level) to view detailed communication logs:
 
 ```typescript
+import { LogLevel } from 'request-iframe';
+
 const client = requestIframeClient(iframe, { 
   secretKey: 'demo',
-  trace: true 
+  trace: true // equivalent to LogLevel.TRACE
 });
 
 const server = requestIframeServer({ 
   secretKey: 'demo',
-  trace: true 
+  trace: LogLevel.INFO // enable info/warn/error logs (less verbose than trace)
 });
 
 // Console output:
@@ -891,6 +925,14 @@ const server = requestIframeServer({
 // [request-iframe] [INFO] ✅ Request Success { status: 200, data: {...} }
 ```
 
+`trace` supports:
+- `true` / `false`
+- `'trace' | 'info' | 'warn' | 'error' | 'silent'` (or `LogLevel.*`)
+
+Notes:
+- When `trace` is `LogLevel.TRACE` or `LogLevel.INFO`, the library will also attach built-in debug interceptors/listeners for richer request/response logs.
+- When `trace` is `LogLevel.WARN` / `LogLevel.ERROR` / `LogLevel.SILENT`, it only affects log output level (no extra debug interceptors attached).
+
 ### Internationalization
 
 ```typescript
@@ -921,7 +963,7 @@ Create a Client instance.
 |-----------|------|-------------|
 | `target` | `HTMLIFrameElement \| Window` | Target iframe element or window object |
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
-| `options.trace` | `boolean` | Whether to enable trace mode (optional) |
+| `options.trace` | `boolean \| 'trace' \| 'info' \| 'warn' \| 'error' \| 'silent'` | Trace/log level (optional). Default logs are warn/error only |
 | `options.targetOrigin` | `string` | Override postMessage targetOrigin for sending (optional). If `target` is a `Window`, default is `*`. |
 | `options.ackTimeout` | `number` | Global default ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Global default request timeout (ms), default 5000 |
@@ -1006,7 +1048,7 @@ Create a Server instance.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
-| `options.trace` | `boolean` | Whether to enable trace mode (optional) |
+| `options.trace` | `boolean \| 'trace' \| 'info' \| 'warn' \| 'error' \| 'silent'` | Trace/log level (optional). Default logs are warn/error only |
 | `options.ackTimeout` | `number` | Wait for client acknowledgment timeout (ms), default 1000 |
 | `options.maxConcurrentRequestsPerClient` | `number` | Max concurrent in-flight requests per client (per origin + creatorId). Default Infinity |
 | `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | Allowlist for incoming message origins (optional, recommended for production) |
@@ -1014,6 +1056,65 @@ Create a Server instance.
 
 **Returns:** `RequestIframeServer`
 
+### requestIframeEndpoint(target, options?)
+
+Create an **endpoint facade** (client + server) for a peer window/iframe.
+
+It can:
+- **send requests** to the peer: `endpoint.send(...)`
+- **handle requests** from the peer: `endpoint.on(...)`, `endpoint.use(...)`, `endpoint.map(...)`
+
+Notes:
+- Client and server instances are **lazily created** (only when you first access send/handlers APIs).
+- `options.id` (if provided) becomes the shared ID for both sides (client + server); otherwise a random one is generated.
+- `options.trace` follows the same leveled logging rules as client/server (`LogLevel.*` recommended).
+
+Example (bidirectional via endpoint, recommended):
+
+```typescript
+import { requestIframeEndpoint, LogLevel } from 'request-iframe';
+
+// Parent page (has iframe element)
+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 page (has 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 }));
+
+// Either side can now send + handle
+await parentEndpoint.send('/api/ping', { from: 'parent' });
+await iframeEndpoint.send('/notify', { from: 'iframe' });
+```
+
+Production configuration template (recommended):
+
+```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],
+  // Mitigate message explosion (tune as needed)
+  maxConcurrentRequestsPerClient: 50,
+  // Logs: default is warn/error; choose info for debugging
+  trace: LogLevel.WARN
+});
+```
+
 ### Client API
 
 #### client.send(path, body?, options?)
@@ -1591,7 +1692,11 @@ Just ensure both sides use the same `secretKey`.
 
 ### 4. Can Server actively push messages?
 
-request-iframe is request-response mode, Server cannot actively push. For bidirectional communication, you can create a Client inside the iframe:
+request-iframe is request-response mode, Server cannot actively push by itself.
+
+For bidirectional communication, you have 2 options:
+- Create a reverse `client` inside the iframe (traditional way)
+- Use `requestIframeEndpoint()` on both sides (recommended) so each side has **send + handle** in one object
 
 ```typescript
 // Inside iframe
@@ -1604,10 +1709,11 @@ await client.send('/notify', { event: 'data-changed' });
 
 ### 5. How to debug communication issues?
 
-1. **Enable trace mode**: View detailed communication logs
+1. **Enable logs with levels**: by default only warn/error logs are printed; enable `trace: LogLevel.INFO` (or `trace: true`) to see detailed logs
 2. **Check secretKey**: Ensure Client and Server use the same secretKey
 3. **Check iframe loading**: Ensure iframe is fully loaded
-4. **Check console**: Check for cross-origin errors
+4. **Check origin constraints**: prefer setting strict `targetOrigin` and configure `allowedOrigins` / `validateOrigin`
+5. **Consider using `requestIframeEndpoint()`**: it unifies both directions (send + handle) and makes it easier to debug flows in one place
 
 ---
 
@@ -1659,12 +1765,7 @@ yarn build
 
 ### Test Coverage
 
-The project currently has **76.88%** test coverage, meeting production requirements:
-
-- **Statement Coverage**: 76.88%
-- **Branch Coverage**: 64.13%
-- **Function Coverage**: 75%
-- **Line Coverage**: 78.71%
+The project maintains **high test coverage** and CI coverage reports (see badges at the top of this README).
 
 Coverage reports are generated in the `coverage/` directory, view detailed coverage report via `coverage/index.html`.