chrome-in-iframe 1.0.1 → 2.0.1

package/README.md

@@ -8,6 +8,20 @@ Bridge Chrome extension APIs from a Chrome extension page into an embedded ifram
 
 This is useful when an extension page such as `options.html`, `popup.html`, or another `chrome-extension://...` page embeds an iframe, but the iframe itself cannot directly access Chrome extension APIs.
 
+## Module Format
+
+**This package is ESM-only.** It ships a single ECMAScript module and exposes no CommonJS entry point. Use it from an ESM project (Vite, Rollup, webpack 5+, Parcel 2+, modern bundlers, or native `<script type="module">`).
+
+`require('chrome-in-iframe')` will not work.
+
+```json
+{
+  "type": "module"
+}
+```
+
+If your tooling still emits CommonJS, configure it to leave `chrome-in-iframe` as an ESM external, or migrate the consuming project to ESM.
+
 ## Install
 
 ```bash
@@ -133,9 +147,9 @@ window.addEventListener('beforeunload', () => {
 
 ## Security Options
 
-`targetOrigin` and `allowedOrigin` are optional. If omitted, messages are sent with `'*'` and incoming messages are only checked against the expected iframe or parent window source (via `MessageEvent.source`).
+`targetOrigin` and `allowedOrigin` are optional. When `targetOrigin` is not supplied, the library resolves it from `iframe.src` / `contentWindow.location.origin` (on the extension side) or from `document.referrer` / `location.ancestorOrigins` (on the iframe side); it only falls back to `'*'` when none of those are available. Incoming messages are checked against both the expected window source and, by default, the same origin resolved for `targetOrigin`.
 
-> **Warning**: When both sides are Chrome extension pages under the same `chrome-extension://` origin, the default behavior is safe. However, if your iframe loads a **third-party page** or a page from a **different origin**, leaving `allowedOrigin` unset means **any window** can send forged `postMessage` messages and impersonate Chrome API calls. In that case, always set `allowedOrigin` to the expected origin.
+> **Warning**: If origin auto-detection cannot resolve a concrete origin and falls back to `'*'`, incoming messages from the expected window source are allowed from any origin. For third-party iframes, navigable iframes, or any page from a different origin, pass explicit `targetOrigin` and `allowedOrigin`.
 
 For production, pass origins when you know them.
 
@@ -160,6 +174,17 @@ const { chrome } = connectChromeInIframe({
 });
 ```
 
+## Data Types Across the Bridge
+
+The bridge serializes `undefined`, `null`, all primitive types (including `bigint`, `NaN`, `Infinity`, `-0`), plain objects (string- and symbol-keyed), arrays, functions, `Error` (preserves `name`, `stack`, and `cause`), `Date`, `RegExp`, `Map`, and `Set`. Circular references throw.
+
+A few inherent limitations of any RPC-style bridge:
+
+- **Object identity is not preserved.** A `Date`, `Map`, `Set`, or plain object that crosses the bridge is reconstructed on the other side. `===` between the original and the round-tripped value is `false`.
+- **Map / Set keyed on objects loses lookup.** If you put a `Date` (or any object) into a `Map` and send the `Map` across, `map.get(originalDate)` on the receiving side does **not** find it — the deserialized `Map` holds a different `Date` instance. Key on strings or numbers when the `Map` is meant to travel.
+- **Non-global symbols cannot cross.** Use `Symbol.for(...)` or a well-known symbol; ad-hoc `Symbol('local')` throws on serialization.
+- **Class prototypes are erased.** A `class Foo { ... }` instance arrives as a plain object with the same enumerable properties. `instanceof Foo` is `false`.
+
 ## Reading Properties
 
 Chrome API methods can be called directly:
@@ -168,13 +193,54 @@ Chrome API methods can be called directly:
 const tabs = await chrome.tabs.query({ active: true });
 ```
 
-Readable properties should be read through `get()` or `$get()`:
+Readable properties — anything that is not a function call — should be read through `get()` (returned from `connectChromeInIframe`) or `$get()` (available on every proxy node).
+
+### Path Forms
+
+`$get` / `get` accept three equivalent shapes for the path:
 
 ```ts
-const extensionId = await get<string>('runtime.id');
-const platformOs = await chrome.runtime.$get<string>('PlatformOs');
+// 1. Array form (recommended) — each segment is taken verbatim
+await get<string>(['runtime', 'id']);
+
+// 2. Multiple string arguments — each argument is one segment
+await get<string>('runtime', 'id');
+
+// 3. Single dotted string — split on `.`
+await get<string>('runtime.id');
 ```
 
+You can also start from a nested proxy node:
+
+```ts
+await chrome.runtime.$get<string>('id');
+await chrome.runtime.$get<string>(['id']);
+```
+
+Symbols are allowed as path keys (must be `Symbol.for(...)` or a well-known symbol so identity survives the wire):
+
+```ts
+const queryKey = Symbol.for('queryBySymbol');
+await get(queryKey);
+```
+
+### Dotted Keys: Use the Array Form
+
+The dotted-string form is convenient, but it **splits on every `.` it finds**, so it cannot address keys that contain a dot — for example `chrome.storage.local`'s users sometimes store entries under names like `'user.email'` or `'flag.v2'`. To address those safely, use the array form (or pass each segment as its own argument):
+
+```ts
+// ❌ Wrong — the dotted form would try to read `local.user.email`
+await get('storage.local.user.email');
+
+// ✅ Correct — the array form treats `user.email` as a single key
+await get(['storage', 'local', 'user.email']);
+
+// ✅ Also correct — multiple arguments are kept verbatim
+await get('storage', 'local', 'user.email');
+```
+
+Rule of thumb: **prefer the array form whenever the path is dynamic or comes from data you don't fully control.** Reserve the dotted-string form for short, hand-written, static lookups.
+
 ## API
 
 ### `exposeChromeInIframe(options)`
@@ -188,6 +254,11 @@ const bridge = exposeChromeInIframe({
   targetOrigin,
   allowedOrigin,
   chromeApi,
+  timeout,
+  functionCacheMax,
+  functionCacheTtl,
+  remoteCallbackCacheMax,
+  remoteCallbackCacheTtl,
 });
 ```
 
@@ -195,15 +266,18 @@ Options:
 
 - `iframe`: the iframe element to bridge.
 - `key`: optional shared bridge key. Use the same key on both sides.
-- `targetOrigin`: optional origin used by `postMessage`.
-- `allowedOrigin`: optional origin, origin list, or predicate used to filter incoming messages.
+- `targetOrigin`: optional origin used by `postMessage`. Falls back to a value resolved from `iframe.src`.
+- `allowedOrigin`: optional origin, origin list, or predicate used to filter incoming messages. Defaults to the resolved `targetOrigin` when it is a concrete origin.
 - `chromeApi`: optional custom Chrome-like object. Defaults to `globalThis.chrome`.
+- `timeout`: optional per-call timeout in ms (default `30000`).
+- `functionCacheMax` / `functionCacheTtl`: tune the LRU that stores non-persistent callbacks the local side has sent.
+- `remoteCallbackCacheMax` / `remoteCallbackCacheTtl`: tune the LRU that stores callbacks the remote side has handed to us.
 
 Returns:
 
 - `proxy`: the bridged Chrome API proxy.
-- `get(path)`: read a property from the bridged Chrome API.
-- `destroy()`: remove message listeners and clear bridge state.
+- `get(path)`: read a property from the bridged Chrome API. See [Path Forms](#path-forms).
+- `destroy()`: remove message listeners, clear bridge state, and tell the remote peer to release any callbacks it is holding on our behalf.
 
 ### `connectChromeInIframe(options)`
 
@@ -214,6 +288,11 @@ const { chrome, get, destroy } = connectChromeInIframe({
   key,
   targetOrigin,
   allowedOrigin,
+  timeout,
+  functionCacheMax,
+  functionCacheTtl,
+  remoteCallbackCacheMax,
+  remoteCallbackCacheTtl,
 });
 ```
 
@@ -221,6 +300,21 @@ Returns:
 
 - `chrome`: a proxy for the extension page's Chrome API.
 - `proxy`: the same object as `chrome`.
-- `get(path)`: read a property from the bridged Chrome API.
-- `destroy()`: remove message listeners and clear bridge state.
+- `get(path)`: read a property from the bridged Chrome API. See [Path Forms](#path-forms).
+- `destroy()`: remove message listeners, clear bridge state, and notify the remote peer.
+
+### `setLogger(logger)`
+
+Customize or silence library warnings. All internal warnings carry a `[chrome-in-iframe]` prefix and a scope tag.
 
+```ts
+import { setLogger } from 'chrome-in-iframe';
+
+// Silence all warnings
+setLogger(null);
+
+// Route warnings to a custom sink (e.g. Sentry)
+setLogger((scope, ...args) => {
+  captureMessage(`[chrome-in-iframe] ${scope}`, { extra: { args } });
+});
+```

package/README.zh-CN.md

@@ -8,6 +8,20 @@
 
 当扩展页面（如 `options.html`、`popup.html` 或其他 `chrome-extension://...` 页面）嵌入了 iframe，但 iframe 本身无法直接访问 Chrome 扩展 API 时，这个库非常有用。
 
+## 模块格式
+
+**本包只提供 ESM。** 发布产物是单个 ECMAScript 模块，没有 CommonJS 入口。请在 ESM 项目中使用（Vite、Rollup、webpack 5+、Parcel 2+、其他现代打包器，或浏览器原生 `<script type="module">`）。
+
+`require('chrome-in-iframe')` 无法工作。
+
+```json
+{
+  "type": "module"
+}
+```
+
+如果你的构建工具仍然产出 CommonJS，请将 `chrome-in-iframe` 配置为 ESM external，或将消费方项目迁移到 ESM。
+
 ## 安装
 
 ```bash
@@ -133,11 +147,11 @@ window.addEventListener('beforeunload', () => {
 
 ## 安全选项
 
-`targetOrigin` 和 `allowedOrigin` 是可选的。如果省略，消息将使用 `'*'` 发送，传入的消息仅通过 `MessageEvent.source` 与预期的 iframe 或父窗口进行校验。
+`targetOrigin` 和 `allowedOrigin` 是可选的。当不传 `targetOrigin` 时，库会自动从 `iframe.src` / `contentWindow.location.origin`（扩展侧）或 `document.referrer` / `location.ancestorOrigins`（iframe 侧）推导出 origin；只有在以上来源都不可用时才回退到 `'*'`。传入的消息默认同时校验预期的 window source，以及为 `targetOrigin` 推导出的同一个 origin。
 
-> **警告**：当两侧都是同一 `chrome-extension://` origin 下的 Chrome 扩展页面时，默认行为是安全的。但如果 iframe 加载的是**第三方页面**或来自**不同 origin** 的页面，不设置 `allowedOrigin` 意味着**任何窗口**都可以发送伪造的 `postMessage` 消息来冒充 Chrome API 调用。在这种情况下，务必将 `allowedOrigin` 设置为预期的 origin。
+> **警告**：如果自动推导无法得到具体 origin 并回退到 `'*'`，来自预期 window source 的传入消息会允许任意 origin。对于第三方 iframe、可能被导航的 iframe，或任何不同 origin 的页面，请显式传入 `targetOrigin` 和 `allowedOrigin`。
 
-在生产环境中，如果知道具体来源，建议传入 origin。
+在生产环境中，如果知道具体来源，建议显式传入 origin。
 
 ### 扩展页面
 
@@ -160,6 +174,17 @@ const { chrome } = connectChromeInIframe({
 });
 ```
 
+## 跨桥的数据类型
+
+桥接层支持 `undefined`、`null`、所有原始类型（含 `bigint`、`NaN`、`Infinity`、`-0`）、普通对象（字符串键和 symbol 键都行）、数组、函数、`Error`（保留 `name`、`stack`、`cause`）、`Date`、`RegExp`、`Map`、`Set`。循环引用会抛错。
+
+任何 RPC 桥接都有的固有限制：
+
+- **对象身份不被保留。** 跨桥的 `Date`、`Map`、`Set`、普通对象会在对端被重新构造。原对象和往返后的对象之间 `===` 为 `false`。
+- **以对象为 key 的 Map / Set 会丢失查找能力。** 把 `Date`（或任何对象）作为 `Map` 的 key，跨桥之后，对端 `map.get(originalDate)` 找不到 —— 反序列化得到的 `Map` 里持有的是另一个 `Date` 实例。需要跨桥传输的 `Map`，请用字符串或数字作 key。
+- **非全局 symbol 不能跨桥。** 用 `Symbol.for(...)` 或 well-known symbol；临时 `Symbol('local')` 在序列化时抛错。
+- **类原型会被擦除。** `class Foo { ... }` 的实例到对端只是一个普通对象，只保留可枚举字段；`instanceof Foo` 为 `false`。
+
 ## 读取属性
 
 Chrome API 方法可以直接调用：
@@ -168,13 +193,54 @@ Chrome API 方法可以直接调用：
 const tabs = await chrome.tabs.query({ active: true });
 ```
 
-可读属性应通过 `get()` 或 `$get()` 读取：
+非函数的可读属性应通过 `get()`（由 `connectChromeInIframe` 返回）或代理上任意节点的 `$get()` 读取。
+
+### 路径形式
+
+`$get` / `get` 支持三种等价的路径写法：
 
 ```ts
-const extensionId = await get<string>('runtime.id');
-const platformOs = await chrome.runtime.$get<string>('PlatformOs');
+// 1. 数组形式（推荐）—— 每个元素都被视为单独一段
+await get<string>(['runtime', 'id']);
+
+// 2. 多参数字符串 —— 每个参数都是单独一段
+await get<string>('runtime', 'id');
+
+// 3. 单个带 `.` 的字符串 —— 按 `.` 自动拆分
+await get<string>('runtime.id');
+```
+
+也可以从代理的中间节点开始：
+
+```ts
+await chrome.runtime.$get<string>('id');
+await chrome.runtime.$get<string>(['id']);
+```
+
+Symbol 也可以作为路径片段（必须是 `Symbol.for(...)` 或 well-known symbol，以便在序列化后仍能保持身份）：
+
+```ts
+const queryKey = Symbol.for('queryBySymbol');
+await get(queryKey);
 ```
 
+### 含 `.` 的键：请用数组形式
+
+字符串带 `.` 的写法很方便，但会**对每一个 `.` 都做拆分**，所以无法访问 key 本身就包含 `.` 的属性 —— 例如 `chrome.storage.local` 的使用者经常会存 `'user.email'`、`'flag.v2'` 这类条目。要安全访问它们，必须改用数组形式（或把每段当作独立参数传）：
+
+```ts
+// ❌ 错误 —— 字符串形式会把它当作 `local → user → email` 三段
+await get('storage.local.user.email');
+
+// ✅ 正确 —— 数组形式把 `user.email` 当作一段
+await get(['storage', 'local', 'user.email']);
+
+// ✅ 也正确 —— 多参数形式同样保留原样
+await get('storage', 'local', 'user.email');
+```
+
+经验法则：**路径只要是动态的，或者来自不完全可控的数据源，就用数组形式。** 字符串带 `.` 的形式留给短小、手写、静态的查询。
+
 ## API
 
 ### `exposeChromeInIframe(options)`
@@ -188,22 +254,30 @@ const bridge = exposeChromeInIframe({
   targetOrigin,
   allowedOrigin,
   chromeApi,
+  timeout,
+  functionCacheMax,
+  functionCacheTtl,
+  remoteCallbackCacheMax,
+  remoteCallbackCacheTtl,
 });
 ```
 
 选项：
 
 - `iframe`：要桥接的 iframe 元素。
-- `key`：可选的共享桥接密钥。两侧使用相同的 key。
-- `targetOrigin`：可选，`postMessage` 使用的 origin。
-- `allowedOrigin`：可选，用于过滤传入消息的 origin、origin 列表或判断函数。
+- `key`：可选的共享桥接 key。两侧使用相同的 key。
+- `targetOrigin`：可选，`postMessage` 使用的 origin。不传时由 `iframe.src` 推导。
+- `allowedOrigin`：可选，用于过滤传入消息；可以是 origin、origin 列表或判断函数。默认使用解析后的 `targetOrigin`（当它是具体 origin 时）。
 - `chromeApi`：可选，自定义的 Chrome API 对象。默认为 `globalThis.chrome`。
+- `timeout`：可选，单次调用的超时时长（毫秒，默认 `30000`）。
+- `functionCacheMax` / `functionCacheTtl`：调整本端发出的非持久 callback 的 LRU 缓存。
+- `remoteCallbackCacheMax` / `remoteCallbackCacheTtl`：调整对端发给本端的 callback 的 LRU 缓存。
 
 返回值：
 
 - `proxy`：桥接后的 Chrome API 代理。
-- `get(path)`：从桥接的 Chrome API 中读取属性。
-- `destroy()`：移除消息监听器并清除桥接状态。
+- `get(path)`：从桥接的 Chrome API 中读取属性。详见 [路径形式](#路径形式)。
+- `destroy()`：移除消息监听器，清理桥接状态，并通知对端释放它为我们持有的 callback。
 
 ### `connectChromeInIframe(options)`
 
@@ -214,6 +288,11 @@ const { chrome, get, destroy } = connectChromeInIframe({
   key,
   targetOrigin,
   allowedOrigin,
+  timeout,
+  functionCacheMax,
+  functionCacheTtl,
+  remoteCallbackCacheMax,
+  remoteCallbackCacheTtl,
 });
 ```
 
@@ -221,5 +300,21 @@ const { chrome, get, destroy } = connectChromeInIframe({
 
 - `chrome`：扩展页面 Chrome API 的代理。
 - `proxy`：与 `chrome` 相同的对象。
-- `get(path)`：从桥接的 Chrome API 中读取属性。
-- `destroy()`：移除消息监听器并清除桥接状态。
+- `get(path)`：从桥接的 Chrome API 中读取属性。详见 [路径形式](#路径形式)。
+- `destroy()`：移除消息监听器，清理桥接状态，并通知对端。
+
+### `setLogger(logger)`
+
+自定义或静默库内警告。所有内部警告均带有 `[chrome-in-iframe]` 前缀和 scope 标签。
+
+```ts
+import { setLogger } from 'chrome-in-iframe';
+
+// 静默所有警告
+setLogger(null);
+
+// 将警告路由到自定义 sink（如 Sentry）
+setLogger((scope, ...args) => {
+  captureMessage(`[chrome-in-iframe] ${scope}`, { extra: { args } });
+});
+```

package/dist/api.d.ts

@@ -11,6 +11,10 @@ export interface ConnectionOptions {
     timeout?: number;
     targetOrigin?: string;
     allowedOrigin?: AllowedOrigin;
+    functionCacheMax?: number;
+    functionCacheTtl?: number;
+    remoteCallbackCacheMax?: number;
+    remoteCallbackCacheTtl?: number;
 }
 export interface SetupInMainWindowOptions<T = unknown> extends ConnectionOptions {
     iframe: HTMLIFrameElement;

package/dist/channel/channel.d.ts

@@ -1,3 +1,3 @@
 import type { ProcessorRegistry } from '../processor/registry';
 import type { ClientContext, MessageChannel, MessagePoster } from './types';
-export declare function createMessageChannel(poster: MessagePoster, key: string, context: ClientContext, processorRegistry: ProcessorRegistry): MessageChannel;
+export declare function createMessageChannel(poster: MessagePoster, key: string, instanceId: string, context: ClientContext, processorRegistry: ProcessorRegistry): MessageChannel;

package/dist/channel/deserializer.d.ts

@@ -1,2 +1,4 @@
 import type { Callable, CallbackCacheOptions, MessageValue } from './types';
-export declare function deserialize(arg: MessageValue, generateCallback: (id: string, args: MessageValue[], options?: CallbackCacheOptions) => MessageValue, getRemoteCallback?: (id: string, invoke: (args: MessageValue[]) => void, options?: CallbackCacheOptions) => Callable, options?: CallbackCacheOptions): MessageValue;
+export type GenerateCallbackFn = (id: string, args: MessageValue[], options?: CallbackCacheOptions) => MessageValue;
+export type GetRemoteCallbackFn = (id: string, invoke: (args: MessageValue[]) => MessageValue, options?: CallbackCacheOptions) => Callable;
+export declare function deserialize(arg: MessageValue, generateCallback: GenerateCallbackFn, getRemoteCallback?: GetRemoteCallbackFn): MessageValue;

package/dist/channel/listener.d.ts

@@ -1,3 +1,4 @@
-import type { MessageValue, PathKey } from './types';
+import type { PathKey } from './types';
 export declare function isListenerRegistrationPath(path: PathKey[]): boolean;
-export declare function isLikelyListenerPath(path: PathKey[], value?: MessageValue): boolean;
+export declare function isListenerRemovalPath(path: PathKey[]): boolean;
+export declare function isLikelyListenerPath(path: PathKey[]): boolean;

package/dist/channel/sender.d.ts

@@ -1,2 +1,2 @@
 import type { MessagePoster, MessageSender } from './types';
-export declare function createMessageSender(poster: MessagePoster, key: string): MessageSender;
+export declare function createMessageSender(poster: MessagePoster, key: string, instanceId: string): MessageSender;

package/dist/channel/serializer.d.ts

@@ -1,2 +1,4 @@
 import type { Callable, CallbackCacheOptions, MessageValue } from './types';
-export declare function serialize(arg: MessageValue, registerFunction: (fn: Callable, options?: CallbackCacheOptions) => string, options?: CallbackCacheOptions): MessageValue;
+export declare const TYPE_KEY = "$cii$";
+export type RegisterFunctionFn = (fn: Callable, thisArg: MessageValue, options?: CallbackCacheOptions) => string;
+export declare function serialize(arg: MessageValue, registerFunction: RegisterFunctionFn, options?: CallbackCacheOptions): MessageValue;

package/dist/channel/types.d.ts

@@ -40,12 +40,20 @@ export interface Messages {
         data?: MessageValue;
         error?: SerializedError;
     };
+    releaseCallbacks: {
+        ids: string[];
+    };
+    destroyEndpoint: {
+        instanceId: string;
+    };
 }
 export type MessageType = keyof Messages;
 export type MessageBody<K extends MessageType = MessageType> = {
     type: K;
     key: string;
     data: Messages[K];
+    senderInstanceId: string;
+    targetInstanceId?: string;
 };
 export interface MessagePoster {
     postMessage(message: string): void;
@@ -56,36 +64,51 @@ export interface PromiseCallbacks {
     resolve: (value: MessageValue) => void;
     reject: (reason: MessageValue) => void;
     timer: ReturnType<typeof setTimeout>;
+    onResolve?: () => void;
+    onReject?: () => void;
 }
 export interface ClientContext {
     getDelegateTarget(): MessageValue;
     getMessageChannel(): MessageChannel;
-    getFunctionCache(): LRUCache<string, Callable>;
-    getPersistentFunctionCache(): Map<string, Callable>;
-    registerFunction(fn: Callable, options?: CallbackCacheOptions): string;
-    getRemoteCallback(id: string, invoke: (args: MessageValue[]) => MessageValue, options?: CallbackCacheOptions): Callable;
+    getInstanceId(): string;
+    getFunctionCache(): LRUCache<string, CallbackEntry>;
+    getPersistentFunctionCache(): Map<string, CallbackEntry>;
+    registerFunction(fn: Callable, thisArg: MessageValue, options?: CallbackCacheOptions): string;
+    getRemoteCallback(id: string, invoke: (args: MessageValue[]) => MessageValue, options: CallbackCacheOptions | undefined, remoteInstanceId: string): Callable;
     getAndRemovePendingPromise(id: RequestId): PromiseCallbacks | undefined;
     invoke(path: PathKey[], args: MessageValue[]): Promise<MessageValue>;
     accessProperty(path: PathKey[]): Promise<MessageValue>;
     invokeFunctionById(id: string, args: MessageValue[], options?: CallbackCacheOptions): Promise<MessageValue>;
-    registerPendingPromise(id: RequestId, callbacks: PromiseCallbacks): void;
-    destroy(): void;
+    handleRemoteDestroy(instanceId: string): void;
+    releaseRemoteCallbacks(remoteInstanceId: string, ids: readonly string[]): void;
+    dropLocalCallback(id: string): void;
+    bindMethod(fn: Callable, owner: MessageValue): Callable;
+    /** @internal Exposed for tests; do not use in application code. */
+    getRemoteCallbackCounts(remoteInstanceId: string): {
+        lru: number;
+        persistent: number;
+    };
+    destroy(notifyRemote?: boolean): void;
 }
 export interface CallbackCacheOptions {
     persistent?: boolean;
 }
+export interface CallbackEntry {
+    fn: Callable;
+    thisArg: MessageValue;
+}
 export interface MessageChannel {
     getSender(): MessageSender;
-    getContext(): ClientContext;
-    getPoster(): MessagePoster;
-    getKey(): string;
     destroy(): void;
 }
 export interface MessageSender {
-    sendMessage<K extends MessageType>(type: K, data: Messages[K]): void;
+    sendMessage<K extends MessageType>(type: K, data: Messages[K], targetInstanceId?: string): void;
 }
 export interface RequestHandler<K extends MessageType = MessageType> {
-    (data: Messages[K], ctx: ClientContext): void;
+    (data: Messages[K], ctx: ClientContext, meta: MessageMeta): void;
+}
+export interface MessageMeta {
+    senderInstanceId: string;
 }
 export type ProxyNode = {
     parent?: ProxyNode;

package/dist/channel/utils.d.ts

@@ -3,3 +3,4 @@ export declare const WELL_KNOWN_SYMBOLS: Record<string, symbol>;
 export declare function getWellKnownSymbolName(value: symbol): string | undefined;
 export declare function getWellKnownSymbol(name: string): symbol | undefined;
 export declare function serializeThrownError(err: unknown): SerializedError;
+export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;

package/dist/client/context.d.ts

@@ -2,5 +2,9 @@ import type { ClientContext, MessageChannel, MessageValue } from '../channel/typ
 export interface ClientContextOptions {
     delegateTarget?: MessageValue;
     timeout?: number;
+    functionCacheMax?: number;
+    functionCacheTtl?: number;
+    remoteCallbackCacheMax?: number;
+    remoteCallbackCacheTtl?: number;
 }
-export declare function createClientContext(getMessageChannel: () => MessageChannel, options?: ClientContextOptions): ClientContext;
+export declare function createClientContext(getMessageChannel: () => MessageChannel, instanceId: string, options?: ClientContextOptions): ClientContext;

package/dist/client/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { MessagePoster } from '../channel/types';
+import type { ClientContext, MessagePoster } from '../channel/types';
 import { type ClientContextOptions } from './context';
 export interface EndpointOptions {
     poster: MessagePoster;
@@ -8,5 +8,7 @@ export interface EndpointOptions {
 export interface Endpoint<TProxy = unknown> {
     proxy: TProxy;
     destroy: () => void;
+    /** @internal Exposed for tests; do not use in application code. */
+    getContext: () => ClientContext;
 }
 export declare function createEndpoint<TProxy = unknown>(options: EndpointOptions): Endpoint<TProxy>;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { connectChromeInIframe, exposeChromeInIframe, setupInIframe, setupInMainWindow } from './api';
+export { setLogger } from './log';
+export type { Logger } from './log';
 export type { AllowedOrigin, PropertyAccess, PropertyPathPart, ConnectionHandle, ChromeIframeHandle, ExposeChromeInIframeOptions, SetupInIframeOptions, SetupInMainWindowOptions, ConnectionOptions, } from './api';
 export type { Messages, MessageType, MessageBody, MessagePoster, ClientContext, MessageChannel, MessageSender, ProxyNode, ListenerCallback, SerializedError, } from './channel/types';