release: v4.4.3

CHANGELOG.md

@@ -1,12 +1,55 @@
 # Changelog
 
-## [v4.4.2](https://github.com/contentstack/live-preview-sdk/compare/v4.4.2...v4.4.2)
+## [v4.4.3](https://github.com/contentstack/live-preview-sdk/compare/v4.4.2...v4.4.3)
+
+> 29 May 2026
+
+### New Features
+
+- feat(VB-1583): restrict toolbar actions for multiple custom field instances (Hitesh Shetty - [#593](https://github.com/contentstack/live-preview-sdk/pull/593))
+
+### Fixes
+
+- fix: added changes of new tab init related remaining code (Mridul Sharma - [#597](https://github.com/contentstack/live-preview-sdk/pull/597))
+
+### Changes to Test Assests
+
+- test: added test cases of useCollab / preview share (Mridul Sharma - [#595](https://github.com/contentstack/live-preview-sdk/pull/595))
+- test: added unit test cases fo visual builder specific to mode (Mridul Sharma - [#592](https://github.com/contentstack/live-preview-sdk/pull/592))
+- test: added test cases for post message hook (Mridul Sharma - [#591](https://github.com/contentstack/live-preview-sdk/pull/591))
+
+### General Changes
+
+- release: 4.4.2 (Hitesh Shetty - [#596](https://github.com/contentstack/live-preview-sdk/pull/596))
+
+### New Features
+
+- feat(VB-1583): suppress hover and click interactions for multiple custom field instances (hitesh-shetty-cstk - [8119684](https://github.com/contentstack/live-preview-sdk/commit/81196845e2c01b3ca023ddae575cb3d67d21bd4f))
+- feat(VB-1623): extend overlayPropagation to standalone Live Preview Edit button (hitesh-shetty-cstk - [f402b41](https://github.com/contentstack/live-preview-sdk/commit/f402b41b69454a59a9a6c143b698d06d5ab1459f))
+- feat(visual-builder): add overlayPropagation init flag for cslp hover/click (hitesh-shetty-cstk - [aa57ba9](https://github.com/contentstack/live-preview-sdk/commit/aa57ba951081a2726122fa9d0fd489a65bb7bdee))
+- feat(VB-1623): extend overlayPropagation to standalone Live Preview Edit button (hitesh-shetty-cstk - [be27497](https://github.com/contentstack/live-preview-sdk/commit/be27497b69e7a08f95c5ec96ffddf11e22b35029))
+
+### Fixes
+
+- fix(isCustomFieldMultipleInstance): handle optional chaining for instance fieldPathWithIndex (hitesh-shetty-cstk - [f0219d7](https://github.com/contentstack/live-preview-sdk/commit/f0219d72b31c8e06b2a93185a20cde791a157667))
+- fix: update CDN version to 4.4.2 in README (hitesh-shetty-cstk - [892a9c8](https://github.com/contentstack/live-preview-sdk/commit/892a9c8ba169a02830a311394a9a2a88a39d6c76))
+- fix(editButton): increase throttle delay for overlay mouse move handler (hitesh-shetty-cstk - [55532b2](https://github.com/contentstack/live-preview-sdk/commit/55532b22a7c1a9ba47538a23945c3b25a0c83fdd))
+
+### Documentation Changes
+
+- docs: clarify overlayPropagation functionality for hover/click detection (hitesh-shetty-cstk - [e88aee3](https://github.com/contentstack/live-preview-sdk/commit/e88aee3602a03e093751178bc10c5ce85e694e20))
+- docs(main.mustache): add overlayPropagation entry to config list (hitesh-shetty-cstk - [b30f41f](https://github.com/contentstack/live-preview-sdk/commit/b30f41f6b1bb86a36bc5ea2bfcc3d76cb3061e43))
+
+### Refactoring and Updates
+
+- refactor(VB-1583): redirect custom field instances to whole-field parent via closest() (hitesh-shetty-cstk - [15f10ed](https://github.com/contentstack/live-preview-sdk/commit/15f10ed90ad0b95759833d549659cc12ab38ffc6))
+
+## [v4.4.2](https://github.com/contentstack/live-preview-sdk/compare/v4.4.1...v4.4.2)
 
 > 21 May 2026
 
 ### Fixes
 
-- fix: update CDN version to 4.4.2 in README (hitesh-shetty-cstk - [11bf951](https://github.com/contentstack/live-preview-sdk/commit/11bf9511a5deb7fb009ba9c01310504755a5f17c))
 - fix(hover): guard generateCursor to fire only on new element hover (Hitesh Shetty - [#590](https://github.com/contentstack/live-preview-sdk/pull/590))
 - fix(VB-1541): hide field extension and comment icons on update-restricted fields (Sahil Chalke - [#589](https://github.com/contentstack/live-preview-sdk/pull/589))
 - fix(security): bump dompurify from ^3.4.0 to ^3.4.1 (Hitesh Shetty - [#588](https://github.com/contentstack/live-preview-sdk/pull/588))

README.md

@@ -29,11 +29,11 @@ npm install @contentstack/live-preview-utils
 
 ### Load from a CDN (advanced)
 
-Pin the version to match your app (update `4.4.2` when you upgrade):
+Pin the version to match your app (update `4.4.3` when you upgrade):
 
 ```html
 <script type="module" crossorigin="anonymous">
-  import ContentstackLivePreview from "https://esm.sh/@contentstack/live-preview-utils@4.4.2";
+  import ContentstackLivePreview from "https://esm.sh/@contentstack/live-preview-utils@4.4.3";
 
   ContentstackLivePreview.init({
     stackDetails: {
@@ -71,6 +71,7 @@ You can configure the SDK using the following options:
 - [`mode`](docs/live-preview-configs.md#mode) (`preview` vs `builder`)
 - [`editButton`](docs/live-preview-configs.md#editbutton)
 - [`editInVisualBuilderButton`](docs/live-preview-configs.md#editinvisualbuilderbutton) (Start Editing outside Visual Editor)
+- [`overlayPropagation`](docs/live-preview-configs.md#overlaypropagation) (opt-in fallback to pierce blocking sibling overlays during hover/click detection)
 - [`cleanCslpOnProduction`](docs/live-preview-configs.md#cleancslponproduction)
 - [`stackDetails`](docs/live-preview-configs.md#stackdetails) ([`apiKey`](docs/live-preview-configs.md#apikey), [`environment`](docs/live-preview-configs.md#environment))
 - [`clientUrlParams`](docs/live-preview-configs.md#clienturlparams) — [NA](docs/live-preview-configs.md#na-config) / [EU](docs/live-preview-configs.md#eu-config)

docs/live-preview-configs.md

@@ -145,6 +145,33 @@ The editInVisualBuilderButton object contains two keys:
     The user can place the "Start Editing" button in four predefined positions 
     top-left, top-right, bottom-left, and bottom-right.
 
+### `overlayPropagation`
+
+Use this option when hovering or clicking on a field in your app does nothing — no outline appears and the Edit button doesn't show up. This typically happens when another element (such as a navigation overlay, image layer, or layout spacer) sits on top of the field and captures the mouse event instead.
+
+Enabling `overlayPropagation` tells the SDK to look through stacked elements at the cursor position to find the field underneath. It works in both Visual Builder and the standalone Live Preview Edit button.
+
+> **When to enable:** Only turn this on if you notice fields that are invisible to hover/click in your specific app layout. It is off by default.
+
+The `overlayPropagation` object contains one key:
+
+1. #### `enable`
+    | type    | default | optional |
+    | ------- | ------- | -------- |
+    | boolean | false   | yes      |
+
+    Set to `true` to allow the SDK to detect fields that are visually covered by other elements.
+
+**For example:**
+```ts
+ContentstackLivePreview.init({
+    ...
+    overlayPropagation: {
+        enable: true,
+    }
+});
+```
+
 ### `cleanCslpOnProduction`
 
 | type    | default | optional |

main.mustache

@@ -71,6 +71,7 @@ You can configure the SDK using the following options:
 - [`mode`](docs/live-preview-configs.md#mode) (`preview` vs `builder`)
 - [`editButton`](docs/live-preview-configs.md#editbutton)
 - [`editInVisualBuilderButton`](docs/live-preview-configs.md#editinvisualbuilderbutton) (Start Editing outside Visual Editor)
+- [`overlayPropagation`](docs/live-preview-configs.md#overlaypropagation) (opt-in fallback to pierce blocking sibling overlays during hover/click detection)
 - [`cleanCslpOnProduction`](docs/live-preview-configs.md#cleancslponproduction)
 - [`stackDetails`](docs/live-preview-configs.md#stackdetails) ([`apiKey`](docs/live-preview-configs.md#apikey), [`environment`](docs/live-preview-configs.md#environment))
 - [`clientUrlParams`](docs/live-preview-configs.md#clienturlparams) — [NA](docs/live-preview-configs.md#na-config) / [EU](docs/live-preview-configs.md#eu-config)

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@contentstack/live-preview-utils",
-    "version": "4.4.2",
+    "version": "4.4.3",
     "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/__test__/data/fields.ts

@@ -50,3 +50,29 @@ export const mockMultipleFileFieldSchema: ISchemaFieldMap = {
     non_localizable: false,
     unique: false,
 };
+
+export const mockMultipleCustomFieldSchema: ISchemaFieldMap = {
+    extension_uid: "test_extension_uid",
+    field_metadata: { extension: true },
+    config: {},
+    data_type: "number",
+    display_name: "Custom Field",
+    uid: "custom_field",
+    mandatory: false,
+    multiple: true,
+    non_localizable: false,
+    unique: false,
+} as unknown as ISchemaFieldMap;
+
+export const mockSingleCustomFieldSchema: ISchemaFieldMap = {
+    extension_uid: "test_extension_uid",
+    field_metadata: { extension: true },
+    config: {},
+    data_type: "number",
+    display_name: "Custom Field",
+    uid: "custom_field",
+    mandatory: false,
+    multiple: false,
+    non_localizable: false,
+    unique: false,
+} as unknown as ISchemaFieldMap;

src/common/__test__/inIframe.test.ts

@@ -1,4 +1,7 @@
-import { inIframe } from "../inIframe";
+import { inIframe, isOpeningInNewTab } from "../inIframe";
+import { hasWindow } from "../../utils";
+
+vi.mock("../../utils", () => ({ hasWindow: vi.fn() }));
 
 describe("inIframe", () => {
     let windowSpy: any;
@@ -39,3 +42,39 @@ describe("inIframe", () => {
         expect(inIframe()).toBe(true);
     });
 });
+
+describe("isOpeningInNewTab", () => {
+    let windowSpy: any;
+
+    beforeEach(() => {
+        vi.mocked(hasWindow).mockReturnValue(true);
+        windowSpy = vi.spyOn(window, "window", "get");
+    });
+
+    afterEach(() => {
+        windowSpy.mockRestore();
+        vi.mocked(hasWindow).mockReset();
+    });
+
+    test("should return true when window.opener is truthy", () => {
+        windowSpy.mockReturnValue({ opener: {} });
+        expect(isOpeningInNewTab()).toBe(true);
+    });
+
+    test("should return false when window.opener is null", () => {
+        windowSpy.mockReturnValue({ opener: null });
+        expect(isOpeningInNewTab()).toBe(false);
+    });
+
+    test("should return false when hasWindow returns false", () => {
+        vi.mocked(hasWindow).mockReturnValue(false);
+        expect(isOpeningInNewTab()).toBe(false);
+    });
+
+    test("should return false when accessing window throws", () => {
+        windowSpy.mockImplementation(() => {
+            throw new Error("Test error");
+        });
+        expect(isOpeningInNewTab()).toBe(false);
+    });
+});

src/configManager/__test__/handleUserConfig.test.ts

@@ -409,6 +409,69 @@ describe("handleInitData()", () => {
             expect(config.editButton.includeByQueryParameter).toBe(false);
         });
     });
+
+    describe("handleInitData() - overlayPropagation configuration", () => {
+        let config: DeepSignal<IConfig>;
+
+        beforeEach(() => {
+            Config.reset();
+            config = Config.get();
+        });
+
+        afterAll(() => {
+            Config.reset();
+        });
+
+        test("should default overlayPropagation.enable to false when not provided", () => {
+            handleInitData({});
+            expect(config.overlayPropagation.enable).toBe(false);
+        });
+
+        test("should set overlayPropagation.enable from initData when true", () => {
+            const initData: Partial<IInitData> = {
+                overlayPropagation: { enable: true },
+            };
+
+            handleInitData(initData);
+            expect(config.overlayPropagation.enable).toBe(true);
+        });
+
+        test("should keep overlayPropagation.enable false when initData sets it false explicitly", () => {
+            const initData: Partial<IInitData> = {
+                overlayPropagation: { enable: false },
+            };
+
+            handleInitData(initData);
+            expect(config.overlayPropagation.enable).toBe(false);
+        });
+
+        test("should set overlayPropagation.enable from stackSdk when initData does not provide it", () => {
+            const initData: Partial<IInitData> = {
+                stackSdk: {
+                    live_preview: {
+                        overlayPropagation: { enable: true },
+                    },
+                } as any,
+            };
+
+            handleInitData(initData);
+            expect(config.overlayPropagation.enable).toBe(true);
+        });
+
+        test("initData overlayPropagation takes precedence over stackSdk", () => {
+            const initData: Partial<IInitData> = {
+                overlayPropagation: { enable: false },
+                stackSdk: {
+                    live_preview: {
+                        overlayPropagation: { enable: true },
+                    },
+                } as any,
+            };
+
+            handleInitData(initData);
+            expect(config.overlayPropagation.enable).toBe(false);
+        });
+    });
 });
 
 describe("handleInitData() - enableLivePreviewOutsideIframe", () => {

src/configManager/config.default.ts

@@ -20,6 +20,9 @@ export function getUserInitData(): IInitData {
             enable: true,
             position: "bottom-right"
         },
+        overlayPropagation: {
+            enable: false,
+        },
 
         mode: "preview",
 
@@ -59,6 +62,9 @@ export function getDefaultConfig(): IConfig {
             enable: true,
             position: "bottom-right"
         },
+        overlayPropagation: {
+            enable: false,
+        },
 
         hash: "",
         mode: 1,

src/configManager/handleUserConfig.ts

@@ -114,13 +114,20 @@ export const handleInitData = (initData: Partial<IInitData>): void => {
             initData.editInVisualBuilderButton?.enable ??
             stackSdk.live_preview?.editInVisualBuilderButton?.enable ??
             config.editInVisualBuilderButton.enable,
-        position:  
+        position:
             initData.editInVisualBuilderButton?.position ??
             stackSdk.live_preview?.position ??
             config.editInVisualBuilderButton.position ??
             "bottom-right",
     })
 
+    Config.set("overlayPropagation", {
+        enable:
+            initData.overlayPropagation?.enable ??
+            stackSdk.live_preview?.overlayPropagation?.enable ??
+            config.overlayPropagation.enable,
+    });
+
     Config.set(
         "enableLivePreviewOutsideIframe",
         initData.enableLivePreviewOutsideIframe ??