@blocksdiy/react-common 1.38.0 → 1.39.0

package/dist/iframe-communication/bridge-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-provider.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/bridge-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAiB,KAAK,SAAS,EAAwB,MAAM,OAAO,CAAC;AAE5E,KAAK,iBAAiB,CAAC,IAAI,IAAI;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAC/D,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AACxD,KAAK,mBAAmB,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEhE,KAAK,UAAU,CAAC,IAAI,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,eAAe,GAAG,mBAAmB,CAAC;AAExF,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,OAAO,IAAI;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,mBAAmB,EAAE,MAAM,IAAI,CAAC;IAChC,mBAAmB,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAC;IACzC,iBAAiB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1C,iBAAiB,EAAE,MAAM,IAAI,CAAC;CAC/B,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;AAIrB,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BA+BnE;AAED,wBAAgB,cAAc,CAAC,IAAI,SAAS,OAAO,EAAE,QAAQ,SAAmB,EAAE,YAAY,SAAmB,qBAOhH"}
+{"version":3,"file":"bridge-provider.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/bridge-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAiB,KAAK,SAAS,EAAiC,MAAM,OAAO,CAAC;AAErF,KAAK,iBAAiB,CAAC,IAAI,IAAI;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAC/D,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AACxD,KAAK,mBAAmB,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEhE,KAAK,UAAU,CAAC,IAAI,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,eAAe,GAAG,mBAAmB,CAAC;AAExF,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,OAAO,IAAI;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,mBAAmB,EAAE,MAAM,IAAI,CAAC;IAChC,mBAAmB,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,CAAC;IACzC,iBAAiB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1C,iBAAiB,EAAE,MAAM,IAAI,CAAC;CAC/B,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;AAIrB,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAgCnE;AAED,wBAAgB,cAAc,CAAC,IAAI,SAAS,OAAO,EAAE,QAAQ,SAAmB,EAAE,YAAY,SAAmB,qBAOhH"}

package/dist/iframe-communication/bridge-provider.js

@@ -1,26 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useState } from "react";
+import { createContext, useContext, useMemo, useState } from "react";
 const BridgeStateContext = createContext(undefined);
 export function BridgeProvider({ children }) {
     const [data, setData] = useState({ api: undefined, error: undefined });
     const [isLoading, setIsLoading] = useState(false);
-    const onConnectionSuccess = (api) => {
-        setIsLoading(false);
-        setData({ api, error: undefined });
-    };
-    const onConnectionError = (error) => {
-        setIsLoading(false);
-        setData({ api: undefined, error });
-    };
-    const onConnectionLoading = () => {
-        setIsLoading(true);
-        setData({ api: undefined, error: undefined });
-    };
-    const onConnectionEnded = () => {
-        setIsLoading(false);
-        setData({ api: undefined, error: undefined });
-    };
-    return (_jsx(BridgeStateContext, { value: { isLoading, onConnectionLoading, onConnectionSuccess, onConnectionError, onConnectionEnded, ...data }, children: children }));
+    // Created once (state initializer) so the connection-owning effects can list
+    // these as dependencies without ever re-running; they only close over React
+    // state setters, which are stable.
+    const [transitions] = useState(() => ({
+        onConnectionLoading: () => {
+            setIsLoading(true);
+            setData({ api: undefined, error: undefined });
+        },
+        onConnectionSuccess: (api) => {
+            setIsLoading(false);
+            setData({ api, error: undefined });
+        },
+        onConnectionError: (error) => {
+            setIsLoading(false);
+            setData({ api: undefined, error });
+        },
+        onConnectionEnded: () => {
+            setIsLoading(false);
+            setData({ api: undefined, error: undefined });
+        },
+    }));
+    // Memoized so consumers re-render only when the connection state actually
+    // changes, not whenever the provider's parent re-renders (the platform side
+    // sits under a busy MobX observer).
+    const value = useMemo(() => ({ isLoading, ...transitions, ...data }), [isLoading, transitions, data]);
+    return _jsx(BridgeStateContext, { value: value, children: children });
 }
 export function useBridgeState(hookName = "useBridgeState", providerName = "BridgeProvider") {
     const context = useContext(BridgeStateContext);

package/dist/iframe-communication/iframe-bridge-provider.d.ts

@@ -1,8 +1,10 @@
+import "./promise-with-resolvers-polyfill.js";
 import { type ReactNode } from "react";
-import { IframeApi, PlatformApi } from "./types.js";
+import type { IframeApi, PlatformApi } from "./types.js";
 /**
  * Provider for the iframe (app-render) side of the bridge.
- * Wraps the app inside the iframe and connects to the parent platform window.
+ * Wraps the app inside the iframe and owns the single connection to the
+ * parent platform window.
  *
  * Use `usePlatform()` anywhere inside to access the platform's api.
  */
@@ -13,8 +15,9 @@ export declare function IframeBridgeProvider({ iframeApi, children }: {
 /**
  * Hook for iframe-side code to access the platform's api and connection state.
  *
- * Returns `{ api, error, isLoading }`.
- * `api` is undefined before the connection is established.
+ * Returns `{ platformApi, error, isLoading }`; `platformApi` is undefined
+ * until the connection is established. Read-only — the connection is owned by
+ * `IframeBridgeProvider`, so any number of components may call this.
  */
 export declare function usePlatform(): {
     platformApi: PlatformApi | undefined;

package/dist/iframe-communication/iframe-bridge-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"iframe-bridge-provider.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/iframe-bridge-provider.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,SAAS,EAAiC,MAAM,OAAO,CAAC;AAGrF,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAIjD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAM1G;AAED;;;;;GAKG;AACH,wBAAgB,WAAW;;;;EAyD1B"}
+{"version":3,"file":"iframe-bridge-provider.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/iframe-bridge-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,mCAAmC,CAAC;AAI3C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAO1G;AAkBD;;;;;;GAMG;AACH,wBAAgB,WAAW;;;;EAI1B"}

package/dist/iframe-communication/iframe-bridge-provider.js

@@ -1,67 +1,40 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "./promise-with-resolvers-polyfill.js";
 import { getDomain, getProtocol } from "@blocksdiy/blocks-client-api/envService";
-import { connect, WindowMessenger } from "penpal";
-import { createContext, useContext, useEffect, useRef } from "react";
+import { WindowMessenger } from "penpal";
 import { BridgeProvider, useBridgeState } from "./bridge-provider.js";
-const IframeApiContext = createContext(undefined);
+import { useBridgeConnection } from "./use-bridge-connection.js";
 /**
  * Provider for the iframe (app-render) side of the bridge.
- * Wraps the app inside the iframe and connects to the parent platform window.
+ * Wraps the app inside the iframe and owns the single connection to the
+ * parent platform window.
  *
  * Use `usePlatform()` anywhere inside to access the platform's api.
  */
 export function IframeBridgeProvider({ iframeApi, children }) {
-    return (_jsx(BridgeProvider, { children: _jsx(IframeApiContext, { value: iframeApi, children: children }) }));
+    return (_jsxs(BridgeProvider, { children: [_jsx(PlatformConnection, { iframeApi: iframeApi }), children] }));
+}
+/** Owns the penpal connection to the parent platform window. Renders nothing. */
+function PlatformConnection({ iframeApi }) {
+    useBridgeConnection({
+        hookName: "PlatformConnection",
+        providerName: "IframeBridgeProvider",
+        methods: iframeApi,
+        createMessenger: () => new WindowMessenger({
+            remoteWindow: window.parent,
+            allowedOrigins: [new RegExp(`^${getProtocol()}://(b-\\d+\\.)?${getDomain().replace(/\./g, "\\.")}$`)],
+        }),
+    });
+    return null;
 }
 /**
  * Hook for iframe-side code to access the platform's api and connection state.
  *
- * Returns `{ api, error, isLoading }`.
- * `api` is undefined before the connection is established.
+ * Returns `{ platformApi, error, isLoading }`; `platformApi` is undefined
+ * until the connection is established. Read-only — the connection is owned by
+ * `IframeBridgeProvider`, so any number of components may call this.
  */
 export function usePlatform() {
-    const { error, isLoading, onConnectionSuccess, onConnectionError, onConnectionEnded, onConnectionLoading, api } = useBridgeState("usePlatform", "IframeBridgeProvider");
-    const iframeApi = useContext(IframeApiContext);
-    const iframeApiRef = useRef(iframeApi);
-    useEffect(() => {
-        iframeApiRef.current = iframeApi;
-    }, [iframeApi]);
-    const onConnectionSuccessRef = useRef(onConnectionSuccess);
-    useEffect(() => {
-        onConnectionSuccessRef.current = onConnectionSuccess;
-    }, [onConnectionSuccess]);
-    const onConnectionErrorRef = useRef(onConnectionError);
-    useEffect(() => {
-        onConnectionErrorRef.current = onConnectionError;
-    }, [onConnectionError]);
-    const onConnectionLoadingRef = useRef(onConnectionLoading);
-    useEffect(() => {
-        onConnectionLoadingRef.current = onConnectionLoading;
-    }, [onConnectionLoading]);
-    const onConnectionEndedRef = useRef(onConnectionEnded);
-    useEffect(() => {
-        onConnectionEndedRef.current = onConnectionEnded;
-    }, [onConnectionEnded]);
-    useEffect(() => {
-        onConnectionLoadingRef.current?.();
-        const messenger = new WindowMessenger({
-            remoteWindow: window.parent,
-            allowedOrigins: [new RegExp(`^${getProtocol()}://(b-\\d+\\.)?${getDomain().replace(/\./g, "\\.")}$`)],
-        });
-        const connection = connect({
-            messenger,
-            methods: iframeApiRef.current,
-            // log: debug("iframe-window"),
-        });
-        connection.promise
-            .then((platformApi) => onConnectionSuccessRef.current(platformApi))
-            .catch((error) => {
-            onConnectionErrorRef.current(error);
-        });
-        return () => {
-            connection.destroy();
-            onConnectionEndedRef.current?.();
-        };
-    }, []);
+    const { api, error, isLoading } = useBridgeState("usePlatform", "IframeBridgeProvider");
     return { platformApi: api, error, isLoading };
 }

package/dist/iframe-communication/index.d.ts

@@ -1,5 +1,5 @@
 export type { ThemeMode, AppUpdate, PlatformApi, IframeApi, EditedElement, ElementData } from "./types.js";
-export { BridgeProvider, useBridgeState, type BridgeState } from "./bridge-provider.js";
+export { BridgeProvider, type BridgeState } from "./bridge-provider.js";
 export { IframeBridgeProvider, usePlatform } from "./iframe-bridge-provider.js";
 export { PlatformBridgeProvider, PlatformBridgeIframe, useIframe } from "./platform-bridge-provider.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/iframe-communication/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACxG,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErF,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGxG,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/iframe-communication/index.js

@@ -1,3 +1,5 @@
-export { BridgeProvider, useBridgeState } from "./bridge-provider.js";
+// useBridgeState is deliberately not exported: it hands out the connection
+// state mutators, which belong solely to the providers below.
+export { BridgeProvider } from "./bridge-provider.js";
 export { IframeBridgeProvider, usePlatform } from "./iframe-bridge-provider.js";
 export { PlatformBridgeProvider, PlatformBridgeIframe, useIframe } from "./platform-bridge-provider.js";

package/dist/iframe-communication/live-methods.d.ts

@@ -0,0 +1,19 @@
+import type { Methods } from "penpal";
+import { type RefObject } from "react";
+/**
+ * penpal holds the `methods` object it was given at connect() time and
+ * resolves every incoming call against it at call time (own properties only,
+ * walked segment by segment — nested namespaces are part of its contract).
+ * React consumers rebuild their handler objects every render, so handing one
+ * to connect() directly would pin every handler to its first-render closures —
+ * a classic source of stale-state bugs that each consumer previously had to
+ * work around with refs.
+ *
+ * This returns a stable proxy that delegates every lookup to
+ * `methodsRef.current`, so remote calls always reach the latest committed
+ * handlers — including nested method namespaces and methods added or removed
+ * after connect(). Like penpal itself, only own properties are visible;
+ * prototype (class-instance) methods are not.
+ */
+export declare function createLiveMethods<TMethods extends Methods>(methodsRef: RefObject<TMethods>): TMethods;
+//# sourceMappingURL=live-methods.d.ts.map

package/dist/iframe-communication/live-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-methods.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/live-methods.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,SAAS,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAYrG"}

package/dist/iframe-communication/live-methods.js

@@ -0,0 +1,28 @@
+/**
+ * penpal holds the `methods` object it was given at connect() time and
+ * resolves every incoming call against it at call time (own properties only,
+ * walked segment by segment — nested namespaces are part of its contract).
+ * React consumers rebuild their handler objects every render, so handing one
+ * to connect() directly would pin every handler to its first-render closures —
+ * a classic source of stale-state bugs that each consumer previously had to
+ * work around with refs.
+ *
+ * This returns a stable proxy that delegates every lookup to
+ * `methodsRef.current`, so remote calls always reach the latest committed
+ * handlers — including nested method namespaces and methods added or removed
+ * after connect(). Like penpal itself, only own properties are visible;
+ * prototype (class-instance) methods are not.
+ */
+export function createLiveMethods(methodsRef) {
+    return new Proxy({}, {
+        get: (_target, property) => Reflect.get(methodsRef.current, property),
+        has: (_target, property) => Reflect.has(methodsRef.current, property),
+        ownKeys: () => Reflect.ownKeys(methodsRef.current),
+        getOwnPropertyDescriptor: (_target, property) => {
+            const descriptor = Reflect.getOwnPropertyDescriptor(methodsRef.current, property);
+            // Proxy invariant: a property the (empty) target lacks must be reported
+            // as configurable.
+            return descriptor && { ...descriptor, configurable: true };
+        },
+    });
+}

package/dist/iframe-communication/platform-bridge-provider.d.ts

@@ -1,11 +1,12 @@
+import "./promise-with-resolvers-polyfill.js";
 import { type ReactNode } from "react";
 import type { IframeApi, PlatformApi } from "./types.js";
 /**
  * Context provider for the platform (Remix) side of the bridge.
  * Does NOT render any iframe — use `PlatformBridgeIframe` inside this provider.
  *
- * `methods` — handlers the iframe can call on the platform.
- * Use `useIframe()` anywhere inside to check `isLoaded` and call iframe methods.
+ * Use `useIframe()` anywhere inside to check the connection state and call
+ * methods the iframe exposes.
  */
 export declare function PlatformBridgeProvider({ children }: {
     children: ReactNode;

package/dist/iframe-communication/platform-bridge-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-bridge-provider.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/platform-bridge-provider.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,OAAO,CAAC;AAG1D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAE3E;AAED,KAAK,yBAAyB,GAAG;IAAE,WAAW,EAAE,WAAW,CAAA;CAAE,GAAG,IAAI,CAClE,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAC7C,KAAK,GAAG,OAAO,CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,EAAE,yBAAyB,+BA2E9F;AAED;;;;GAIG;AACH,wBAAgB,SAAS;;;;EAQxB"}
+{"version":3,"file":"platform-bridge-provider.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/platform-bridge-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,mCAAmC,CAAC;AAG3C,OAAO,EAAE,KAAK,SAAS,EAAU,MAAM,OAAO,CAAC;AAG/C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAE3E;AAED,KAAK,yBAAyB,GAAG;IAAE,WAAW,EAAE,WAAW,CAAA;CAAE,GAAG,IAAI,CAClE,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAC7C,KAAK,GAAG,OAAO,CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,EAAE,yBAAyB,+BA0B9F;AAED;;;;GAIG;AACH,wBAAgB,SAAS;;;;EAQxB"}

package/dist/iframe-communication/platform-bridge-provider.js

@@ -1,13 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { connect, WindowMessenger } from "penpal";
-import { useEffect, useRef } from "react";
+import "./promise-with-resolvers-polyfill.js";
+import { WindowMessenger } from "penpal";
+import { useRef } from "react";
 import { BridgeProvider, useBridgeState } from "./bridge-provider.js";
+import { useBridgeConnection } from "./use-bridge-connection.js";
 /**
  * Context provider for the platform (Remix) side of the bridge.
  * Does NOT render any iframe — use `PlatformBridgeIframe` inside this provider.
  *
- * `methods` — handlers the iframe can call on the platform.
- * Use `useIframe()` anywhere inside to check `isLoaded` and call iframe methods.
+ * Use `useIframe()` anywhere inside to check the connection state and call
+ * methods the iframe exposes.
  */
 export function PlatformBridgeProvider({ children }) {
     return _jsx(BridgeProvider, { children: children });
@@ -19,57 +21,22 @@ export function PlatformBridgeProvider({ children }) {
  * Accepts all standard `<iframe>` HTML attributes (`src`, `className`, `allow`, etc.).
  */
 export function PlatformBridgeIframe({ platformApi, ...iframeProps }) {
-    const { onConnectionSuccess, onConnectionError, onConnectionLoading, onConnectionEnded } = useBridgeState("PlatformBridgeIframe", "PlatformBridgeProvider");
-    const connectionRef = useRef(null);
-    const platformApiRef = useRef(platformApi);
-    useEffect(() => {
-        platformApiRef.current = platformApi;
-    }, [platformApi]);
-    const onConnectionSuccessRef = useRef(onConnectionSuccess);
-    useEffect(() => {
-        onConnectionSuccessRef.current = onConnectionSuccess;
-    }, [onConnectionSuccess]);
-    const onConnectionErrorRef = useRef(onConnectionError);
-    useEffect(() => {
-        onConnectionErrorRef.current = onConnectionError;
-    }, [onConnectionError]);
-    const onConnectionLoadingRef = useRef(onConnectionLoading);
-    useEffect(() => {
-        onConnectionLoadingRef.current = onConnectionLoading;
-    }, [onConnectionLoading]);
-    const onConnectionEndedRef = useRef(onConnectionEnded);
-    useEffect(() => {
-        onConnectionEndedRef.current = onConnectionEnded;
-    }, [onConnectionEnded]);
     const iframeRef = useRef(null);
-    useEffect(() => {
-        const iframe = iframeRef.current;
-        if (!iframe?.contentWindow) {
-            onConnectionEndedRef.current();
-            return;
-        }
-        onConnectionLoadingRef.current();
-        const messenger = new WindowMessenger({
-            remoteWindow: iframe.contentWindow,
-            allowedOrigins: [new URL(iframe.src).origin],
-        });
-        connectionRef.current?.destroy();
-        connectionRef.current = connect({
-            messenger,
-            methods: platformApiRef.current,
-            // log: debug("platform-window"),
-        });
-        connectionRef.current.promise
-            .then((api) => onConnectionSuccessRef.current(api))
-            .catch((error) => {
-            connectionRef.current?.destroy();
-            onConnectionErrorRef.current(error);
-        });
-        return () => {
-            connectionRef.current?.destroy();
-            onConnectionEndedRef.current();
-        };
-    }, []);
+    useBridgeConnection({
+        hookName: "PlatformBridgeIframe",
+        providerName: "PlatformBridgeProvider",
+        methods: platformApi,
+        createMessenger: () => {
+            const iframe = iframeRef.current;
+            if (!iframe?.contentWindow) {
+                return undefined;
+            }
+            return new WindowMessenger({
+                remoteWindow: iframe.contentWindow,
+                allowedOrigins: [new URL(iframe.src).origin],
+            });
+        },
+    });
     return (_jsx("iframe", { ref: iframeRef, allow: "accelerometer; autoplay; camera; encrypted-media; fullscreen; geolocation; gyroscope; microphone; midi; clipboard-read; clipboard-write; payment; usb; xr-spatial-tracking; screen-wake-lock; magnetometer; gamepad; picture-in-picture; display-capture; bluetooth;", ...iframeProps }));
 }
 /**

package/dist/iframe-communication/promise-with-resolvers-polyfill.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=promise-with-resolvers-polyfill.d.ts.map

package/dist/iframe-communication/promise-with-resolvers-polyfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise-with-resolvers-polyfill.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/promise-with-resolvers-polyfill.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,CAAC"}

package/dist/iframe-communication/promise-with-resolvers-polyfill.js

@@ -0,0 +1,19 @@
+/**
+ * penpal 8 targets ES2024 and calls `Promise.withResolvers()` natively
+ * (Chrome/Edge 119+, Firefox 121+, Safari 17.4+). The iframe side of the
+ * bridge ships inside published apps that run on end-user devices we don't
+ * control, so back-fill the method where it's missing instead of raising the
+ * browser floor for every published app.
+ */
+if (typeof Promise.withResolvers !== "function") {
+    Promise.withResolvers = function withResolvers() {
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        return { promise, resolve, reject };
+    };
+}
+export {};

package/dist/iframe-communication/use-bridge-connection.d.ts

@@ -0,0 +1,34 @@
+import { type Messenger, type Methods, PenpalError, type RemoteProxy } from "penpal";
+/**
+ * Owns one penpal connection for the lifetime of the calling component and
+ * drives the shared bridge state through it: loading on mount, success/error
+ * from the handshake, ended on unmount. Both sides of the bridge share this
+ * hook so the subtle parts below stay identical on each side.
+ */
+export declare function useBridgeConnection<TRemoteApi extends Methods>({ hookName, providerName, createMessenger, methods, }: {
+    hookName: string;
+    providerName: string;
+    /**
+     * Builds the messenger for this connection, called one tick after mount.
+     * Return undefined to skip connecting (e.g. no iframe contentWindow yet);
+     * throws surface as connection errors.
+     */
+    createMessenger: () => Messenger | undefined;
+    /**
+     * Methods to expose to the remote. Pass the current render's object as-is —
+     * the hook forwards remote calls to the latest committed handlers (see
+     * `createLiveMethods`), so it never goes stale and never re-connects.
+     */
+    methods: Methods;
+}): void;
+/**
+ * penpal gives no signal when the remote destroys an established connection —
+ * the remote proxy just starts throwing CONNECTION_DESTROYED synchronously
+ * from every method call. Wrap the proxy so those throws become rejections
+ * (matching the methods' async signatures) and report the death, instead of
+ * crashing whichever component happened to make the next call.
+ *
+ * Exported for tests.
+ */
+export declare function guardDestroyedProxy<TApi extends Methods>(api: RemoteProxy<TApi>, onDestroyedCall: (error: PenpalError) => void): RemoteProxy<TApi>;
+//# sourceMappingURL=use-bridge-connection.d.ts.map

package/dist/iframe-communication/use-bridge-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-bridge-connection.d.ts","sourceRoot":"","sources":["../../src/iframe-communication/use-bridge-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,WAAW,EACX,KAAK,WAAW,EACjB,MAAM,QAAQ,CAAC;AAehB;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,SAAS,OAAO,EAAE,EAC9D,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,OAAO,GACR,EAAE;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,EAAE,MAAM,SAAS,GAAG,SAAS,CAAC;IAC7C;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB,QAoFA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,OAAO,EACtD,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,EACtB,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAC5C,WAAW,CAAC,IAAI,CAAC,CAuBnB"}

package/dist/iframe-communication/use-bridge-connection.js

@@ -0,0 +1,128 @@
+import { connect, ErrorCode, PenpalError, } from "penpal";
+import { useEffect, useRef } from "react";
+import { useBridgeState } from "./bridge-provider.js";
+import { createLiveMethods } from "./live-methods.js";
+/**
+ * How long to wait for the penpal handshake before failing the connection.
+ * penpal only arms its handshake timer when a timeout is provided — without
+ * one, an iframe that never loads (bad src, CSP denial, fatal script error
+ * before the provider mounts) leaves the bridge loading forever with no error
+ * for consumers to surface.
+ */
+const CONNECT_TIMEOUT_MS = 60_000;
+/**
+ * Owns one penpal connection for the lifetime of the calling component and
+ * drives the shared bridge state through it: loading on mount, success/error
+ * from the handshake, ended on unmount. Both sides of the bridge share this
+ * hook so the subtle parts below stay identical on each side.
+ */
+export function useBridgeConnection({ hookName, providerName, createMessenger, methods, }) {
+    const { onConnectionSuccess, onConnectionError, onConnectionLoading, onConnectionEnded } = useBridgeState(hookName, providerName);
+    // Latest committed factory and methods, so the connection effect never
+    // re-runs just because a render rebuilt them.
+    const createMessengerRef = useRef(createMessenger);
+    const methodsRef = useRef(methods);
+    useEffect(() => {
+        createMessengerRef.current = createMessenger;
+        methodsRef.current = methods;
+    }, [createMessenger, methods]);
+    useEffect(() => {
+        onConnectionLoading();
+        // Deferred one tick, cancelled by cleanup: dev StrictMode's synchronous
+        // mount -> cleanup -> remount then never creates the throwaway first
+        // connection. A destroyed connection's SYN otherwise stays on the wire and
+        // can mispair the real handshake — both sides resolve but the MessagePorts
+        // end up crossed and every call hangs (reproduced: 6/12 trials).
+        let connection;
+        // Set before cleanup destroys the connection, so the rejection that
+        // destroy() causes can be told apart from a remote-initiated teardown.
+        let destroyedByCleanup = false;
+        const connectTimer = setTimeout(() => {
+            // Synchronous setup throws (an invalid iframe src URL, penpal argument
+            // validation) would otherwise become uncaught errors inside the timer —
+            // route them into the bridge state like any other connection failure.
+            try {
+                const messenger = createMessengerRef.current();
+                if (!messenger) {
+                    onConnectionEnded();
+                    return;
+                }
+                connection = connect({
+                    messenger,
+                    methods: createLiveMethods(methodsRef),
+                    timeout: CONNECT_TIMEOUT_MS,
+                });
+                connection.promise
+                    .then((api) => {
+                    const guardedApi = guardDestroyedProxy(api, (error) => {
+                        // Ignore calls on a proxy this effect already tore down — the
+                        // bridge state has moved on (possibly to a newer connection).
+                        if (!destroyedByCleanup) {
+                            onConnectionError(error);
+                        }
+                    });
+                    // RemoteProxy<T> is structurally T for our promise-returning
+                    // bridge APIs; TypeScript just can't prove it for an unresolved
+                    // type parameter.
+                    onConnectionSuccess(guardedApi);
+                })
+                    .catch((error) => {
+                    // Since penpal 8, destroying a pending connection rejects its
+                    // promise instead of leaking it. Only our own cleanup's destroy()
+                    // is expected teardown — a CONNECTION_DESTROYED from anywhere else
+                    // means the remote tore down a connection we still wanted, which
+                    // is a failure like any other.
+                    if (destroyedByCleanup && error instanceof PenpalError && error.code === ErrorCode.ConnectionDestroyed) {
+                        return;
+                    }
+                    onConnectionError(error);
+                });
+            }
+            catch (error) {
+                onConnectionError(error instanceof Error ? error : new Error(String(error)));
+            }
+        }, 0);
+        return () => {
+            destroyedByCleanup = true;
+            clearTimeout(connectTimer);
+            connection?.destroy();
+            onConnectionEnded();
+        };
+        // The transitions are created once by BridgeProvider, so this effect runs
+        // once per mounted connection owner.
+    }, [onConnectionSuccess, onConnectionError, onConnectionLoading, onConnectionEnded]);
+}
+/**
+ * penpal gives no signal when the remote destroys an established connection —
+ * the remote proxy just starts throwing CONNECTION_DESTROYED synchronously
+ * from every method call. Wrap the proxy so those throws become rejections
+ * (matching the methods' async signatures) and report the death, instead of
+ * crashing whichever component happened to make the next call.
+ *
+ * Exported for tests.
+ */
+export function guardDestroyedProxy(api, onDestroyedCall) {
+    const wrap = (value) => {
+        if ((typeof value !== "function" && typeof value !== "object") || value === null) {
+            return value;
+        }
+        return new Proxy(value, {
+            // penpal's remote proxy resolves nested method paths lazily through
+            // property gets, so wrap whatever comes back the same way.
+            get: (target, property, receiver) => wrap(Reflect.get(target, property, receiver)),
+            apply: (target, thisArg, args) => {
+                try {
+                    return Reflect.apply(target, thisArg, args);
+                }
+                catch (error) {
+                    if (error instanceof PenpalError && error.code === ErrorCode.ConnectionDestroyed) {
+                        onDestroyedCall(error);
+                        return Promise.reject(error);
+                    }
+                    throw error;
+                }
+            },
+        });
+    };
+    return wrap(api);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocksdiy/react-common",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "type": "module",
   "description": "React common",
   "keywords": [],
@@ -35,7 +35,7 @@
     "@copilotkit/react-core": "1.60.1",
     "@radix-ui/react-slot": "^1.2.3",
     "@vapi-ai/web": "^2.5.2",
-    "penpal": "^7.0.6",
+    "penpal": "^8.0.0",
     "react": "^19.2.8",
     "use-stick-to-bottom": "1.1.4",
     "@blocksdiy/blocks-client-api": "1.5.0"
@@ -45,6 +45,8 @@
     "babel-plugin-react-compiler": "^1.0.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
     "tsc-alias": "^1.8.10",
     "typescript": "^5.9.3",
     "@blockscom/eslint-config": "4.6.4"
@@ -55,7 +57,7 @@
   "scripts": {
     "clean": "rm -rf ./dist/ && rm -rf tsconfig.tsbuildinfo && rm -rf node_modules",
     "build": "rm -rf dist && tsc && tsc-alias && echo $(date +%s) > .build-sentinel.json",
-    "test": "echo \"no tests\"",
+    "test": "jest --config test/jest.json",
     "lint": "pnpm eslint src/",
     "lint-fix": "pnpm eslint src/ --fix"
   }