@dino-dev/bridge-core-ts 0.0.1

package/dist/src/mrp-bridge.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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;
+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>>>;
+    }
+}
+/**
+ * Bridge SDK 主类。
+ *
+ * 提供两大能力：
+ * 1. **消息通信**：H5 ↔ Flutter 的双向消息收发
+ * 2. **模块调用**：通过 `module<T>()` 获取类型安全的原生模块代理
+ */
+export declare class MrpBridge {
+    private _messageHandlers;
+    private _ready;
+    private _pendingMessages;
+    private _readyPromiseResolve;
+    private _readyPromise;
+    private _retryCount;
+    constructor();
+    private _checkReady;
+    /** 等待 Bridge 就绪 */
+    whenReady(): Promise<void>;
+    /** 是否在 Flutter WebView 容器中运行 */
+    get isInContainer(): boolean;
+    /**
+     * 发送消息到 Flutter
+     * @param type - 消息类型
+     * @param action - 动作名称
+     * @param payload - 消息数据
+     */
+    send<R = unknown>(type: string, action: string, payload?: Record<string, unknown>): Promise<R>;
+    private _doSend;
+    /**
+     * 监听 Flutter 发来的所有消息
+     * @returns 取消监听的函数
+     */
+    onMessage<T = Record<string, unknown>>(handler: MessageHandler<T>): Unsubscribe;
+    /**
+     * 监听特定类型/动作的消息
+     * @param type - 消息类型
+     * @param action - 动作名称，传 null 匹配所有
+     */
+    on<T = Record<string, unknown>>(type: string, action: string | null, handler: MessageHandler<T>): Unsubscribe;
+    /**
+     * 获取模块代理，按命名空间调用原生 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;
+}
+/** Bridge 单例实例 */
+export declare const bridge: MrpBridge;
+export default bridge;
+//# sourceMappingURL=mrp-bridge.d.ts.map

package/dist/src/mrp-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mrp-bridge.d.ts","sourceRoot":"","sources":["../../src/mrp-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,kBAAkB;AAClB,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,aAAa;AACb,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACxD,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KACtB,IAAI,CAAC;AAEV,aAAa;AACb,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAMrC,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB;QACpB,SAAS,EAAE,SAAS,CAAC;QACrB,2BAA2B;QAC3B,kBAAkB,CAAC,EAAE;YACnB,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;YACpB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;SACrC,CAAC;QACF,yBAAyB;QACzB,aAAa,CAAC,EAAE,MAAM,CACpB,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CACzD,CAAC;KACH;CACF;AAsBD;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAK;;IA0BxB,OAAO,CAAC,WAAW;IAkBnB,mBAAmB;IACnB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1B,gCAAgC;IAChC,IAAI,aAAa,IAAI,OAAO,CAE3B;IAID;;;;;OAKG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,OAAO,CAAC,CAAC,CAAC;IASb,OAAO,CAAC,OAAO;IAaf;;;OAGG;IACH,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,WAAW;IASd;;;;OAIG;IACH,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,WAAW;IAmBd;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CACJ,CAAC,SAAS,MAAM,GAAG,MAAM,CACvB,MAAM,EACN,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CACjC,EACD,SAAS,EAAE,MAAM,GAAG,CAAC;CA8BxB;AAMD,kBAAkB;AAClB,eAAO,MAAM,MAAM,WAAkB,CAAC;AAKtC,eAAe,MAAM,CAAC"}

package/dist/src/mrp-bridge.js

@@ -0,0 +1,185 @@
+/**
+ * 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 });
+ * ```
+ */
+// ============================================================
+// MrpBridge
+// ============================================================
+/**
+ * Bridge SDK 主类。
+ *
+ * 提供两大能力：
+ * 1. **消息通信**：H5 ↔ Flutter 的双向消息收发
+ * 2. **模块调用**：通过 `module<T>()` 获取类型安全的原生模块代理
+ */
+export class MrpBridge {
+    constructor() {
+        this._messageHandlers = [];
+        this._ready = false;
+        this._pendingMessages = [];
+        this._readyPromiseResolve = null;
+        this._retryCount = 0;
+        this._readyPromise = new Promise((resolve) => {
+            this._readyPromiseResolve = resolve;
+        });
+        // 监听 Flutter → H5 消息
+        window.addEventListener('flutterMessage', ((event) => {
+            const msg = event.detail;
+            // 复制一份避免迭代中修改
+            const handlers = [...this._messageHandlers];
+            for (const handler of handlers) {
+                try {
+                    handler(msg);
+                }
+                catch (e) {
+                    console.error('[MRP Bridge] 消息处理错误:', e);
+                }
+            }
+        }));
+        this._checkReady();
+    }
+    // ---- 就绪检测 ----
+    _checkReady() {
+        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() {
+        return this._readyPromise;
+    }
+    /** 是否在 Flutter WebView 容器中运行 */
+    get isInContainer() {
+        return !!window.__FLUTTER_BRIDGE__ || !!window.flutter_inappwebview;
+    }
+    // ---- 消息发送 ----
+    /**
+     * 发送消息到 Flutter
+     * @param type - 消息类型
+     * @param action - 动作名称
+     * @param payload - 消息数据
+     */
+    send(type, action, payload = {}) {
+        const msg = { type, action, payload };
+        if (this._ready) {
+            return this._doSend(msg);
+        }
+        this._pendingMessages.push(msg);
+        return Promise.resolve(null);
+    }
+    _doSend(msg) {
+        if (window.__FLUTTER_BRIDGE__) {
+            return window.__FLUTTER_BRIDGE__.send(msg.type, msg.action, msg.payload);
+        }
+        return Promise.resolve(null);
+    }
+    // ---- 消息监听 ----
+    /**
+     * 监听 Flutter 发来的所有消息
+     * @returns 取消监听的函数
+     */
+    onMessage(handler) {
+        this._messageHandlers.push(handler);
+        return () => {
+            this._messageHandlers = this._messageHandlers.filter((h) => h !== handler);
+        };
+    }
+    /**
+     * 监听特定类型/动作的消息
+     * @param type - 消息类型
+     * @param action - 动作名称，传 null 匹配所有
+     */
+    on(type, action, handler) {
+        const wrappedHandler = (msg) => {
+            if (msg.type === type && (action === null || msg.action === action)) {
+                handler(msg);
+            }
+        };
+        wrappedHandler._original = handler;
+        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(namespace) {
+        return new Proxy({}, {
+            get: (_target, method) => {
+                if (typeof method !== 'string')
+                    return undefined;
+                return async (...args) => {
+                    if (window.NativeModules?.[namespace]?.[method]) {
+                        const result = await window.NativeModules[namespace][method](...args);
+                        // 检查模块访问被拒绝错误
+                        if (result &&
+                            typeof result === 'object' &&
+                            result.__error__ === 'MODULE_ACCESS_DENIED') {
+                            console.error(`[MRP Bridge] 模块访问被拒绝: ${namespace}.${method}`, result.__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;
+//# sourceMappingURL=mrp-bridge.js.map

package/dist/src/mrp-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mrp-bridge.js","sourceRoot":"","sources":["../../src/mrp-bridge.ts"],"names":[],"mappings":"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"}

package/dist/src/system-module.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 容器内置系统模块类型定义与工厂函数。
+ *
+ * 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();
+ * ```
+ */
+/** 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;
+}
+/**
+ * 容器内置系统模块接口。
+ *
+ * 提供模块权限查询、可用模块列表、容器元信息获取等能力。
+ */
+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 declare function getSystemModule(): SystemModule;
+//# sourceMappingURL=system-module.d.ts.map

package/dist/src/system-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-module.d.ts","sourceRoot":"","sources":["../../src/system-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,0BAA0B;AAC1B,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8BAA8B;AAC9B,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,2BAA2B;AAC3B,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAMD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qBAAqB;IACrB,eAAe,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7E,yBAAyB;IACzB,mBAAmB,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACvD,cAAc;IACd,gBAAgB,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAClD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAE9C"}

package/dist/src/system-module.js

@@ -0,0 +1,33 @@
+/**
+ * 容器内置系统模块类型定义与工厂函数。
+ *
+ * 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';
+// ============================================================
+// 工厂函数
+// ============================================================
+/**
+ * 获取系统模块的类型安全代理。
+ *
+ * @example
+ * ```ts
+ * const system = getSystemModule();
+ * const { allowed } = await system.isModuleAllowed({ namespace: 'audio' });
+ * ```
+ */
+export function getSystemModule() {
+    return bridge.module('system');
+}
+//# sourceMappingURL=system-module.js.map

package/dist/src/system-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-module.js","sourceRoot":"","sources":["../../src/system-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AA4CtC,+DAA+D;AAC/D,OAAO;AACP,+DAA+D;AAE/D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAC,MAAM,CAAe,QAAQ,CAAC,CAAC;AAC/C,CAAC"}

package/generated/ai_tutor.ts

@@ -0,0 +1,72 @@
+// ============================================================
+// 此文件由 h5_app_container_generator 自动生成，请勿手动修改。
+// 运行 `dart run build_runner build` 重新生成。
+// ============================================================
+
+/** AI Tutor 交互网关（宿主侧 AI 能力） */
+export interface AiTutor {
+  /** 将用户在绘本中的交互事件发送给 AI Tutor */
+  sendInteraction(args: {
+    /** 动作名称 */
+    action: string;
+    /** 事件负载 */
+    payload?: Record<string, unknown> | null;
+  }): Promise<{
+    /** 是否成功 */
+    success: boolean;
+  }>;
+
+  /** 发送文本消息给 AI Tutor */
+  sendTextMessage(args: {
+    /** 文本内容 */
+    text: string;
+  }): Promise<{
+    /** 是否成功 */
+    success: boolean;
+  }>;
+
+  /** 将当前截图发送给 AI Tutor（多模态视觉输入） */
+  sendScreenshot(args: {
+    /** Base64 编码的图片数据 */
+    imageBase64: string;
+  }): Promise<{
+    /** 是否成功 */
+    success: boolean;
+  }>;
+
+  /** 通知 AI Tutor 当前绘本场景已切换 */
+  notifySceneChanged(args: {
+    /** 当前页码 */
+    pageIndex: number;
+    /** 场景标识符 */
+    sceneId?: string | null;
+    /** 场景标题 */
+    title?: string | null;
+    /** 附加元数据 */
+    metadata?: Record<string, unknown> | null;
+  }): Promise<{
+    /** 是否成功 */
+    success: boolean;
+  }>;
+
+  /** 请求开启/关闭学生麦克风进行语音输入 */
+  setMicEnabled(args: {
+    /** 是否开启麦克风 */
+    enabled: boolean;
+  }): Promise<{
+    /** 是否成功 */
+    success: boolean;
+    /** 当前麦克风状态 */
+    enabled: boolean;
+  }>;
+
+  /** 获取 AI Tutor 当前状态 */
+  getState(): Promise<{
+    /** 状态标识（idle / thinking / speaking / waitingForResponse / error） */
+    state: string;
+    /** 麦克风是否开启 */
+    micEnabled: boolean;
+    /** 当前场景上下文（可能为 null） */
+    currentScene: Record<string, unknown> | null;
+  }>;
+}

package/generated/audio.ts

@@ -0,0 +1,35 @@
+// ============================================================
+// 此文件由 h5_app_container_generator 自动生成，请勿手动修改。
+// 运行 `dart run build_runner build` 重新生成。
+// ============================================================
+
+/** 原生音频播放控制 */
+export interface Audio {
+  /** 播放音效 */
+  play(args: {
+    /** 音效 ID */
+    soundId: string;
+    /** 音量 0.0~1.0 */
+    volume?: number;
+  }): Promise<{
+    /** 是否正在播放 */
+    playing: boolean;
+    /** 音效 ID */
+    soundId: string;
+  }>;
+
+  /** 停止当前播放 */
+  stop(): Promise<{
+    /** 是否成功 */
+    success: boolean;
+  }>;
+
+  /** 预加载音效到内存 */
+  preload(args: {
+    /** 音效 ID 列表 */
+    soundIds: string[];
+  }): Promise<{
+    /** 成功预加载的资源数量 */
+    preloaded: number;
+  }>;
+}

package/generated/device.ts

@@ -0,0 +1,28 @@
+// ============================================================
+// 此文件由 h5_app_container_generator 自动生成，请勿手动修改。
+// 运行 `dart run build_runner build` 重新生成。
+// ============================================================
+
+/** 设备能力调用 */
+export interface Device {
+  /** 触发设备震动 */
+  vibrate(args: {
+    /** 震动时长（毫秒） */
+    duration?: number;
+  }): Promise<{
+    /** 是否成功 */
+    success: boolean;
+  }>;
+
+  /** 获取设备信息 */
+  getDeviceInfo(): Promise<{
+    /** 平台标识（ios / android） */
+    platform: string;
+    /** 系统版本号 */
+    version: string;
+    /** 屏幕宽度（逻辑像素） */
+    screenWidth: number;
+    /** 屏幕高度（逻辑像素） */
+    screenHeight: number;
+  }>;
+}

package/generated/index.ts

@@ -0,0 +1,40 @@
+// ============================================================
+// 此文件由 h5_app_container_generator 自动生成，请勿手动修改。
+// 运行 `dart run build_runner build` 重新生成。
+// ============================================================
+
+import { bridge } from '../src/mrp-bridge';
+import type { AiTutor } from './ai_tutor';
+import type { Audio } from './audio';
+import type { Device } from './device';
+import type { User } from './user';
+
+export type { AiTutor } from './ai_tutor';
+export type { Audio } from './audio';
+export type { Device } from './device';
+export type { User } from './user';
+
+// ============================================================
+// 工厂函数（适用于任何上下文）
+// ============================================================
+
+/** 获取 ai_tutor 的类型安全代理 */
+export function getAiTutor(): AiTutor {
+  return bridge.module<AiTutor>('ai_tutor');
+}
+
+/** 获取 audio 的类型安全代理 */
+export function getAudio(): Audio {
+  return bridge.module<Audio>('audio');
+}
+
+/** 获取 device 的类型安全代理 */
+export function getDevice(): Device {
+  return bridge.module<Device>('device');
+}
+
+/** 获取 user 的类型安全代理 */
+export function getUser(): User {
+  return bridge.module<User>('user');
+}
+

package/generated/user.ts

@@ -0,0 +1,30 @@
+// ============================================================
+// 此文件由 h5_app_container_generator 自动生成，请勿手动修改。
+// 运行 `dart run build_runner build` 重新生成。
+// ============================================================
+
+/** 用户信息与进度管理 */
+export interface User {
+  /** 获取当前学生信息 */
+  getProfile(): Promise<{
+    /** 学生姓名 */
+    name: string;
+    /** 当前等级 */
+    level: number;
+    /** 头像 URL */
+    avatar: string;
+    /** 年龄 */
+    age: number;
+  }>;
+
+  /** 保存学习进度 */
+  saveProgress(args: {
+    /** 当前页码 */
+    pageIndex: number;
+    /** 得分 */
+    score: number;
+  }): Promise<{
+    /** 是否成功 */
+    success: boolean;
+  }>;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dino-dev/bridge-core-ts",
+  "version": "0.0.1",
+  "description": "Bridge Core SDK for h5_app_container — H5 ↔ Flutter 通信 + 原生模块类型安全调用（零框架依赖）",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "generated"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "flutter",
+    "webview",
+    "bridge",
+    "h5-container"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nengli/h5_app_container",
+    "directory": "packages/bridge_core_ts"
+  }
+}