@dino-dev/bridge-core-ts 0.0.1 → 0.0.2

package/README.md

@@ -9,6 +9,7 @@ H5 端与 Flutter 容器通信的核心 TypeScript SDK（零框架依赖）。
 |------|------|
 | `src/mrp-bridge.ts` | 核心 Bridge SDK（消息通信 + 模块代理） |
 | `src/system-module.ts` | 内置系统模块类型定义 + `getSystemModule()` 工厂 |
+| `src/content-protocol.ts` | 标准渲染、交互与错误协议 |
 | `src/index.ts` | 包入口，统一 re-export 所有 API |
 | `generated/*_module.ts` | 各模块的 TypeScript 类型定义（由 build_runner 自动生成，纯类型） |
 | `generated/index.ts` | 自动生成的模块类型 re-export + 工厂函数 |
@@ -128,9 +129,50 @@ const { modules } = await system.getAvailableModules();
 const info = await system.getContainerInfo();
 ```
 
-## 协议规范
+## 标准内容协议
 
-所有消息遵循统一格式（`type` 为自由字符串，由业务层约定）：
+SDK 为内容型 H5 固定定义以下协议域：
+
+| 方向 | type | action | payload |
+|---|---|---|---|
+| Flutter → H5 | `render` | `set` | `{ data, options? }` |
+| Flutter → H5 | `render` | `update` | `{ data, options? }` |
+| Flutter → H5 | `render` | `clear` | `{}` |
+| H5 → Flutter | `render` | `ready` | 应用能力信息 |
+| H5 → Flutter | `render` | `applied` | 已执行操作信息 |
+| H5 → Flutter | `interaction` | 业务动作 | `{ sourceId, value?, ... }` |
+| H5 → Flutter | `error` | `report` | `{ source, code, message, details? }` |
+
+H5 通过 `bindRenderProtocol()` 接收渲染消息，通过 `renderProtocol`、`interaction` 和 `bridgeError` 上报事件：
+
+```ts
+import {
+  bindRenderProtocol,
+  bridgeError,
+  interaction,
+  renderProtocol,
+} from '@h5-container/bridge-core-ts';
+
+const unsubscribe = bindRenderProtocol({
+  set: ({ data }) => renderCompleteContent(data),
+  update: ({ data, options }) => updateContent(data, options),
+  clear: () => clearContent(),
+});
+
+await renderProtocol.ready({ supportedOrientations: ['portrait'] });
+await interaction.send('submit', { sourceId: 'choice-1', value: ['fast'] });
+await bridgeError.report({
+  source: 'render',
+  code: 'INVALID_CONTENT',
+  message: 'Unsupported content type',
+});
+```
+
+`payload.data` 的结构由当前 H5 package 定义和校验，Container SDK 不理解具体业务类型。`packageId` 负责区分当前加载的 H5 应用。
+
+## 底层协议
+
+所有消息遵循统一信封。除上述标准内容协议外，底层 `bridge.send()` 和 `bridge.on()` 仍允许业务扩展自由字符串：
 
 ```json
 {
@@ -142,4 +184,4 @@ const info = await system.getContainerInfo();
 }
 ```
 
-> SDK 不硬编码任何消息类别。`type` 和 `action` 完全由业务定义，SDK 只负责序列化传输。
+> 新的内容型 H5 应优先使用标准内容协议；自由字符串只用于无法归入标准域的扩展能力。

package/dist/src/content-protocol.d.ts

@@ -0,0 +1,50 @@
+import { type BridgeMessage, type Unsubscribe } from './mrp-bridge';
+export declare const bridgeMessageTypes: {
+    readonly render: "render";
+    readonly interaction: "interaction";
+    readonly error: "error";
+};
+export declare const renderActions: {
+    readonly set: "set";
+    readonly update: "update";
+    readonly clear: "clear";
+    readonly ready: "ready";
+    readonly applied: "applied";
+};
+export interface RenderPayload<T = unknown> {
+    data: T;
+    options?: Record<string, unknown>;
+}
+export interface RenderHandlers<T = unknown> {
+    set(payload: RenderPayload<T>, message: BridgeMessage<RenderPayload<T>>): void;
+    update?(payload: RenderPayload<T>, message: BridgeMessage<RenderPayload<T>>): void;
+    clear(message: BridgeMessage<Record<string, unknown>>): void;
+}
+export interface InteractionPayload<T = unknown> {
+    sourceId: string;
+    value?: T;
+    [key: string]: unknown;
+}
+export interface BridgeErrorPayload {
+    source: string;
+    code: string;
+    message: string;
+    details?: unknown;
+    [key: string]: unknown;
+}
+export interface ProtocolTransport {
+    on(type: string, action: string | null, handler: (message: BridgeMessage<any>) => void): Unsubscribe;
+    send(type: string, action: string, payload: Record<string, unknown>): Promise<unknown>;
+}
+export declare function bindRenderProtocol<T>(handlers: RenderHandlers<T>, transport?: ProtocolTransport): Unsubscribe;
+export declare const renderProtocol: {
+    readonly ready: (payload?: Record<string, unknown>) => Promise<unknown>;
+    readonly applied: (payload?: Record<string, unknown>) => Promise<unknown>;
+};
+export declare const interaction: {
+    readonly send: <T>(action: string, payload: InteractionPayload<T>) => Promise<unknown>;
+};
+export declare const bridgeError: {
+    readonly report: (payload: BridgeErrorPayload) => Promise<unknown>;
+};
+//# sourceMappingURL=content-protocol.d.ts.map

package/dist/src/content-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-protocol.d.ts","sourceRoot":"","sources":["../../src/content-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE5E,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAEX,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/E,MAAM,CAAC,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACnF,KAAK,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,CACA,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,IAAI,GAC7C,WAAW,CAAC;IACf,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;CACrB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAC3B,SAAS,GAAE,iBAA0B,GACpC,WAAW,CAcb;AAED,eAAO,MAAM,cAAc;+BACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAQ,OAAO,CAAC,OAAO,CAAC;iCAI7C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAQ,OAAO,CAAC,OAAO,CAAC;CAGxD,CAAC;AAEX,eAAO,MAAM,WAAW;oBACjB,CAAC,UAAU,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,OAAO,CAAC;CAGjE,CAAC;AAEX,eAAO,MAAM,WAAW;+BACN,kBAAkB,KAAG,OAAO,CAAC,OAAO,CAAC;CAG7C,CAAC"}

package/dist/src/content-protocol.js

@@ -0,0 +1,46 @@
+import { bridge } from './mrp-bridge';
+export const bridgeMessageTypes = {
+    render: 'render',
+    interaction: 'interaction',
+    error: 'error',
+};
+export const renderActions = {
+    set: 'set',
+    update: 'update',
+    clear: 'clear',
+    ready: 'ready',
+    applied: 'applied',
+};
+export function bindRenderProtocol(handlers, transport = bridge) {
+    const subscriptions = [
+        transport.on(bridgeMessageTypes.render, renderActions.set, (message) => {
+            handlers.set(message.payload, message);
+        }),
+        transport.on(bridgeMessageTypes.render, renderActions.update, (message) => {
+            handlers.update?.(message.payload, message);
+        }),
+        transport.on(bridgeMessageTypes.render, renderActions.clear, (message) => {
+            handlers.clear(message);
+        }),
+    ];
+    return () => subscriptions.forEach((unsubscribe) => unsubscribe());
+}
+export const renderProtocol = {
+    ready(payload = {}) {
+        return bridge.send(bridgeMessageTypes.render, renderActions.ready, payload);
+    },
+    applied(payload = {}) {
+        return bridge.send(bridgeMessageTypes.render, renderActions.applied, payload);
+    },
+};
+export const interaction = {
+    send(action, payload) {
+        return bridge.send(bridgeMessageTypes.interaction, action, payload);
+    },
+};
+export const bridgeError = {
+    report(payload) {
+        return bridge.send(bridgeMessageTypes.error, 'report', payload);
+    },
+};
+//# sourceMappingURL=content-protocol.js.map

package/dist/src/content-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-protocol.js","sourceRoot":"","sources":["../../src/content-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAwC,MAAM,cAAc,CAAC;AAE5E,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,aAAa;IAC1B,KAAK,EAAE,OAAO;CACN,CAAC;AAEX,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;CACV,CAAC;AAwCX,MAAM,UAAU,kBAAkB,CAChC,QAA2B,EAC3B,YAA+B,MAAM;IAErC,MAAM,aAAa,GAAG;QACpB,SAAS,CAAC,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,CAAC,OAAwC,EAAE,EAAE;YACtG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC,CAAC;QACF,SAAS,CAAC,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,CAAC,OAAwC,EAAE,EAAE;YACzG,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9C,CAAC,CAAC;QACF,SAAS,CAAC,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE;YACvE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC,CAAC;KACH,CAAC;IAEF,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,KAAK,CAAC,UAAmC,EAAE;QACzC,OAAO,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,CAAC,UAAmC,EAAE;QAC3C,OAAO,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,CAAI,MAAc,EAAE,OAA8B;QACpD,OAAO,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM,CAAC,OAA2B;QAChC,OAAO,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;CACO,CAAC"}

package/dist/src/index.d.ts

@@ -14,4 +14,6 @@ export type { SystemModule, ModuleAllowedResult, AvailableModulesResult, Contain
 export * from '../generated/index';
 export { lifecycle } from './lifecycle';
 export type { RouteChangedPayload, AppMountedPayload } from './lifecycle';
+export { bindRenderProtocol, bridgeError, bridgeMessageTypes, interaction, renderActions, renderProtocol, } from './content-protocol';
+export type { BridgeErrorPayload, InteractionPayload, ProtocolTransport, RenderHandlers, RenderPayload, } from './content-protocol';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EACV,aAAa,EACb,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EACV,aAAa,EACb,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG1E,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,aAAa,GACd,MAAM,oBAAoB,CAAC"}

package/dist/src/index.js

@@ -15,4 +15,6 @@ export { getSystemModule } from './system-module';
 export * from '../generated/index';
 // 生命周期上报工具
 export { lifecycle } from './lifecycle';
+// 标准内容渲染、交互与错误协议
+export { bindRenderProtocol, bridgeError, bridgeMessageTypes, interaction, renderActions, renderProtocol, } from './content-protocol';
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY;AACZ,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAOjD,0BAA0B;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAQlD,yBAAyB;AACzB,cAAc,oBAAoB,CAAC;AAEnC,WAAW;AACX,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY;AACZ,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAOjD,0BAA0B;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAQlD,yBAAyB;AACzB,cAAc,oBAAoB,CAAC;AAEnC,WAAW;AACX,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,iBAAiB;AACjB,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dino-dev/bridge-core-ts",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Bridge Core SDK for h5_app_container — H5 ↔ Flutter 通信 + 原生模块类型安全调用（零框架依赖）",
   "type": "module",
   "main": "dist/src/index.js",

package/src/content-protocol.ts

@@ -0,0 +1,94 @@
+import { bridge, type BridgeMessage, type Unsubscribe } from './mrp-bridge';
+
+export const bridgeMessageTypes = {
+  render: 'render',
+  interaction: 'interaction',
+  error: 'error',
+} as const;
+
+export const renderActions = {
+  set: 'set',
+  update: 'update',
+  clear: 'clear',
+  ready: 'ready',
+  applied: 'applied',
+} as const;
+
+export interface RenderPayload<T = unknown> {
+  data: T;
+  options?: Record<string, unknown>;
+}
+
+export interface RenderHandlers<T = unknown> {
+  set(payload: RenderPayload<T>, message: BridgeMessage<RenderPayload<T>>): void;
+  update?(payload: RenderPayload<T>, message: BridgeMessage<RenderPayload<T>>): void;
+  clear(message: BridgeMessage<Record<string, unknown>>): void;
+}
+
+export interface InteractionPayload<T = unknown> {
+  sourceId: string;
+  value?: T;
+  [key: string]: unknown;
+}
+
+export interface BridgeErrorPayload {
+  source: string;
+  code: string;
+  message: string;
+  details?: unknown;
+  [key: string]: unknown;
+}
+
+export interface ProtocolTransport {
+  on(
+    type: string,
+    action: string | null,
+    handler: (message: BridgeMessage<any>) => void,
+  ): Unsubscribe;
+  send(
+    type: string,
+    action: string,
+    payload: Record<string, unknown>,
+  ): Promise<unknown>;
+}
+
+export function bindRenderProtocol<T>(
+  handlers: RenderHandlers<T>,
+  transport: ProtocolTransport = bridge,
+): Unsubscribe {
+  const subscriptions = [
+    transport.on(bridgeMessageTypes.render, renderActions.set, (message: BridgeMessage<RenderPayload<T>>) => {
+      handlers.set(message.payload, message);
+    }),
+    transport.on(bridgeMessageTypes.render, renderActions.update, (message: BridgeMessage<RenderPayload<T>>) => {
+      handlers.update?.(message.payload, message);
+    }),
+    transport.on(bridgeMessageTypes.render, renderActions.clear, (message) => {
+      handlers.clear(message);
+    }),
+  ];
+
+  return () => subscriptions.forEach((unsubscribe) => unsubscribe());
+}
+
+export const renderProtocol = {
+  ready(payload: Record<string, unknown> = {}): Promise<unknown> {
+    return bridge.send(bridgeMessageTypes.render, renderActions.ready, payload);
+  },
+
+  applied(payload: Record<string, unknown> = {}): Promise<unknown> {
+    return bridge.send(bridgeMessageTypes.render, renderActions.applied, payload);
+  },
+} as const;
+
+export const interaction = {
+  send<T>(action: string, payload: InteractionPayload<T>): Promise<unknown> {
+    return bridge.send(bridgeMessageTypes.interaction, action, payload);
+  },
+} as const;
+
+export const bridgeError = {
+  report(payload: BridgeErrorPayload): Promise<unknown> {
+    return bridge.send(bridgeMessageTypes.error, 'report', payload);
+  },
+} as const;

package/src/index.ts

@@ -31,3 +31,20 @@ export * from '../generated/index';
 // 生命周期上报工具
 export { lifecycle } from './lifecycle';
 export type { RouteChangedPayload, AppMountedPayload } from './lifecycle';
+
+// 标准内容渲染、交互与错误协议
+export {
+  bindRenderProtocol,
+  bridgeError,
+  bridgeMessageTypes,
+  interaction,
+  renderActions,
+  renderProtocol,
+} from './content-protocol';
+export type {
+  BridgeErrorPayload,
+  InteractionPayload,
+  ProtocolTransport,
+  RenderHandlers,
+  RenderPayload,
+} from './content-protocol';