feat: add page context helper for custom URL handling in Visual Builder

src/configManager/config.default.ts

@@ -118,5 +118,6 @@ export function getDefaultConfig(): IConfig {
             payload: [],
         },
         enableLivePreviewOutsideIframe: undefined,
+        pageContext: null,
     };
 }

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

@@ -690,7 +690,6 @@ describe("postMessageEvent.hooks", () => {
             await sendInitializeLivePreviewPostMessageEvent();
             await Promise.resolve();
 
-            expect(setConfigFromParams).not.toHaveBeenCalled();
             expect(Config.set).not.toHaveBeenCalled();
             expect(addParamsToUrl).not.toHaveBeenCalled();
             expect(livePreviewPostMessage?.on).not.toHaveBeenCalledWith(

src/preview/contentstack-live-preview-HOC.ts

@@ -1,5 +1,6 @@
 import { cloneDeep, isEmpty, pick } from "lodash-es";
 import { v4 as uuidv4 } from "uuid";
+import { inIframe } from "../common/inIframe";
 import { getUserInitData } from "../configManager/config.default";
 import Config, { updateConfigFromUrl } from "../configManager/configManager";
 import LivePreview from "../livePreview/live-preview";
@@ -16,6 +17,11 @@ import { PublicLogger } from "../logger/logger";
 import { handleWebCompare } from "../timeline/compare/compare";
 import type { IExportedConfig, IInitData } from "../types/types";
 import { VisualBuilder } from "../visualBuilder";
+import visualBuilderPostMessage from "../visualBuilder/utils/visualBuilderPostMessage";
+import {
+    IPageContextPostMessageEvent,
+    VisualBuilderPostMessageEvents,
+} from "../visualBuilder/utils/types/postMessage.types";
 
 class ContentstackLivePreview {
     private static previewConstructors:
@@ -247,6 +253,34 @@ class ContentstackLivePreview {
         );
     }
 
+    /**
+     * Sets the page-level entry context for the current page.
+     * Used by the Visual Builder "Start Editing" button to know which entry
+     * the current page is rendering, enabling accurate VB navigation.
+     *
+     * Place this call alongside your existing `addEditableTags` call — both
+     * reference the same `entry` object so there is no extra lookup.
+     *
+     * @example
+     * ```js
+     * // In your page component / useEffect
+     * Utils.addEditableTags(entry, "blog_post", true, "en-us");
+     * ContentstackLivePreview.setPageContext({ entryUid: entry.uid, contentTypeUid: "blog_post" });
+     * ```
+     */
+    static setPageContext(context: { entryUid: string; contentTypeUid: string }): void {
+        Config.set("pageContext", context);
+        // init() fires before async data fetching, so the INIT post-message has no
+        // entry context in CSR apps. Send it now so VB can update its current entry.
+        // Only send when inside an iframe — skip when the site opens in a plain browser tab.
+        if (inIframe()) {
+            visualBuilderPostMessage?.send<IPageContextPostMessageEvent>(
+                VisualBuilderPostMessageEvents.PAGE_CONTEXT,
+                { entryUid: context.entryUid, contentTypeUid: context.contentTypeUid }
+            );
+        }
+    }
+
     /**
      * Retrieves the version of the SDK.
      * @returns The version of the SDK as a string.

src/types/global.d.ts

@@ -0,0 +1,9 @@
+import type { IPageContext } from "./types";
+
+declare global {
+    interface Window {
+        __CS_PAGE_CONTEXT__?: IPageContext;
+    }
+}
+
+export {};

src/types/types.ts

@@ -65,6 +65,11 @@ export enum ILivePreviewWindowType {
     INDEPENDENT = "independent",
 }
 
+export declare interface IPageContext {
+    entryUid: string;
+    contentTypeUid: string;
+}
+
 export declare interface IConfig {
     ssr: boolean;
     enable: boolean;
@@ -89,6 +94,7 @@ export declare interface IConfig {
     };
     collab: ICollabConfig["collab"];
     enableLivePreviewOutsideIframe: boolean | undefined;
+    pageContext: IPageContext | null;
 }
 
 

src/visualBuilder/index.ts

@@ -15,6 +15,7 @@ import { generateStartEditingButton } from "./generators/generateStartEditingBut
 
 import { addFocusOverlay } from "./generators/generateOverlay";
 import { getEntryIdentifiersInCurrentPage } from "./utils/getEntryIdentifiersInCurrentPage";
+import { resolvePageContext } from "./utils/resolvePageContext";
 import visualBuilderPostMessage from "./utils/visualBuilderPostMessage";
 import { VisualBuilderPostMessageEvents } from "./utils/types/postMessage.types";
 
@@ -308,11 +309,16 @@ export class VisualBuilder {
             return;
         }
 
+        const { entryUid, contentTypeUid } = resolvePageContext();
+        const initPayload: any = {
+            isSSR: config.ssr,
+            href: window.location.href,
+            entry_uid: entryUid,
+            content_type_uid: contentTypeUid,
+        };
+
         visualBuilderPostMessage
-            ?.send<IVisualBuilderInitEvent>("init", {
-                isSSR: config.ssr,
-                href: window.location.href,
-            })
+            ?.send<IVisualBuilderInitEvent>("init", initPayload)
             .then((data) => {
                 const {
                     windowType = ILivePreviewWindowType.BUILDER,

src/visualBuilder/utils/getVisualBuilderRedirectionUrl.ts

@@ -1,5 +1,6 @@
 import Config from "../../configManager/configManager";
 import { extractDetailsFromCslp, isValidCslp } from "../../cslp";
+import { resolvePageContext } from "./resolvePageContext";
 
 /**
  * Returns the redirection URL for the Visual builder.
@@ -36,6 +37,15 @@ export default function getVisualBuilderRedirectionUrl(): URL {
         searchParams.set("locale", localeToUse);
     }
 
+    const { entryUid, contentTypeUid } = resolvePageContext();
+
+    if (entryUid) {
+        searchParams.set("entry_uid", entryUid);
+    }
+    if (contentTypeUid) {
+        searchParams.set("content_type_uid", contentTypeUid);
+    }
+
     const completeURL = new URL(
         `/#!/stack/${apiKey}/visual-editor?${searchParams.toString()}`,
         appUrl

src/visualBuilder/utils/resolvePageContext.ts

@@ -0,0 +1,28 @@
+import Config from "../../configManager/configManager";
+
+// Meta tags are kept as a fallback because:
+// - Next.js App Router's metadata/generateMetadata() and Nuxt's useHead() produce
+//   <meta> tags natively — there is no built-in hook for injecting window globals.
+// - Strict CSP policies (no unsafe-inline) block inline <script> tags, but never meta tags.
+export function resolvePageContext(): {
+    entryUid: string | undefined;
+    contentTypeUid: string | undefined;
+} {
+    const configCtx = Config.get().pageContext;
+    return {
+        entryUid:
+            configCtx?.entryUid ??
+            window.__CS_PAGE_CONTEXT__?.entryUid ??
+            document
+                .querySelector('meta[name="contentstack:entry-uid"]')
+                ?.getAttribute("content") ??
+            undefined,
+        contentTypeUid:
+            configCtx?.contentTypeUid ??
+            window.__CS_PAGE_CONTEXT__?.contentTypeUid ??
+            document
+                .querySelector('meta[name="contentstack:content-type-uid"]')
+                ?.getAttribute("content") ??
+            undefined,
+    };
+}

src/visualBuilder/utils/types/postMessage.types.ts

@@ -59,5 +59,11 @@ export enum VisualBuilderPostMessageEvents {
     COLLAB_THREAD_REOPEN = "collab-thread-reopen",
     COLLAB_THREAD_HIGHLIGHT = "collab-thread-highlight",
     TOGGLE_SCROLL = "toggle-scroll",
+    PAGE_CONTEXT = "page-context",
     REQUEST_DISCUSSION_HIGHLIGHTS = "request-discussion-highlights",
 }
+
+export interface IPageContextPostMessageEvent {
+    entryUid: string;
+    contentTypeUid: string;
+}