feat(platform-common): 添加WASM加载器和环境检测API

packages/platform-common/src/wasm/IWasmLibraryLoader.ts

@@ -0,0 +1,240 @@
+/**
+ * WASM 库平台适配层
+ *
+ * 提供统一的 WASM 库加载接口，屏蔽不同平台的差异
+ *
+ * 支持的平台：
+ * - Web 浏览器（标准 WebAssembly API）
+ * - 微信小游戏（WXWebAssembly）
+ * - 字节跳动小游戏
+ * - 支付宝小游戏
+ * - 百度小游戏
+ */
+
+/**
+ * 平台类型枚举
+ */
+export enum PlatformType {
+    /** Web 浏览器 */
+    Web = 'web',
+    /** 微信小游戏 */
+    WeChatMiniGame = 'wechat-minigame',
+    /** 字节跳动小游戏 */
+    ByteDanceMiniGame = 'bytedance-minigame',
+    /** 支付宝小游戏 */
+    AlipayMiniGame = 'alipay-minigame',
+    /** 百度小游戏 */
+    BaiduMiniGame = 'baidu-minigame',
+    /** Node.js */
+    NodeJS = 'nodejs',
+    /** 未知平台 */
+    Unknown = 'unknown'
+}
+
+/**
+ * WASM 库加载配置
+ *
+ * @example
+ * ```typescript
+ * const config: WasmLibraryConfig = {
+ *     name: 'Rapier2D',
+ *     web: {
+ *         useCompat: true,  // Web 使用 compat 版本
+ *     },
+ *     minigame: {
+ *         wasmPath: 'wasm/rapier2d_bg.wasm',
+ *         needsTextDecoderPolyfill: true,
+ *     }
+ * };
+ * ```
+ */
+export interface WasmLibraryConfig {
+    /**
+     * 库名称（用于日志和错误提示）
+     */
+    name: string;
+
+    /**
+     * Web 平台配置
+     */
+    web?: {
+        /**
+         * 使用 -compat 版本（WASM 以 base64 嵌入 JS）
+         *
+         * 优点：无需额外配置，开箱即用
+         * 缺点：包体积较大，首次加载慢
+         */
+        useCompat?: boolean;
+
+        /**
+         * 模块路径（非 compat 版本时使用）
+         */
+        modulePath?: string;
+
+        /**
+         * WASM 文件路径（非 compat 版本时使用）
+         */
+        wasmPath?: string;
+    };
+
+    /**
+     * 小游戏平台配置
+     */
+    minigame?: {
+        /**
+         * WASM 文件路径（相对于小游戏根目录）
+         */
+        wasmPath: string;
+
+        /**
+         * JS glue 文件路径（可选）
+         */
+        gluePath?: string;
+
+        /**
+         * 是否需要 TextDecoder polyfill
+         *
+         * iOS 微信小游戏通常需要此 polyfill
+         */
+        needsTextDecoderPolyfill?: boolean;
+
+        /**
+         * 是否需要 TextEncoder polyfill
+         *
+         * iOS 微信小游戏通常需要此 polyfill
+         */
+        needsTextEncoderPolyfill?: boolean;
+    };
+
+    /**
+     * 自定义初始化函数
+     *
+     * 用于库特定的初始化逻辑
+     *
+     * @param wasmInstance - WASM 实例
+     * @returns 初始化后的模块
+     */
+    customInit?: (wasmInstance: any) => Promise<any>;
+}
+
+/**
+ * 平台信息
+ * Platform information
+ */
+export interface PlatformInfo {
+    /** 平台类型 | Platform type */
+    type: PlatformType;
+
+    /** 是否支持 WebAssembly | Supports WebAssembly */
+    supportsWasm: boolean;
+
+    /** 是否支持 SharedArrayBuffer | Supports SharedArrayBuffer */
+    supportsSharedArrayBuffer: boolean;
+
+    /** 需要安装的 polyfills 列表 | Required polyfills */
+    needsPolyfills: string[];
+
+    /**
+     * 是否在编辑器环境（Tauri 桌面应用）
+     * Whether running in editor environment (Tauri desktop app)
+     */
+    isEditor: boolean;
+}
+
+/**
+ * WASM 库加载器接口
+ *
+ * 每个 WASM 库需要实现此接口以支持跨平台加载
+ *
+ * @typeParam T - WASM 库模块类型
+ *
+ * @example
+ * ```typescript
+ * class Rapier2DLoader implements IWasmLibraryLoader<typeof RAPIER> {
+ *     async load(): Promise<typeof RAPIER> {
+ *         const RAPIER = await import('@dimforge/rapier2d-compat');
+ *         await RAPIER.init();
+ *         return RAPIER;
+ *     }
+ *
+ *     isSupported(): boolean {
+ *         return typeof WebAssembly !== 'undefined';
+ *     }
+ *
+ *     getPlatformInfo(): PlatformInfo {
+ *         return {
+ *             type: PlatformType.Web,
+ *             supportsWasm: true,
+ *             supportsSharedArrayBuffer: true,
+ *             needsPolyfills: []
+ *         };
+ *     }
+ * }
+ * ```
+ */
+export interface IWasmLibraryLoader<T> {
+    /**
+     * 加载 WASM 库
+     *
+     * @returns 加载完成的库模块
+     * @throws 如果加载失败或平台不支持
+     */
+    load(): Promise<T>;
+
+    /**
+     * 检查当前平台是否支持此库
+     *
+     * @returns 是否支持
+     */
+    isSupported(): boolean;
+
+    /**
+     * 获取当前平台信息
+     *
+     * @returns 平台信息
+     */
+    getPlatformInfo(): PlatformInfo;
+
+    /**
+     * 获取库配置
+     *
+     * @returns 库配置
+     */
+    getConfig(): WasmLibraryConfig;
+}
+
+/**
+ * 平台特定 WASM 加载器接口
+ *
+ * 提供平台级别的 WASM 加载能力
+ */
+export interface IPlatformWasmLoader {
+    /**
+     * 平台类型
+     */
+    readonly platformType: PlatformType;
+
+    /**
+     * 加载 WASM 模块
+     *
+     * @param wasmPath - WASM 文件路径
+     * @param imports - WASM 导入对象
+     * @returns WASM 实例
+     */
+    loadWasmModule(
+        wasmPath: string,
+        imports?: WebAssembly.Imports
+    ): Promise<WebAssembly.Instance>;
+
+    /**
+     * 检查是否支持 WASM
+     *
+     * @returns 是否支持
+     */
+    isSupported(): boolean;
+
+    /**
+     * 安装必要的 polyfills
+     */
+    installPolyfills(): void;
+}