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

package/src/content-protocol.ts

@@ -4,6 +4,8 @@ export const bridgeMessageTypes = {
   render: 'render',
   interaction: 'interaction',
   error: 'error',
+  /** 宿主镜像给 H5 的回合事件（单向：宿主 → H5）。 */
+  agent: 'agent',
 } as const;
 
 export const renderActions = {
@@ -91,4 +93,69 @@ export const bridgeError = {
   report(payload: BridgeErrorPayload): Promise<unknown> {
     return bridge.send(bridgeMessageTypes.error, 'report', payload);
   },
-} as const;
+} as const;
+
+/**
+ * 回合事件协议：宿主把「现在轮到谁、这一轮发生了什么」镜像给 H5。
+ *
+ * 用在 H5 页面**作为一个交互步骤**嵌在原生流程里的场景（AI 教学 / 问诊等）：
+ * 原生题型能收到宿主的回合事件，H5 题型也应该能。宿主只负责把事实发下来，
+ * 怎么响应（放开作答、复位重做、演完反馈再收尾）由 H5 自己决定。
+ *
+ * 线格式：`{ type: 'agent', action, payload: { iid, ... } }`
+ */
+export const agentEvents = {
+  /** 作答权交回给用户（宿主的开场播报已结束）。 */
+  startLearn: 'start_learn',
+  /** 本题重做。 */
+  retryLearn: 'retry_learn',
+  /** 本题判过；若宿主把收尾交给了 H5，H5 需回发一次收尾动作，否则流程不推进。 */
+  passLearn: 'pass_learn',
+  /** 用户**绕过这块 H5** 上行了一次作答（原生输入栏、原生选择器等）。 */
+  externalAnswer: 'external_answer',
+} as const;
+
+export interface AgentEventPayload {
+  /**
+   * 这条事件属于哪一屏。
+   *
+   * 内容（`render/set`）和事件通常来自宿主上游的两条独立消息，到达先后不保证。
+   * 拿它对齐「这条事件说的是不是我现在这一屏」，不匹配就先扣着。
+   */
+  iid?: string;
+  [key: string]: unknown;
+}
+
+export interface ExternalAnswerPayload extends AgentEventPayload {
+  /** 那次绕过本页的上行负载（形态由宿主定义）。 */
+  answer?: Record<string, unknown>;
+}
+
+export interface AgentEventHandlers {
+  startLearn?(payload: AgentEventPayload, message: BridgeMessage<AgentEventPayload>): void;
+  retryLearn?(payload: AgentEventPayload, message: BridgeMessage<AgentEventPayload>): void;
+  passLearn?(payload: AgentEventPayload, message: BridgeMessage<AgentEventPayload>): void;
+  externalAnswer?(payload: ExternalAnswerPayload, message: BridgeMessage<ExternalAnswerPayload>): void;
+}
+
+/** 只订阅传了 handler 的那几个事件；返回的函数一次性退订。 */
+export function bindAgentProtocol(
+  handlers: AgentEventHandlers,
+  transport: Pick<ProtocolTransport, 'on'> = bridge,
+): Unsubscribe {
+  const pairs: Array<[string, ((payload: never, message: never) => void) | undefined]> = [
+    [agentEvents.startLearn, handlers.startLearn],
+    [agentEvents.retryLearn, handlers.retryLearn],
+    [agentEvents.passLearn, handlers.passLearn],
+    [agentEvents.externalAnswer, handlers.externalAnswer],
+  ];
+  const subscriptions = pairs
+    .filter(([, handler]) => handler !== undefined)
+    .map(([action, handler]) =>
+      transport.on(bridgeMessageTypes.agent, action, (message: BridgeMessage<any>) => {
+        (handler as (payload: unknown, message: unknown) => void)(message.payload ?? {}, message);
+      }),
+    );
+
+  return () => subscriptions.forEach((unsubscribe) => unsubscribe());
+}

package/src/iframe-host.ts

@@ -0,0 +1,169 @@
+/**
+ * iframe 宿主模式：H5 被嵌在网页 iframe 里（如教研后台的实时预览）时，把父窗口当作原生容器。
+ *
+ * 触发条件：页面在 iframe 内，且 URL 带 `nl_host=iframe&nl_host_origin=<父窗口 origin>`。
+ * 父窗口 origin 由宿主显式声明：只向它发消息、只收它发来的消息，其它来源一律忽略。
+ *
+ * H5 业务代码无需改动：`bridge.whenReady()` / `bindRenderProtocol` / `bindAgentProtocol`
+ * 照常工作。原生模块在预览里不可用（`system` 除外），调用返回 `null` 并通知宿主记录。
+ *
+ * 线格式（postMessage，均带 `__nlBridge: 1`）：
+ * - H5 → 宿主：`{ kind: 'send', type, action, payload }`
+ * - H5 → 宿主：`{ kind: 'module', namespace, method }`（预览里不可用的原生调用）
+ * - 宿主 → H5：`{ kind: 'message', type, action, payload }`
+ */
+
+import type { BridgeMessage } from './mrp-bridge';
+import type { ArAdaptationInfo } from './system-module';
+
+export const IFRAME_HOST_PARAM = 'nl_host';
+export const IFRAME_HOST_ORIGIN_PARAM = 'nl_host_origin';
+export const IFRAME_HOST_MARK = '__nlBridge';
+
+const DESIGN_LONG_SIDE = 812;
+
+interface HostEnvelope {
+	[IFRAME_HOST_MARK]: 1;
+	kind: string;
+	[key: string]: unknown;
+}
+
+function isHostEnvelope(data: unknown): data is HostEnvelope {
+	return (
+		typeof data === 'object' &&
+		data !== null &&
+		(data as Record<string, unknown>)[IFRAME_HOST_MARK] === 1
+	);
+}
+
+function resolveHostOrigin(): string | null {
+	if (!window.parent || window.parent === window || !window.location) return null;
+	const params = new URLSearchParams(window.location.search);
+	if (params.get(IFRAME_HOST_PARAM) !== 'iframe') return null;
+	const raw = params.get(IFRAME_HOST_ORIGIN_PARAM);
+	if (!raw) return null;
+	try {
+		const origin = new URL(raw).origin;
+		return origin === 'null' ? null : origin;
+	} catch {
+		return null;
+	}
+}
+
+function currentAdaptation(): ArAdaptationInfo {
+	const screenWidth = window.innerWidth;
+	const screenHeight = window.innerHeight;
+	return {
+		designLongSide: DESIGN_LONG_SIDE,
+		screenWidth,
+		screenHeight,
+		scale: Math.max(screenWidth, screenHeight) / DESIGN_LONG_SIDE,
+		safeArea: { top: 0, bottom: 0, left: 0, right: 0 },
+	};
+}
+
+/**
+ * 满足触发条件时安装 iframe 宿主桥；已在原生容器内或条件不满足时什么都不做。
+ *
+ * @returns 是否已安装
+ */
+export function installIframeHostBridge(): boolean {
+	if (typeof window === 'undefined' || window.__FLUTTER_BRIDGE__) return false;
+	const hostOrigin = resolveHostOrigin();
+	if (!hostOrigin) return false;
+
+	const post = (kind: string, body: Record<string, unknown>): void => {
+		window.parent.postMessage(
+			{ [IFRAME_HOST_MARK]: 1, kind, ...body },
+			hostOrigin,
+		);
+	};
+
+	const dispatch = (
+		type: string,
+		action: string,
+		payload: Record<string, unknown>,
+	): void => {
+		const message: BridgeMessage = {
+			type,
+			action,
+			payload,
+			timestamp: Date.now(),
+		};
+		window.dispatchEvent(new CustomEvent('flutterMessage', { detail: message }));
+	};
+
+	window.addEventListener('message', (event: MessageEvent) => {
+		if (event.source !== window.parent || event.origin !== hostOrigin) return;
+		const data = event.data;
+		if (!isHostEnvelope(data) || data.kind !== 'message') return;
+		if (typeof data.type !== 'string' || typeof data.action !== 'string') return;
+		const payload =
+			typeof data.payload === 'object' && data.payload !== null
+				? (data.payload as Record<string, unknown>)
+				: {};
+		dispatch(data.type, data.action, payload);
+	});
+
+	window.addEventListener('resize', () => {
+		dispatch(
+			'adaptation',
+			'changed',
+			currentAdaptation() as unknown as Record<string, unknown>,
+		);
+	});
+
+	const systemModule: Record<string, () => unknown> = {
+		isModuleAllowed: () => ({ allowed: false, namespace: '' }),
+		getAvailableModules: () => ({ modules: [] }),
+		getContainerInfo: () => ({
+			packageId: null,
+			registeredModules: [],
+			allowedModules: [],
+			adaptation: currentAdaptation(),
+			isIframeHost: true,
+		}),
+	};
+
+	const moduleProxy = (namespace: string) =>
+		new Proxy({} as Record<string, unknown>, {
+			// bridge.module() 用 `NativeModules[ns][method]` 做存在性判断，必须恒为真
+			has: () => true,
+			get: (_target, method: string | symbol) => {
+				if (typeof method !== 'string') return undefined;
+				return async () => {
+					if (namespace === 'system' && method in systemModule) {
+						return systemModule[method]();
+					}
+					post('module', { namespace, method });
+					return null;
+				};
+			},
+		});
+
+	window.NativeModules = new Proxy(
+		{} as NonNullable<Window['NativeModules']>,
+		{
+			has: () => true,
+			get: (_target, namespace: string | symbol) =>
+				typeof namespace === 'string' ? moduleProxy(namespace) : undefined,
+		},
+	);
+
+	window.__FLUTTER_BRIDGE__ = {
+		send: async (type, action, payload) => {
+			post('send', { type, action, payload });
+			return null;
+		},
+		onMessage: (jsonString: string) => {
+			try {
+				const message = JSON.parse(jsonString) as BridgeMessage;
+				dispatch(message.type, message.action, message.payload);
+			} catch (e) {
+				console.error('[MRP Bridge] iframe 宿主消息解析失败:', e);
+			}
+		},
+	};
+
+	return true;
+}

package/src/index.ts

@@ -10,24 +10,34 @@
 
 // 核心 Bridge
 export { bridge, MrpBridge } from './mrp-bridge';
-export type {
-  BridgeMessage,
-  MessageHandler,
-  Unsubscribe,
-} from './mrp-bridge';
+export type { BridgeMessage, MessageHandler, Unsubscribe } from './mrp-bridge';
+
+// iframe 宿主模式（网页内嵌预览）的契约常量
+export {
+	IFRAME_HOST_MARK,
+	IFRAME_HOST_ORIGIN_PARAM,
+	IFRAME_HOST_PARAM,
+} from './iframe-host';
 
 // 内置系统模块类型 + 工厂函数（容器核心契约）
 export { getSystemModule } from './system-module';
 export type {
-  SystemModule,
-  ModuleAllowedResult,
-  AvailableModulesResult,
-  ContainerInfoResult,
-  ArAdaptationInfo,
+	SystemModule,
+	ModuleAllowedResult,
+	AvailableModulesResult,
+	ContainerInfoResult,
+	ArAdaptationInfo,
+	SafeAreaInsets,
 } from './system-module';
 
 // App/H5 统一屏幕适配
-export { ar, getArScale, initArAdaptation, onArAdaptationChange } from './adaptation';
+export {
+	ar,
+	getArScale,
+	getSafeArea,
+	initArAdaptation,
+	onArAdaptationChange,
+} from './adaptation';
 export type { ArAdaptationListener } from './adaptation';
 
 // Generated 模块：类型 + 工厂函数
@@ -39,17 +49,22 @@ export type { RouteChangedPayload, AppMountedPayload } from './lifecycle';
 
 // 标准内容渲染、交互与错误协议
 export {
-  bindRenderProtocol,
-  bridgeError,
-  bridgeMessageTypes,
-  interaction,
-  renderActions,
-  renderProtocol,
+	agentEvents,
+	bindAgentProtocol,
+	bindRenderProtocol,
+	bridgeError,
+	bridgeMessageTypes,
+	interaction,
+	renderActions,
+	renderProtocol,
 } from './content-protocol';
 export type {
-  BridgeErrorPayload,
-  InteractionPayload,
-  ProtocolTransport,
-  RenderHandlers,
-  RenderPayload,
+	AgentEventHandlers,
+	AgentEventPayload,
+	BridgeErrorPayload,
+	ExternalAnswerPayload,
+	InteractionPayload,
+	ProtocolTransport,
+	RenderHandlers,
+	RenderPayload,
 } from './content-protocol';