request-iframe 0.0.6 → 0.1.1

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:
@@ -229,7 +252,7 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
        │                                          │
        │  ──── REQUEST ────────────────────────>  │  Send request
        │                                          │
-       │  <──── ACK ───────────────────────────  │  Acknowledge receipt
+       │  <──── ACK (optional) ────────────────  │  Acknowledge receipt (controlled by request `requireAck`, default true)
        │                                          │
        │                                          │  Execute handler
        │                                          │
@@ -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
+       │  ──── ACK (optional) ─────────────────>  │  Acknowledge receipt of response/error (ACK-only requireAck)
        │                                          │
 ```
 
@@ -246,13 +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 |
+| `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 (optional, controlled by `requireAck`) |
-| `ping` | Client → Server | Connection detection (`isConnect()` method) |
+| `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) |
 
 ### Timeout Mechanism
 
@@ -262,7 +285,8 @@ request-iframe uses a three-stage timeout strategy to intelligently adapt to dif
 client.send('/api/getData', data, {
   ackTimeout: 1000,       // Stage 1: ACK timeout (default 1000ms)
   timeout: 5000,          // Stage 2: Request timeout (default 5s)
-  asyncTimeout: 120000    // Stage 3: Async request timeout (default 120s)
+  asyncTimeout: 120000,   // Stage 3: Async request timeout (default 120s)
+  requireAck: true        // Whether to wait for server ACK before switching to stage 2 (default true)
 });
 ```
 
@@ -304,13 +328,17 @@ Send REQUEST
 | timeout | Medium (5s) | Suitable for simple synchronous processing, like reading data, parameter validation |
 | asyncTimeout | Long (120s) | Suitable for complex async operations, like file processing, batch operations, third-party API calls |
 
+**Notes:**
+- If you set `requireAck: false`, the request will **skip** the ACK stage and start `timeout` immediately.
+- Stream transfer has its own optional idle timeout: use `streamTimeout` (see [Streaming](#streaming)).
+
 ### Protocol Version
 
 Each message contains a `__requestIframe__` field identifying the protocol version, and a `timestamp` field recording message creation time:
 
 ```typescript
 {
-  __requestIframe__: 1,  // Protocol version number
+  __requestIframe__: 2,  // Protocol version number
   timestamp: 1704067200000,  // Message creation timestamp (milliseconds)
   type: 'request',
   requestId: 'req_xxx',
@@ -321,7 +349,7 @@ Each message contains a `__requestIframe__` field identifying the protocol versi
 
 This enables:
 - Different library versions can handle compatibility
-- New version Server can be compatible with old version Client
+- Current protocol version is `2`. For the new stream pull/ack flow, both sides should use the same version.
 - Clear error messages when version is too low
 - `timestamp` facilitates debugging message delays and analyzing communication performance
 
@@ -551,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
@@ -585,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)
@@ -609,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,
@@ -630,6 +715,11 @@ server.on('/api/stream', async (req, res) => {
   const stream = new IframeWritableStream({
     type: 'data',
     chunked: true,
+    mode: 'pull', // default: pull/ack protocol (backpressure)
+    // Optional: auto-expire stream to avoid leaking resources (default: asyncTimeout)
+    // expireTimeout: 120000,
+    // Optional: writer-side idle timeout while waiting for pull/ack
+    // streamTimeout: 10000,
     // Generate data using async iterator
     iterator: async function* () {
       for (let i = 0; i < 10; i++) {
@@ -643,14 +733,19 @@ server.on('/api/stream', async (req, res) => {
 });
 
 // Client side: Receive stream data
-const response = await client.send('/api/stream', {});
+const response = await client.send('/api/stream', {}, { streamTimeout: 10000 });
 
 // Check if it's a stream response
 if (isIframeReadableStream(response.stream)) {
+  // Sender stream mode (from stream_start)
+  console.log('Stream mode:', response.stream.mode); // 'pull' | 'push' | undefined
+
   // Method 1: Read all data at once
   const allData = await response.stream.read();
+  // If you want a consistent return type (always an array of chunks), use readAll()
+  const allChunks = await response.stream.readAll();
   
-  // Method 2: Read chunk by chunk using async iterator
+  // Method 2: Read chunk by chunk using async iterator (consume defaults to true)
   for await (const chunk of response.stream) {
     console.log('Received chunk:', chunk);
   }
@@ -723,10 +818,26 @@ 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 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` 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):**
+- 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.
 
 ### Connection Detection
 
@@ -747,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)');
@@ -757,6 +868,8 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
+> **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
 
 Enable trace mode to view detailed communication logs in console:
@@ -809,12 +922,81 @@ 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.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 |
 | `options.asyncTimeout` | `number` | Global default async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Global default for request delivery ACK (default true). If false, requests skip the ACK stage and start `timeout` immediately |
+| `options.streamTimeout` | `number` | Global default stream idle timeout (ms) when consuming `response.stream` (optional) |
+| `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | Allowlist for incoming message origins (optional, recommended for production) |
+| `options.validateOrigin` | `(origin, data, context) => boolean` | Custom origin validator (optional, higher priority than `allowedOrigins`) |
 
 **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.
@@ -826,6 +1008,9 @@ Create a Server instance.
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
 | `options.trace` | `boolean` | Whether to enable trace mode (optional) |
 | `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) |
+| `options.validateOrigin` | `(origin, data, context) => boolean` | Custom origin validator (optional, higher priority than `allowedOrigins`) |
 
 **Returns:** `RequestIframeServer`
 
@@ -844,6 +1029,8 @@ Send a request. Automatically dispatches to `sendFile()` or `sendStream()` based
 | `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Whether to require server delivery ACK (default true). If false, skips ACK stage |
+| `options.streamTimeout` | `number` | Stream idle timeout (ms) while consuming `response.stream` (optional) |
 | `options.headers` | `object` | Request headers (optional) |
 | `options.cookies` | `object` | Request cookies (optional, merged with internally stored cookies, passed-in takes priority) |
 | `options.requestId` | `string` | Custom request ID (optional) |
@@ -895,6 +1082,8 @@ Send file as request body (via stream; server receives File/Blob when autoResolv
 | `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Whether to require server delivery ACK (default true). If false, skips ACK stage |
+| `options.streamTimeout` | `number` | Stream idle timeout (ms) while consuming `response.stream` (optional) |
 | `options.headers` | `object` | Request headers (optional) |
 | `options.cookies` | `object` | Request cookies (optional) |
 | `options.requestId` | `string` | Custom request ID (optional) |
@@ -916,6 +1105,8 @@ Send stream as request body (server receives readable stream).
 | `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
+| `options.requireAck` | `boolean` | Whether to require server delivery ACK (default true). If false, skips ACK stage |
+| `options.streamTimeout` | `number` | Stream idle timeout (ms) while consuming `response.stream` (optional) |
 | `options.headers` | `object` | Request headers (optional) |
 | `options.cookies` | `object` | Request cookies (optional) |
 | `options.requestId` | `string` | Custom request ID (optional) |
@@ -1064,6 +1255,8 @@ Destroy Server instance, remove all listeners.
 
 request-iframe provides React hooks for easy integration in React applications. Import hooks from `request-iframe/react`:
 
+> Note: React is only required if you use `request-iframe/react`. Installing `request-iframe` alone does not require React.
+
 ```typescript
 import { useClient, useServer, useServerHandler, useServerHandlerMap } from 'request-iframe/react';
 ```
@@ -1328,8 +1521,12 @@ const IframeComponent = () => {
 | `PROTOCOL_UNSUPPORTED` | Protocol version not supported |
 | `IFRAME_NOT_READY` | iframe not ready |
 | `STREAM_ERROR` | Stream transfer error |
+| `STREAM_TIMEOUT` | Stream idle timeout |
+| `STREAM_EXPIRED` | Stream expired (writable stream lifetime exceeded) |
 | `STREAM_CANCELLED` | Stream cancelled |
 | `STREAM_NOT_BOUND` | Stream not bound to request context |
+| `STREAM_START_TIMEOUT` | Stream start timeout (request body stream_start not received in time) |
+| `TOO_MANY_REQUESTS` | Too many concurrent requests (server-side limit) |
 
 ### Error Handling Example
 

package/esm/api/client.js

@@ -0,0 +1,80 @@
+import { getIframeTargetOrigin, generateInstanceId } from '../utils';
+import { RequestIframeClientServer } from '../core/client-server';
+import { RequestIframeClientImpl } from '../core/client';
+import { setupClientDebugInterceptors } from '../utils/debug';
+import { Messages, ErrorCode, OriginConstant } from '../constants';
+
+/**
+ * Create a client (for sending requests)
+ * 
+ * Note:
+ * - MessageChannel is cached at the window level by secretKey (ensures unique message listener)
+ * - Client instances are not cached, a new instance is created on each call
+ * - This allows different versions of the library to coexist
+ */
+export function requestIframeClient(target, options) {
+  var targetWindow = null;
+  var targetOrigin = OriginConstant.ANY;
+  if (target.tagName === 'IFRAME') {
+    var iframe = target;
+    targetWindow = iframe.contentWindow;
+    targetOrigin = getIframeTargetOrigin(iframe);
+    if (!targetWindow) {
+      throw {
+        message: Messages.IFRAME_NOT_READY,
+        code: ErrorCode.IFRAME_NOT_READY
+      };
+    }
+  } else {
+    targetWindow = target;
+    targetOrigin = OriginConstant.ANY;
+  }
+
+  // Allow user to override targetOrigin explicitly
+  if (options !== null && options !== void 0 && options.targetOrigin) {
+    targetOrigin = options.targetOrigin;
+  }
+
+  // Determine secretKey
+  var secretKey = options === null || options === void 0 ? void 0 : options.secretKey;
+
+  // Generate instance ID first (will be used by both client and server)
+  var instanceId = generateInstanceId();
+
+  // Create ClientServer (internally obtains or creates a shared MessageChannel)
+  var server = new RequestIframeClientServer({
+    secretKey,
+    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
+  var client = new RequestIframeClientImpl(targetWindow, targetOrigin, server, {
+    secretKey,
+    ackTimeout: options === null || options === void 0 ? void 0 : options.ackTimeout,
+    timeout: options === null || options === void 0 ? void 0 : options.timeout,
+    asyncTimeout: options === null || options === void 0 ? void 0 : options.asyncTimeout,
+    returnData: options === null || options === void 0 ? void 0 : options.returnData,
+    headers: options === null || options === void 0 ? void 0 : options.headers,
+    allowedOrigins: options === null || options === void 0 ? void 0 : options.allowedOrigins,
+    validateOrigin: options === null || options === void 0 ? void 0 : options.validateOrigin
+  }, instanceId);
+
+  // If trace mode is enabled, register debug interceptors
+  if (options !== null && options !== void 0 && options.trace) {
+    setupClientDebugInterceptors(client);
+  }
+  return client;
+}
+
+/**
+ * Clear MessageChannel cache (for testing or reset)
+ * Note: This clears the shared message channel for the specified secretKey
+ */
+export function clearRequestIframeClientCache(secretKey) {
+  // Now client is no longer cached, only need to clear MessageChannel cache
+  // MessageChannel cleanup is handled by clearMessageChannelCache in cache.ts
+  // Empty implementation kept here to maintain API compatibility
+  void secretKey;
+}

package/esm/api/server.js

@@ -0,0 +1,61 @@
+import { RequestIframeServerImpl } from '../core/server';
+import { setupServerDebugListeners } from '../utils/debug';
+import { getCachedServer, cacheServer, clearServerCache } from '../utils/cache';
+
+/**
+ * Create a server (for receiving and handling requests)
+ * 
+ * Note:
+ * - MessageChannel is cached at the window level by secretKey (ensures unique message listener)
+ * - If options.id is specified, the server will be cached and reused (singleton pattern)
+ * - If options.id is not specified, a new instance is created on each call
+ * - This allows different versions of the library to coexist
+ */
+export function requestIframeServer(options) {
+  // Determine secretKey and id
+  var secretKey = options === null || options === void 0 ? void 0 : options.secretKey;
+  var id = options === null || options === void 0 ? void 0 : options.id;
+
+  // If id is specified, check cache first
+  if (id) {
+    var cached = getCachedServer(secretKey, id);
+    if (cached) {
+      return cached;
+    }
+  }
+
+  // Create server (internally obtains or creates a shared MessageChannel)
+  var server = new RequestIframeServerImpl({
+    secretKey,
+    id,
+    ackTimeout: options === null || options === void 0 ? void 0 : options.ackTimeout,
+    autoOpen: options === null || options === void 0 ? void 0 : options.autoOpen,
+    allowedOrigins: options === null || options === void 0 ? void 0 : options.allowedOrigins,
+    validateOrigin: options === null || options === void 0 ? void 0 : options.validateOrigin,
+    maxConcurrentRequestsPerClient: options === null || options === void 0 ? void 0 : options.maxConcurrentRequestsPerClient,
+    autoAckMaxMetaLength: options === null || options === void 0 ? void 0 : options.autoAckMaxMetaLength,
+    autoAckMaxIdLength: options === null || options === void 0 ? void 0 : options.autoAckMaxIdLength
+  });
+
+  // If trace mode is enabled, register debug listeners
+  if (options !== null && options !== void 0 && options.trace) {
+    setupServerDebugListeners(server);
+  }
+
+  // Cache server if id is specified
+  if (id) {
+    cacheServer(server, secretKey, id);
+  }
+  return server;
+}
+
+/**
+ * Clear server cache (for testing or reset)
+ * Note: This clears the cached server instances
+ */
+export function clearRequestIframeServerCache(secretKey) {
+  // Clear server cache
+  clearServerCache();
+  // MessageChannel cleanup is handled by clearMessageChannelCache in cache.ts
+  void secretKey;
+}