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

package/dist/src/mock-bridge.js

@@ -0,0 +1,247 @@
+/**
+ * 浏览器 Mock Bridge —— 让 H5 页面脱离 App 容器，在 Chrome 里直接开发调试。
+ *
+ * 不安装时，浏览器环境下 `whenReady()` 永不 resolve、所有原生调用静默返回 `null`，
+ * 页面会停在空状态且不报错。安装后即可拿到可控的假数据与事件。
+ *
+ * 仅供开发使用，请通过子路径引入，避免被打进生产包：
+ *
+ * @example
+ * ```ts
+ * if (import.meta.env.DEV) {
+ *   const { installMockBridge } = await import('@h5-container/bridge-core-ts/mock');
+ *   installMockBridge({
+ *     packageId: 'student_micro_pages',
+ *     allowedModules: ['user', 'audio', 'navigation'],
+ *     modules: {
+ *       user: { getProfile: { userId: '1', nickname: '测试同学' } },
+ *       audio: { play: async () => ({ ok: true }) },
+ *     },
+ *   });
+ * }
+ * ```
+ */
+import { bridge } from './mrp-bridge';
+// ============================================================
+// 内部状态
+// ============================================================
+const MOCK_FLAG = '__MRP_MOCK_BRIDGE__';
+const DEFAULT_DESIGN_LONG_SIDE = 812;
+const ZERO_SAFE_AREA = { top: 0, bottom: 0, left: 0, right: 0 };
+function buildAdaptation(patch) {
+    const screenWidth = patch?.screenWidth ?? window.innerWidth;
+    const screenHeight = patch?.screenHeight ?? window.innerHeight;
+    const designLongSide = patch?.designLongSide ?? DEFAULT_DESIGN_LONG_SIDE;
+    const scale = patch?.scale ?? Math.max(screenWidth, screenHeight) / designLongSide;
+    return {
+        designLongSide,
+        screenWidth,
+        screenHeight,
+        scale,
+        safeArea: patch?.safeArea ?? ZERO_SAFE_AREA,
+    };
+}
+// ============================================================
+// 安装
+// ============================================================
+/**
+ * 安装 Mock Bridge。
+ *
+ * 已经在真实容器中运行时会直接跳过，因此可以无条件调用。
+ */
+export function installMockBridge(config = {}) {
+    const existing = window.__MRP_MOCK__;
+    if (existing) {
+        console.warn('[Mock Bridge] 已安装，忽略重复调用');
+        return existing;
+    }
+    if (window.__FLUTTER_BRIDGE__) {
+        console.info('[Mock Bridge] 检测到真实原生容器，跳过安装');
+        return null;
+    }
+    const log = config.log ?? true;
+    const calls = [];
+    let adaptation = buildAdaptation(config.adaptation);
+    const previousNativeModules = window.NativeModules;
+    const emit = (type, action, payload = {}) => {
+        const message = {
+            type,
+            action,
+            payload,
+            timestamp: Date.now(),
+        };
+        if (log) {
+            console.log(`[Mock Bridge] → H5  ${type}/${action}`, payload);
+        }
+        window.dispatchEvent(new CustomEvent('flutterMessage', { detail: message }));
+    };
+    // ---- system 模块：容器内置，始终可用 ----
+    const systemModule = {
+        isModuleAllowed: (params) => ({
+            allowed: isAllowed(params?.namespace),
+            namespace: params?.namespace,
+        }),
+        getAvailableModules: () => ({
+            modules: config.registeredModules ?? config.allowedModules ?? [],
+        }),
+        getContainerInfo: () => ({
+            packageId: config.packageId ?? 'mock_package',
+            registeredModules: config.registeredModules ?? config.allowedModules ?? [],
+            allowedModules: config.allowedModules ?? null,
+            adaptation,
+            auth: config.auth,
+            debugEnabled: true,
+            isMockBridge: true,
+            ...config.containerInfoExtra,
+        }),
+    };
+    function isAllowed(namespace) {
+        if (namespace === 'system')
+            return true;
+        if (!config.allowedModules)
+            return true;
+        return config.allowedModules.includes(namespace);
+    }
+    function resolveImpl(namespace, method) {
+        if (namespace === 'system')
+            return systemModule[method];
+        return config.modules?.[namespace]?.[method];
+    }
+    // ---- NativeModules 代理 ----
+    const moduleProxyCache = new Map();
+    function createModuleProxy(namespace) {
+        const cached = moduleProxyCache.get(namespace);
+        if (cached)
+            return cached;
+        const proxy = new Proxy({}, {
+            // module() 用 `NativeModules[ns][method]` 做存在性判断，必须恒为真
+            has: () => true,
+            get: (_target, method) => {
+                if (typeof method !== 'string')
+                    return undefined;
+                return async (...args) => {
+                    if (!isAllowed(namespace)) {
+                        console.error(`[Mock Bridge] 模块 "${namespace}" 不在 allowedModules 中，` +
+                            `调用 ${namespace}.${method} 被拒绝。` +
+                            '请检查 package.meta.json 的 allowedModules。');
+                        return {
+                            __error__: 'MODULE_ACCESS_DENIED',
+                            __message__: `Module "${namespace}" not allowed`,
+                        };
+                    }
+                    const impl = resolveImpl(namespace, method);
+                    const missing = impl === undefined;
+                    const result = missing
+                        ? null
+                        : typeof impl === 'function'
+                            ? await impl(...args)
+                            : impl;
+                    calls.push({
+                        namespace,
+                        method,
+                        args,
+                        result,
+                        missing,
+                        timestamp: Date.now(),
+                    });
+                    if (missing) {
+                        console.warn(`[Mock Bridge] 未定义 ${namespace}.${method}，返回 null。` +
+                            `可在 installMockBridge 的 modules.${namespace}.${method} 中补充。`, { args });
+                    }
+                    else if (log) {
+                        console.log(`[Mock Bridge] ${namespace}.${method}`, {
+                            args,
+                            result,
+                        });
+                    }
+                    return result;
+                };
+            },
+        });
+        moduleProxyCache.set(namespace, proxy);
+        return proxy;
+    }
+    window.NativeModules = new Proxy({}, {
+        has: () => true,
+        get: (_target, namespace) => {
+            if (typeof namespace !== 'string')
+                return undefined;
+            return createModuleProxy(namespace);
+        },
+    });
+    // ---- __FLUTTER_BRIDGE__ ----
+    window.__FLUTTER_BRIDGE__ = {
+        send: async (type, action, payload) => {
+            const result = config.onSend?.(type, action, payload) ?? null;
+            if (log) {
+                console.log(`[Mock Bridge] H5 → ${type}/${action}`, payload);
+            }
+            return result;
+        },
+        onMessage: (jsonString) => {
+            try {
+                const message = JSON.parse(jsonString);
+                emit(message.type, message.action, message.payload);
+            }
+            catch (e) {
+                console.error('[Mock Bridge] onMessage 解析失败:', e);
+            }
+        },
+    };
+    window.__FLUTTER_BRIDGE__[MOCK_FLAG] = true;
+    // ---- 窗口尺寸联动 ----
+    const handleResize = () => {
+        adaptation = buildAdaptation({
+            ...config.adaptation,
+            screenWidth: window.innerWidth,
+            screenHeight: window.innerHeight,
+            scale: undefined,
+        });
+        emit('adaptation', 'changed', adaptation);
+    };
+    const followResize = config.followWindowResize ?? true;
+    if (followResize) {
+        window.addEventListener('resize', handleResize);
+    }
+    // ---- 句柄 ----
+    const handle = {
+        emit,
+        setAdaptation(patch) {
+            adaptation = buildAdaptation({ ...adaptation, ...patch });
+            emit('adaptation', 'changed', adaptation);
+        },
+        calls,
+        printMissing() {
+            const missing = calls.filter((c) => c.missing);
+            if (missing.length === 0) {
+                console.log('[Mock Bridge] 所有原生调用都已命中 mock 定义');
+                return;
+            }
+            console.table(missing.map((c) => ({
+                调用: `${c.namespace}.${c.method}`,
+                参数: JSON.stringify(c.args),
+            })));
+        },
+        uninstall() {
+            if (followResize) {
+                window.removeEventListener('resize', handleResize);
+            }
+            delete window.__FLUTTER_BRIDGE__;
+            window.NativeModules = previousNativeModules;
+            delete window.__MRP_MOCK__;
+        },
+    };
+    window.__MRP_MOCK__ = handle;
+    // 唤醒可能已结束的就绪轮询，让 whenReady() 立即 resolve
+    bridge.refreshReady();
+    console.info(`[Mock Bridge] 已安装（packageId=${config.packageId ?? 'mock_package'}）。` +
+        '控制台可用 window.__MRP_MOCK__ 手工触发事件、查看调用记录。');
+    return handle;
+}
+/**
+ * 仅在非容器环境安装 mock，在真机/App 中自动跳过。
+ *
+ * 等价于 `installMockBridge`，语义更明确，适合直接写在入口文件里。
+ */
+export const setupDevBridge = installMockBridge;
+//# sourceMappingURL=mock-bridge.js.map

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

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

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

@@ -41,6 +41,13 @@ declare global {
         NativeModules?: Record<string, Record<string, (...args: unknown[]) => Promise<unknown>>>;
     }
 }
+/** Bridge 就绪状态 */
+export type BridgeReadyState = 'pending' | 'ready' | 'unavailable';
+/** `whenReady()` 选项 */
+export interface WhenReadyOptions {
+    /** 超时毫秒数，超时后 Promise 以错误 reject；不传则沿用「永不 reject」的旧行为 */
+    timeoutMs?: number;
+}
 /**
  * Bridge SDK 主类。
  *
@@ -55,10 +62,25 @@ export declare class MrpBridge {
     private _readyPromiseResolve;
     private _readyPromise;
     private _retryCount;
+    private _readyState;
+    private _readyTimer;
     constructor();
     private _checkReady;
-    /** 等待 Bridge 就绪 */
-    whenReady(): Promise<void>;
+    /**
+     * 重新触发一次就绪检测。
+     *
+     * 供 Mock Bridge 在注入后立即生效使用；轮询已结束时也能重新唤醒。
+     */
+    refreshReady(): void;
+    /** 当前就绪状态：等待中 / 已就绪 / 判定为不在容器环境 */
+    get readyState(): BridgeReadyState;
+    /**
+     * 等待 Bridge 就绪。
+     *
+     * 默认沿用旧语义：未就绪时 Promise 一直挂起、不会 reject。
+     * 传入 `timeoutMs` 可在超时后 reject，便于页面给出明确的错误态。
+     */
+    whenReady(options?: WhenReadyOptions): Promise<void>;
     /** 是否在 Flutter WebView 容器中运行 */
     get isInContainer(): boolean;
     /**
@@ -102,7 +124,6 @@ export declare class MrpBridge {
      */
     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

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

package/dist/src/mrp-bridge.js

@@ -16,6 +16,12 @@
  * await audio.play({ soundId: 'success', volume: 0.8 });
  * ```
  */
+import { installIframeHostBridge } from './iframe-host';
+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
 // ============================================================
@@ -33,6 +39,8 @@ export class MrpBridge {
         this._pendingMessages = [];
         this._readyPromiseResolve = null;
         this._retryCount = 0;
+        this._readyState = 'pending';
+        this._readyTimer = null;
         this._readyPromise = new Promise((resolve) => {
             this._readyPromiseResolve = resolve;
         });
@@ -54,29 +62,79 @@ export class MrpBridge {
     }
     // ---- 就绪检测 ----
     _checkReady() {
+        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;
         }
-        else {
-            this._retryCount++;
-            if (this._retryCount < 50) {
-                setTimeout(() => this._checkReady(), 100);
-            }
-            else {
-                console.warn('[MRP Bridge] Flutter Bridge 未注入，可能不在容器环境中运行');
-            }
+        this._retryCount++;
+        if (this._retryCount < READY_MAX_RETRY) {
+            this._readyTimer = setTimeout(() => this._checkReady(), READY_POLL_INTERVAL_MS);
+            return;
+        }
+        if (window.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));
     }
-    /** 等待 Bridge 就绪 */
-    whenReady() {
-        return this._readyPromise;
+    /**
+     * 重新触发一次就绪检测。
+     *
+     * 供 Mock Bridge 在注入后立即生效使用；轮询已结束时也能重新唤醒。
+     */
+    refreshReady() {
+        if (this._readyState === 'ready')
+            return;
+        this._retryCount = 0;
+        this._readyState = 'pending';
+        this._checkReady();
+    }
+    /** 当前就绪状态：等待中 / 已就绪 / 判定为不在容器环境 */
+    get readyState() {
+        return this._readyState;
+    }
+    /**
+     * 等待 Bridge 就绪。
+     *
+     * 默认沿用旧语义：未就绪时 Promise 一直挂起、不会 reject。
+     * 传入 `timeoutMs` 可在超时后 reject，便于页面给出明确的错误态。
+     */
+    whenReady(options) {
+        const timeoutMs = options?.timeoutMs;
+        if (timeoutMs === undefined)
+            return this._readyPromise;
+        return new Promise((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() {
-        return !!window.__FLUTTER_BRIDGE__ || !!window.flutter_inappwebview;
+        return (!!window.__FLUTTER_BRIDGE__ || !!window.flutter_inappwebview);
     }
     // ---- 消息发送 ----
     /**
@@ -161,7 +219,8 @@ export class MrpBridge {
                         // 检查模块访问被拒绝错误
                         if (result &&
                             typeof result === 'object' &&
-                            result.__error__ === 'MODULE_ACCESS_DENIED') {
+                            result.__error__ ===
+                                'MODULE_ACCESS_DENIED') {
                             console.error(`[MRP Bridge] 模块访问被拒绝: ${namespace}.${method}`, result.__message__);
                             return null;
                         }
@@ -178,6 +237,7 @@ export class MrpBridge {
 // 单例 & 导出
 // ============================================================
 /** Bridge 单例实例 */
+installIframeHostBridge();
 export const bridge = new MrpBridge();
 // 挂载到 window，方便非模块化项目使用
 window.mrpBridge = bridge;

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

@@ -1 +1 @@
-{"version":3,"file":"mrp-bridge.js","sourceRoot":"","sources":["../../src/mrp-bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mrp-bridge.js","sourceRoot":"","sources":["../../src/mrp-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAyExD,MAAM,sBAAsB,GAAG,GAAG,CAAC;AACnC,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,wDAAwD;AACxD,+DAA+D;AAC/D,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAExC,+DAA+D;AAC/D,YAAY;AACZ,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IAUrB;QATQ,qBAAgB,GAAqB,EAAE,CAAC;QACxC,WAAM,GAAG,KAAK,CAAC;QACf,qBAAgB,GAAqB,EAAE,CAAC;QACxC,yBAAoB,GAAwB,IAAI,CAAC;QAEjD,gBAAW,GAAG,CAAC,CAAC;QAChB,gBAAW,GAAqB,SAAS,CAAC;QAC1C,gBAAW,GAAyC,IAAI,CAAC;QAGhE,IAAI,CAAC,aAAa,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClD,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC;QACrC,CAAC,CAAC,CAAC;QAEH,qBAAqB;QACrB,MAAM,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,CAAC,CAAC,KAAkB,EAAE,EAAE;YACjE,MAAM,GAAG,GAAG,KAAK,CAAC,MAAuB,CAAC;YAC1C,cAAc;YACd,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAC5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAChC,IAAI,CAAC;oBACJ,OAAO,CAAC,GAAG,CAAC,CAAC;gBACd,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACZ,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC,CAAC,CAAC;gBAC1C,CAAC;YACF,CAAC;QACF,CAAC,CAAkB,CAAC,CAAC;QAErB,IAAI,CAAC,WAAW,EAAE,CAAC;IACpB,CAAC;IAED,iBAAiB;IAET,WAAW;QAClB,IAAI,IAAI,CAAC,WAAW,KAAK,OAAO;YAAE,OAAO;QAEzC,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;gBAC/B,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACzB,CAAC;YACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;YAC3B,IAAI,CAAC,oBAAoB,EAAE,EAAE,CAAC;YAC9B,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1D,IAAI,CAAC,gBAAgB,GAAG,EAAE,CAAC;YAC3B,OAAO;QACR,CAAC;QAED,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,IAAI,CAAC,WAAW,GAAG,eAAe,EAAE,CAAC;YACxC,IAAI,CAAC,WAAW,GAAG,UAAU,CAC5B,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,EACxB,sBAAsB,CACtB,CAAC;YACF,OAAO;QACR,CAAC;QAED,IAAK,MAAc,CAAC,oBAAoB,EAAE,CAAC;YAC1C,IAAI,CAAC,WAAW,GAAG,UAAU,CAC5B,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,EACxB,2BAA2B,CAC3B,CAAC;YACF,OAAO;QACR,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,aAAa,CAAC;QACjC,OAAO,CAAC,KAAK,CACZ;YACC,4DAA4D;YAC5D,kDAAkD;YAClD,qCAAqC;YACrC,+BAA+B;YAC/B,0EAA0E;SAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,EACZ,CAAC,CAAC,eAAe,GAAG,sBAAsB,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAC9D,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,YAAY;QACX,IAAI,IAAI,CAAC,WAAW,KAAK,OAAO;YAAE,OAAO;QACzC,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC7B,IAAI,CAAC,WAAW,EAAE,CAAC;IACpB,CAAC;IAED,mCAAmC;IACnC,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,WAAW,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,OAA0B;QACnC,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,CAAC;QACrC,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,aAAa,CAAC;QAEvD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC7B,MAAM,CACL,IAAI,KAAK,CACR,2BAA2B,SAAS,MAAM;oBACzC,mCAAmC,CACpC,CACD,CAAC;YACH,CAAC,EAAE,SAAS,CAAC,CAAC;YACd,KAAK,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE;gBACjC,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,EAAE,CAAC;YACX,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,gCAAgC;IAChC,IAAI,aAAa;QAChB,OAAO,CACN,CAAC,CAAC,MAAM,CAAC,kBAAkB,IAAI,CAAC,CAAE,MAAc,CAAC,oBAAoB,CACrE,CAAC;IACH,CAAC;IAED,iBAAiB;IAEjB;;;;;OAKG;IACH,IAAI,CACH,IAAY,EACZ,MAAc,EACd,UAAmC,EAAE;QAErC,MAAM,GAAG,GAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QACtD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC,OAAO,CAAC,IAAS,CAAC,CAAC;IACnC,CAAC;IAEO,OAAO,CAAI,GAAmB;QACrC,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAC/B,OAAO,MAAM,CAAC,kBAAkB,CAAC,IAAI,CACpC,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,MAAM,EACV,GAAG,CAAC,OAAO,CACG,CAAC;QACjB,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,IAAS,CAAC,CAAC;IACnC,CAAC;IAED,iBAAiB;IAEjB;;;OAGG;IACH,SAAS,CACR,OAA0B;QAE1B,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAyB,CAAC,CAAC;QACtD,OAAO,GAAG,EAAE;YACX,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CACnD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,OAAO,CACpB,CAAC;QACH,CAAC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,EAAE,CACD,IAAY,EACZ,MAAqB,EACrB,OAA0B;QAE1B,MAAM,cAAc,GAAmB,CAAC,GAAG,EAAE,EAAE;YAC9C,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC;gBACpE,OAA0B,CAAC,GAAG,CAAC,CAAC;YAClC,CAAC;QACF,CAAC,CAAC;QACF,cAAc,CAAC,SAAS,GAAG,OAAyB,CAAC;QACrD,cAAc,CAAC,KAAK,GAAG,IAAI,CAAC;QAC5B,cAAc,CAAC,OAAO,GAAG,MAAM,CAAC;QAChC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3C,OAAO,GAAG,EAAE;YACX,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CACnD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,cAAc,CAC3B,CAAC;QACH,CAAC,CAAC;IACH,CAAC;IAED,mBAAmB;IAEnB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CACL,SAAiB;QAEjB,OAAO,IAAI,KAAK,CAAC,EAAO,EAAE;YACzB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAuB,EAAE,EAAE;gBACzC,IAAI,OAAO,MAAM,KAAK,QAAQ;oBAAE,OAAO,SAAS,CAAC;gBACjD,OAAO,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;oBACnC,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;wBACjD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAC3D,GAAG,IAAI,CACP,CAAC;wBACF,cAAc;wBACd,IACC,MAAM;4BACN,OAAO,MAAM,KAAK,QAAQ;4BACzB,MAAkC,CAAC,SAAS;gCAC5C,sBAAsB,EACtB,CAAC;4BACF,OAAO,CAAC,KAAK,CACZ,yBAAyB,SAAS,IAAI,MAAM,EAAE,EAC7C,MAAkC,CAAC,WAAW,CAC/C,CAAC;4BACF,OAAO,IAAI,CAAC;wBACb,CAAC;wBACD,OAAO,MAAM,CAAC;oBACf,CAAC;oBACD,OAAO,CAAC,IAAI,CACX,8BAA8B,SAAS,IAAI,MAAM,MAAM,CACvD,CAAC;oBACF,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC9B,CAAC,CAAC;YACH,CAAC;SACD,CAAC,CAAC;IACJ,CAAC;CACD;AAED,+DAA+D;AAC/D,UAAU;AACV,+DAA+D;AAE/D,kBAAkB;AAClB,uBAAuB,EAAE,CAAC;AAC1B,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;AAEtC,wBAAwB;AACxB,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC;AAE1B,eAAe,MAAM,CAAC"}

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

@@ -38,6 +38,15 @@ export interface ArAdaptationInfo {
     screenWidth: number;
     screenHeight: number;
     scale: number;
+    /** 设备安全区（逻辑像素）。WebView 里 `env(safe-area-inset-*)` 常常拿不到，改由 App 注入。 */
+    safeArea?: SafeAreaInsets;
+}
+/** 设备四边的安全区尺寸，单位与 screenWidth/screenHeight 一致。 */
+export interface SafeAreaInsets {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
 }
 /**
  * 容器内置系统模块接口。

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

@@ -1 +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,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;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"}
+{"version":3,"file":"system-module.d.ts","sourceRoot":"","sources":["../../src/system-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,0BAA0B;AAC1B,MAAM,WAAW,mBAAmB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8BAA8B;AAC9B,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,2BAA2B;AAC3B,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAChC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACd;AAMD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,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;CACjD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAE9C"}

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

@@ -1 +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;AAqDtC,+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"}
+{"version":3,"file":"system-module.js","sourceRoot":"","sources":["../../src/system-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AA+DtC,+DAA+D;AAC/D,OAAO;AACP,+DAA+D;AAE/D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe;IAC9B,OAAO,MAAM,CAAC,MAAM,CAAe,QAAQ,CAAC,CAAC;AAC9C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dino-dev/bridge-core-ts",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Bridge Core SDK for h5_app_container — H5 ↔ Flutter 通信 + 原生模块类型安全调用（零框架依赖）",
   "type": "module",
   "main": "dist/src/index.js",
@@ -10,6 +10,11 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js",
       "default": "./dist/src/index.js"
+    },
+    "./mock": {
+      "types": "./dist/src/mock-bridge.d.ts",
+      "import": "./dist/src/mock-bridge.js",
+      "default": "./dist/src/mock-bridge.js"
     }
   },
   "files": [
@@ -22,6 +27,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm run build",
     "release": "npm publish --registry https://registry.npmjs.org",
     "dev": "tsc --watch",
@@ -42,4 +48,4 @@
     "url": "https://github.com/nengli/h5_app_container",
     "directory": "packages/bridge_core_ts"
   }
-}
+}

package/src/adaptation.ts

@@ -4,54 +4,80 @@
  * App 端以 812 作为设计稿最长边基准，将 adaptation 注入 system 模块。
  */
 
-import { getSystemModule, type ArAdaptationInfo } from './system-module';
+import {
+	getSystemModule,
+	type ArAdaptationInfo,
+	type SafeAreaInsets,
+} from './system-module';
 import { bridge, type Unsubscribe } from './mrp-bridge';
 
+const ZERO_SAFE_AREA: SafeAreaInsets = { top: 0, bottom: 0, left: 0, right: 0 };
+
 let currentScale = 1;
+let currentSafeArea: SafeAreaInsets = ZERO_SAFE_AREA;
 let bridgeUnsubscribe: Unsubscribe | null = null;
 const listeners = new Set<ArAdaptationListener>();
 
 export type ArAdaptationListener = (adaptation: ArAdaptationInfo) => void;
 
-function applyAdaptation(adaptation: ArAdaptationInfo | null | undefined): ArAdaptationInfo | null {
-  if (!adaptation || !Number.isFinite(adaptation.scale) || adaptation.scale <= 0) {
-    currentScale = 1;
-    return null;
-  }
-  currentScale = adaptation.scale;
-  for (const listener of listeners) {
-    listener(adaptation);
-  }
-  return adaptation;
+function applyAdaptation(
+	adaptation: ArAdaptationInfo | null | undefined,
+): ArAdaptationInfo | null {
+	if (
+		!adaptation ||
+		!Number.isFinite(adaptation.scale) ||
+		adaptation.scale <= 0
+	) {
+		currentScale = 1;
+		currentSafeArea = ZERO_SAFE_AREA;
+		return null;
+	}
+	currentScale = adaptation.scale;
+	currentSafeArea = adaptation.safeArea ?? ZERO_SAFE_AREA;
+	for (const listener of listeners) {
+		listener(adaptation);
+	}
+	return adaptation;
 }
 
 function ensureAdaptationListener(): void {
-  if (bridgeUnsubscribe) return;
-  bridgeUnsubscribe = bridge.on<ArAdaptationInfo>('adaptation', 'changed', (message) => {
-    applyAdaptation(message.payload);
-  });
+	if (bridgeUnsubscribe) return;
+	bridgeUnsubscribe = bridge.on<ArAdaptationInfo>(
+		'adaptation',
+		'changed',
+		(message) => {
+			applyAdaptation(message.payload);
+		},
+	);
 }
 
 /** 从容器读取初始适配信息，并注册横竖屏变化监听。 */
 export async function initArAdaptation(): Promise<ArAdaptationInfo | null> {
-  ensureAdaptationListener();
-  const info = await getSystemModule().getContainerInfo();
-  return applyAdaptation(info?.adaptation);
+	ensureAdaptationListener();
+	const info = await getSystemModule().getContainerInfo();
+	return applyAdaptation(info?.adaptation);
 }
 
 /** 将设计稿尺寸转换为当前 App 屏幕尺寸。 */
 export function ar(value: number): number {
-  return value * currentScale;
+	return value * currentScale;
 }
 
 /** 获取当前适配比例，便于 Canvas 或自定义渲染使用。 */
 export function getArScale(): number {
-  return currentScale;
+	return currentScale;
+}
+
+/** 获取 App 注入的设备安全区；不在容器内或 App 未注入时返回全 0。 */
+export function getSafeArea(): SafeAreaInsets {
+	return currentSafeArea;
 }
 
 /** 监听 App 横竖屏或窗口尺寸变化，返回取消监听函数。 */
-export function onArAdaptationChange(listener: ArAdaptationListener): Unsubscribe {
-  ensureAdaptationListener();
-  listeners.add(listener);
-  return () => listeners.delete(listener);
+export function onArAdaptationChange(
+	listener: ArAdaptationListener,
+): Unsubscribe {
+	ensureAdaptationListener();
+	listeners.add(listener);
+	return () => listeners.delete(listener);
 }