refactor: enhance UVE script injection logic (#35128)

This pull request improves the logging and error handling in the UVE
script injection process within the HTML page rendering flow. The
changes make it easier to trace when and how the UVE script is injected,
and ensure that failures in script building are handled gracefully.

**Enhanced logging and error handling for UVE script injection:**

* Added debug logs to indicate when the UVE script is injected or
skipped based on the page mode in the `build` method of
`HTMLPageAssetRenderedBuilder`
(`dotCMS/src/main/java/com/dotmarketing/portlets/htmlpageasset/business/render/page/HTMLPageAssetRenderedBuilder.java`).
* Improved the `injectUVEScript` method to:
- Log when the rendered HTML is empty or null and script injection is
skipped.
- Use a `Try` block to handle exceptions during script building, logging
errors and falling back to a default script if needed.
- Add debug logs to indicate where the script is injected (before
`</body>` or at the end if no `</body>` tag is found).

#35127

Author: nicobytes

core-web/libs/dotcms-models/src/lib/shared-models.ts

@@ -32,7 +32,8 @@ export const enum FeaturedFlags {
     FEATURE_FLAG_UVE_PREVIEW_MODE = 'FEATURE_FLAG_UVE_PREVIEW_MODE',
     FEATURE_FLAG_UVE_TOGGLE_LOCK = 'FEATURE_FLAG_UVE_TOGGLE_LOCK',
     FEATURE_FLAG_UVE_STYLE_EDITOR = 'FEATURE_FLAG_UVE_STYLE_EDITOR',
-    FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES = 'FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES'
+    FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES = 'FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES',
+    FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION = 'FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION'
 }
 
 export const enum DotConfigurationVariables {

core-web/libs/dotcms-webcomponents/project.json

@@ -31,7 +31,7 @@
         "build": {
             "executor": "nx:run-commands",
             "options": {
-                "command": "npx stencil build --config libs/dotcms-webcomponents/stencil.config.ts --prod"
+                "command": "yarn stencil build --config libs/dotcms-webcomponents/stencil.config.ts --prod"
             }
         },
         "serve": {

core-web/libs/portlets/edit-ema/portlet/src/lib/edit-ema-editor/edit-ema-editor.component.spec.ts

@@ -117,6 +117,7 @@ import { ActionPayload, ContentTypeDragPayload } from '../shared/models';
 import { UVEStore } from '../store/dot-uve.store';
 import * as uveUtils from '../utils';
 import { TEMPORAL_DRAG_ITEM } from '../utils';
+import { SDK_EDITOR_SCRIPT_SOURCE } from '../utils/ema-legacy-script-injection';
 
 global.URL.createObjectURL = jest.fn(
     () => 'blob:http://localhost:3000/12345678-1234-1234-1234-123456789012'
@@ -3481,6 +3482,77 @@ describe('EditEmaEditorComponent', () => {
                     });
                 });
 
+                describe('legacy script injection (FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION)', () => {
+                    let componentStore: InstanceType<typeof UVEStore>;
+
+                    beforeEach(() => {
+                        componentStore = (
+                            spectator.component as unknown as {
+                                uveStore: InstanceType<typeof UVEStore>;
+                            }
+                        ).uveStore;
+
+                        jest.spyOn(dotPageApiService, 'get').mockReturnValue(of(MOCK_RESPONSE_VTL));
+                        store.loadPageAsset({ url: 'index', clientHost: null });
+                    });
+
+                    it('should inject the UVE script when the flag is enabled', () => {
+                        patchState(componentStore, {
+                            flags: {
+                                ...componentStore.flags(),
+                                [FeaturedFlags.FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION]: true
+                            }
+                        });
+
+                        const iframe = spectator.query(byTestId('iframe')) as HTMLIFrameElement;
+                        const spyWrite = jest.spyOn(iframe.contentDocument, 'write');
+
+                        iframe.dispatchEvent(new Event('load'));
+                        spectator.detectChanges();
+
+                        expect(spyWrite).toHaveBeenCalledWith(
+                            expect.stringContaining(
+                                `<script src="${SDK_EDITOR_SCRIPT_SOURCE}"></script>`
+                            )
+                        );
+                    });
+
+                    it('should NOT inject the UVE script when the flag is disabled', () => {
+                        patchState(componentStore, {
+                            flags: {
+                                ...componentStore.flags(),
+                                [FeaturedFlags.FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION]: false
+                            }
+                        });
+
+                        const iframe = spectator.query(byTestId('iframe')) as HTMLIFrameElement;
+                        const spyWrite = jest.spyOn(iframe.contentDocument, 'write');
+
+                        iframe.dispatchEvent(new Event('load'));
+                        spectator.detectChanges();
+
+                        expect(spyWrite).toHaveBeenCalledWith(
+                            expect.not.stringContaining(
+                                `<script src="${SDK_EDITOR_SCRIPT_SOURCE}"></script>`
+                            )
+                        );
+                    });
+
+                    it('should NOT inject the UVE script when the flag is not set', () => {
+                        const iframe = spectator.query(byTestId('iframe')) as HTMLIFrameElement;
+                        const spyWrite = jest.spyOn(iframe.contentDocument, 'write');
+
+                        iframe.dispatchEvent(new Event('load'));
+                        spectator.detectChanges();
+
+                        expect(spyWrite).toHaveBeenCalledWith(
+                            expect.not.stringContaining(
+                                `<script src="${SDK_EDITOR_SCRIPT_SOURCE}"></script>`
+                            )
+                        );
+                    });
+                });
+
                 describe('when pageRender is undefined', () => {
                     beforeEach(() => {
                         jest.spyOn(dotPageApiService, 'get').mockReturnValue(

core-web/libs/portlets/edit-ema/portlet/src/lib/edit-ema-editor/edit-ema-editor.component.ts

@@ -115,6 +115,7 @@ import {
     insertContentletInContainer,
     shouldNavigate
 } from '../utils';
+import { addEditorPageScript } from '../utils/ema-legacy-script-injection';
 
 // Message keys constants
 const MESSAGE_KEY = {
@@ -565,18 +566,30 @@ export class EditEmaEditorComponent implements OnInit, OnDestroy, AfterViewInit
     }
 
     /**
-     * Inject the editor page styles to the VTL content
+     * Inject the editor page styles (and optionally the legacy UVE script)
+     * into the VTL content before writing it to the iframe.
+     *
+     * When `FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION` is enabled, the
+     * `dot-uve.js` script tag is also injected. This restores the pre-PR
+     * #34995 behavior for EMA customers whose headless frontends do not
+     * consume the backend-rendered output where the script now lives.
      *
      * @private
-     * @param {string} html
-     * @return {*}  {string}
-     * @memberof EditEmaEditorComponent
+     * @param html - Raw rendered HTML from the Page API.
+     * @returns Transformed HTML ready for `document.write()`.
+     * @see {@link addEditorPageScript} for the legacy script injection logic.
      */
     private injectCodeToVTL(html: string): string {
         const url = this.uveStore.pageAPIResponse()?.page?.pageURI ?? '';
         const origin = this.window.location.origin;
         const fileWithBase = injectBaseTag({ html, url, origin });
-        return this.addCustomStyles(fileWithBase);
+        const fileWithStyles = this.addCustomStyles(fileWithBase);
+
+        if (this.uveStore.$isEmaLegacyScriptInjectionEnabled()) {
+            return addEditorPageScript(fileWithStyles);
+        }
+
+        return fileWithStyles;
     }
 
     ngOnDestroy(): void {
@@ -747,9 +760,11 @@ export class EditEmaEditorComponent implements OnInit, OnDestroy, AfterViewInit
     /**
      * Sets up the iframe content for traditional (VTL) pages.
      *
-     * NOTE: The `dot-uve.js` editor script is intentionally NOT injected here.
-     * It is now included by the backend directly in `entity.page.rendered`
-     * (see PR #34927). Do not re-add script injection on the frontend.
+     * The `dot-uve.js` editor script is normally included by the backend
+     * directly in `entity.page.rendered` (see PR #34927). However, when
+     * `FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION` is enabled, the script
+     * is also injected from the frontend to support EMA customers whose
+     * headless setup does not consume the backend-rendered output.
      *
      * @memberof EditEmaEditorComponent
      */

core-web/libs/portlets/edit-ema/portlet/src/lib/shared/consts.ts

@@ -76,7 +76,8 @@ export const DEFAULT_PERSONA: DotCMSViewAsPersona = {
 export const UVE_FEATURE_FLAGS = [
     FeaturedFlags.FEATURE_FLAG_UVE_TOGGLE_LOCK,
     FeaturedFlags.FEATURE_FLAG_UVE_STYLE_EDITOR,
-    FeaturedFlags.FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES
+    FeaturedFlags.FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES,
+    FeaturedFlags.FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION
 ];
 
 export const DEFAULT_DEVICE: DotDeviceListItem = {

core-web/libs/portlets/edit-ema/portlet/src/lib/shared/mocks.ts

@@ -1044,7 +1044,8 @@ export const dotPropertiesServiceMock = {
             [FeaturedFlags.FEATURE_FLAG_UVE_PREVIEW_MODE]: false,
             [FeaturedFlags.FEATURE_FLAG_UVE_TOGGLE_LOCK]: false,
             [FeaturedFlags.FEATURE_FLAG_UVE_STYLE_EDITOR]: false,
-            [FeaturedFlags.FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES]: false
+            [FeaturedFlags.FEATURE_FLAG_UVE_STYLE_EDITOR_FOR_TRADITIONAL_PAGES]: false,
+            [FeaturedFlags.FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION]: false
         })
 };
 

core-web/libs/portlets/edit-ema/portlet/src/lib/store/features/withPageContext.ts

@@ -16,6 +16,7 @@ export interface PageContextComputed {
     $isPageLocked: Signal<boolean>;
     $isLockFeatureEnabled: Signal<boolean>;
     $isStyleEditorEnabled: Signal<boolean>;
+    $isEmaLegacyScriptInjectionEnabled: Signal<boolean>;
     $hasAccessToEditMode: Signal<boolean>;
     $languageId: Signal<number>;
     $isPreviewMode: Signal<boolean>;
@@ -60,6 +61,9 @@ export function withPageContext() {
 
                     return flags().FEATURE_FLAG_UVE_STYLE_EDITOR;
                 });
+                const $isEmaLegacyScriptInjectionEnabled = computed(
+                    () => flags().FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION === true
+                );
                 const $isPageLocked = computed(() => {
                     return computeIsPageLocked(page(), currentUser());
                 });
@@ -79,6 +83,7 @@ export function withPageContext() {
                     $isPageLocked,
                     $isLockFeatureEnabled,
                     $isStyleEditorEnabled,
+                    $isEmaLegacyScriptInjectionEnabled,
                     $hasAccessToEditMode,
                     $languageId: computed(() => viewAs()?.language?.id || 1),
                     $pageURI: computed(() => page()?.pageURI ?? ''),

core-web/libs/portlets/edit-ema/portlet/src/lib/utils/ema-legacy-script-injection.spec.ts

@@ -0,0 +1,40 @@
+import { addEditorPageScript, SDK_EDITOR_SCRIPT_SOURCE } from './ema-legacy-script-injection';
+
+describe('ema-legacy-script-injection', () => {
+    describe('SDK_EDITOR_SCRIPT_SOURCE', () => {
+        it('should point to the UVE editor script path', () => {
+            expect(SDK_EDITOR_SCRIPT_SOURCE).toBe('/ext/uve/dot-uve.js');
+        });
+    });
+
+    describe('addEditorPageScript', () => {
+        const expectedScript = `<script src="${SDK_EDITOR_SCRIPT_SOURCE}"></script>`;
+
+        it('should insert the script tag before </body> when body tag exists', () => {
+            const html = '<html><head></head><body><p>Hello</p></body></html>';
+            const result = addEditorPageScript(html);
+
+            expect(result).toContain(expectedScript + '</body>');
+            expect(result).toBe(
+                `<html><head></head><body><p>Hello</p>${expectedScript}</body></html>`
+            );
+        });
+
+        it('should append the script tag at the end when no body tag exists', () => {
+            const html = '<div>Advanced template content</div>';
+            const result = addEditorPageScript(html);
+
+            expect(result).toBe(html + expectedScript);
+        });
+
+        it('should handle empty string input', () => {
+            const result = addEditorPageScript('');
+            expect(result).toBe(expectedScript);
+        });
+
+        it('should handle undefined input (defaults to empty string)', () => {
+            const result = addEditorPageScript();
+            expect(result).toBe(expectedScript);
+        });
+    });
+});

core-web/libs/portlets/edit-ema/portlet/src/lib/utils/ema-legacy-script-injection.ts

@@ -0,0 +1,65 @@
+/**
+ * @module ema-legacy-script-injection
+ *
+ * @deprecated This module is a temporary workaround and will be removed once
+ * EMA (Edit Mode Anywhere) headless editing is fully sunset.
+ *
+ * ## Why this exists
+ *
+ * PR #34927 moved the `dot-uve.js` editor script injection from the Angular
+ * frontend to the backend, embedding it directly in `entity.page.rendered`.
+ * PR #34995 then removed the frontend injection code.
+ *
+ * This broke EMA-based customers (e.g. Freshdesk #36029) because EMA runs
+ * headless — the iframe loads the customer's own frontend (Next.js, etc.)
+ * and does **not** consume the backend-rendered HTML that now contains the
+ * script. As a result, the UVE editor controls stopped appearing in edit mode.
+ *
+ * ## How it works
+ *
+ * When the backend feature flag `FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION` is
+ * set to `true`, the Angular editor re-injects the `dot-uve.js` script tag
+ * into VTL page content before writing it to the iframe — restoring the
+ * pre-PR #34995 behavior.
+ *
+ * ## Removal plan
+ *
+ * Once all EMA customers have migrated to the Universal Visual Editor (UVE),
+ * delete this file and remove:
+ * - `FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION` from `FeaturedFlags` enum
+ * - The flag entry from `UVE_FEATURE_FLAGS` in `consts.ts`
+ * - `$isEmaLegacyScriptInjectionEnabled` from `withPageContext.ts`
+ * - The conditional call in `EditEmaEditorComponent.injectCodeToVTL`
+ *
+ * @see {@link https://github.com/dotCMS/core/pull/34927 PR #34927 — backend script injection}
+ * @see {@link https://github.com/dotCMS/core/pull/34995 PR #34995 — frontend injection removal}
+ */
+
+/**
+ * Path to the UVE editor script served by the dotCMS backend.
+ *
+ * @deprecated Gated behind `FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION`.
+ */
+export const SDK_EDITOR_SCRIPT_SOURCE = '/ext/uve/dot-uve.js';
+
+/**
+ * Injects the `dot-uve.js` editor script tag into the rendered HTML content.
+ *
+ * If a `</body>` tag exists, the script is inserted just before it.
+ * For advanced templates that may lack a `<body>`, the script is appended
+ * at the end of the content.
+ *
+ * @deprecated Gated behind `FEATURE_FLAG_UVE_LEGACY_SCRIPT_INJECTION`.
+ * @param rendered - The HTML string to inject the script into.
+ * @returns The HTML string with the editor script tag added.
+ */
+export function addEditorPageScript(rendered = ''): string {
+    const scriptString = `<script src="${SDK_EDITOR_SCRIPT_SOURCE}"></script>`;
+    const bodyExists = rendered.includes('</body>');
+
+    if (!bodyExists) {
+        return rendered + scriptString;
+    }
+
+    return rendered.replace('</body>', scriptString + '</body>');
+}

core-web/package.json

@@ -280,5 +280,6 @@
     },
     "nx": {
         "includedScripts": []
-    }
+    },
+    "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }