@playcraft/iframe-bridge 0.0.1-alpha.100

package/README.md

@@ -0,0 +1,428 @@
+# @playcraft/iframe-bridge
+
+PlayCraft iframe 通讯协议 SDK — 基于 `window.postMessage`，适用于 **平台 (Parent) ↔ iframe 内游戏/编辑器 (Child)** 场景。
+
+发送方 **`bridge.emit(name, data)`**；接收方 **`bridge.on(name, fn)`**。需要返回结果时 callback 返回数据（SDK 自动发 `res`）；仅通知、无需回包时 callback 处理完即可。是否等待 `res` 由 wire name 决定，API 形状相同。
+
+---
+
+## 安装
+
+```bash
+# pnpm
+pnpm add @playcraft/iframe-bridge
+
+# npm
+npm install @playcraft/iframe-bridge
+
+# yarn
+yarn add @playcraft/iframe-bridge
+```
+
+---
+
+## Child 侧用法
+
+Child 运行在 iframe 内，通过 `bridge.emit` 与 Parent 通讯。
+
+### 1. 初始化 Bridge
+
+推荐使用 `setupChildBridge`，它会创建 `Bridge`、注册 `host.init` 监听，并在嵌入模式下自动发送 `child.ready`：
+
+```typescript
+import { setupChildBridge, BridgeMethods } from '@playcraft/iframe-bridge';
+
+// Parent 打开 iframe 时应在 URL 带上 ?parentOrigin=<parent-origin>
+const parentOrigin = new URLSearchParams(location.search).get('parentOrigin') ?? location.origin;
+
+const { bridge, whenParentReady } = setupChildBridge({
+  parentOrigin,
+  // readyEvent: BridgeMethods.host.init,      // 默认 — Parent 发来的就绪信号
+  // announceEvent: BridgeMethods.child.ready, // 默认 — Child 发出的 bridge 就绪通知
+  debug: true, // 或 (direction, envelope) => { ... } 记录 Timeline
+});
+
+// 等待 Parent 发送 host.init 后再调用其他 wire name
+const init = await whenParentReady();
+// init.params — Parent 可选传入的初始化参数
+```
+
+若不用 `setupChildBridge`，需自行 `new Bridge({ peer: () => window.parent, ... })` 并手动处理握手。
+
+### 2. 调用（emit）
+
+```typescript
+// 批量读路径（req 仅为 path 字符串数组，不含文件内容）
+const { paths } = await bridge.emit(BridgeMethods.form.get, ['scene.bg', 'scene.role']);
+// paths[i].data — string
+
+// 批量写路径
+await bridge.emit(BridgeMethods.form.set, {
+  paths: [{ path: 'scene.role', data: '...' }],
+});
+
+// AI 生图
+await bridge.emit(BridgeMethods.image.aiGenerate, {
+  prompt: '赛博朋克风格的城市夜景',
+  referenceImageBase64: ['<base64>'],
+});
+
+// 通知 Parent 关闭 iframe（无 res，emit 立即返回）
+await bridge.emit(BridgeMethods.dialog.close, { reason: 'user_done' });
+```
+
+### 3. 批量调用与超时
+
+`bridge.emit` 的数组形式用于**编排多个独立调用**（可混合不同 wire name、各自 payload）。  
+读多个 path 请用上文单次 `form.get` + path 数组（1 次往返）；不要拆成多次 `form.get`。
+
+```typescript
+// 串行批量（默认）— 混合不同 wire name，按顺序执行
+const [getRes, setRes, aiRes] = await bridge.emit([
+  [BridgeMethods.form.get, ['scene.bg', 'scene.role']],
+  [BridgeMethods.form.set, { paths: [{ path: 'scene.role', data: '...' }] }],
+  [
+    BridgeMethods.image.aiGenerate,
+    { prompt: '赛博朋克城市', referenceImageBase64: ['<base64>'] },
+    { timeout: 60_000 }, // 可选：该 call 单独超时
+  ],
+]);
+
+// 并行批量 — 互不依赖的 call 可同时发出
+const parallel = await bridge.emit(
+  [
+    [BridgeMethods.form.get, ['scene.bg']],
+    [BridgeMethods.form.get, ['scene.ui']],
+  ],
+  { mode: 'parallel' },
+);
+// parallel[0] 成功时为 { paths: [...] }；失败项为 { error: PlaycraftBridgeError }
+
+// 单 call 超时 / 取消
+const controller = new AbortController();
+await bridge.emit(BridgeMethods.image.aiGenerate, payload, {
+  timeout: 60_000,
+  signal: controller.signal,
+});
+```
+
+### 4. 生命周期
+
+```typescript
+// 页面卸载时销毁 Bridge，移除 message 监听
+bridge.destroy();
+```
+
+### Child 侧典型时序
+
+```
+Child                          Parent
+  | child.ready (auto)    -->    |
+  |                       <--    | host.init
+  | form.get / set / ...  -->    | on → res
+  | dialog.close          -->    | on（无 res）→ 关闭 iframe
+```
+
+---
+
+## Parent 侧用法
+
+Parent 挂载 iframe、注册 `bridge.on`、响应握手与 `dialog.close`。DOM 由业务方管理；Bridge 与握手推荐用 `setupParentBridge`。
+
+### 1. 初始化 Bridge
+
+```typescript
+import { setupParentBridge, withParentOrigin, BridgeMethods } from '@playcraft/iframe-bridge';
+
+const iframe = document.createElement('iframe');
+iframe.src = withParentOrigin(childUrl).toString();
+container.appendChild(iframe);
+
+const { bridge, whenChildReady } = setupParentBridge({
+  iframe,
+  childOrigin: new URL(childUrl).origin,
+  init: { params: { theme: 'dark' } }, // 收到 child.ready 后自动 emit host.init
+  debug: true,
+});
+
+await whenChildReady();
+```
+
+`withParentOrigin` 仅负责给 Child URL 追加 `parentOrigin` query；iframe 样式、挂载时机仍由业务控制。
+
+若不用 `setupParentBridge`，需自行 `new Bridge({ peer: () => iframe.contentWindow, ... })` 并手动处理握手。
+
+### 2. 注册 on
+
+```typescript
+bridge.on(BridgeMethods.form.get, async (pathKeys) => ({
+  paths: await Promise.all(
+    pathKeys.map(async (path) => ({ path, data: await loadPathData(path) })),
+  ),
+}));
+
+bridge.on(BridgeMethods.form.set, async ({ paths }) => {
+  for (const entry of paths) {
+    await savePathData(entry.path, entry.data);
+  }
+  return { paths: paths.map(({ path }) => path) };
+});
+
+// 无 res — callback 处理完即可，不 return 结果
+bridge.on(BridgeMethods.dialog.close, () => {
+  iframe.remove();
+  bridge.destroy();
+});
+```
+
+完整字段与错误约定见下文 [API 参考](#api-参考)。
+
+### 3. 生命周期
+
+```typescript
+bridge.destroy();
+```
+
+### Parent 侧典型时序
+
+```
+Child                          Parent
+  | child.ready (auto)    -->    | whenChildReady() resolve
+  |                       <--    | host.init (auto emit)
+  | form.get / set / ...  -->    | on → res
+  | dialog.close          -->    | on（无 res）→ 关闭 iframe
+```
+
+### Parent 侧职责小结
+
+| 职责             | API                                    |
+| ---------------- | -------------------------------------- |
+| iframe DOM / URL | 业务方（可用 `withParentOrigin`）      |
+| 握手             | `setupParentBridge` + `whenChildReady` |
+| 业务逻辑         | `bridge.on`（有/无 res 均可）          |
+| 销毁             | `bridge.destroy()`                     |
+
+---
+
+## 调试
+
+URL 带 `?debug` 或 `?debug=1` 时，`setupChildBridge` / `setupParentBridge` 会开启 envelope 日志：
+
+```typescript
+import { isDebugFromUrl } from '@playcraft/iframe-bridge';
+
+setupChildBridge({
+  parentOrigin,
+  debug: isDebugFromUrl() ? (dir, env) => console.log(dir, env) : false,
+});
+```
+
+---
+
+## 协议概览
+
+| 概念                | 说明                                                                        |
+| ------------------- | --------------------------------------------------------------------------- |
+| **Envelope**        | `{ __playcraft__, kind, id, name, data?, ret?, msg? }` — 所有消息的统一信封 |
+| **`__playcraft__`** | 协议版本，与 npm 包 `version` 字段一致                                      |
+| **`req`**           | 请求 envelope；接收方 `bridge.on` 处理                                      |
+| **`res`**           | 响应 envelope（可选）。`ret === 0` 时 `data` 为结果；失败时 `msg` 描述原因  |
+| **PathEntry**       | `{ path, data }` — `data` 恒为 **string**                                   |
+
+**出站**：`bridge.emit(name, data)` — 需要 `res` 的 wire name 会 await；否则立即返回。
+
+**入站**：`bridge.on(name, fn)` — callback 返回数据则发 `res`；无返回则不回包。callback 支持 `async` / `Promise`。
+
+Wire 名称统一为 `${domain}.${action}` 格式，在 `BridgeMethods` 中维护。
+
+---
+
+## API 参考
+
+### SDK 导出
+
+| 导出                                             | 说明                                    |
+| ------------------------------------------------ | --------------------------------------- |
+| `Bridge`（`emit` / `on`）                        | postMessage 封装 + 出站/入站 API        |
+| `setupChildBridge`                               | Child 侧一键初始化 + 握手               |
+| `setupParentBridge` / `withParentOrigin`         | Parent 侧绑定 iframe + 握手             |
+| `emitOne` / `normalizeInvokeCall` 等             | 批量 emit 辅助（高级）                  |
+| `PlaycraftBridgeError` / `BridgeErrorCodes`      | 结构化错误                              |
+| `PROTOCOL_VERSION`                               | 当前协议版本字符串                      |
+| `BridgeMethods` / `bridgeMethod`                 | 全部 wire 名称（`${domain}.${action}`） |
+| `BRIDGE_RPC_NAMES`                               | 需要 `res` 的 wire 名称列表             |
+| `RetCodes` / `errorCodeToRet` / `retToErrorCode` | Envelope `ret` 与错误码映射             |
+| `isPlaycraftEnvelope`                            | 校验未知 postMessage 是否为本协议       |
+
+Wire 名称在 `BridgeMethods` 中维护：
+
+```typescript
+import { BridgeMethods, bridgeMethod } from '@playcraft/iframe-bridge';
+
+BridgeMethods.form.get; // 'form.get' — emit 等待 res
+BridgeMethods.dialog.close; // 'dialog.close' — emit 立即返回
+bridgeMethod('form', 'get'); // 'form.get'
+```
+
+修改 wire 名称时只需改 `BridgeMethods`（`bridgeMethod('domain', 'action')`）一处；`MethodMap`、`EventMap`、`InvokeMap` 等均从此派生。
+
+---
+
+### `form.get`
+
+批量读取路径内容。
+
+**方向**：Child → Parent（Child `emit`，Parent `on`）
+
+**Request** `string[]` — path 列表，不含 data
+
+```typescript
+['scene.bg', 'scene.role'];
+```
+
+**Response** `{ paths: PathEntry[] }`
+
+```typescript
+{
+  paths: [
+    { path: 'scene.bg', data: '...' },
+    { path: 'scene.role', data: '...' },
+  ];
+}
+```
+
+---
+
+### `form.set`
+
+批量写入路径。
+
+**方向**：Child → Parent（Child `emit`，Parent `on`）
+
+**Request** `{ paths: PathEntry[] }`
+
+```typescript
+{
+  paths: [{ path: 'scene.role', data: '...' }],
+}
+```
+
+**Response**（`ret === 0` 时）`{ paths: string[] }` — 已成功写入的 path 列表
+
+```typescript
+{
+  paths: ['scene.role'],
+}
+```
+
+任一路径写入失败时 Parent handler 应 `throw PlaycraftBridgeError`，Child 侧 `emit` 收到 `ret !== 0` 与 `msg`。
+
+---
+
+### `image.aiGenerate`
+
+**Request** `AiGenerateImagePayload`
+
+| 字段                   | 类型        | 必填 | 说明                                   |
+| ---------------------- | ----------- | ---- | -------------------------------------- |
+| `prompt`               | `string`    |      | 生成提示词                             |
+| `referenceImageBase64` | `string[]`  |      | 参考图 base64 列表（无 `data:` 前缀） |
+
+**Response** `{ paths: PathEntry[] }`
+
+生成结果已写入 `path`（多张时 Parent 可能使用 `path#0`、`path#1` 等衍生路径）。`data` 为 base64 字符串。
+
+```typescript
+{
+  paths: [{ path: 'scene.bg', data: '<base64>' }];
+}
+```
+
+---
+
+### `child.ready`
+
+**方向**：Child → Parent · **res**：无  
+**Payload**：`{}`
+
+`setupChildBridge` 在嵌入模式下自动 `emit`。Parent 侧 `setupParentBridge` 收到后自动 `emit` `host.init`。
+
+---
+
+### `host.init`
+
+**方向**：Parent → Child · **res**：无  
+**Payload**：`{ params?: Record<string, unknown> }`
+
+Child 侧 `whenParentReady()` / Parent 侧 `whenChildReady()` 在握手完成后 resolve。
+
+---
+
+### `dialog.close`
+
+**方向**：Child → Parent · **res**：无  
+**Payload**：`{ reason?: string }`
+
+Parent 用 `bridge.on` 注册（无 return），通常在此移除 iframe 并 `bridge.destroy()`。
+
+---
+
+### 错误码
+
+有 `res` 的调用失败时 `ret !== 0`，`msg` 为错误描述；`ret` 与 `BridgeErrorCodes` 的映射见 `RetCodes`：
+
+| ret | Code               | 含义               |
+| --- | ------------------ | ------------------ |
+| `0` | —                  | 成功               |
+| `1` | `INVALID_PARAM`    | 参数不合法         |
+| `2` | `TIMEOUT`          | 等待响应超时       |
+| `3` | `ABORTED`          | 调用方 abort       |
+| `4` | `REQUEST_FAILED`   | 通用失败           |
+| `5` | `INTERNAL_ERROR`   | Handler 内部错误   |
+| `6` | `PEER_UNAVAILABLE` | 对端 window 不可用 |
+| `7` | `DESTROYED`        | Bridge 已销毁      |
+| `8` | `METHOD_NOT_FOUND` | 方法未注册         |
+
+Client 侧 `bridge.emit` 对有 `res` 的 wire name 失败时会 `reject` 为 `PlaycraftBridgeError`（由 `ret` 反查 `code`）。
+
+---
+
+### Envelope 示例
+
+**请求（有 res）**
+
+```json
+{
+  "__playcraft__": "0.0.1",
+  "kind": "req",
+  "id": "1702819473736-0",
+  "name": "form.get",
+  "data": ["scene.bg", "scene.role"]
+}
+```
+
+**成功响应**
+
+```json
+{
+  "__playcraft__": "0.0.1",
+  "kind": "res",
+  "id": "1702819473736-0",
+  "name": "form.get",
+  "ret": 0,
+  "data": { "paths": [{ "path": "scene.bg", "data": "..." }] }
+}
+```
+
+**失败响应**
+
+```json
+{
+  "__playcraft__": "0.0.1",
+  "kind": "res",
+  "id": "1702819473736-0",
+  "name": "form.set",
+  "ret": 1,
+  "msg": "Invalid path: scene.unknown"
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,298 @@
+type Kind = 'req' | 'res';
+/** RPC failure — maps to envelope `ret` / `msg` on the wire. */
+type RpcError = {
+    ret: number;
+    msg: string;
+};
+type Envelope<T = unknown> = {
+    /** Package version from package.json */
+    __playcraft__: string;
+    kind: Kind;
+    id: string;
+    name: string;
+    data?: T;
+    /** RPC response only — 0 success, non-zero failure */
+    ret?: number;
+    /** RPC error message when ret !== 0 */
+    msg?: string;
+};
+
+/** All wire names — format `${domain}.${action}` (RPC + one-way events). */
+declare const BridgeMethods: {
+    readonly form: {
+        readonly get: "form.get";
+        readonly set: "form.set";
+    };
+    readonly image: {
+        readonly aiGenerate: "image.aiGenerate";
+    };
+    readonly dialog: {
+        readonly close: "dialog.close";
+    };
+    readonly child: {
+        readonly ready: "child.ready";
+    };
+    readonly host: {
+        readonly init: "host.init";
+    };
+};
+type BridgeMethodDomain = keyof typeof BridgeMethods;
+/** One-way events (no `res` envelope). */
+declare const BRIDGE_EVENT_NAMES: readonly ["child.ready", "host.init", "dialog.close"];
+type BridgeEventName = (typeof BRIDGE_EVENT_NAMES)[number];
+/** RPC methods (request/response). */
+declare const BRIDGE_RPC_NAMES: readonly ["form.get", "form.set", "image.aiGenerate"];
+type BridgeRpcName = (typeof BRIDGE_RPC_NAMES)[number];
+/** Build a wire name from domain + action keys. */
+declare function bridgeMethod<D extends BridgeMethodDomain>(domain: D, action: keyof (typeof BridgeMethods)[D] & string): string;
+
+type ChildReadyEvt = Record<string, never>;
+type DialogCloseEvt = {
+    reason?: string;
+};
+type HostInitEvt = {
+    params?: Record<string, unknown>;
+};
+type EventMap = {
+    [BridgeMethods.child.ready]: ChildReadyEvt;
+    [BridgeMethods.host.init]: HostInitEvt;
+    [BridgeMethods.dialog.close]: DialogCloseEvt;
+};
+type EventName = keyof EventMap;
+
+/** Path payload in responses and form.set requests — always a string. */
+type PathEntry = {
+    path: string;
+    /** JSON string for structured config; base64 (no data: prefix) for binary/image assets. */
+    data: string;
+};
+/** Path keys only — no data on read. */
+type PathsGetReq = string[];
+type PathsGetRes = {
+    paths: PathEntry[];
+};
+type PathsSetReq = {
+    paths: PathEntry[];
+};
+type PathsSetRes = {
+    /** Paths successfully written — present when envelope `ret === 0`. */
+    paths: string[];
+};
+/** Request body for `image.aiGenerate`. */
+type AiGenerateImagePayload = {
+    /** User prompt — optional when reference images are provided. */
+    prompt?: string;
+    /** Reference images as base64 strings (no `data:` prefix). */
+    referenceImageBase64?: string[];
+};
+type AiGenerateImageResult = {
+    paths: PathEntry[];
+};
+type MethodMap = {
+    [BridgeMethods.form.get]: {
+        req: PathsGetReq;
+        res: PathsGetRes;
+    };
+    [BridgeMethods.form.set]: {
+        req: PathsSetReq;
+        res: PathsSetRes;
+    };
+    [BridgeMethods.image.aiGenerate]: {
+        req: AiGenerateImagePayload;
+        res: AiGenerateImageResult;
+    };
+};
+type MethodName = keyof MethodMap;
+
+/** RPC methods + one-way events — unified outbound API via `invoke`. */
+type InvokeMap = MethodMap & {
+    [K in EventName]: {
+        req: EventMap[K];
+        res: void;
+    };
+};
+type InvokeName = keyof InvokeMap;
+
+type DebugLogger = (event: 'send' | 'recv', msg: Envelope) => void;
+type RequestOptions = {
+    timeout?: number;
+    signal?: AbortSignal;
+};
+type InvokeBatchOptions = RequestOptions & {
+    mode?: 'serial' | 'parallel';
+};
+type InvokeCall = {
+    [K in MethodName]: {
+        name: K;
+        data: MethodMap[K]['req'];
+        options?: RequestOptions;
+    };
+}[MethodName];
+type InvokeTuple = [MethodName, MethodMap[MethodName]['req']] | [MethodName, MethodMap[MethodName]['req'], RequestOptions?];
+type InvokeGroup = {
+    mode?: 'serial' | 'parallel';
+    calls: readonly (InvokeCall | InvokeTuple)[];
+};
+type InvokeBatchInput = readonly (InvokeCall | InvokeTuple)[];
+type InvokeGroupsInput = readonly InvokeGroup[];
+type BridgeOptions = {
+    peer: () => Window | null;
+    targetOrigin: string;
+    allowedOrigins: string[];
+    timeout?: number;
+    debug?: boolean | DebugLogger;
+    /** Defaults to window; inject MockMessageTarget in tests */
+    messageTarget?: EventTarget;
+};
+type Handler<K extends MethodName> = (data: MethodMap[K]['req'], ctx: {
+    id: string;
+}) => MethodMap[K]['res'] | Promise<MethodMap[K]['res']>;
+/** Handler for wire names that do not send `res` — same as `handle`, no reply. */
+type NotifyHandler<K extends EventName> = (data: EventMap[K]) => void | Promise<void>;
+type BridgeMessageEvent = {
+    data: Envelope;
+    origin: string;
+    source: MessageEventSource | null;
+};
+type PendingReq = {
+    resolve: (value: unknown) => void;
+    reject: (reason: unknown) => void;
+    timer: ReturnType<typeof setTimeout>;
+    cleanupAbortListener?: () => void;
+    offMessage: () => void;
+};
+/** parallel batch item: success is normal res, failure is { error: RpcError } */
+type InvokeParallelResult<T> = T | {
+    error: RpcError;
+};
+
+declare class Bridge {
+    private readonly options;
+    readonly targetOrigin: string;
+    private readonly listeners;
+    private destroyed;
+    private readonly messageTarget;
+    constructor(options: BridgeOptions);
+    emit<K extends InvokeName>(name: K, data: InvokeMap[K]['req'], options?: RequestOptions): Promise<InvokeMap[K]['res']>;
+    emit(calls: InvokeBatchInput, options?: InvokeBatchOptions): Promise<unknown[] | InvokeParallelResult<unknown>[]>;
+    emit(groups: InvokeGroupsInput, options?: InvokeBatchOptions): Promise<unknown[][] | InvokeParallelResult<unknown[]>[]>;
+    on<K extends MethodName>(name: K, fn: Handler<K>): () => void;
+    on<K extends EventName>(name: K, fn: NotifyHandler<K>): () => void;
+    postMessage(message: Envelope, targetOrigin?: string, transfer?: Transferable[]): void;
+    addEventListener(type: 'message', listener: (event: BridgeMessageEvent) => void): () => void;
+    destroy(): void;
+    private assertAlive;
+    private log;
+    private onWindowMessage;
+}
+
+declare function normalizeInvokeCall(call: InvokeCall | InvokeTuple): InvokeCall;
+declare function isInvokeGroups(input: unknown): input is InvokeGroupsInput;
+declare function settleParallel<T>(promises: readonly Promise<T>[]): Promise<InvokeParallelResult<T>[]>;
+declare function emitOne<K extends InvokeName>(bridge: Bridge, name: K, data: InvokeMap[K]['req'], options?: RequestOptions, defaultTimeout?: number): Promise<InvokeMap[K]['res']>;
+
+/** Default one-way events used by the child-side handshake. */
+type ChildBridgeDefaultEvents = {
+    readyEvent: typeof BridgeMethods.host.init;
+    announceEvent: typeof BridgeMethods.child.ready;
+};
+type SetupChildBridgeOptions = {
+    parentOrigin: string;
+    /** Parent → child event that resolves {@link SetupChildBridgeResult.whenParentReady}. */
+    readyEvent?: ChildBridgeDefaultEvents['readyEvent'];
+    /** Child → parent event announcing bridge readiness. */
+    announceEvent?: ChildBridgeDefaultEvents['announceEvent'];
+    debug?: boolean | DebugLogger;
+};
+type SetupChildBridgeResult = {
+    bridge: Bridge;
+    whenParentReady: () => Promise<EventMap[ChildBridgeDefaultEvents['readyEvent']]>;
+};
+
+/** Default one-way events used by the child-side handshake. */
+declare const ChildBridgeDefaults: {
+    readonly readyEvent: "host.init";
+    readonly announceEvent: "child.ready";
+};
+declare function setupChildBridge(options: SetupChildBridgeOptions | string): SetupChildBridgeResult;
+
+/** Default one-way events used by the parent-side handshake. */
+type ParentBridgeDefaultEvents = {
+    announceEvent: typeof BridgeMethods.child.ready;
+    readyEvent: typeof BridgeMethods.host.init;
+};
+type SetupParentBridgeOptions = {
+    /** Existing iframe element — DOM lifecycle stays with the caller. */
+    iframe: HTMLIFrameElement;
+    /** Child frame origin for postMessage targetOrigin / allowedOrigins. */
+    childOrigin: string;
+    /** Payload sent via invoke(readyEvent) when announceEvent arrives. */
+    init?: HostInitEvt;
+    /** Child → parent event that resolves {@link SetupParentBridgeResult.whenChildReady}. */
+    announceEvent?: ParentBridgeDefaultEvents['announceEvent'];
+    /** Parent → child event sent automatically after announceEvent. */
+    readyEvent?: ParentBridgeDefaultEvents['readyEvent'];
+    debug?: boolean | DebugLogger;
+};
+type SetupParentBridgeResult = {
+    bridge: Bridge;
+    whenChildReady: () => Promise<EventMap[ParentBridgeDefaultEvents['announceEvent']]>;
+};
+
+/** Default one-way events used by the parent-side handshake. */
+declare const ParentBridgeDefaults: {
+    readonly announceEvent: "child.ready";
+    readonly readyEvent: "host.init";
+};
+declare function setupParentBridge(options: SetupParentBridgeOptions): SetupParentBridgeResult;
+/** Append `parentOrigin` query param for child iframe URLs. */
+declare function withParentOrigin(childUrl: string | URL, parentOrigin?: string): URL;
+
+/** Protocol marker on every envelope; matches package.json version */
+declare const PROTOCOL_VERSION: string;
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 150000;
+declare const BridgeErrorCodes: {
+    readonly ABORTED: "ABORTED";
+    readonly DESTROYED: "DESTROYED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly INVALID_PARAM: "INVALID_PARAM";
+    readonly METHOD_NOT_FOUND: "METHOD_NOT_FOUND";
+    readonly PEER_UNAVAILABLE: "PEER_UNAVAILABLE";
+    readonly REQUEST_FAILED: "REQUEST_FAILED";
+    readonly TIMEOUT: "TIMEOUT";
+};
+type BridgeErrorCode = (typeof BridgeErrorCodes)[keyof typeof BridgeErrorCodes];
+/** Envelope `ret` on RPC responses — 0 means success, non-zero means failure. */
+declare const RetCodes: {
+    readonly OK: 0;
+    readonly INVALID_PARAM: 1;
+    readonly TIMEOUT: 2;
+    readonly ABORTED: 3;
+    readonly REQUEST_FAILED: 4;
+    readonly INTERNAL_ERROR: 5;
+    readonly PEER_UNAVAILABLE: 6;
+    readonly DESTROYED: 7;
+    readonly METHOD_NOT_FOUND: 8;
+};
+type RetCode = (typeof RetCodes)[keyof typeof RetCodes];
+declare function errorCodeToRet(code: string): RetCode;
+declare function retToErrorCode(ret: number): BridgeErrorCode;
+
+/** True when `debug` query param is set (e.g. `?debug`, `?debug=1`, `?debug=true`). */
+declare function isDebugFromUrl(search?: string | URLSearchParams): boolean;
+
+declare function createEnvelope(kind: Kind, id: string, name: string, data?: unknown): Envelope;
+declare function createSuccessResponse(id: string, name: string, data: unknown): Envelope;
+declare function createErrorResponse(id: string, name: string, error: RpcError): Envelope;
+declare function isPlaycraftEnvelope(data: unknown): data is Envelope;
+
+declare class PlaycraftBridgeError extends Error {
+    readonly code: string;
+    readonly detail?: unknown;
+    constructor(code: BridgeErrorCode | string, message: string, detail?: unknown);
+}
+/** Normalize thrown/unknown errors to wire-shaped `{ ret, msg }`. */
+declare function toPlaycraftError(err: unknown): RpcError;
+
+export { BRIDGE_EVENT_NAMES, BRIDGE_RPC_NAMES, Bridge, BridgeErrorCodes, BridgeMethods, ChildBridgeDefaults, DEFAULT_REQUEST_TIMEOUT_MS, PROTOCOL_VERSION, ParentBridgeDefaults, PlaycraftBridgeError, RetCodes, bridgeMethod, createEnvelope, createErrorResponse, createSuccessResponse, emitOne, errorCodeToRet, isDebugFromUrl, isInvokeGroups, isPlaycraftEnvelope, normalizeInvokeCall, retToErrorCode, settleParallel, setupChildBridge, setupParentBridge, toPlaycraftError, withParentOrigin };
+export type { AiGenerateImagePayload, AiGenerateImageResult, BridgeErrorCode, BridgeEventName, BridgeMessageEvent, BridgeMethodDomain, BridgeOptions, BridgeRpcName, ChildBridgeDefaultEvents, ChildReadyEvt, DebugLogger, DialogCloseEvt, Envelope, EventMap, EventName, Handler, HostInitEvt, InvokeBatchInput, InvokeBatchOptions, InvokeCall, InvokeGroup, InvokeGroupsInput, InvokeMap, InvokeName, InvokeParallelResult, InvokeTuple, Kind, MethodMap, MethodName, NotifyHandler, ParentBridgeDefaultEvents, PathEntry, PathsGetReq, PathsGetRes, PathsSetReq, PathsSetRes, PendingReq, RequestOptions, RetCode, RpcError, SetupChildBridgeOptions, SetupChildBridgeResult, SetupParentBridgeOptions, SetupParentBridgeResult };

package/dist/index.js

@@ -0,0 +1,463 @@
+var version = "0.0.1-alpha.100";
+var pkg = {
+    version: version};
+
+/** Protocol marker on every envelope; matches package.json version */ const PROTOCOL_VERSION = pkg.version;
+const DEFAULT_REQUEST_TIMEOUT_MS = 150_000;
+const BridgeErrorCodes = {
+    ABORTED: 'ABORTED',
+    DESTROYED: 'DESTROYED',
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    INVALID_PARAM: 'INVALID_PARAM',
+    METHOD_NOT_FOUND: 'METHOD_NOT_FOUND',
+    PEER_UNAVAILABLE: 'PEER_UNAVAILABLE',
+    REQUEST_FAILED: 'REQUEST_FAILED',
+    TIMEOUT: 'TIMEOUT'
+};
+/** Envelope `ret` on RPC responses — 0 means success, non-zero means failure. */ const RetCodes = {
+    OK: 0,
+    INVALID_PARAM: 1,
+    TIMEOUT: 2,
+    ABORTED: 3,
+    REQUEST_FAILED: 4,
+    INTERNAL_ERROR: 5,
+    PEER_UNAVAILABLE: 6,
+    DESTROYED: 7,
+    METHOD_NOT_FOUND: 8
+};
+const ERROR_CODE_TO_RET = {
+    [BridgeErrorCodes.INVALID_PARAM]: RetCodes.INVALID_PARAM,
+    [BridgeErrorCodes.TIMEOUT]: RetCodes.TIMEOUT,
+    [BridgeErrorCodes.ABORTED]: RetCodes.ABORTED,
+    [BridgeErrorCodes.REQUEST_FAILED]: RetCodes.REQUEST_FAILED,
+    [BridgeErrorCodes.INTERNAL_ERROR]: RetCodes.INTERNAL_ERROR,
+    [BridgeErrorCodes.PEER_UNAVAILABLE]: RetCodes.PEER_UNAVAILABLE,
+    [BridgeErrorCodes.DESTROYED]: RetCodes.DESTROYED,
+    [BridgeErrorCodes.METHOD_NOT_FOUND]: RetCodes.METHOD_NOT_FOUND
+};
+const RET_TO_ERROR_CODE = {
+    [RetCodes.INVALID_PARAM]: BridgeErrorCodes.INVALID_PARAM,
+    [RetCodes.TIMEOUT]: BridgeErrorCodes.TIMEOUT,
+    [RetCodes.ABORTED]: BridgeErrorCodes.ABORTED,
+    [RetCodes.REQUEST_FAILED]: BridgeErrorCodes.REQUEST_FAILED,
+    [RetCodes.INTERNAL_ERROR]: BridgeErrorCodes.INTERNAL_ERROR,
+    [RetCodes.PEER_UNAVAILABLE]: BridgeErrorCodes.PEER_UNAVAILABLE,
+    [RetCodes.DESTROYED]: BridgeErrorCodes.DESTROYED,
+    [RetCodes.METHOD_NOT_FOUND]: BridgeErrorCodes.METHOD_NOT_FOUND
+};
+function errorCodeToRet(code) {
+    return ERROR_CODE_TO_RET[code] ?? RetCodes.REQUEST_FAILED;
+}
+function retToErrorCode(ret) {
+    return RET_TO_ERROR_CODE[ret] ?? BridgeErrorCodes.REQUEST_FAILED;
+}
+
+function createEnvelope(kind, id, name, data) {
+    return {
+        __playcraft__: PROTOCOL_VERSION,
+        kind,
+        id,
+        name,
+        data
+    };
+}
+function createSuccessResponse(id, name, data) {
+    return {
+        ...createEnvelope('res', id, name),
+        ret: RetCodes.OK,
+        data
+    };
+}
+function createErrorResponse(id, name, error) {
+    return {
+        ...createEnvelope('res', id, name),
+        ret: error.ret,
+        msg: error.msg
+    };
+}
+function isPlaycraftEnvelope(data) {
+    return !!data && typeof data === 'object' && data.__playcraft__ === PROTOCOL_VERSION;
+}
+
+class PlaycraftBridgeError extends Error {
+    constructor(code, message, detail){
+        super(message);
+        this.name = 'PlaycraftBridgeError';
+        this.code = code;
+        this.detail = detail;
+    }
+}
+function isRpcError(value) {
+    return !!value && typeof value === 'object' && 'ret' in value && 'msg' in value && typeof value.ret === 'number' && typeof value.msg === 'string';
+}
+function isLegacyCodeMessageError(value) {
+    return !!value && typeof value === 'object' && 'code' in value && 'message' in value && typeof value.code === 'string' && typeof value.message === 'string';
+}
+/** Normalize thrown/unknown errors to wire-shaped `{ ret, msg }`. */ function toPlaycraftError(err) {
+    if (isRpcError(err)) {
+        return err;
+    }
+    if (err instanceof PlaycraftBridgeError) {
+        return {
+            ret: errorCodeToRet(err.code),
+            msg: err.message
+        };
+    }
+    if (isLegacyCodeMessageError(err)) {
+        return {
+            ret: errorCodeToRet(err.code),
+            msg: err.message
+        };
+    }
+    return {
+        ret: RetCodes.INTERNAL_ERROR,
+        msg: err instanceof Error ? err.message : String(err)
+    };
+}
+
+/** All wire names — format `${domain}.${action}` (RPC + one-way events). */ const BridgeMethods = {
+    form: {
+        get: 'form.get',
+        set: 'form.set'
+    },
+    image: {
+        aiGenerate: 'image.aiGenerate'
+    },
+    dialog: {
+        close: 'dialog.close'
+    },
+    child: {
+        ready: 'child.ready'
+    },
+    host: {
+        init: 'host.init'
+    }
+};
+/** One-way events (no `res` envelope). */ const BRIDGE_EVENT_NAMES = [
+    BridgeMethods.child.ready,
+    BridgeMethods.host.init,
+    BridgeMethods.dialog.close
+];
+/** RPC methods (request/response). */ const BRIDGE_RPC_NAMES = [
+    BridgeMethods.form.get,
+    BridgeMethods.form.set,
+    BridgeMethods.image.aiGenerate
+];
+/** Build a wire name from domain + action keys. */ function bridgeMethod(domain, action) {
+    return BridgeMethods[domain][action];
+}
+
+const EVENT_NAMES = new Set(BRIDGE_EVENT_NAMES);
+function isEventName(name) {
+    return EVENT_NAMES.has(name);
+}
+
+let idSeq = 0;
+function genId() {
+    return `${Date.now()}-${idSeq++}`;
+}
+
+/** Send a one-way or RPC `req` envelope (no response handling). */ function sendReq(bridge, name, data) {
+    bridge.postMessage(createEnvelope('req', genId(), name, data));
+}
+
+function normalizeInvokeCall(call) {
+    if (Array.isArray(call)) {
+        const [name, data, options] = call;
+        return {
+            name,
+            data,
+            options
+        };
+    }
+    return call;
+}
+function isInvokeGroups(input) {
+    return Array.isArray(input) && input.length > 0 && typeof input[0] === 'object' && input[0] !== null && 'calls' in input[0];
+}
+async function settleParallel(promises) {
+    const settled = await Promise.allSettled(promises);
+    return settled.map((outcome)=>outcome.status === 'fulfilled' ? outcome.value : {
+            error: toPlaycraftError(outcome.reason)
+        });
+}
+async function runInvokeCalls(bridge, calls, mode, batchOptions = {}, defaultTimeout = DEFAULT_REQUEST_TIMEOUT_MS) {
+    const normalized = calls.map(normalizeInvokeCall);
+    const shared = {
+        timeout: batchOptions.timeout,
+        signal: batchOptions.signal
+    };
+    if (mode === 'parallel') {
+        return settleParallel(normalized.map((call)=>emitOne(bridge, call.name, call.data, {
+                ...shared,
+                ...call.options
+            }, defaultTimeout)));
+    }
+    const results = [];
+    for (const call of normalized){
+        results.push(await emitOne(bridge, call.name, call.data, {
+            ...shared,
+            ...call.options
+        }, defaultTimeout));
+    }
+    return results;
+}
+function emitOne(bridge, name, data, options = {}, defaultTimeout = DEFAULT_REQUEST_TIMEOUT_MS) {
+    if (isEventName(name)) {
+        sendReq(bridge, name, data ?? {});
+        return Promise.resolve(undefined);
+    }
+    const timeout = options.timeout ?? defaultTimeout;
+    const id = genId();
+    return new Promise((resolve, reject)=>{
+        let pending;
+        const offMessage = bridge.addEventListener('message', (e)=>{
+            const msg = e.data;
+            if (msg.kind !== 'res' || msg.id !== id) return;
+            clearTimeout(pending.timer);
+            pending.cleanupAbortListener?.();
+            offMessage();
+            if (msg.ret === RetCodes.OK) {
+                resolve(msg.data);
+            } else {
+                reject(new PlaycraftBridgeError(retToErrorCode(msg.ret ?? RetCodes.REQUEST_FAILED), msg.msg ?? 'request failed'));
+            }
+        });
+        pending = {
+            resolve: resolve,
+            reject,
+            timer: setTimeout(()=>{
+                offMessage();
+                reject(new PlaycraftBridgeError(BridgeErrorCodes.TIMEOUT, `[playcraft] emit "${name}" timeout after ${timeout}ms`));
+            }, timeout),
+            offMessage
+        };
+        if (options.signal) {
+            const onAbort = ()=>{
+                clearTimeout(pending.timer);
+                offMessage();
+                reject(new PlaycraftBridgeError(BridgeErrorCodes.ABORTED, `[playcraft] emit "${name}" aborted`));
+            };
+            if (options.signal.aborted) {
+                onAbort();
+                return;
+            }
+            options.signal.addEventListener('abort', onAbort, {
+                once: true
+            });
+            pending.cleanupAbortListener = ()=>options.signal?.removeEventListener('abort', onAbort);
+        }
+        try {
+            bridge.postMessage(createEnvelope('req', id, name, data));
+        } catch (err) {
+            clearTimeout(pending.timer);
+            offMessage();
+            reject(err);
+        }
+    });
+}
+function emitForBridge(bridge, nameOrCalls, dataOrOptions, options) {
+    if (typeof nameOrCalls === 'string') {
+        return emitOne(bridge, nameOrCalls, dataOrOptions, options);
+    }
+    const batchOptions = dataOrOptions ?? {};
+    if (isInvokeGroups(nameOrCalls)) {
+        const outerMode = batchOptions.mode ?? 'serial';
+        const runGroup = (group)=>runInvokeCalls(bridge, group.calls, group.mode ?? 'serial', batchOptions);
+        if (outerMode === 'parallel') {
+            return settleParallel(nameOrCalls.map(runGroup));
+        }
+        return (async ()=>{
+            const results = [];
+            for (const group of nameOrCalls){
+                results.push(await runGroup(group));
+            }
+            return results;
+        })();
+    }
+    return runInvokeCalls(bridge, nameOrCalls, batchOptions.mode ?? 'serial', batchOptions);
+}
+
+function safeReply(bridge, message) {
+    try {
+        bridge.postMessage(message);
+    } catch (err) {
+        if (err instanceof PlaycraftBridgeError && err.code === BridgeErrorCodes.PEER_UNAVAILABLE) {
+            return;
+        }
+        throw err;
+    }
+}
+function onForBridge(bridge, name, fn) {
+    return bridge.addEventListener('message', async (e)=>{
+        const msg = e.data;
+        if (msg.kind !== 'req' || msg.name !== name) return;
+        if (isEventName(name)) {
+            await fn(msg.data);
+            return;
+        }
+        try {
+            const data = await fn(msg.data, {
+                id: msg.id
+            });
+            safeReply(bridge, createSuccessResponse(msg.id, msg.name, data));
+        } catch (err) {
+            safeReply(bridge, createErrorResponse(msg.id, msg.name, toPlaycraftError(err)));
+        }
+    });
+}
+
+class Bridge {
+    constructor(options){
+        this.options = options;
+        this.listeners = new Set();
+        this.destroyed = false;
+        this.onWindowMessage = (e)=>{
+            const msgEvent = e;
+            if (this.destroyed || !this.options.allowedOrigins.includes(msgEvent.origin)) return;
+            if (!isPlaycraftEnvelope(msgEvent.data)) return;
+            this.log('recv', msgEvent.data);
+            const event = {
+                data: msgEvent.data,
+                origin: msgEvent.origin,
+                source: msgEvent.source
+            };
+            this.listeners.forEach((fn)=>fn(event));
+        };
+        this.targetOrigin = options.targetOrigin;
+        this.messageTarget = options.messageTarget ?? window;
+        this.messageTarget.addEventListener('message', this.onWindowMessage);
+    }
+    emit(nameOrCalls, dataOrOptions, options) {
+        return emitForBridge(this, nameOrCalls, dataOrOptions, options);
+    }
+    on(name, fn) {
+        return onForBridge(this, name, fn);
+    }
+    postMessage(message, targetOrigin = this.options.targetOrigin, transfer) {
+        this.assertAlive();
+        const peer = this.options.peer();
+        if (!peer) {
+            throw new PlaycraftBridgeError(BridgeErrorCodes.PEER_UNAVAILABLE, '[playcraft] peer window is not available');
+        }
+        this.log('send', message);
+        peer.postMessage(message, targetOrigin, transfer ?? []);
+    }
+    addEventListener(type, listener) {
+        this.assertAlive();
+        this.listeners.add(listener);
+        return ()=>this.listeners.delete(listener);
+    }
+    destroy() {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        this.messageTarget.removeEventListener('message', this.onWindowMessage);
+        this.listeners.clear();
+    }
+    assertAlive() {
+        if (this.destroyed) {
+            throw new PlaycraftBridgeError(BridgeErrorCodes.DESTROYED, '[playcraft] bridge destroyed');
+        }
+    }
+    log(event, msg) {
+        const { debug } = this.options;
+        if (!debug) return;
+        if (typeof debug === 'function') debug(event, msg);
+        else console.debug(`[playcraft:${event}]`, msg);
+    }
+}
+
+function parseTruthyDebug(value) {
+    if (value === null) return false;
+    if ([
+        '',
+        '1',
+        'true'
+    ].includes(value)) return true;
+    return false;
+}
+/** True when `debug` query param is set (e.g. `?debug`, `?debug=1`, `?debug=true`). */ function isDebugFromUrl(search) {
+    const params = search instanceof URLSearchParams ? search : typeof search === 'string' ? new URLSearchParams(search.startsWith('?') ? search.slice(1) : search) : typeof globalThis !== 'undefined' && 'location' in globalThis ? new URLSearchParams(globalThis.location.search) : new URLSearchParams();
+    if (!params.has('debug')) return false;
+    return parseTruthyDebug(params.get('debug'));
+}
+
+function createReadyGate() {
+    let resolve;
+    const promise = new Promise((res)=>{
+        resolve = res;
+    });
+    return {
+        promise,
+        resolve
+    };
+}
+
+/** Default one-way events used by the child-side handshake. */ const ChildBridgeDefaults = {
+    readyEvent: BridgeMethods.host.init,
+    announceEvent: BridgeMethods.child.ready
+};
+function normalizeOptions(options) {
+    return typeof options === 'string' ? {
+        parentOrigin: options
+    } : options;
+}
+function createChildBridge(parentOrigin, debug) {
+    return new Bridge({
+        peer: ()=>window.parent,
+        targetOrigin: parentOrigin,
+        allowedOrigins: [
+            parentOrigin
+        ],
+        debug
+    });
+}
+function setupChildBridge(options) {
+    const { parentOrigin, readyEvent = ChildBridgeDefaults.readyEvent, announceEvent = ChildBridgeDefaults.announceEvent, debug = isDebugFromUrl() } = normalizeOptions(options);
+    const bridge = createChildBridge(parentOrigin, debug);
+    const ready = createReadyGate();
+    bridge.on(readyEvent, (evt)=>ready.resolve(evt));
+    if (window.parent !== window) {
+        void bridge.emit(announceEvent, {});
+    }
+    return {
+        bridge,
+        whenParentReady: ()=>ready.promise
+    };
+}
+
+/** Default one-way events used by the parent-side handshake. */ const ParentBridgeDefaults = {
+    announceEvent: BridgeMethods.child.ready,
+    readyEvent: BridgeMethods.host.init
+};
+function createParentBridge(iframe, childOrigin, debug) {
+    return new Bridge({
+        peer: ()=>iframe.contentWindow,
+        targetOrigin: childOrigin,
+        allowedOrigins: [
+            childOrigin
+        ],
+        debug
+    });
+}
+function setupParentBridge(options) {
+    const { iframe, childOrigin, init = {}, announceEvent = ParentBridgeDefaults.announceEvent, readyEvent = ParentBridgeDefaults.readyEvent, debug = isDebugFromUrl() } = options;
+    const bridge = createParentBridge(iframe, childOrigin, debug);
+    const ready = createReadyGate();
+    bridge.on(announceEvent, (evt)=>{
+        void bridge.emit(readyEvent, init);
+        ready.resolve(evt);
+    });
+    return {
+        bridge,
+        whenChildReady: ()=>ready.promise
+    };
+}
+/** Append `parentOrigin` query param for child iframe URLs. */ function withParentOrigin(childUrl, parentOrigin = typeof location !== 'undefined' ? location.origin : '') {
+    const base = typeof location !== 'undefined' ? location.href : 'http://localhost';
+    const url = new URL(childUrl, base);
+    url.searchParams.set('parentOrigin', parentOrigin);
+    return url;
+}
+
+export { BRIDGE_EVENT_NAMES, BRIDGE_RPC_NAMES, Bridge, BridgeErrorCodes, BridgeMethods, ChildBridgeDefaults, DEFAULT_REQUEST_TIMEOUT_MS, PROTOCOL_VERSION, ParentBridgeDefaults, PlaycraftBridgeError, RetCodes, bridgeMethod, createEnvelope, createErrorResponse, createSuccessResponse, emitOne, errorCodeToRet, isDebugFromUrl, isInvokeGroups, isPlaycraftEnvelope, normalizeInvokeCall, retToErrorCode, settleParallel, setupChildBridge, setupParentBridge, toPlaycraftError, withParentOrigin };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@playcraft/iframe-bridge",
+  "version": "0.0.1-alpha.100",
+  "private": false,
+  "type": "module",
+  "description": "PlayCraft iframe postMessage bridge SDK for parent ↔ child communication",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && rollup -c",
+    "dev": "rollup -c -w",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "playground": "pnpm --filter \"@playcraft/iframe-bridge-playground-*\" --parallel dev",
+    "lint": "echo 'No eslint config yet'",
+    "release": "node ../../scripts/release-npm.mjs --packages=iframe-bridge --skip-install --skip-tests --skip-git-push"
+  },
+  "devDependencies": {
+    "@rollup/plugin-json": "6.1.0",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-swc": "0.4.0",
+    "@swc/core": "1.15.3",
+    "@types/node": "^25.2.0",
+    "happy-dom": "^20.0.10",
+    "rollup": "4.57.1",
+    "rollup-plugin-dts": "6.3.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.3",
+    "vitest": "^3.2.4"
+  }
+}