Release v4.4.4

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.3` when you upgrade):
+Pin the version to match your app (update `4.4.4` when you upgrade):
 
 ```html
 <script type="module" crossorigin="anonymous">
-  import ContentstackLivePreview from "https://esm.sh/@contentstack/live-preview-utils@4.4.3";
+  import ContentstackLivePreview from "https://esm.sh/@contentstack/live-preview-utils@4.4.4";
 
   ContentstackLivePreview.init({
     stackDetails: {
@@ -84,6 +84,7 @@ Full tables and examples: **[docs/live-preview-configs.md](docs/live-preview-con
 - [`onLiveEdit`](docs/live-preview-configs.md#onliveeditcallback---void): Trigger actions on live edits
 - [`onEntryChange`](docs/live-preview-configs.md#onentrychangecallback---void): Listen for entry updates
 - [`hash`](docs/live-preview-configs.md#hash): Access preview state identifier
+- [`setPageContext`](docs/live-preview-configs.md#setpagecontextcontext): Tell Visual Builder which entry the current page renders so “Start Editing” targets the right entry (needed for custom-URL pages)
 - [`config`](docs/live-preview-configs.md#config): Includes runtime context (for example Live Preview / Timeline preview, Visual Editor, or independent)
 
 The [configs table of contents](docs/live-preview-configs.md#contentstack-live-preview-utils-sdk-configs) also lists `setConfigFromParams` and `getGatsbyDataFormat` for deeper workflows.

docs/live-preview-configs.md

@@ -18,6 +18,7 @@ The init data has following structure
         -   [`stackSdk`](#stacksdk)
     -   [`onLiveEdit(callback: () => void)`](#onliveeditcallback---void)
     -   [`onEntryChange(callback: () => void)`](#onentrychangecallback---void)
+    -   [`setPageContext(context)`](#setpagecontextcontext)
     -   [hash](#hash)
     -   [setConfigFromParams(config: ConstructorParameters\[0\])](#setconfigfromparamsconfig-constructorparameters0)
     -   [`getGatsbyDataFormat(sdkQuery: IStackSdk, prefix: string)`](#getgatsbydataformatsdkquery-istacksdk-prefix-string)
@@ -323,6 +324,62 @@ const Footer = () => {
 onEntryChange(fetchData, { skipInitialRender: true });
 ```
 
+## `setPageContext(context)`
+
+```ts
+setPageContext(context: { entryUid: string; contentTypeUid: string }): void
+```
+
+The `setPageContext()` method tells the Visual Builder which entry the current page is rendering. The Visual Builder uses this context so that the **"Start Editing"** button (and the `init` handshake) target the correct entry, even when a page is served from a custom URL that the SDK cannot map to an entry on its own.
+
+This context is used in two places: on the initial `init` handshake, so the Visual Builder can confirm whether the entry it has open matches the page rendered in the iframe; and on the "Start Editing" button click, so it can navigate to the correct entry in the Visual Editor. Because `init()` runs before your async data fetch resolves, the handshake may carry no entry context on its own — calling `setPageContext()` once your entry is available sends the context to the Visual Builder so it can update its current entry.
+
+Place the call alongside your existing `addEditableTags` call — both reference the same `entry` object, so there is no extra lookup.
+
+| parameter             | type     | description                                       |
+| --------------------- | -------- | ------------------------------------------------- |
+| `context.entryUid`    | string   | UID of the entry the current page is rendering.   |
+| `context.contentTypeUid` | string | UID of that entry's content type.               |
+
+**For example:**
+
+```js
+import ContentstackLivePreview from "@contentstack/live-preview-utils";
+import Utils from "@contentstack/utils";
+
+// In your page component (e.g. inside useEffect, once the entry is fetched)
+Utils.addEditableTags(entry, "blog_post", true, "en-us");
+ContentstackLivePreview.setPageContext({
+    entryUid: entry.uid,
+    contentTypeUid: "blog_post",
+});
+```
+
+> **Note:** When the page is loaded inside the Visual Builder/Live Preview iframe, the context is also sent to Contentstack via a post message. Outside an iframe, the context is only stored locally and used when generating the "Start Editing" redirection URL.
+
+### Alternative ways to supply page context
+
+If you cannot call `setPageContext()` directly (for example, when no JavaScript hook is available for injecting runtime values), the SDK resolves the page context from the following sources, in order of precedence:
+
+1. The value set via `ContentstackLivePreview.setPageContext()`.
+2. A `window.__CS_PAGE_CONTEXT__` global:
+
+    ```ts
+    window.__CS_PAGE_CONTEXT__ = {
+        entryUid: "entry-123",
+        contentTypeUid: "blog_post",
+    };
+    ```
+
+3. `<meta>` tags in the page `<head>`:
+
+    ```html
+    <meta name="contentstack:entry-uid" content="entry-123" />
+    <meta name="contentstack:content-type-uid" content="blog_post" />
+    ```
+
+    Meta tags are a useful fallback for frameworks that render `<meta>` natively (for example, Next.js App Router `metadata`/`generateMetadata()` or Nuxt `useHead()`) and for sites with a strict Content Security Policy (`no unsafe-inline`) that blocks inline `<script>` tags but allows meta tags.
+
 ## hash
 
 The `hash` property returns the live preview hash of the entry. It returns an empty string if the page is not opened in live preivew pane.

main.mustache

@@ -84,6 +84,7 @@ Full tables and examples: **[docs/live-preview-configs.md](docs/live-preview-con
 - [`onLiveEdit`](docs/live-preview-configs.md#onliveeditcallback---void): Trigger actions on live edits
 - [`onEntryChange`](docs/live-preview-configs.md#onentrychangecallback---void): Listen for entry updates
 - [`hash`](docs/live-preview-configs.md#hash): Access preview state identifier
+- [`setPageContext`](docs/live-preview-configs.md#setpagecontextcontext): Tell Visual Builder which entry the current page renders so “Start Editing” targets the right entry (needed for custom-URL pages)
 - [`config`](docs/live-preview-configs.md#config): Includes runtime context (for example Live Preview / Timeline preview, Visual Editor, or independent)
 
 The [configs table of contents](docs/live-preview-configs.md#contentstack-live-preview-utils-sdk-configs) also lists `setConfigFromParams` and `getGatsbyDataFormat` for deeper workflows.

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@contentstack/live-preview-utils",
-    "version": "4.4.3",
+    "version": "4.4.4",
     "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/common/inIframe.ts

@@ -8,6 +8,14 @@ export function inIframe(): boolean {
     }
 }
 
+export function inVisualEditor(): boolean{
+    try {
+        return inIframe() && window?.name == 'visual-editor'
+    } catch (e) {
+        return false;
+    }
+}
+
 export function isOpeningInNewTab(): boolean {
     try {
         if(hasWindow()) {

src/configManager/__test__/configManager.test.ts

@@ -1,4 +1,4 @@
-import Config, { updateConfigFromUrl } from "../configManager";
+import Config, { updateConfigFromUrl, syncToStackSdk } from "../configManager";
 import { getDefaultConfig, getUserInitData } from "../config.default";
 import { DeepSignal } from "deepsignal";
 import { IConfig } from "../../types/types";
@@ -102,6 +102,73 @@ describe("config default flags", () => {
     });
 });
 
+describe("syncToStackSdk", () => {
+    beforeEach(() => {
+        Config.reset();
+    });
+
+    afterAll(() => {
+        Config.reset();
+    });
+
+    test("should set hash, stackSdkLivePreview.hash and stackSdkLivePreview.live_preview when hash is provided", () => {
+        syncToStackSdk({ hash: "abc123" });
+
+        const config = Config.get();
+        expect(config.stackSdk.live_preview.hash).toBe("abc123");
+        expect(config.stackSdk.live_preview.live_preview).toBe("abc123");
+        expect(config.stackSdk.live_preview.content_type_uid).toBeUndefined();
+        expect(config.stackSdk.live_preview.entry_uid).toBeUndefined();
+    });
+
+    test("should set content_type_uid on stackSdk when contentTypeUid is provided", () => {
+        syncToStackSdk({ contentTypeUid: "blog" });
+
+        const config = Config.get();
+        expect(config.stackSdk.live_preview.content_type_uid).toBe("blog");
+        expect(config.stackSdk.live_preview.hash).toBeUndefined();
+        expect(config.stackSdk.live_preview.entry_uid).toBeUndefined();
+    });
+
+    test("should set entry_uid on stackSdk when entryUid is provided", () => {
+        syncToStackSdk({ entryUid: "entry-42" });
+
+        const config = Config.get();
+        expect(config.stackSdk.live_preview.entry_uid).toBe("entry-42");
+        expect(config.stackSdk.live_preview.hash).toBeUndefined();
+        expect(config.stackSdk.live_preview.content_type_uid).toBeUndefined();
+    });
+
+    test("should set all three fields when all params are provided", () => {
+        syncToStackSdk({ hash: "h1", contentTypeUid: "page", entryUid: "e1" });
+
+        const config = Config.get();
+        expect(config.stackSdk.live_preview.hash).toBe("h1");
+        expect(config.stackSdk.live_preview.live_preview).toBe("h1");
+        expect(config.stackSdk.live_preview.content_type_uid).toBe("page");
+        expect(config.stackSdk.live_preview.entry_uid).toBe("e1");
+    });
+
+    test("should skip falsy values — null and undefined are ignored", () => {
+        syncToStackSdk({ hash: null, contentTypeUid: undefined, entryUid: null });
+
+        const config = Config.get();
+        expect(config.stackSdk.live_preview.hash).toBeUndefined();
+        expect(config.stackSdk.live_preview.content_type_uid).toBeUndefined();
+        expect(config.stackSdk.live_preview.entry_uid).toBeUndefined();
+    });
+
+    test("should not overwrite existing stackSdk values for keys not passed", () => {
+        syncToStackSdk({ hash: "first", contentTypeUid: "ct1", entryUid: "e1" });
+        syncToStackSdk({ hash: "second" });
+
+        const config = Config.get();
+        expect(config.stackSdk.live_preview.hash).toBe("second");
+        expect(config.stackSdk.live_preview.content_type_uid).toBe("ct1");
+        expect(config.stackSdk.live_preview.entry_uid).toBe("e1");
+    });
+});
+
 describe("update config from url", () => {
     let config: DeepSignal<IConfig>;