@playruo/embed 1.3.1 → 1.3.2

package/README.md

@@ -1,3 +1,12 @@
 # @playruo/embed
 
 React SDK to embed Playruo via iframe + postMessage.
+
+## Event forwarding
+
+When the embedded Playruo iframe sends `{ type: "playruo_event", data }`, the
+React package forwards the payload through `onEvent(data)`.
+
+If the package host is itself inside another iframe, the same message is also
+forwarded one level up with `window.parent.postMessage({ type:
+"playruo_event", data }, "*")`.

package/dist/index.cjs

@@ -74,14 +74,18 @@ var PlayruoEmbed = ({
   onReady,
   onStateChange,
   onDemoCompleted,
+  onEvent,
   onPurchaseRequest,
   onError,
+  forwardEventsToParent = true,
   renderState,
   iframeRef: externalIframeRef
 }) => {
   const internalIframeRef = (0, import_react.useRef)(null);
   const iframeRef = externalIframeRef || internalIframeRef;
   const wasEmbedFullscreenRef = (0, import_react.useRef)(false);
+  const hasNotifiedCompletionRef = (0, import_react.useRef)(false);
+  const suppressNextFullscreenExitCleanupRef = (0, import_react.useRef)(false);
   const [isIframeLoaded, setIsIframeLoaded] = (0, import_react.useState)(false);
   const [hasPlayedOnce, setHasPlayedOnce] = (0, import_react.useState)(false);
   const [showGameIframe, setShowGameIframe] = (0, import_react.useState)(false);
@@ -151,6 +155,149 @@ var PlayruoEmbed = ({
       console.warn("[PlayruoEmbed] Failed to release Escape key lock:", error);
     }
   }, [getKeyboardApi]);
+  const getFullscreenElement = (0, import_react.useCallback)(() => {
+    const doc = document;
+    return doc.fullscreenElement || doc.webkitFullscreenElement || doc.mozFullScreenElement || doc.msFullscreenElement || null;
+  }, []);
+  const notifyDemoCompletedOnce = (0, import_react.useCallback)(
+    (payload) => {
+      if (hasNotifiedCompletionRef.current) {
+        return;
+      }
+      hasNotifiedCompletionRef.current = true;
+      onDemoCompleted?.(
+        payload ?? {
+          reason: "Demo session ended",
+          storeUrl
+        }
+      );
+    },
+    [onDemoCompleted, storeUrl]
+  );
+  const postExitFullscreenToIframe = (0, import_react.useCallback)(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) {
+      return;
+    }
+    try {
+      iframe.contentWindow?.postMessage({
+        type: "playruo",
+        action: "exitFullscreen",
+        fromEmbed: true,
+        isFullscreen: false,
+        parentWillHandleFullscreen: true
+      }, "*");
+    } catch {
+      console.error("[PlayruoEmbed] Failed to exit fullscreen");
+    }
+  }, [iframeRef]);
+  const postExitFullscreenAckToIframe = (0, import_react.useCallback)(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) {
+      return;
+    }
+    try {
+      iframe.contentWindow?.postMessage({ type: "ACK_EXIT_FULLSCREEN" }, "*");
+    } catch {
+      console.error("[PlayruoEmbed] Failed to acknowledge fullscreen exit");
+    }
+  }, [iframeRef]);
+  const exitEmbedFullscreen = (0, import_react.useCallback)(
+    async ({
+      reason = "cleanup",
+      suppressFullscreenExitCleanup = true
+    } = {}) => {
+      const fullscreenElement = getFullscreenElement();
+      const doc = document;
+      const exitFullscreen = doc.exitFullscreen?.bind(doc) ?? doc.webkitExitFullscreen?.bind(doc) ?? doc.mozCancelFullScreen?.bind(doc) ?? doc.msExitFullscreen?.bind(doc);
+      const shouldAttemptExit = Boolean(fullscreenElement || wasEmbedFullscreenRef.current);
+      if (!shouldAttemptExit || !exitFullscreen) {
+        console.log("[PlayruoEmbed] Parent fullscreen exit skipped", {
+          hasFullscreenElement: Boolean(fullscreenElement),
+          hasExitFullscreen: Boolean(exitFullscreen),
+          reason,
+          wasEmbedFullscreen: wasEmbedFullscreenRef.current
+        });
+        return false;
+      }
+      console.log("[PlayruoEmbed] Parent fullscreen exit requested", {
+        fullscreenElement: fullscreenElement?.tagName,
+        reason,
+        wasEmbedFullscreen: wasEmbedFullscreenRef.current
+      });
+      const shouldSuppressFullscreenExitCleanup = Boolean(
+        suppressFullscreenExitCleanup && fullscreenElement
+      );
+      if (shouldSuppressFullscreenExitCleanup) {
+        suppressNextFullscreenExitCleanupRef.current = true;
+        wasEmbedFullscreenRef.current = false;
+      }
+      try {
+        await exitFullscreen();
+        if (shouldSuppressFullscreenExitCleanup) {
+          window.setTimeout(() => {
+            suppressNextFullscreenExitCleanupRef.current = false;
+          }, 1e3);
+        }
+        return true;
+      } catch (error) {
+        if (shouldSuppressFullscreenExitCleanup) {
+          suppressNextFullscreenExitCleanupRef.current = false;
+          wasEmbedFullscreenRef.current = Boolean(getFullscreenElement());
+        }
+        console.warn("[PlayruoEmbed] Failed to leave fullscreen:", error);
+        return false;
+      }
+    },
+    [getFullscreenElement]
+  );
+  const cleanupEmbedSession = (0, import_react.useCallback)(
+    ({
+      payload,
+      notifyCompletion = true,
+      requestFullscreenExit = true,
+      notifyIframe = false,
+      markPlayed = true
+    } = {}) => {
+      setShowGameIframe(false);
+      if (markPlayed) {
+        setHasPlayedOnce(true);
+      }
+      releaseEscapeKeyLock();
+      if (notifyIframe) {
+        postExitFullscreenToIframe();
+      }
+      if (requestFullscreenExit) {
+        void exitEmbedFullscreen();
+      }
+      if (notifyCompletion) {
+        notifyDemoCompletedOnce(payload);
+      }
+    },
+    [
+      exitEmbedFullscreen,
+      notifyDemoCompletedOnce,
+      postExitFullscreenToIframe,
+      releaseEscapeKeyLock
+    ]
+  );
+  const markStreamActive = (0, import_react.useCallback)(() => {
+    hasNotifiedCompletionRef.current = false;
+    setShowGameIframe(true);
+  }, []);
+  const forwardEventToParent = (0, import_react.useCallback)(
+    (message) => {
+      if (!forwardEventsToParent || typeof window === "undefined" || window.parent === window) {
+        return;
+      }
+      try {
+        window.parent.postMessage(message, "*");
+      } catch (error) {
+        console.warn("[PlayruoEmbed] Failed to forward event to parent:", error);
+      }
+    },
+    [forwardEventsToParent]
+  );
   const lockEscapeKey = (0, import_react.useCallback)(async () => {
     const keyboard = getKeyboardApi();
     if (!keyboard?.lock) {
@@ -187,6 +334,7 @@ var PlayruoEmbed = ({
       console.warn("[PlayruoEmbed] Iframe not ready");
       return;
     }
+    hasNotifiedCompletionRef.current = false;
     setShowGameIframe(true);
     try {
       try {
@@ -210,6 +358,7 @@ var PlayruoEmbed = ({
       setHasPlayedOnce(true);
     } catch (error) {
       console.error("[PlayruoEmbed] Failed to start game:", error);
+      setShowGameIframe(false);
       setErrorMessage("Failed to start game");
       onError?.("Failed to start game");
     }
@@ -233,7 +382,8 @@ var PlayruoEmbed = ({
   }, [isReady, onReady]);
   (0, import_react.useEffect)(() => {
     const handleGameMessage = (event) => {
-      const { type, data } = event.data || {};
+      const message = event.data || {};
+      const { type, data } = message;
       const iframe = iframeRef.current;
       if (!iframe || event.source !== iframe.contentWindow) {
         return;
@@ -254,8 +404,7 @@ var PlayruoEmbed = ({
         onPurchaseRequest?.(data);
       } else if (type === "playruo_demo_completed" && data) {
         console.log("\u{1F537} [Embed] playruo_demo_completed received:", data);
-        setHasPlayedOnce(true);
-        onDemoCompleted?.(data);
+        cleanupEmbedSession({ payload: data });
       } else if (type === "playruo_error") {
         const errorMessage2 = typeof data === "string" ? data : data?.message || "Unknown error";
         console.log("\u{1F537} [Embed] playruo_error received:", errorMessage2);
@@ -276,25 +425,65 @@ var PlayruoEmbed = ({
         onError?.(errorMessage2);
       } else if (type === "playruo_session_over" && data) {
         console.log("\u{1F537} [Embed] playruo_session_over received:", data);
-        setHasPlayedOnce(true);
+        void exitEmbedFullscreen({ reason: "playruo_session_over" });
         setIframeState(data);
         onStateChange?.(data);
+        cleanupEmbedSession({ requestFullscreenExit: false });
       } else if (type === "playruo_stream_start") {
         console.log("\u{1F537} [Embed] playruo_stream_start received");
+        markStreamActive();
+      } else if (type === "playruo_stream_stop") {
+        console.log("\u{1F537} [Embed] playruo_stream_stop received");
+        void exitEmbedFullscreen({ reason: "playruo_stream_stop" });
+        cleanupEmbedSession({
+          markPlayed: false,
+          notifyCompletion: false,
+          requestFullscreenExit: false
+        });
+      } else if (type === "REQUEST_EXIT_FULLSCREEN") {
+        console.log("\u{1F537} [Embed] REQUEST_EXIT_FULLSCREEN received");
+        void exitEmbedFullscreen({
+          reason: "REQUEST_EXIT_FULLSCREEN",
+          suppressFullscreenExitCleanup: false
+        }).finally(postExitFullscreenAckToIframe);
+      } else if (type === "playruo_event" && data && typeof data === "object") {
+        console.log("\u{1F537} [Embed] playruo_event received:", data);
+        const eventPayload = data;
+        onEvent?.(eventPayload);
+        forwardEventToParent({ type: "playruo_event", data: eventPayload });
+      } else if (type === "playruo" && message.action === "event" && message.payload && typeof message.payload === "object") {
+        console.log("\u{1F537} [Embed] legacy playruo event received:", message.payload);
+        const eventPayload = message.payload;
+        onEvent?.(eventPayload);
+        forwardEventToParent({ type: "playruo_event", data: eventPayload });
       }
       if (type === "error" || type === "closeForBuy" || type === "goToStore") {
         console.log("\u{1F537} [Embed] Legacy message received:", type);
-        setHasPlayedOnce(true);
-        const payload = {
-          reason: "Demo session ended",
-          storeUrl
-        };
-        onDemoCompleted?.(payload);
+        cleanupEmbedSession({
+          payload: {
+            reason: "Demo session ended",
+            storeUrl
+          }
+        });
       }
     };
     window.addEventListener("message", handleGameMessage);
     return () => window.removeEventListener("message", handleGameMessage);
-  }, [storeUrl, onDemoCompleted, onReady, onStateChange, onPurchaseRequest, onError, iframeRef]);
+  }, [
+    cleanupEmbedSession,
+    exitEmbedFullscreen,
+    forwardEventToParent,
+    hasPlayedOnce,
+    iframeRef,
+    markStreamActive,
+    onEvent,
+    onError,
+    onPurchaseRequest,
+    onReady,
+    onStateChange,
+    postExitFullscreenAckToIframe,
+    storeUrl
+  ]);
   const generateUUID = () => {
     if (self.crypto.randomUUID) return self.crypto.randomUUID();
     const bytes = new Uint8Array(16);
@@ -341,9 +530,8 @@ var PlayruoEmbed = ({
   }, [iframeRef]);
   (0, import_react.useEffect)(() => {
     const handleFullscreenChange = () => {
-      const doc = document;
       const iframe = iframeRef.current;
-      const fullscreenElement = doc.fullscreenElement || doc.webkitFullscreenElement || doc.mozFullScreenElement || doc.msFullscreenElement || null;
+      const fullscreenElement = getFullscreenElement();
       const isEmbedFullscreen = Boolean(iframe && fullscreenElement === iframe);
       if (isEmbedFullscreen) {
         wasEmbedFullscreenRef.current = true;
@@ -360,26 +548,15 @@ var PlayruoEmbed = ({
         return;
       }
       releaseEscapeKeyLock();
+      if (suppressNextFullscreenExitCleanupRef.current) {
+        suppressNextFullscreenExitCleanupRef.current = false;
+        return;
+      }
       if (wasEmbedFullscreenRef.current) {
         wasEmbedFullscreenRef.current = false;
-        if (iframe) {
-          try {
-            iframe.contentWindow?.postMessage({
-              type: "playruo",
-              action: "exitFullscreen",
-              fromEmbed: true,
-              isFullscreen: false,
-              parentWillHandleFullscreen: true
-            }, "*");
-          } catch {
-            console.error("[PlayruoEmbed] Failed to exit fullscreen");
-          }
-        }
-        setShowGameIframe(false);
-        setHasPlayedOnce(true);
-        onDemoCompleted?.({
-          reason: "Demo session ended",
-          storeUrl
+        cleanupEmbedSession({
+          notifyIframe: true,
+          requestFullscreenExit: false
         });
       }
     };
@@ -393,7 +570,13 @@ var PlayruoEmbed = ({
       document.removeEventListener("mozfullscreenchange", handleFullscreenChange);
       document.removeEventListener("MSFullscreenChange", handleFullscreenChange);
     };
-  }, [storeUrl, onDemoCompleted, iframeRef, lockEscapeKey, releaseEscapeKeyLock]);
+  }, [
+    cleanupEmbedSession,
+    getFullscreenElement,
+    iframeRef,
+    lockEscapeKey,
+    releaseEscapeKeyLock
+  ]);
   (0, import_react.useEffect)(() => {
     return () => {
       releaseEscapeKeyLock();
@@ -478,6 +661,8 @@ var PlayruoEmbed = ({
     }
   }, [isReady]);
   const isAvailable = Boolean(isReady && isCompatible && hasIframeConfirmed);
+  const shouldDisplayGameIframe = showGameIframe;
+  const shouldShowIframeMisuseMessage = Boolean(showIframe && !showGameIframe);
   const renderContent = () => {
     if (!renderState) return null;
     const canTryNow = Boolean(
@@ -507,6 +692,26 @@ var PlayruoEmbed = ({
   };
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className, children: [
     renderContent(),
+    isCompatible && shouldShowIframeMisuseMessage && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        role: "status",
+        style: {
+          alignItems: "center",
+          background: "#000",
+          color: "#fff",
+          display: "flex",
+          fontFamily: "system-ui, sans-serif",
+          fontSize: 14,
+          height: "100%",
+          justifyContent: "center",
+          padding: 24,
+          textAlign: "center",
+          width: "100%"
+        },
+        children: "This iframe is only meant to be displayed through PlayruoEmbed during an active stream."
+      }
+    ),
     isCompatible && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       "iframe",
       {
@@ -519,9 +724,9 @@ var PlayruoEmbed = ({
         title: "Playruo",
         referrerPolicy: "strict-origin-when-cross-origin",
         style: {
-          // Only mounted when compatible; visible after click (internal) or if parent explicitly asks
-          opacity: showGameIframe || showIframe ? 1 : 0,
-          pointerEvents: showGameIframe || showIframe ? "auto" : "none",
+          // The iframe stays mounted for readiness checks, visible only during launch/play, and hidden after terminal events.
+          opacity: shouldDisplayGameIframe ? 1 : 0,
+          pointerEvents: shouldDisplayGameIframe ? "auto" : "none",
           width: "100%",
           height: "100%",
           border: 0
@@ -680,6 +885,13 @@ var EmbedTester = (props = {}) => {
       console.error("Embed error:", error);
     }
   }, [addEvent, enableConsoleLog]);
+  const handleEvent = (0, import_react2.useCallback)((data) => {
+    const eventName = typeof data.event === "string" ? data.event : typeof data.name === "string" ? data.name : "unknown";
+    addEvent(`Event received: ${eventName}`);
+    if (enableConsoleLog) {
+      console.log("Embed event:", data);
+    }
+  }, [addEvent, enableConsoleLog]);
   const handlePurchaseRequest = (0, import_react2.useCallback)((data) => {
     addEvent(`\u{1F4B3} Explicit purchase request from Buy Now button`);
     addEvent(`Opening store: ${data.storeUrl}`);
@@ -1627,6 +1839,7 @@ var EmbedTester = (props = {}) => {
                         iframeRef,
                         onDemoCompleted: handleDemoCompleted,
                         onError: handleError,
+                        onEvent: handleEvent,
                         onPurchaseRequest: handlePurchaseRequest,
                         onReady: handleReady,
                         onStateChange: handleStateChange,
@@ -1754,7 +1967,7 @@ var isPlayruoEmbedMessage = (data) => {
   if (!data || typeof data !== "object") return false;
   const msg = data;
   if (typeof msg.type !== "string") return false;
-  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error" || msg.type === "playruo_session_over" || msg.type === "playruo_stream_start" || msg.type === "playruo_stream_stop";
+  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error" || msg.type === "playruo_session_over" || msg.type === "playruo_stream_start" || msg.type === "playruo_stream_stop" || msg.type === "REQUEST_EXIT_FULLSCREEN" || msg.type === "playruo_event";
 };
 var isPlayruoInternalMessage = (data) => {
   if (!data || typeof data !== "object") return false;

package/dist/index.d.cts

@@ -17,6 +17,12 @@ interface DemoCompletedPayload {
     reason?: string;
     storeUrl?: string;
 }
+type PlayruoEventPayload = Record<string, unknown> & {
+    action?: string;
+    category?: string;
+    event?: string;
+    name?: string;
+};
 
 interface PlayruoEmbedActions {
     /** Start the demo session */
@@ -44,10 +50,17 @@ interface PlayruoEmbedProps {
     onReady?: () => void;
     onStateChange?: (state: PlayruoEmbedState) => void;
     onDemoCompleted?: (data: DemoCompletedPayload) => void;
+    onEvent?: (data: PlayruoEventPayload) => void;
     onPurchaseRequest?: (data: {
         storeUrl: string;
     }) => void;
     onError?: (error: string) => void;
+    /**
+     * Forward playruo_event messages to the parent window when the package host
+     * itself is embedded in another iframe. Direct host pages already receive the
+     * original iframe postMessage.
+     */
+    forwardEventsToParent?: boolean;
     /**
      * Single render entry point representing the current status.
      * Provides status, message, and available actions based on current state.
@@ -103,7 +116,14 @@ interface PlayruoStreamStartMessage {
 interface PlayruoStreamStopMessage {
     type: "playruo_stream_stop";
 }
-type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage;
+interface PlayruoRequestExitFullscreenMessage {
+    type: "REQUEST_EXIT_FULLSCREEN";
+}
+interface PlayruoEventMessage {
+    type: "playruo_event";
+    data: PlayruoEventPayload;
+}
+type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage;
 interface PlayruoInternalMessage {
     type: "playruo";
     action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute";
@@ -136,4 +156,4 @@ interface BuildUrlParams {
  */
 declare const buildEmbedUrl: ({ operation, storeUrl }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoInternalMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };
+export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };

package/dist/index.d.ts

@@ -17,6 +17,12 @@ interface DemoCompletedPayload {
     reason?: string;
     storeUrl?: string;
 }
+type PlayruoEventPayload = Record<string, unknown> & {
+    action?: string;
+    category?: string;
+    event?: string;
+    name?: string;
+};
 
 interface PlayruoEmbedActions {
     /** Start the demo session */
@@ -44,10 +50,17 @@ interface PlayruoEmbedProps {
     onReady?: () => void;
     onStateChange?: (state: PlayruoEmbedState) => void;
     onDemoCompleted?: (data: DemoCompletedPayload) => void;
+    onEvent?: (data: PlayruoEventPayload) => void;
     onPurchaseRequest?: (data: {
         storeUrl: string;
     }) => void;
     onError?: (error: string) => void;
+    /**
+     * Forward playruo_event messages to the parent window when the package host
+     * itself is embedded in another iframe. Direct host pages already receive the
+     * original iframe postMessage.
+     */
+    forwardEventsToParent?: boolean;
     /**
      * Single render entry point representing the current status.
      * Provides status, message, and available actions based on current state.
@@ -103,7 +116,14 @@ interface PlayruoStreamStartMessage {
 interface PlayruoStreamStopMessage {
     type: "playruo_stream_stop";
 }
-type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage;
+interface PlayruoRequestExitFullscreenMessage {
+    type: "REQUEST_EXIT_FULLSCREEN";
+}
+interface PlayruoEventMessage {
+    type: "playruo_event";
+    data: PlayruoEventPayload;
+}
+type PlayruoEmbedMessage = PlayruoReadyMessage | PlayruoStateUpdateMessage | PlayruoPurchaseRequestMessage | PlayruoDemoCompletedMessage | PlayruoErrorMessage | PlayruoSessionOverMessage | PlayruoStreamStartMessage | PlayruoStreamStopMessage | PlayruoRequestExitFullscreenMessage | PlayruoEventMessage;
 interface PlayruoInternalMessage {
     type: "playruo";
     action: "tryNowClick" | "exitFullscreen" | "mute" | "unmute";
@@ -136,4 +156,4 @@ interface BuildUrlParams {
  */
 declare const buildEmbedUrl: ({ operation, storeUrl }: BuildUrlParams) => string;
 
-export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoInternalMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };
+export { type DemoCompletedPayload, EmbedTester, type EmbedTesterProps, type PlayruoDemoCompletedMessage, PlayruoEmbed, type PlayruoEmbedActions, type PlayruoEmbedMessage, type PlayruoEmbedProps, type PlayruoEmbedRenderState, type PlayruoEmbedState, type PlayruoErrorMessage, type PlayruoEventMessage, type PlayruoEventPayload, type PlayruoInternalMessage, type PlayruoPurchaseRequestMessage, type PlayruoReadyMessage, type PlayruoRequestExitFullscreenMessage, type PlayruoSessionOverMessage, type PlayruoStateUpdateMessage, type PlayruoStreamStartMessage, type PlayruoStreamStopMessage, buildEmbedUrl, isPlayruoEmbedMessage, isPlayruoInternalMessage };

package/dist/index.js

@@ -34,14 +34,18 @@ var PlayruoEmbed = ({
   onReady,
   onStateChange,
   onDemoCompleted,
+  onEvent,
   onPurchaseRequest,
   onError,
+  forwardEventsToParent = true,
   renderState,
   iframeRef: externalIframeRef
 }) => {
   const internalIframeRef = useRef(null);
   const iframeRef = externalIframeRef || internalIframeRef;
   const wasEmbedFullscreenRef = useRef(false);
+  const hasNotifiedCompletionRef = useRef(false);
+  const suppressNextFullscreenExitCleanupRef = useRef(false);
   const [isIframeLoaded, setIsIframeLoaded] = useState(false);
   const [hasPlayedOnce, setHasPlayedOnce] = useState(false);
   const [showGameIframe, setShowGameIframe] = useState(false);
@@ -111,6 +115,149 @@ var PlayruoEmbed = ({
       console.warn("[PlayruoEmbed] Failed to release Escape key lock:", error);
     }
   }, [getKeyboardApi]);
+  const getFullscreenElement = useCallback(() => {
+    const doc = document;
+    return doc.fullscreenElement || doc.webkitFullscreenElement || doc.mozFullScreenElement || doc.msFullscreenElement || null;
+  }, []);
+  const notifyDemoCompletedOnce = useCallback(
+    (payload) => {
+      if (hasNotifiedCompletionRef.current) {
+        return;
+      }
+      hasNotifiedCompletionRef.current = true;
+      onDemoCompleted?.(
+        payload ?? {
+          reason: "Demo session ended",
+          storeUrl
+        }
+      );
+    },
+    [onDemoCompleted, storeUrl]
+  );
+  const postExitFullscreenToIframe = useCallback(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) {
+      return;
+    }
+    try {
+      iframe.contentWindow?.postMessage({
+        type: "playruo",
+        action: "exitFullscreen",
+        fromEmbed: true,
+        isFullscreen: false,
+        parentWillHandleFullscreen: true
+      }, "*");
+    } catch {
+      console.error("[PlayruoEmbed] Failed to exit fullscreen");
+    }
+  }, [iframeRef]);
+  const postExitFullscreenAckToIframe = useCallback(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) {
+      return;
+    }
+    try {
+      iframe.contentWindow?.postMessage({ type: "ACK_EXIT_FULLSCREEN" }, "*");
+    } catch {
+      console.error("[PlayruoEmbed] Failed to acknowledge fullscreen exit");
+    }
+  }, [iframeRef]);
+  const exitEmbedFullscreen = useCallback(
+    async ({
+      reason = "cleanup",
+      suppressFullscreenExitCleanup = true
+    } = {}) => {
+      const fullscreenElement = getFullscreenElement();
+      const doc = document;
+      const exitFullscreen = doc.exitFullscreen?.bind(doc) ?? doc.webkitExitFullscreen?.bind(doc) ?? doc.mozCancelFullScreen?.bind(doc) ?? doc.msExitFullscreen?.bind(doc);
+      const shouldAttemptExit = Boolean(fullscreenElement || wasEmbedFullscreenRef.current);
+      if (!shouldAttemptExit || !exitFullscreen) {
+        console.log("[PlayruoEmbed] Parent fullscreen exit skipped", {
+          hasFullscreenElement: Boolean(fullscreenElement),
+          hasExitFullscreen: Boolean(exitFullscreen),
+          reason,
+          wasEmbedFullscreen: wasEmbedFullscreenRef.current
+        });
+        return false;
+      }
+      console.log("[PlayruoEmbed] Parent fullscreen exit requested", {
+        fullscreenElement: fullscreenElement?.tagName,
+        reason,
+        wasEmbedFullscreen: wasEmbedFullscreenRef.current
+      });
+      const shouldSuppressFullscreenExitCleanup = Boolean(
+        suppressFullscreenExitCleanup && fullscreenElement
+      );
+      if (shouldSuppressFullscreenExitCleanup) {
+        suppressNextFullscreenExitCleanupRef.current = true;
+        wasEmbedFullscreenRef.current = false;
+      }
+      try {
+        await exitFullscreen();
+        if (shouldSuppressFullscreenExitCleanup) {
+          window.setTimeout(() => {
+            suppressNextFullscreenExitCleanupRef.current = false;
+          }, 1e3);
+        }
+        return true;
+      } catch (error) {
+        if (shouldSuppressFullscreenExitCleanup) {
+          suppressNextFullscreenExitCleanupRef.current = false;
+          wasEmbedFullscreenRef.current = Boolean(getFullscreenElement());
+        }
+        console.warn("[PlayruoEmbed] Failed to leave fullscreen:", error);
+        return false;
+      }
+    },
+    [getFullscreenElement]
+  );
+  const cleanupEmbedSession = useCallback(
+    ({
+      payload,
+      notifyCompletion = true,
+      requestFullscreenExit = true,
+      notifyIframe = false,
+      markPlayed = true
+    } = {}) => {
+      setShowGameIframe(false);
+      if (markPlayed) {
+        setHasPlayedOnce(true);
+      }
+      releaseEscapeKeyLock();
+      if (notifyIframe) {
+        postExitFullscreenToIframe();
+      }
+      if (requestFullscreenExit) {
+        void exitEmbedFullscreen();
+      }
+      if (notifyCompletion) {
+        notifyDemoCompletedOnce(payload);
+      }
+    },
+    [
+      exitEmbedFullscreen,
+      notifyDemoCompletedOnce,
+      postExitFullscreenToIframe,
+      releaseEscapeKeyLock
+    ]
+  );
+  const markStreamActive = useCallback(() => {
+    hasNotifiedCompletionRef.current = false;
+    setShowGameIframe(true);
+  }, []);
+  const forwardEventToParent = useCallback(
+    (message) => {
+      if (!forwardEventsToParent || typeof window === "undefined" || window.parent === window) {
+        return;
+      }
+      try {
+        window.parent.postMessage(message, "*");
+      } catch (error) {
+        console.warn("[PlayruoEmbed] Failed to forward event to parent:", error);
+      }
+    },
+    [forwardEventsToParent]
+  );
   const lockEscapeKey = useCallback(async () => {
     const keyboard = getKeyboardApi();
     if (!keyboard?.lock) {
@@ -147,6 +294,7 @@ var PlayruoEmbed = ({
       console.warn("[PlayruoEmbed] Iframe not ready");
       return;
     }
+    hasNotifiedCompletionRef.current = false;
     setShowGameIframe(true);
     try {
       try {
@@ -170,6 +318,7 @@ var PlayruoEmbed = ({
       setHasPlayedOnce(true);
     } catch (error) {
       console.error("[PlayruoEmbed] Failed to start game:", error);
+      setShowGameIframe(false);
       setErrorMessage("Failed to start game");
       onError?.("Failed to start game");
     }
@@ -193,7 +342,8 @@ var PlayruoEmbed = ({
   }, [isReady, onReady]);
   useEffect(() => {
     const handleGameMessage = (event) => {
-      const { type, data } = event.data || {};
+      const message = event.data || {};
+      const { type, data } = message;
       const iframe = iframeRef.current;
       if (!iframe || event.source !== iframe.contentWindow) {
         return;
@@ -214,8 +364,7 @@ var PlayruoEmbed = ({
         onPurchaseRequest?.(data);
       } else if (type === "playruo_demo_completed" && data) {
         console.log("\u{1F537} [Embed] playruo_demo_completed received:", data);
-        setHasPlayedOnce(true);
-        onDemoCompleted?.(data);
+        cleanupEmbedSession({ payload: data });
       } else if (type === "playruo_error") {
         const errorMessage2 = typeof data === "string" ? data : data?.message || "Unknown error";
         console.log("\u{1F537} [Embed] playruo_error received:", errorMessage2);
@@ -236,25 +385,65 @@ var PlayruoEmbed = ({
         onError?.(errorMessage2);
       } else if (type === "playruo_session_over" && data) {
         console.log("\u{1F537} [Embed] playruo_session_over received:", data);
-        setHasPlayedOnce(true);
+        void exitEmbedFullscreen({ reason: "playruo_session_over" });
         setIframeState(data);
         onStateChange?.(data);
+        cleanupEmbedSession({ requestFullscreenExit: false });
       } else if (type === "playruo_stream_start") {
         console.log("\u{1F537} [Embed] playruo_stream_start received");
+        markStreamActive();
+      } else if (type === "playruo_stream_stop") {
+        console.log("\u{1F537} [Embed] playruo_stream_stop received");
+        void exitEmbedFullscreen({ reason: "playruo_stream_stop" });
+        cleanupEmbedSession({
+          markPlayed: false,
+          notifyCompletion: false,
+          requestFullscreenExit: false
+        });
+      } else if (type === "REQUEST_EXIT_FULLSCREEN") {
+        console.log("\u{1F537} [Embed] REQUEST_EXIT_FULLSCREEN received");
+        void exitEmbedFullscreen({
+          reason: "REQUEST_EXIT_FULLSCREEN",
+          suppressFullscreenExitCleanup: false
+        }).finally(postExitFullscreenAckToIframe);
+      } else if (type === "playruo_event" && data && typeof data === "object") {
+        console.log("\u{1F537} [Embed] playruo_event received:", data);
+        const eventPayload = data;
+        onEvent?.(eventPayload);
+        forwardEventToParent({ type: "playruo_event", data: eventPayload });
+      } else if (type === "playruo" && message.action === "event" && message.payload && typeof message.payload === "object") {
+        console.log("\u{1F537} [Embed] legacy playruo event received:", message.payload);
+        const eventPayload = message.payload;
+        onEvent?.(eventPayload);
+        forwardEventToParent({ type: "playruo_event", data: eventPayload });
       }
       if (type === "error" || type === "closeForBuy" || type === "goToStore") {
         console.log("\u{1F537} [Embed] Legacy message received:", type);
-        setHasPlayedOnce(true);
-        const payload = {
-          reason: "Demo session ended",
-          storeUrl
-        };
-        onDemoCompleted?.(payload);
+        cleanupEmbedSession({
+          payload: {
+            reason: "Demo session ended",
+            storeUrl
+          }
+        });
       }
     };
     window.addEventListener("message", handleGameMessage);
     return () => window.removeEventListener("message", handleGameMessage);
-  }, [storeUrl, onDemoCompleted, onReady, onStateChange, onPurchaseRequest, onError, iframeRef]);
+  }, [
+    cleanupEmbedSession,
+    exitEmbedFullscreen,
+    forwardEventToParent,
+    hasPlayedOnce,
+    iframeRef,
+    markStreamActive,
+    onEvent,
+    onError,
+    onPurchaseRequest,
+    onReady,
+    onStateChange,
+    postExitFullscreenAckToIframe,
+    storeUrl
+  ]);
   const generateUUID = () => {
     if (self.crypto.randomUUID) return self.crypto.randomUUID();
     const bytes = new Uint8Array(16);
@@ -301,9 +490,8 @@ var PlayruoEmbed = ({
   }, [iframeRef]);
   useEffect(() => {
     const handleFullscreenChange = () => {
-      const doc = document;
       const iframe = iframeRef.current;
-      const fullscreenElement = doc.fullscreenElement || doc.webkitFullscreenElement || doc.mozFullScreenElement || doc.msFullscreenElement || null;
+      const fullscreenElement = getFullscreenElement();
       const isEmbedFullscreen = Boolean(iframe && fullscreenElement === iframe);
       if (isEmbedFullscreen) {
         wasEmbedFullscreenRef.current = true;
@@ -320,26 +508,15 @@ var PlayruoEmbed = ({
         return;
       }
       releaseEscapeKeyLock();
+      if (suppressNextFullscreenExitCleanupRef.current) {
+        suppressNextFullscreenExitCleanupRef.current = false;
+        return;
+      }
       if (wasEmbedFullscreenRef.current) {
         wasEmbedFullscreenRef.current = false;
-        if (iframe) {
-          try {
-            iframe.contentWindow?.postMessage({
-              type: "playruo",
-              action: "exitFullscreen",
-              fromEmbed: true,
-              isFullscreen: false,
-              parentWillHandleFullscreen: true
-            }, "*");
-          } catch {
-            console.error("[PlayruoEmbed] Failed to exit fullscreen");
-          }
-        }
-        setShowGameIframe(false);
-        setHasPlayedOnce(true);
-        onDemoCompleted?.({
-          reason: "Demo session ended",
-          storeUrl
+        cleanupEmbedSession({
+          notifyIframe: true,
+          requestFullscreenExit: false
         });
       }
     };
@@ -353,7 +530,13 @@ var PlayruoEmbed = ({
       document.removeEventListener("mozfullscreenchange", handleFullscreenChange);
       document.removeEventListener("MSFullscreenChange", handleFullscreenChange);
     };
-  }, [storeUrl, onDemoCompleted, iframeRef, lockEscapeKey, releaseEscapeKeyLock]);
+  }, [
+    cleanupEmbedSession,
+    getFullscreenElement,
+    iframeRef,
+    lockEscapeKey,
+    releaseEscapeKeyLock
+  ]);
   useEffect(() => {
     return () => {
       releaseEscapeKeyLock();
@@ -438,6 +621,8 @@ var PlayruoEmbed = ({
     }
   }, [isReady]);
   const isAvailable = Boolean(isReady && isCompatible && hasIframeConfirmed);
+  const shouldDisplayGameIframe = showGameIframe;
+  const shouldShowIframeMisuseMessage = Boolean(showIframe && !showGameIframe);
   const renderContent = () => {
     if (!renderState) return null;
     const canTryNow = Boolean(
@@ -467,6 +652,26 @@ var PlayruoEmbed = ({
   };
   return /* @__PURE__ */ jsxs("div", { className, children: [
     renderContent(),
+    isCompatible && shouldShowIframeMisuseMessage && /* @__PURE__ */ jsx(
+      "div",
+      {
+        role: "status",
+        style: {
+          alignItems: "center",
+          background: "#000",
+          color: "#fff",
+          display: "flex",
+          fontFamily: "system-ui, sans-serif",
+          fontSize: 14,
+          height: "100%",
+          justifyContent: "center",
+          padding: 24,
+          textAlign: "center",
+          width: "100%"
+        },
+        children: "This iframe is only meant to be displayed through PlayruoEmbed during an active stream."
+      }
+    ),
     isCompatible && /* @__PURE__ */ jsx(
       "iframe",
       {
@@ -479,9 +684,9 @@ var PlayruoEmbed = ({
         title: "Playruo",
         referrerPolicy: "strict-origin-when-cross-origin",
         style: {
-          // Only mounted when compatible; visible after click (internal) or if parent explicitly asks
-          opacity: showGameIframe || showIframe ? 1 : 0,
-          pointerEvents: showGameIframe || showIframe ? "auto" : "none",
+          // The iframe stays mounted for readiness checks, visible only during launch/play, and hidden after terminal events.
+          opacity: shouldDisplayGameIframe ? 1 : 0,
+          pointerEvents: shouldDisplayGameIframe ? "auto" : "none",
           width: "100%",
           height: "100%",
           border: 0
@@ -640,6 +845,13 @@ var EmbedTester = (props = {}) => {
       console.error("Embed error:", error);
     }
   }, [addEvent, enableConsoleLog]);
+  const handleEvent = useCallback2((data) => {
+    const eventName = typeof data.event === "string" ? data.event : typeof data.name === "string" ? data.name : "unknown";
+    addEvent(`Event received: ${eventName}`);
+    if (enableConsoleLog) {
+      console.log("Embed event:", data);
+    }
+  }, [addEvent, enableConsoleLog]);
   const handlePurchaseRequest = useCallback2((data) => {
     addEvent(`\u{1F4B3} Explicit purchase request from Buy Now button`);
     addEvent(`Opening store: ${data.storeUrl}`);
@@ -1587,6 +1799,7 @@ var EmbedTester = (props = {}) => {
                         iframeRef,
                         onDemoCompleted: handleDemoCompleted,
                         onError: handleError,
+                        onEvent: handleEvent,
                         onPurchaseRequest: handlePurchaseRequest,
                         onReady: handleReady,
                         onStateChange: handleStateChange,
@@ -1714,7 +1927,7 @@ var isPlayruoEmbedMessage = (data) => {
   if (!data || typeof data !== "object") return false;
   const msg = data;
   if (typeof msg.type !== "string") return false;
-  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error" || msg.type === "playruo_session_over" || msg.type === "playruo_stream_start" || msg.type === "playruo_stream_stop";
+  return msg.type === "playruo_ready" || msg.type === "playruo_state_update" || msg.type === "playruo_purchase_request" || msg.type === "playruo_demo_completed" || msg.type === "playruo_error" || msg.type === "playruo_session_over" || msg.type === "playruo_stream_start" || msg.type === "playruo_stream_stop" || msg.type === "REQUEST_EXIT_FULLSCREEN" || msg.type === "playruo_event";
 };
 var isPlayruoInternalMessage = (data) => {
   if (!data || typeof data !== "object") return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playruo/embed",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "React SDK to embed Playruo with postMessage API.",
   "license": "MIT",
   "type": "module",