@dino-dev/bridge-core-ts 0.0.4 → 0.0.5

package/src/mrp-bridge.ts

@@ -17,22 +17,24 @@
  * ```
  */
 
+import { installIframeHostBridge } from './iframe-host';
+
 // ============================================================
 // 类型定义
 // ============================================================
 
 /** Bridge 消息格式 */
 export interface BridgeMessage<T = Record<string, unknown>> {
-  type: string;
-  action: string;
-  payload: T;
-  messageId?: string;
-  timestamp: number;
+	type: string;
+	action: string;
+	payload: T;
+	messageId?: string;
+	timestamp: number;
 }
 
 /** 消息处理函数 */
 export type MessageHandler<T = Record<string, unknown>> = (
-  message: BridgeMessage<T>,
+	message: BridgeMessage<T>,
 ) => void;
 
 /** 取消监听函数 */
@@ -43,24 +45,24 @@ export type Unsubscribe = () => void;
 // ============================================================
 
 declare global {
-  interface Window {
-    /** Bridge SDK 单例 */
-    mrpBridge: MrpBridge;
-    /** Flutter 内部 Bridge 接口 */
-    __FLUTTER_BRIDGE__?: {
-      send(
-        type: string,
-        action: string,
-        payload: Record<string, unknown>,
-      ): Promise<unknown>;
-      onMessage(jsonString: string): void;
-    };
-    /** 宿主注册的原生模块（按命名空间分组） */
-    NativeModules?: Record<
-      string,
-      Record<string, (...args: unknown[]) => Promise<unknown>>
-    >;
-  }
+	interface Window {
+		/** Bridge SDK 单例 */
+		mrpBridge: MrpBridge;
+		/** Flutter 内部 Bridge 接口 */
+		__FLUTTER_BRIDGE__?: {
+			send(
+				type: string,
+				action: string,
+				payload: Record<string, unknown>,
+			): Promise<unknown>;
+			onMessage(jsonString: string): void;
+		};
+		/** 宿主注册的原生模块（按命名空间分组） */
+		NativeModules?: Record<
+			string,
+			Record<string, (...args: unknown[]) => Promise<unknown>>
+		>;
+	}
 }
 
 // ============================================================
@@ -68,17 +70,32 @@ declare global {
 // ============================================================
 
 interface WrappedHandler extends MessageHandler {
-  _original?: MessageHandler;
-  _type?: string;
-  _action?: string | null;
+	_original?: MessageHandler;
+	_type?: string;
+	_action?: string | null;
 }
 
 interface PendingMessage {
-  type: string;
-  action: string;
-  payload: Record<string, unknown>;
+	type: string;
+	action: string;
+	payload: Record<string, unknown>;
+}
+
+/** Bridge 就绪状态 */
+export type BridgeReadyState = 'pending' | 'ready' | 'unavailable';
+
+/** `whenReady()` 选项 */
+export interface WhenReadyOptions {
+	/** 超时毫秒数，超时后 Promise 以错误 reject；不传则沿用「永不 reject」的旧行为 */
+	timeoutMs?: number;
 }
 
+const READY_POLL_INTERVAL_MS = 100;
+const READY_MAX_RETRY = 50;
+// 容器在 onLoadStop（window.onload，需等图片/iframe 等子资源加载完）后才注入
+// __FLUTTER_BRIDGE__，弱网下可能远超 5 秒；已在 WebView 内时不能放弃，否则排队消息全部丢失。
+const READY_SLOW_POLL_INTERVAL_MS = 250;
+
 // ============================================================
 // MrpBridge
 // ============================================================
@@ -91,197 +108,267 @@ interface PendingMessage {
  * 2. **模块调用**：通过 `module<T>()` 获取类型安全的原生模块代理
  */
 export class MrpBridge {
-  private _messageHandlers: WrappedHandler[] = [];
-  private _ready = false;
-  private _pendingMessages: PendingMessage[] = [];
-  private _readyPromiseResolve: (() => void) | null = null;
-  private _readyPromise: Promise<void>;
-  private _retryCount = 0;
-
-  constructor() {
-    this._readyPromise = new Promise<void>((resolve) => {
-      this._readyPromiseResolve = resolve;
-    });
-
-    // 监听 Flutter → H5 消息
-    window.addEventListener('flutterMessage', ((event: CustomEvent) => {
-      const msg = event.detail as BridgeMessage;
-      // 复制一份避免迭代中修改
-      const handlers = [...this._messageHandlers];
-      for (const handler of handlers) {
-        try {
-          handler(msg);
-        } catch (e) {
-          console.error('[MRP Bridge] 消息处理错误:', e);
-        }
-      }
-    }) as EventListener);
-
-    this._checkReady();
-  }
-
-  // ---- 就绪检测 ----
-
-  private _checkReady(): void {
-    if (window.__FLUTTER_BRIDGE__) {
-      this._ready = true;
-      this._readyPromiseResolve?.();
-      this._pendingMessages.forEach((msg) => this._doSend(msg));
-      this._pendingMessages = [];
-    } else {
-      this._retryCount++;
-      if (this._retryCount < 50) {
-        setTimeout(() => this._checkReady(), 100);
-      } else {
-        console.warn(
-          '[MRP Bridge] Flutter Bridge 未注入，可能不在容器环境中运行',
-        );
-      }
-    }
-  }
-
-  /** 等待 Bridge 就绪 */
-  whenReady(): Promise<void> {
-    return this._readyPromise;
-  }
-
-  /** 是否在 Flutter WebView 容器中运行 */
-  get isInContainer(): boolean {
-    return !!window.__FLUTTER_BRIDGE__ || !!(window as any).flutter_inappwebview;
-  }
-
-  // ---- 消息发送 ----
-
-  /**
-   * 发送消息到 Flutter
-   * @param type - 消息类型
-   * @param action - 动作名称
-   * @param payload - 消息数据
-   */
-  send<R = unknown>(
-    type: string,
-    action: string,
-    payload: Record<string, unknown> = {},
-  ): Promise<R> {
-    const msg: PendingMessage = { type, action, payload };
-    if (this._ready) {
-      return this._doSend(msg);
-    }
-    this._pendingMessages.push(msg);
-    return Promise.resolve(null as R);
-  }
-
-  private _doSend<R>(msg: PendingMessage): Promise<R> {
-    if (window.__FLUTTER_BRIDGE__) {
-      return window.__FLUTTER_BRIDGE__.send(
-        msg.type,
-        msg.action,
-        msg.payload,
-      ) as Promise<R>;
-    }
-    return Promise.resolve(null as R);
-  }
-
-  // ---- 消息监听 ----
-
-  /**
-   * 监听 Flutter 发来的所有消息
-   * @returns 取消监听的函数
-   */
-  onMessage<T = Record<string, unknown>>(
-    handler: MessageHandler<T>,
-  ): Unsubscribe {
-    this._messageHandlers.push(handler as WrappedHandler);
-    return () => {
-      this._messageHandlers = this._messageHandlers.filter(
-        (h) => h !== handler,
-      );
-    };
-  }
-
-  /**
-   * 监听特定类型/动作的消息
-   * @param type - 消息类型
-   * @param action - 动作名称，传 null 匹配所有
-   */
-  on<T = Record<string, unknown>>(
-    type: string,
-    action: string | null,
-    handler: MessageHandler<T>,
-  ): Unsubscribe {
-    const wrappedHandler: WrappedHandler = (msg) => {
-      if (msg.type === type && (action === null || msg.action === action)) {
-        (handler as MessageHandler)(msg);
-      }
-    };
-    wrappedHandler._original = handler as MessageHandler;
-    wrappedHandler._type = type;
-    wrappedHandler._action = action;
-    this._messageHandlers.push(wrappedHandler);
-    return () => {
-      this._messageHandlers = this._messageHandlers.filter(
-        (h) => h !== wrappedHandler,
-      );
-    };
-  }
-
-  // ---- 原生模块调用 ----
-
-  /**
-   * 获取模块代理，按命名空间调用原生 API（类型安全）。
-   *
-   * 搭配 TypeScript Generator 生成的类型使用，获得完整的类型推断。
-   *
-   * @param namespace - 模块命名空间
-   * @returns 模块方法代理对象
-   *
-   * @example
-   * ```ts
-   * import type { AudioModule } from '../generated/audio_module';
-   * import type { UserModule } from '../generated/user_module';
-   *
-   * const audio = bridge.module<AudioModule>('audio');
-   * await audio.play({ soundId: 'success', volume: 0.8 });
-   *
-   * const user = bridge.module<UserModule>('user');
-   * const profile = await user.getProfile();
-   * ```
-   */
-  module<
-    T extends object = Record<
-      string,
-      (...args: any[]) => Promise<any>
-    >,
-  >(namespace: string): T {
-    return new Proxy({} as T, {
-      get: (_target, method: string | symbol) => {
-        if (typeof method !== 'string') return undefined;
-        return async (...args: unknown[]) => {
-          if (window.NativeModules?.[namespace]?.[method]) {
-            const result = await window.NativeModules[namespace][method](...args);
-            // 检查模块访问被拒绝错误
-            if (
-              result &&
-              typeof result === 'object' &&
-              (result as Record<string, unknown>).__error__ === 'MODULE_ACCESS_DENIED'
-            ) {
-              console.error(
-                `[MRP Bridge] 模块访问被拒绝: ${namespace}.${method}`,
-                (result as Record<string, unknown>).__message__,
-              );
-              return null;
-            }
-            return result;
-          }
-          console.warn(
-            `[MRP Bridge] NativeModules.${namespace}.${method} 不存在`,
-          );
-          return Promise.resolve(null);
-        };
-      },
-    });
-  }
+	private _messageHandlers: WrappedHandler[] = [];
+	private _ready = false;
+	private _pendingMessages: PendingMessage[] = [];
+	private _readyPromiseResolve: (() => void) | null = null;
+	private _readyPromise: Promise<void>;
+	private _retryCount = 0;
+	private _readyState: BridgeReadyState = 'pending';
+	private _readyTimer: ReturnType<typeof setTimeout> | null = null;
+
+	constructor() {
+		this._readyPromise = new Promise<void>((resolve) => {
+			this._readyPromiseResolve = resolve;
+		});
+
+		// 监听 Flutter → H5 消息
+		window.addEventListener('flutterMessage', ((event: CustomEvent) => {
+			const msg = event.detail as BridgeMessage;
+			// 复制一份避免迭代中修改
+			const handlers = [...this._messageHandlers];
+			for (const handler of handlers) {
+				try {
+					handler(msg);
+				} catch (e) {
+					console.error('[MRP Bridge] 消息处理错误:', e);
+				}
+			}
+		}) as EventListener);
+
+		this._checkReady();
+	}
+
+	// ---- 就绪检测 ----
+
+	private _checkReady(): void {
+		if (this._readyState === 'ready') return;
+
+		if (window.__FLUTTER_BRIDGE__) {
+			if (this._readyTimer !== null) {
+				clearTimeout(this._readyTimer);
+				this._readyTimer = null;
+			}
+			this._ready = true;
+			this._readyState = 'ready';
+			this._readyPromiseResolve?.();
+			this._pendingMessages.forEach((msg) => this._doSend(msg));
+			this._pendingMessages = [];
+			return;
+		}
+
+		this._retryCount++;
+		if (this._retryCount < READY_MAX_RETRY) {
+			this._readyTimer = setTimeout(
+				() => this._checkReady(),
+				READY_POLL_INTERVAL_MS,
+			);
+			return;
+		}
+
+		if ((window as any).flutter_inappwebview) {
+			this._readyTimer = setTimeout(
+				() => this._checkReady(),
+				READY_SLOW_POLL_INTERVAL_MS,
+			);
+			return;
+		}
+
+		this._readyTimer = null;
+		this._readyState = 'unavailable';
+		console.error(
+			[
+				'[MRP Bridge] 等待 %ss 后仍未检测到原生容器（window.__FLUTTER_BRIDGE__）。',
+				'· bridge.whenReady() 将永不 resolve，依赖它的页面会一直停在加载态；',
+				'· bridge.send() 与原生模块调用都会静默返回 null。',
+				'如果当前是在浏览器里开发，请安装 Mock Bridge：',
+				"  import { installMockBridge } from '@h5-container/bridge-core-ts/mock';",
+			].join('\n'),
+			((READY_MAX_RETRY * READY_POLL_INTERVAL_MS) / 1000).toFixed(1),
+		);
+	}
+
+	/**
+	 * 重新触发一次就绪检测。
+	 *
+	 * 供 Mock Bridge 在注入后立即生效使用；轮询已结束时也能重新唤醒。
+	 */
+	refreshReady(): void {
+		if (this._readyState === 'ready') return;
+		this._retryCount = 0;
+		this._readyState = 'pending';
+		this._checkReady();
+	}
+
+	/** 当前就绪状态：等待中 / 已就绪 / 判定为不在容器环境 */
+	get readyState(): BridgeReadyState {
+		return this._readyState;
+	}
+
+	/**
+	 * 等待 Bridge 就绪。
+	 *
+	 * 默认沿用旧语义：未就绪时 Promise 一直挂起、不会 reject。
+	 * 传入 `timeoutMs` 可在超时后 reject，便于页面给出明确的错误态。
+	 */
+	whenReady(options?: WhenReadyOptions): Promise<void> {
+		const timeoutMs = options?.timeoutMs;
+		if (timeoutMs === undefined) return this._readyPromise;
+
+		return new Promise<void>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				reject(
+					new Error(
+						`[MRP Bridge] 等待原生容器就绪超时（${timeoutMs}ms）。` +
+							'当前可能不在容器环境中，浏览器开发请安装 Mock Bridge。',
+					),
+				);
+			}, timeoutMs);
+			void this._readyPromise.then(() => {
+				clearTimeout(timer);
+				resolve();
+			});
+		});
+	}
+
+	/** 是否在 Flutter WebView 容器中运行 */
+	get isInContainer(): boolean {
+		return (
+			!!window.__FLUTTER_BRIDGE__ || !!(window as any).flutter_inappwebview
+		);
+	}
+
+	// ---- 消息发送 ----
+
+	/**
+	 * 发送消息到 Flutter
+	 * @param type - 消息类型
+	 * @param action - 动作名称
+	 * @param payload - 消息数据
+	 */
+	send<R = unknown>(
+		type: string,
+		action: string,
+		payload: Record<string, unknown> = {},
+	): Promise<R> {
+		const msg: PendingMessage = { type, action, payload };
+		if (this._ready) {
+			return this._doSend(msg);
+		}
+		this._pendingMessages.push(msg);
+		return Promise.resolve(null as R);
+	}
+
+	private _doSend<R>(msg: PendingMessage): Promise<R> {
+		if (window.__FLUTTER_BRIDGE__) {
+			return window.__FLUTTER_BRIDGE__.send(
+				msg.type,
+				msg.action,
+				msg.payload,
+			) as Promise<R>;
+		}
+		return Promise.resolve(null as R);
+	}
+
+	// ---- 消息监听 ----
+
+	/**
+	 * 监听 Flutter 发来的所有消息
+	 * @returns 取消监听的函数
+	 */
+	onMessage<T = Record<string, unknown>>(
+		handler: MessageHandler<T>,
+	): Unsubscribe {
+		this._messageHandlers.push(handler as WrappedHandler);
+		return () => {
+			this._messageHandlers = this._messageHandlers.filter(
+				(h) => h !== handler,
+			);
+		};
+	}
+
+	/**
+	 * 监听特定类型/动作的消息
+	 * @param type - 消息类型
+	 * @param action - 动作名称，传 null 匹配所有
+	 */
+	on<T = Record<string, unknown>>(
+		type: string,
+		action: string | null,
+		handler: MessageHandler<T>,
+	): Unsubscribe {
+		const wrappedHandler: WrappedHandler = (msg) => {
+			if (msg.type === type && (action === null || msg.action === action)) {
+				(handler as MessageHandler)(msg);
+			}
+		};
+		wrappedHandler._original = handler as MessageHandler;
+		wrappedHandler._type = type;
+		wrappedHandler._action = action;
+		this._messageHandlers.push(wrappedHandler);
+		return () => {
+			this._messageHandlers = this._messageHandlers.filter(
+				(h) => h !== wrappedHandler,
+			);
+		};
+	}
+
+	// ---- 原生模块调用 ----
 
+	/**
+	 * 获取模块代理，按命名空间调用原生 API（类型安全）。
+	 *
+	 * 搭配 TypeScript Generator 生成的类型使用，获得完整的类型推断。
+	 *
+	 * @param namespace - 模块命名空间
+	 * @returns 模块方法代理对象
+	 *
+	 * @example
+	 * ```ts
+	 * import type { AudioModule } from '../generated/audio_module';
+	 * import type { UserModule } from '../generated/user_module';
+	 *
+	 * const audio = bridge.module<AudioModule>('audio');
+	 * await audio.play({ soundId: 'success', volume: 0.8 });
+	 *
+	 * const user = bridge.module<UserModule>('user');
+	 * const profile = await user.getProfile();
+	 * ```
+	 */
+	module<T extends object = Record<string, (...args: any[]) => Promise<any>>>(
+		namespace: string,
+	): T {
+		return new Proxy({} as T, {
+			get: (_target, method: string | symbol) => {
+				if (typeof method !== 'string') return undefined;
+				return async (...args: unknown[]) => {
+					if (window.NativeModules?.[namespace]?.[method]) {
+						const result = await window.NativeModules[namespace][method](
+							...args,
+						);
+						// 检查模块访问被拒绝错误
+						if (
+							result &&
+							typeof result === 'object' &&
+							(result as Record<string, unknown>).__error__ ===
+								'MODULE_ACCESS_DENIED'
+						) {
+							console.error(
+								`[MRP Bridge] 模块访问被拒绝: ${namespace}.${method}`,
+								(result as Record<string, unknown>).__message__,
+							);
+							return null;
+						}
+						return result;
+					}
+					console.warn(
+						`[MRP Bridge] NativeModules.${namespace}.${method} 不存在`,
+					);
+					return Promise.resolve(null);
+				};
+			},
+		});
+	}
 }
 
 // ============================================================
@@ -289,6 +376,7 @@ export class MrpBridge {
 // ============================================================
 
 /** Bridge 单例实例 */
+installIframeHostBridge();
 export const bridge = new MrpBridge();
 
 // 挂载到 window，方便非模块化项目使用