added enableLivePreviewOutsideIframe key to on or off the outside iframe feature by default

README.md

@@ -16,7 +16,7 @@ Alternatively, if you want to include the package directly in your website HTML
 
 ```html
 <script type='module' crossorigin="anonymous">
-     import ContentstackLivePreview from 'https://esm.sh/@contentstack/live-preview-utils@4.1.2';
+     import ContentstackLivePreview from 'https://esm.sh/@contentstack/live-preview-utils@4.3.0';
 
      ContentstackLivePreview.init({
         stackDetails: {
@@ -51,7 +51,7 @@ ContentstackLivePreview.init({
 
 MIT License
 
-Copyright © 2021-2025 [Contentstack](https://www.contentstack.com/). All Rights Reserved
+Copyright © 2021-2026 [Contentstack](https://www.contentstack.com/). All Rights Reserved
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@contentstack/live-preview-utils",
-    "version": "4.1.2",
+    "version": "4.3.0",
     "description": "Contentstack provides the Live Preview SDK to establish a communication channel between the various Contentstack SDKs and your website, transmitting  live changes to the preview pane.",
     "type": "module",
     "types": "dist/legacy/index.d.ts",

src/configManager/__test__/configManager.test.ts

@@ -1,5 +1,5 @@
 import Config, { updateConfigFromUrl } from "../configManager";
-import { getDefaultConfig } from "../config.default";
+import { getDefaultConfig, getUserInitData } from "../config.default";
 import { DeepSignal } from "deepsignal";
 import { IConfig } from "../../types/types";
 
@@ -90,6 +90,18 @@ describe("Config", () => {
     });
 });
 
+describe("config default flags", () => {
+    test("enableLivePreviewOutsideIframe defaults to undefined in getDefaultConfig", () => {
+        const defaultConfig = getDefaultConfig();
+        expect(defaultConfig.enableLivePreviewOutsideIframe).toBeUndefined();
+    });
+
+    test("enableLivePreviewOutsideIframe defaults to undefined in getUserInitData", () => {
+        const initData = getUserInitData();
+        expect(initData.enableLivePreviewOutsideIframe).toBeUndefined();
+    });
+});
+
 describe("update config from url", () => {
     let config: DeepSignal<IConfig>;
 

src/configManager/__test__/handleUserConfig.test.ts

@@ -411,6 +411,41 @@ describe("handleInitData()", () => {
     });
 });
 
+describe("handleInitData() - enableLivePreviewOutsideIframe", () => {
+    let config: DeepSignal<IConfig>;
+
+    beforeEach(() => {
+        Config.reset();
+        config = Config.get();
+    });
+
+    afterAll(() => {
+        Config.reset();
+    });
+
+    test("should default to undefined when not provided", () => {
+        const initData: Partial<IInitData> = {};
+        handleInitData(initData);
+        expect(config.enableLivePreviewOutsideIframe).toBeUndefined();
+    });
+
+    test("should set to true when provided as true", () => {
+        const initData: Partial<IInitData> = {
+            enableLivePreviewOutsideIframe: true,
+        };
+        handleInitData(initData);
+        expect(config.enableLivePreviewOutsideIframe).toBe(true);
+    });
+
+    test("should remain false when provided as false", () => {
+        const initData: Partial<IInitData> = {
+            enableLivePreviewOutsideIframe: false,
+        };
+        handleInitData(initData);
+        expect(config.enableLivePreviewOutsideIframe).toBe(false);
+    });
+});
+
 describe("handleClientUrlParams()", () => {
     let config: DeepSignal<IConfig>;
 

src/configManager/config.default.ts

@@ -39,6 +39,7 @@ export function getUserInitData(): IInitData {
             environment: "",
         },
         runScriptsOnUpdate: false,
+        enableLivePreviewOutsideIframe: undefined,
     };
 }
 
@@ -110,5 +111,6 @@ export function getDefaultConfig(): IConfig {
             },
             payload: [],
         },
+        enableLivePreviewOutsideIframe: undefined,
     };
 }

src/configManager/handleUserConfig.ts

@@ -121,6 +121,12 @@ export const handleInitData = (initData: Partial<IInitData>): void => {
             "bottom-right",
     })
 
+    Config.set(
+        "enableLivePreviewOutsideIframe",
+        initData.enableLivePreviewOutsideIframe ??
+            config.enableLivePreviewOutsideIframe
+    );
+
     // client URL params
     handleClientUrlParams(
         initData.clientUrlParams ??

src/livePreview/eventManager/__test__/postMessageEvent.hooks.test.ts

@@ -15,13 +15,15 @@ import {
 import {
     useOnEntryUpdatePostMessageEvent,
     useHistoryPostMessageEvent,
+    sendInitializeLivePreviewPostMessageEvent,
 } from "../postMessageEvent.hooks";
 import { isOpeningInNewTab } from "../../../common/inIframe";
 
 // Mock dependencies
 vi.mock("../../../configManager/configManager", () => ({
     default: {
         get: vi.fn(),
+        set: vi.fn(),
     },
     setConfigFromParams: vi.fn(),
 }));
@@ -35,13 +37,19 @@ vi.mock("../../../logger/logger", () => ({
 vi.mock("../livePreviewEventManager", () => ({
     default: {
         on: vi.fn(),
+        send: vi.fn(),
     },
 }));
 
 vi.mock("../../../common/inIframe", () => ({
     isOpeningInNewTab: vi.fn(),
 }));
 
+vi.mock("../../../utils", () => ({
+    addParamsToUrl: vi.fn(),
+    isOpeningInTimeline: vi.fn(() => false),
+}));
+
 describe("postMessageEvent.hooks", () => {
     let mockWindow: any;
     let mockConfig: any;
@@ -415,4 +423,73 @@ describe("postMessageEvent.hooks", () => {
             }).toThrow("Unhandled event: unknown");
         });
     });
+
+    describe("sendInitializeLivePreviewPostMessageEvent", () => {
+        beforeEach(() => {
+            // default send resolves with preview windowType, no contentType/entry to avoid side-effects
+            (livePreviewPostMessage as any).send.mockResolvedValue({
+                windowType: "preview",
+            });
+        });
+
+        it("should omit enableLivePreviewOutsideIframe in INIT payload when config is unset", async () => {
+            mockConfig = {
+                ssr: true,
+                mode: 1,
+                enableLivePreviewOutsideIframe: undefined,
+            };
+            (Config.get as any).mockReturnValue(mockConfig);
+
+            await sendInitializeLivePreviewPostMessageEvent();
+            await Promise.resolve();
+
+            const initPayload = (livePreviewPostMessage?.send as any).mock.calls.at(-1)?.[1];
+            expect(initPayload.config).not.toHaveProperty(
+                "enableLivePreviewOutsideIframe"
+            );
+        });
+
+        it("should include enableLivePreviewOutsideIframe=false in INIT payload", async () => {
+            mockConfig = {
+                ssr: true, // avoid timers
+                mode: 1,
+                enableLivePreviewOutsideIframe: false,
+            };
+            (Config.get as any).mockReturnValue(mockConfig);
+
+            await sendInitializeLivePreviewPostMessageEvent();
+            // allow microtasks to flush
+            await Promise.resolve();
+
+            expect(livePreviewPostMessage?.send).toHaveBeenCalledWith(
+                LIVE_PREVIEW_POST_MESSAGE_EVENTS.INIT,
+                expect.objectContaining({
+                    config: expect.objectContaining({
+                        enableLivePreviewOutsideIframe: false,
+                    }),
+                })
+            );
+        });
+
+        it("should include enableLivePreviewOutsideIframe=true in INIT payload", async () => {
+            mockConfig = {
+                ssr: true, // avoid timers
+                mode: 1,
+                enableLivePreviewOutsideIframe: true,
+            };
+            (Config.get as any).mockReturnValue(mockConfig);
+
+            await sendInitializeLivePreviewPostMessageEvent();
+            await Promise.resolve();
+
+            expect(livePreviewPostMessage?.send).toHaveBeenCalledWith(
+                LIVE_PREVIEW_POST_MESSAGE_EVENTS.INIT,
+                expect.objectContaining({
+                    config: expect.objectContaining({
+                        enableLivePreviewOutsideIframe: true,
+                    }),
+                })
+            );
+        });
+    });
 });

src/livePreview/eventManager/postMessageEvent.hooks.ts

@@ -119,16 +119,29 @@ export function useOnEntryUpdatePostMessageEvent(): void {
 }
 
 export function sendInitializeLivePreviewPostMessageEvent(): void {
+    const config = Config.get();
+    const initConfig: {
+        shouldReload: boolean;
+        href: string;
+        sdkVersion: string | undefined;
+        mode: number;
+        enableLivePreviewOutsideIframe?: boolean;
+    } = {
+        shouldReload: config.ssr,
+        href: window.location.href,
+        sdkVersion: process?.env?.PACKAGE_VERSION,
+        mode: config.mode,
+    };
+
+    if (config.enableLivePreviewOutsideIframe !== undefined) {
+        initConfig.enableLivePreviewOutsideIframe = config.enableLivePreviewOutsideIframe;
+    }
+
     livePreviewPostMessage
         ?.send<LivePreviewInitEventResponse>(
             LIVE_PREVIEW_POST_MESSAGE_EVENTS.INIT,
             {
-                config: {
-                    shouldReload: Config.get().ssr,
-                    href: window.location.href,
-                    sdkVersion: process?.env?.PACKAGE_VERSION,
-                    mode: Config.get().mode,
-                },
+                config: initConfig,
             }
         )
         .then((data) => {

src/types/types.ts

@@ -87,6 +87,7 @@ export declare interface IConfig {
         highlightedElement: HTMLElement | null;
     };
     collab: ICollabConfig["collab"];
+    enableLivePreviewOutsideIframe: boolean | undefined;
 }
 
 
@@ -132,6 +133,7 @@ export declare interface IInitData {
     editButton: IConfigEditButton;
     editInVisualBuilderButton: IConfigEditInVisualBuilderButton;
     mode: ILivePreviewMode;
+    enableLivePreviewOutsideIframe: boolean | undefined; // default: undefined
 }
 
 // type PickPartial<T, K extends keyof T> = Partial<Pick<T, K>> & Omit<T, K>;