@playcraft/iframe-bridge 0.0.1-alpha.100 → 0.0.1-alpha.101

package/README.md

@@ -142,6 +142,7 @@ const { bridge, whenChildReady } = setupParentBridge({
   iframe,
   childOrigin: new URL(childUrl).origin,
   init: { params: { theme: 'dark' } }, // 收到 child.ready 后自动 emit host.init
+  autoDetectChildReady: true, // iframe load / document complete 也视为 ready
   debug: true,
 });
 
@@ -323,10 +324,10 @@ bridgeMethod('form', 'get'); // 'form.get'
 
 **Request** `AiGenerateImagePayload`
 
-| 字段                   | 类型        | 必填 | 说明                                   |
-| ---------------------- | ----------- | ---- | -------------------------------------- |
-| `prompt`               | `string`    |      | 生成提示词                             |
-| `referenceImageBase64` | `string[]`  |      | 参考图 base64 列表（无 `data:` 前缀） |
+| 字段                   | 类型       | 必填 | 说明                                  |
+| ---------------------- | ---------- | ---- | ------------------------------------- |
+| `prompt`               | `string`   |      | 生成提示词                            |
+| `referenceImageBase64` | `string[]` |      | 参考图 base64 列表（无 `data:` 前缀） |
 
 **Response** `{ paths: PathEntry[] }`
 
@@ -356,6 +357,8 @@ bridgeMethod('form', 'get'); // 'form.get'
 
 Child 侧 `whenParentReady()` / Parent 侧 `whenChildReady()` 在握手完成后 resolve。
 
+若对端未集成 SDK，默认在 `DEFAULT_HANDSHAKE_TIMEOUT_MS`（10s）后仍 resolve 空 payload，并在控制台 `console.warn` 提示；可通过 `handshakeTimeout` 调整等待时间。
+
 ---
 
 ### `dialog.close`

package/dist/index.d.ts

@@ -202,6 +202,8 @@ type SetupChildBridgeOptions = {
     readyEvent?: ChildBridgeDefaultEvents['readyEvent'];
     /** Child → parent event announcing bridge readiness. */
     announceEvent?: ChildBridgeDefaultEvents['announceEvent'];
+    /** Max wait for host.init before resolving with fallback and console.warn. */
+    handshakeTimeout?: number;
     debug?: boolean | DebugLogger;
 };
 type SetupChildBridgeResult = {
@@ -232,6 +234,13 @@ type SetupParentBridgeOptions = {
     announceEvent?: ParentBridgeDefaultEvents['announceEvent'];
     /** Parent → child event sent automatically after announceEvent. */
     readyEvent?: ParentBridgeDefaultEvents['readyEvent'];
+    /** Max wait for child.ready before resolving with fallback and console.warn. */
+    handshakeTimeout?: number;
+    /**
+     * Treat iframe `load` and `contentDocument.readyState === 'complete'` as child ready.
+     * Does not emit `host.init` — only the bridge `child.ready` handshake does that.
+     */
+    autoDetectChildReady?: boolean;
     debug?: boolean | DebugLogger;
 };
 type SetupParentBridgeResult = {
@@ -251,6 +260,8 @@ declare function withParentOrigin(childUrl: string | URL, parentOrigin?: string)
 /** Protocol marker on every envelope; matches package.json version */
 declare const PROTOCOL_VERSION: string;
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 150000;
+/** Max wait for parent ↔ child handshake before resolving with fallback + console.warn. */
+declare const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10000;
 declare const BridgeErrorCodes: {
     readonly ABORTED: "ABORTED";
     readonly DESTROYED: "DESTROYED";
@@ -294,5 +305,5 @@ declare class PlaycraftBridgeError extends Error {
 /** 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 { BRIDGE_EVENT_NAMES, BRIDGE_RPC_NAMES, Bridge, BridgeErrorCodes, BridgeMethods, ChildBridgeDefaults, DEFAULT_HANDSHAKE_TIMEOUT_MS, 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

@@ -1,9 +1,10 @@
-var version = "0.0.1-alpha.100";
+var version = "0.0.1-alpha.101";
 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;
+/** Max wait for parent ↔ child handshake before resolving with fallback + console.warn. */ const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 const BridgeErrorCodes = {
     ABORTED: 'ABORTED',
     DESTROYED: 'DESTROYED',
@@ -382,14 +383,26 @@ function parseTruthyDebug(value) {
     return parseTruthyDebug(params.get('debug'));
 }
 
-function createReadyGate() {
-    let resolve;
-    const promise = new Promise((res)=>{
-        resolve = res;
+/** Resolves on success or after timeout so callers can always continue. */ function createHandshakeGate(options) {
+    let settled = false;
+    let resolveValue;
+    let timer;
+    const promise = new Promise((resolve)=>{
+        resolveValue = (value)=>{
+            if (settled) return;
+            settled = true;
+            if (timer !== undefined) clearTimeout(timer);
+            resolve(value);
+        };
     });
+    timer = setTimeout(()=>{
+        if (settled) return;
+        options.onTimeout();
+        resolveValue(options.fallbackValue);
+    }, options.timeoutMs);
     return {
         promise,
-        resolve
+        resolve: resolveValue
     };
 }
 
@@ -413,9 +426,15 @@ function createChildBridge(parentOrigin, debug) {
     });
 }
 function setupChildBridge(options) {
-    const { parentOrigin, readyEvent = ChildBridgeDefaults.readyEvent, announceEvent = ChildBridgeDefaults.announceEvent, debug = isDebugFromUrl() } = normalizeOptions(options);
+    const { parentOrigin, readyEvent = ChildBridgeDefaults.readyEvent, announceEvent = ChildBridgeDefaults.announceEvent, handshakeTimeout = DEFAULT_HANDSHAKE_TIMEOUT_MS, debug = isDebugFromUrl() } = normalizeOptions(options);
     const bridge = createChildBridge(parentOrigin, debug);
-    const ready = createReadyGate();
+    const ready = createHandshakeGate({
+        timeoutMs: handshakeTimeout,
+        fallbackValue: {},
+        onTimeout: ()=>{
+            console.warn(`[playcraft] whenParentReady timed out after ${handshakeTimeout}ms — parent may not have integrated iframe-bridge SDK`);
+        }
+    });
     bridge.on(readyEvent, (evt)=>ready.resolve(evt));
     if (window.parent !== window) {
         void bridge.emit(announceEvent, {});
@@ -426,6 +445,19 @@ function setupChildBridge(options) {
     };
 }
 
+function attachAutoDetectChildReady(iframe, onReady) {
+    const handleLoad = ()=>{
+        onReady();
+    };
+    iframe.addEventListener('load', handleLoad);
+    if (iframe.src && iframe.contentDocument?.readyState === 'complete') {
+        onReady();
+    }
+    return ()=>{
+        iframe.removeEventListener('load', handleLoad);
+    };
+}
+
 /** Default one-way events used by the parent-side handshake. */ const ParentBridgeDefaults = {
     announceEvent: BridgeMethods.child.ready,
     readyEvent: BridgeMethods.host.init
@@ -441,13 +473,30 @@ function createParentBridge(iframe, childOrigin, debug) {
     });
 }
 function setupParentBridge(options) {
-    const { iframe, childOrigin, init = {}, announceEvent = ParentBridgeDefaults.announceEvent, readyEvent = ParentBridgeDefaults.readyEvent, debug = isDebugFromUrl() } = options;
+    const { iframe, childOrigin, init = {}, announceEvent = ParentBridgeDefaults.announceEvent, readyEvent = ParentBridgeDefaults.readyEvent, handshakeTimeout = DEFAULT_HANDSHAKE_TIMEOUT_MS, autoDetectChildReady = false, debug = isDebugFromUrl() } = options;
     const bridge = createParentBridge(iframe, childOrigin, debug);
-    const ready = createReadyGate();
+    const ready = createHandshakeGate({
+        timeoutMs: handshakeTimeout,
+        fallbackValue: {},
+        onTimeout: ()=>{
+            console.warn(`[playcraft] whenChildReady timed out after ${handshakeTimeout}ms — child may not have integrated iframe-bridge SDK`);
+        }
+    });
+    let detachAutoDetectChildReady;
+    if (autoDetectChildReady) {
+        detachAutoDetectChildReady = attachAutoDetectChildReady(iframe, ()=>{
+            ready.resolve({});
+        });
+    }
     bridge.on(announceEvent, (evt)=>{
         void bridge.emit(readyEvent, init);
         ready.resolve(evt);
     });
+    const destroyBridge = bridge.destroy.bind(bridge);
+    bridge.destroy = ()=>{
+        detachAutoDetectChildReady?.();
+        destroyBridge();
+    };
     return {
         bridge,
         whenChildReady: ()=>ready.promise
@@ -460,4 +509,4 @@ function setupParentBridge(options) {
     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 };
+export { BRIDGE_EVENT_NAMES, BRIDGE_RPC_NAMES, Bridge, BridgeErrorCodes, BridgeMethods, ChildBridgeDefaults, DEFAULT_HANDSHAKE_TIMEOUT_MS, 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

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/iframe-bridge",
-  "version": "0.0.1-alpha.100",
+  "version": "0.0.1-alpha.101",
   "private": false,
   "type": "module",
   "description": "PlayCraft iframe postMessage bridge SDK for parent ↔ child communication",