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

package/src/mock-bridge.ts

@@ -0,0 +1,390 @@
+/**
+ * 浏览器 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, type BridgeMessage } from './mrp-bridge';
+import type { ArAdaptationInfo, SafeAreaInsets } from './system-module';
+
+// ============================================================
+// 类型定义
+// ============================================================
+
+/**
+ * 单个模块的 mock 实现。
+ *
+ * 值可以是函数（接收原始调用参数），也可以是静态数据（直接作为返回值）。
+ */
+export type MockModuleImpl = Record<
+	string,
+	((...args: any[]) => unknown | Promise<unknown>) | unknown
+>;
+
+/** 一次原生调用的记录 */
+export interface MockCallRecord {
+	namespace: string;
+	method: string;
+	args: unknown[];
+	result: unknown;
+	/** 未命中 mock 定义时为 true */
+	missing: boolean;
+	timestamp: number;
+}
+
+export interface MockBridgeConfig {
+	/** 容器信息里的包 ID */
+	packageId?: string;
+	/**
+	 * 授权模块白名单。
+	 *
+	 * 传入后会像真实容器一样拦截越权调用并返回 `MODULE_ACCESS_DENIED`，
+	 * 可在浏览器阶段提前发现 `package.meta.json` 的 `allowedModules` 漏配。
+	 * 不传则不做权限校验。
+	 */
+	allowedModules?: string[];
+	/** 容器已注册模块列表，默认与 allowedModules 一致 */
+	registeredModules?: string[];
+	/** 屏幕适配信息，缺省字段按当前窗口尺寸推算 */
+	adaptation?: Partial<ArAdaptationInfo>;
+	/** 注入到 getContainerInfo().auth，供 h5_app_http 读取 */
+	auth?: Record<string, unknown>;
+	/** 追加到 getContainerInfo() 的其他字段 */
+	containerInfoExtra?: Record<string, unknown>;
+	/** 各命名空间的 mock 实现 */
+	modules?: Record<string, MockModuleImpl>;
+	/** 处理 `bridge.send()`，返回值作为调用方收到的结果 */
+	onSend?: (
+		type: string,
+		action: string,
+		payload: Record<string, unknown>,
+	) => unknown;
+	/** 是否打印调用日志，默认 true */
+	log?: boolean;
+	/** 窗口尺寸变化时自动重算并广播 adaptation，默认 true */
+	followWindowResize?: boolean;
+}
+
+/** 安装后返回的控制句柄 */
+export interface MockBridgeHandle {
+	/** 模拟一条 Native → H5 消息 */
+	emit(type: string, action: string, payload?: Record<string, unknown>): void;
+	/** 更新屏幕适配信息并广播 `adaptation/changed` */
+	setAdaptation(patch: Partial<ArAdaptationInfo>): void;
+	/** 按时间顺序记录的原生调用 */
+	readonly calls: MockCallRecord[];
+	/** 打印所有未命中 mock 定义的调用，便于补齐 */
+	printMissing(): void;
+	/** 卸载 mock，恢复安装前的 window 状态 */
+	uninstall(): void;
+}
+
+// ============================================================
+// 内部状态
+// ============================================================
+
+const MOCK_FLAG = '__MRP_MOCK_BRIDGE__';
+const DEFAULT_DESIGN_LONG_SIDE = 812;
+const ZERO_SAFE_AREA: SafeAreaInsets = { top: 0, bottom: 0, left: 0, right: 0 };
+
+declare global {
+	interface Window {
+		/** 已安装的 Mock Bridge 句柄，可在控制台直接操作 */
+		__MRP_MOCK__?: MockBridgeHandle;
+	}
+}
+
+function buildAdaptation(
+	patch: Partial<ArAdaptationInfo> | undefined,
+): ArAdaptationInfo {
+	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: MockBridgeConfig = {},
+): MockBridgeHandle | null {
+	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: MockCallRecord[] = [];
+	let adaptation = buildAdaptation(config.adaptation);
+
+	const previousNativeModules = window.NativeModules;
+
+	const emit = (
+		type: string,
+		action: string,
+		payload: Record<string, unknown> = {},
+	): void => {
+		const message: BridgeMessage = {
+			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: MockModuleImpl = {
+		isModuleAllowed: (params: { namespace: string }) => ({
+			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: string): boolean {
+		if (namespace === 'system') return true;
+		if (!config.allowedModules) return true;
+		return config.allowedModules.includes(namespace);
+	}
+
+	function resolveImpl(namespace: string, method: string): unknown {
+		if (namespace === 'system') return systemModule[method];
+		return config.modules?.[namespace]?.[method];
+	}
+
+	// ---- NativeModules 代理 ----
+
+	const moduleProxyCache = new Map<string, Record<string, unknown>>();
+
+	function createModuleProxy(namespace: string): Record<string, unknown> {
+		const cached = moduleProxyCache.get(namespace);
+		if (cached) return cached;
+
+		const proxy = new Proxy({} as Record<string, unknown>, {
+			// module() 用 `NativeModules[ns][method]` 做存在性判断，必须恒为真
+			has: () => true,
+			get: (_target, method: string | symbol) => {
+				if (typeof method !== 'string') return undefined;
+				return async (...args: unknown[]) => {
+					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 as (...a: unknown[]) => unknown)(...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(
+		{} as Record<
+			string,
+			Record<string, (...args: unknown[]) => Promise<unknown>>
+		>,
+		{
+			has: () => true,
+			get: (_target, namespace: string | symbol) => {
+				if (typeof namespace !== 'string') return undefined;
+				return createModuleProxy(namespace);
+			},
+		},
+	);
+
+	// ---- __FLUTTER_BRIDGE__ ----
+
+	window.__FLUTTER_BRIDGE__ = {
+		send: async (
+			type: string,
+			action: string,
+			payload: Record<string, unknown>,
+		) => {
+			const result = config.onSend?.(type, action, payload) ?? null;
+			if (log) {
+				console.log(`[Mock Bridge] H5 → ${type}/${action}`, payload);
+			}
+			return result;
+		},
+		onMessage: (jsonString: string) => {
+			try {
+				const message = JSON.parse(jsonString) as BridgeMessage;
+				emit(message.type, message.action, message.payload);
+			} catch (e) {
+				console.error('[Mock Bridge] onMessage 解析失败:', e);
+			}
+		},
+	};
+	(window.__FLUTTER_BRIDGE__ as Record<string, unknown>)[MOCK_FLAG] = true;
+
+	// ---- 窗口尺寸联动 ----
+
+	const handleResize = () => {
+		adaptation = buildAdaptation({
+			...config.adaptation,
+			screenWidth: window.innerWidth,
+			screenHeight: window.innerHeight,
+			scale: undefined,
+		});
+		emit(
+			'adaptation',
+			'changed',
+			adaptation as unknown as Record<string, unknown>,
+		);
+	};
+	const followResize = config.followWindowResize ?? true;
+	if (followResize) {
+		window.addEventListener('resize', handleResize);
+	}
+
+	// ---- 句柄 ----
+
+	const handle: MockBridgeHandle = {
+		emit,
+		setAdaptation(patch) {
+			adaptation = buildAdaptation({ ...adaptation, ...patch });
+			emit(
+				'adaptation',
+				'changed',
+				adaptation as unknown as Record<string, unknown>,
+			);
+		},
+		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;