chrome-in-iframe 2.0.0 → 2.1.0

package/README.zh-CN.md

@@ -10,17 +10,17 @@
 
 ## 模块格式
 
-**本包只提供 ESM。** 发布产物是单个 ECMAScript 模块，没有 CommonJS 入口。请在 ESM 项目中使用（Vite、Rollup、webpack 5+、Parcel 2+、其他现代打包器，或浏览器原生 `<script type="module">`）。
+本包同时提供 ESM 和 CommonJS 入口。现代打包器和原生模块代码会自动使用 ESM 入口；CommonJS 消费方可以使用 `require()`。
 
-`require('chrome-in-iframe')` 无法工作。
+```ts
+import { connectChromeInIframe, exposeChromeInIframe } from 'chrome-in-iframe';
+```
 
-```json
-{
-  "type": "module"
-}
+```js
+const { connectChromeInIframe, exposeChromeInIframe } = require('chrome-in-iframe');
 ```
 
-如果你的构建工具仍然产出 CommonJS，请将 `chrome-in-iframe` 配置为 ESM external，或将消费方项目迁移到 ESM。
+CommonJS 构建会按浏览器条件解析依赖，因此仍可被打包到 Chrome 扩展页面和 iframe 中使用。
 
 ## 安装
 
@@ -147,11 +147,13 @@ window.addEventListener('beforeunload', () => {
 
 ## 安全选项
 
-`targetOrigin` 和 `allowedOrigin` 是可选的。当不传 `targetOrigin` 时，库会自动从 `iframe.src` / `contentWindow.location.origin`（扩展侧）或 `document.referrer` / `location.ancestorOrigins`（iframe 侧）推导出 origin；只有在以上来源都不可用时才回退到 `'*'`。传入的消息还会通过预期的 window source 进行校验。
+`targetOrigin` 和 `allowedOrigin` 是可选的。当不传 `targetOrigin` 时,库会自动从 `iframe.src` / `contentWindow.location.origin`(扩展侧)或 `document.referrer` / `location.ancestorOrigins`(iframe 侧)推导出 origin;只有在以上来源都不可用时才回退到 `'*'`。传入的消息默认同时校验预期的 window source,以及为 `targetOrigin` 推导出的同一个 origin;当 `targetOrigin` 解析失败回退到 `'*'` 时,`allowedOrigin` 默认收紧为 `event.origin === window.location.origin`(同源限制),而不是接受任意 origin。
 
-> **警告**：当两侧都是同一 `chrome-extension://` origin 下的 Chrome 扩展页面时，默认行为是安全的。但如果 iframe 加载的是**第三方页面**或来自**不同 origin** 的页面，不设置 `allowedOrigin` 意味着**任何能向页面发送消息的窗口**都可以伪造 `postMessage` 来冒充 Chrome API 调用。在这种情况下，务必将 `allowedOrigin` 设置为预期的 origin。
+> **提示**:`'*'` 回退仅影响 `postMessage` 出去的 `targetOrigin`(可能被中间人窥探),不会让任意 origin 的消息打进来。对于第三方 iframe、可能被导航的 iframe,或任何不同 origin 的页面,仍建议显式传入 `targetOrigin` 和 `allowedOrigin`,以便消息可以发往明确的目标 origin。
 
-在生产环境中，如果知道具体来源，建议显式传入 origin。
+> **注意**:`targetOrigin` 的自动推导结果会被冻结(`freezeResolvedOrigin`),首次成功解析后不会再变;但首次解析回退到 `'*'` 时不冻结,下次调用会重试,以兼容「先 `createElement('iframe')` 再设 `src`」这种常见模式。
+
+在生产环境中,如果知道具体来源,建议显式传入 origin。
 
 ### 扩展页面
 
@@ -180,10 +182,10 @@ const { chrome } = connectChromeInIframe({
 
 任何 RPC 桥接都有的固有限制：
 
-- **对象身份不被保留。** 跨桥的 `Date`、`Map`、`Set`、普通对象会在对面被重新构造。原对象和 round-trip 后的对象之间 `===` 为 `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`。
+- **对象身份不被保留。** 跨桥的 `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`。
 
 ## 读取属性
 
@@ -267,11 +269,11 @@ const bridge = exposeChromeInIframe({
 - `iframe`：要桥接的 iframe 元素。
 - `key`：可选的共享桥接 key。两侧使用相同的 key。
 - `targetOrigin`：可选，`postMessage` 使用的 origin。不传时由 `iframe.src` 推导。
-- `allowedOrigin`：可选，用于过滤传入消息的 origin、origin 列表或判断函数。
+- `allowedOrigin`:可选,用于过滤传入消息;可以是 origin、origin 列表或判断函数。默认情况下:解析后的 `targetOrigin` 是具体 origin 时,使用它;若回退到 `'*'`,则收紧为同源限制(`event.origin === window.location.origin`)。
 - `chromeApi`：可选，自定义的 Chrome API 对象。默认为 `globalThis.chrome`。
 - `timeout`：可选，单次调用的超时时长（毫秒，默认 `30000`）。
-- `functionCacheMax` / `functionCacheTtl`：调整本地存储的非持久 callback LRU。
-- `remoteCallbackCacheMax` / `remoteCallbackCacheTtl`：调整对端交给我们的 callback LRU。
+- `functionCacheMax` / `functionCacheTtl`：调整本端发出的非持久 callback 的 LRU 缓存。
+- `remoteCallbackCacheMax` / `remoteCallbackCacheTtl`：调整对端发给本端的 callback 的 LRU 缓存。
 
 返回值：
 
@@ -302,3 +304,19 @@ const { chrome, get, destroy } = connectChromeInIframe({
 - `proxy`：与 `chrome` 相同的对象。
 - `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,7 @@ export interface ConnectionOptions {
     timeout?: number;
     targetOrigin?: string;
     allowedOrigin?: AllowedOrigin;
+    strictOrigin?: boolean;
     functionCacheMax?: number;
     functionCacheTtl?: number;
     remoteCallbackCacheMax?: number;
@@ -29,6 +30,7 @@ export interface ConnectionHandle<T> {
     proxy: T & PropertyAccess;
     get: PropertyAccess['$get'];
     destroy: () => void;
+    isDestroyed: () => boolean;
 }
 export interface ChromeIframeHandle<T = ChromeApi> extends ConnectionHandle<T> {
     chrome: T & PropertyAccess;

package/dist/channel/channel.d.ts

@@ -1,3 +1,7 @@
-import type { ProcessorRegistry } from '../processor/registry';
-import type { ClientContext, MessageChannel, MessagePoster } from './types';
+import type { ProcessorRegistry } from '../processor/registry.js';
+import type { ClientContext, MessageChannel, MessagePoster } from './types.js';
+export declare const MAX_PATH_LENGTH = 64;
+export declare const MAX_INVOKE_ARGS = 1024;
+export declare const MAX_MESSAGE_LENGTH = 1000000;
+export declare const MAX_RELEASE_IDS = 10000;
 export declare function createMessageChannel(poster: MessagePoster, key: string, instanceId: string, context: ClientContext, processorRegistry: ProcessorRegistry): MessageChannel;

package/dist/channel/deserializer.d.ts

@@ -1,4 +1,10 @@
-import type { Callable, CallbackCacheOptions, MessageValue } from './types';
+import type { Callable, CallbackCacheOptions, MessageValue } from './types.js';
 export type GenerateCallbackFn = (id: string, args: MessageValue[], options?: CallbackCacheOptions) => MessageValue;
 export type GetRemoteCallbackFn = (id: string, invoke: (args: MessageValue[]) => MessageValue, options?: CallbackCacheOptions) => Callable;
+export declare const MAX_DESERIALIZE_DEPTH = 200;
 export declare function deserialize(arg: MessageValue, generateCallback: GenerateCallbackFn, getRemoteCallback?: GetRemoteCallbackFn): MessageValue;
+export declare function rebuildErrorFromSerialized(serialized: {
+    message: string;
+    name?: string;
+    stack?: string;
+}): Error;

package/dist/channel/listener.d.ts

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

package/dist/channel/path.d.ts

@@ -1,4 +1,4 @@
-import type { PathKey } from './types';
+import type { PathKey } from './types.js';
 type SerializedSymbolPathKey = {
     $type: 'symbol';
     value: string;

package/dist/channel/sender.d.ts

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

package/dist/channel/serializer.d.ts

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

package/dist/channel/types.d.ts

@@ -7,10 +7,22 @@ export type SerializedError = {
     message: string;
     stack?: string;
 };
+export declare const TRANSPORT_DETACHED: unique symbol;
+export interface TransportDetachedError extends Error {
+    [TRANSPORT_DETACHED]: true;
+}
+export declare function isTransportDetachedError(err: unknown): err is TransportDetachedError;
+export declare function createTransportDetachedError(message: string): TransportDetachedError;
 export type ListenerCallback = (event: {
     data: string;
 }) => void;
 export interface Messages {
+    connectRequest: {
+        instanceId: string;
+    };
+    connectResponse: {
+        instanceId: string;
+    };
     invokeRequest: {
         id: RequestId;
         path: PathKey[];
@@ -63,7 +75,10 @@ export interface MessagePoster {
 export interface PromiseCallbacks {
     resolve: (value: MessageValue) => void;
     reject: (reason: MessageValue) => void;
-    timer: ReturnType<typeof setTimeout>;
+    timer: ReturnType<typeof setTimeout> | null;
+    onResolve?: () => void;
+    onReject?: () => void;
+    expectedRemote?: string;
 }
 export interface ClientContext {
     getDelegateTarget(): MessageValue;
@@ -72,13 +87,26 @@ export interface ClientContext {
     getFunctionCache(): LRUCache<string, CallbackEntry>;
     getPersistentFunctionCache(): Map<string, CallbackEntry>;
     registerFunction(fn: Callable, thisArg: MessageValue, options?: CallbackCacheOptions): string;
+    serializeForRemote(value: MessageValue, target: 'broadcast' | string, options?: CallbackCacheOptions): MessageValue;
     getRemoteCallback(id: string, invoke: (args: MessageValue[]) => MessageValue, options: CallbackCacheOptions | undefined, remoteInstanceId: string): Callable;
-    getAndRemovePendingPromise(id: RequestId): PromiseCallbacks | undefined;
+    getAndRemovePendingPromise(id: RequestId, senderInstanceId?: string): 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;
+    invokeFunctionById(id: string, args: MessageValue[], options?: CallbackCacheOptions, remoteInstanceId?: string): Promise<MessageValue>;
     handleRemoteDestroy(instanceId: string): void;
+    bindRemote(remoteInstanceId: string): void;
+    noteFreshConnect(remoteInstanceId: string): void;
+    disableRemoteTargetWait(): void;
+    noteRemoteSeen(remoteInstanceId: string): void;
+    releaseRemoteCallbacks(remoteInstanceId: string, ids: readonly string[]): void;
+    dropLocalCallback(id: string, requesterInstanceId?: 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;
+    };
+    isDestroyed(): boolean;
     destroy(notifyRemote?: boolean): void;
 }
 export interface CallbackCacheOptions {
@@ -90,10 +118,6 @@ export interface CallbackEntry {
 }
 export interface MessageChannel {
     getSender(): MessageSender;
-    getContext(): ClientContext;
-    getPoster(): MessagePoster;
-    getKey(): string;
-    getInstanceId(): string;
     destroy(): void;
 }
 export interface MessageSender {

package/dist/channel/utils.d.ts

@@ -1,5 +1,9 @@
-import type { SerializedError } from './types';
+import type { MessageValue, SerializedError } from './types.js';
 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 encodeSymbolToken(value: symbol, context?: string): string;
+export declare function decodeSymbolToken(value: string, context?: string): symbol;
+export declare function setOwnProperty(target: Record<PropertyKey, MessageValue>, key: PropertyKey, value: MessageValue): void;
 export declare function serializeThrownError(err: unknown): SerializedError;
+export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;

package/dist/client/context.d.ts

@@ -1,4 +1,4 @@
-import type { ClientContext, MessageChannel, MessageValue } from '../channel/types';
+import type { ClientContext, MessageChannel, MessageValue } from '../channel/types.js';
 export interface ClientContextOptions {
     delegateTarget?: MessageValue;
     timeout?: number;

package/dist/client/endpoint.d.ts

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

package/dist/client/proxy.d.ts

@@ -1,3 +1,3 @@
-import type { MessageValue, PathKey, ProxyNode } from '../channel/types';
+import type { MessageValue, PathKey, ProxyNode } from '../channel/types.js';
 export declare function resolvePath(node: ProxyNode): PathKey[];
 export declare function createClientProxy<TProxy = unknown>(invoke: (path: PathKey[], args: MessageValue[]) => Promise<MessageValue>, accessProperty?: (path: PathKey[]) => Promise<MessageValue>): TProxy;