@dino-dev/bridge-core-ts 0.0.1

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @h5-container/bridge-core-ts
+ *
+ * H5 端与 Flutter 容器通信的核心 SDK（零框架依赖）。
+ * 提供 Bridge 消息通信 + 原生模块类型安全调用。
+ *
+ * 适用于 React / Vue / Svelte / Vanilla JS 等任何前端框架。
+ * 所有 API 从此入口统一导出，消费者无需感知内部目录结构。
+ */
+
+// 核心 Bridge
+export { bridge, MrpBridge } from './mrp-bridge';
+export type {
+  BridgeMessage,
+  MessageHandler,
+  Unsubscribe,
+} from './mrp-bridge';
+
+// 内置系统模块类型 + 工厂函数（容器核心契约）
+export { getSystemModule } from './system-module';
+export type {
+  SystemModule,
+  ModuleAllowedResult,
+  AvailableModulesResult,
+  ContainerInfoResult,
+} from './system-module';
+
+// Generated 模块：类型 + 工厂函数
+export * from '../generated/index';
+
+// 生命周期上报工具
+export { lifecycle } from './lifecycle';
+export type { RouteChangedPayload, AppMountedPayload } from './lifecycle';

package/src/lifecycle.ts

@@ -0,0 +1,127 @@
+/**
+ * H5 容器生命周期上报工具。
+ *
+ * 提供类型安全的生命周期事件上报接口，H5 应用通过此模块通知
+ * Flutter 宿主当前的运行状态。
+ *
+ * @example
+ * ```ts
+ * import { lifecycle } from '@h5-container/bridge-core-ts';
+ *
+ * // React
+ * useEffect(() => {
+ *   lifecycle.appMounted({ route: location.pathname });
+ *   return () => lifecycle.appDestroyed();
+ * }, []);
+ *
+ * // 路由跳转
+ * lifecycle.routeChanged({ from: '/home', to: '/game' });
+ *
+ * // 自定义事件
+ * lifecycle.custom('gameStarted', { level: 1 });
+ * ```
+ */
+
+// ============================================================
+// 类型定义
+// ============================================================
+
+/** SPA 路由跳转事件的 payload */
+export interface RouteChangedPayload {
+  /** 跳转前路由 */
+  from: string;
+  /** 跳转后路由 */
+  to: string;
+}
+
+/** appMounted 事件的 payload */
+export interface AppMountedPayload {
+  /** 当前路由（可选） */
+  route?: string;
+}
+
+// ============================================================
+// 工具函数
+// ============================================================
+
+/** 底层上报函数，通过 Bridge 发送 lifecycle 类型消息。 */
+function report(action: string, payload: object = {}): void {
+  if (window.__FLUTTER_BRIDGE__) {
+    window.__FLUTTER_BRIDGE__.send(
+      'lifecycle',
+      action,
+      payload as Record<string, unknown>,
+    );
+  }
+}
+
+// ============================================================
+// 生命周期对象（命名空间风格，方便 tree-shaking）
+// ============================================================
+
+/**
+ * H5 容器生命周期上报 API。
+ *
+ * 调用这些方法通知宿主 Flutter 应用当前 H5 的运行状态。
+ * 宿主通过 `controller.onContainerEvent` 流接收事件。
+ */
+export const lifecycle = {
+  /**
+   * 上报 H5 应用挂载完成。
+   *
+   * 建议在 React 根组件 `useEffect` 或 Vue `onMounted` 中调用。
+   */
+  appMounted(payload?: AppMountedPayload): void {
+    report('appMounted', payload ?? {});
+  },
+
+  /**
+   * 上报 H5 应用销毁。
+   *
+   * 建议在 React 根组件 `useEffect` 的 cleanup 或 Vue `onUnmounted` 中调用。
+   */
+  appDestroyed(): void {
+    report('appDestroyed');
+  },
+
+  /**
+   * 上报 SPA 内部路由跳转。
+   *
+   * 建议在路由守卫或 React Router 的 `useLocation` 变化时调用。
+   */
+  routeChanged(payload: RouteChangedPayload): void {
+    report('routeChanged', payload);
+  },
+
+  /**
+   * 上报页面恢复可见（`visibilitychange: visible`）。
+   *
+   * 建议监听 `document.addEventListener('visibilitychange', ...)` 后调用。
+   */
+  pageVisible(): void {
+    report('pageVisible');
+  },
+
+  /**
+   * 上报页面进入后台（`visibilitychange: hidden`）。
+   */
+  pageHidden(): void {
+    report('pageHidden');
+  },
+
+  /**
+   * 上报自定义事件（业务自定义语义）。
+   *
+   * @param action  事件名称（宿主侧收到 `event.action` 即此值，type 为 `custom`）
+   * @param payload 事件数据
+   *
+   * @example
+   * ```ts
+   * lifecycle.custom('gameStarted', { level: 1, mode: 'easy' });
+   * lifecycle.custom('scoreUpdated', { score: 200 });
+   * ```
+   */
+  custom(action: string, payload?: Record<string, unknown>): void {
+    report(action, payload ?? {});
+  },
+} as const;

package/src/mrp-bridge.ts

@@ -0,0 +1,297 @@
+/**
+ * h5_app_container Bridge SDK
+ *
+ * H5 端与 Flutter 容器通信的核心 SDK。
+ * 提供 Bridge 消息通信 + 原生模块调用能力。
+ *
+ * @example
+ * ```ts
+ * import { bridge } from './mrp-bridge';
+ *
+ * // 发送消息到 Flutter
+ * bridge.send('interaction', 'onFindTarget', { target: 'ladybug' });
+ *
+ * // 调用原生模块（类型安全，搭配 generated 类型使用）
+ * const audio = bridge.module<AudioModule>('audio');
+ * await audio.play({ soundId: 'success', volume: 0.8 });
+ * ```
+ */
+
+// ============================================================
+// 类型定义
+// ============================================================
+
+/** Bridge 消息格式 */
+export interface BridgeMessage<T = Record<string, unknown>> {
+  type: string;
+  action: string;
+  payload: T;
+  messageId?: string;
+  timestamp: number;
+}
+
+/** 消息处理函数 */
+export type MessageHandler<T = Record<string, unknown>> = (
+  message: BridgeMessage<T>,
+) => void;
+
+/** 取消监听函数 */
+export type Unsubscribe = () => void;
+
+// ============================================================
+// Window 全局类型扩展
+// ============================================================
+
+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 WrappedHandler extends MessageHandler {
+  _original?: MessageHandler;
+  _type?: string;
+  _action?: string | null;
+}
+
+interface PendingMessage {
+  type: string;
+  action: string;
+  payload: Record<string, unknown>;
+}
+
+// ============================================================
+// MrpBridge
+// ============================================================
+
+/**
+ * Bridge SDK 主类。
+ *
+ * 提供两大能力：
+ * 1. **消息通信**：H5 ↔ Flutter 的双向消息收发
+ * 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);
+        };
+      },
+    });
+  }
+
+}
+
+// ============================================================
+// 单例 & 导出
+// ============================================================
+
+/** Bridge 单例实例 */
+export const bridge = new MrpBridge();
+
+// 挂载到 window，方便非模块化项目使用
+window.mrpBridge = bridge;
+
+export default bridge;

package/src/system-module.ts

@@ -0,0 +1,77 @@
+/**
+ * 容器内置系统模块类型定义与工厂函数。
+ *
+ * System 模块由容器自动注册，不受 `allowedModules` 白名单限制，始终可用。
+ * 通过 `getSystemModule()` 或 `bridge.module<SystemModule>('system')` 访问。
+ *
+ * @example
+ * ```ts
+ * import { getSystemModule } from '@h5-container/bridge-core-ts';
+ *
+ * const system = getSystemModule();
+ * const { allowed } = await system.isModuleAllowed({ namespace: 'audio' });
+ * const { modules } = await system.getAvailableModules();
+ * const info = await system.getContainerInfo();
+ * ```
+ */
+
+import { bridge } from './mrp-bridge';
+
+// ============================================================
+// System 模块返回值类型
+// ============================================================
+
+/** isModuleAllowed 返回值 */
+export interface ModuleAllowedResult {
+  allowed: boolean;
+  namespace: string;
+  error?: string;
+}
+
+/** getAvailableModules 返回值 */
+export interface AvailableModulesResult {
+  modules: string[];
+}
+
+/** getContainerInfo 返回值 */
+export interface ContainerInfoResult {
+  packageId: string | null;
+  registeredModules: string[];
+  allowedModules: string[] | null;
+  [key: string]: unknown;
+}
+
+// ============================================================
+// System 模块接口
+// ============================================================
+
+/**
+ * 容器内置系统模块接口。
+ *
+ * 提供模块权限查询、可用模块列表、容器元信息获取等能力。
+ */
+export interface SystemModule {
+  /** 查询指定模块是否被当前包授权 */
+  isModuleAllowed(params: { namespace: string }): Promise<ModuleAllowedResult>;
+  /** 获取当前包可用的所有模块命名空间列表 */
+  getAvailableModules(): Promise<AvailableModulesResult>;
+  /** 获取容器元信息 */
+  getContainerInfo(): Promise<ContainerInfoResult>;
+}
+
+// ============================================================
+// 工厂函数
+// ============================================================
+
+/**
+ * 获取系统模块的类型安全代理。
+ *
+ * @example
+ * ```ts
+ * const system = getSystemModule();
+ * const { allowed } = await system.isModuleAllowed({ namespace: 'audio' });
+ * ```
+ */
+export function getSystemModule(): SystemModule {
+  return bridge.module<SystemModule>('system');
+}