@elementor/editor-canvas 4.2.0-919 → 4.2.0-921

package/dist/index.js

@@ -4299,6 +4299,26 @@ var import_editor_elements13 = require("@elementor/editor-elements");
 var import_editor_props7 = require("@elementor/editor-props");
 var import_editor_styles5 = require("@elementor/editor-styles");
 var import_editor_v1_adapters20 = require("@elementor/editor-v1-adapters");
+
+// src/mcp/utils/merge-custom-css.ts
+var CUSTOM_CSS_SEPARATOR = "\n";
+var mergeCustomCssText = (...cssParts) => cssParts.map((cssPart) => cssPart?.trim()).filter((cssPart) => !!cssPart).join(CUSTOM_CSS_SEPARATOR);
+var readStoredCustomCssText = (raw) => {
+  if (!raw) {
+    return "";
+  }
+  try {
+    return atob(raw);
+  } catch {
+    return "";
+  }
+};
+
+// src/mcp/utils/do-update-element-property.ts
+var LOCAL_STYLE_META = {
+  breakpoint: "desktop",
+  state: null
+};
 function resolvePropValue(value, forceKey) {
   const Utils = window.elementorV2.editorVariables.Utils;
   return import_editor_props7.Schema.adjustLlmPropValueSchema(value, {
@@ -4307,7 +4327,7 @@ function resolvePropValue(value, forceKey) {
   });
 }
 var doUpdateElementProperty = (params) => {
-  const { elementId, propertyName, propertyValue, elementType } = params;
+  const { elementId, propertyName, propertyValue, elementType, customCssWriteMode = "replace" } = params;
   if (propertyName === "_styles") {
     const elementStyles = (0, import_editor_elements13.getElementStyles)(elementId) || {};
     const propertyMapValue = propertyValue;
@@ -4324,6 +4344,8 @@ var doUpdateElementProperty = (params) => {
         return [key, resolvePropValue(val, propKey2)];
       })
     );
+    const localStyle = Object.values(elementStyles).find((style) => style.label === "local");
+    const existingCustomCssText = localStyle ? readStoredCustomCssText((0, import_editor_styles5.getVariantByMeta)(localStyle, LOCAL_STYLE_META)?.custom_css?.raw) : "";
     let customCss;
     Object.keys(propertyMapValue).forEach((stylePropName) => {
       const propertyRawSchema = styleSchema[stylePropName];
@@ -4335,9 +4357,14 @@ var doUpdateElementProperty = (params) => {
         if (!customCssValue) {
           customCssValue = "";
         }
-        customCss = {
-          raw: btoa(customCssValue)
-        };
+        const customCssText = customCssWriteMode === "merge-with-stored" ? mergeCustomCssText(existingCustomCssText, customCssValue) : String(customCssValue);
+        if (customCssText) {
+          customCss = {
+            raw: btoa(customCssText)
+          };
+        } else {
+          customCss = { raw: btoa("") };
+        }
         return;
       }
       const isSupported = !!propertyRawSchema;
@@ -4355,7 +4382,6 @@ var doUpdateElementProperty = (params) => {
       }
     });
     delete transformedStyleValues.custom_css;
-    const localStyle = Object.values(elementStyles).find((style) => style.label === "local");
     if (!localStyle) {
       (0, import_editor_elements13.createElementStyle)({
         elementId,
@@ -4658,7 +4684,6 @@ var CompositionBuilder = class _CompositionBuilder {
   async applyProperties() {
     const configErrors = [];
     const styleErrors = [];
-    const invalidStyles = {};
     const allConfigIds = /* @__PURE__ */ new Set([
       ...Object.keys(this.elementConfig),
       ...Object.keys(this.elementStylesConfig),
@@ -4694,17 +4719,18 @@ var CompositionBuilder = class _CompositionBuilder {
         }
       }
       const styleConfig = this.elementStylesConfig[configId];
+      let hasInvalidStyles = false;
       if (styleConfig) {
         const validStylesPropValues = {};
         for (const [styleName, stylePropValue] of Object.entries(styleConfig)) {
+          if (styleName === "$intention") {
+            continue;
+          }
           const { valid, errors: validationErrors } = validateInput.validateStyles({
             [styleName]: stylePropValue
           });
           if (!valid) {
-            if (styleConfig.$intention) {
-              invalidStyles[element.id] = invalidStyles[element.id] || [];
-              invalidStyles[element.id].push(styleName);
-            }
+            hasInvalidStyles = true;
             styleErrors.push(...validationErrors || []);
           } else {
             validStylesPropValues[styleName] = stylePropValue;
@@ -4723,13 +4749,15 @@ var CompositionBuilder = class _CompositionBuilder {
           }
         }
       }
-      const customCSS = this.elementCustomCSS[configId];
-      if (customCSS) {
+      const intentionCss = typeof styleConfig?.$intention === "string" ? styleConfig.$intention.trim() : "";
+      const fallbackCss = hasInvalidStyles && intentionCss ? intentionCss : "";
+      const mergedCustomCss = mergeCustomCssText(this.elementCustomCSS[configId], fallbackCss);
+      if (mergedCustomCss) {
         try {
           this.api.doUpdateElementProperty({
             elementId: element.id,
             propertyName: "_styles",
-            propertyValue: { custom_css: customCSS },
+            propertyValue: { custom_css: mergedCustomCss },
             elementType: node.tagName
           });
         } catch (cssErr) {
@@ -4738,7 +4766,7 @@ var CompositionBuilder = class _CompositionBuilder {
       }
       await this.awaitViewRender(element);
     }
-    return { configErrors, styleErrors, invalidStyles };
+    return { configErrors, styleErrors };
   }
   async build(rootContainer) {
     const widgetsCache = this.api.getWidgetsCache() || {};
@@ -4783,11 +4811,10 @@ ${childTypeErrors.join("\n")}`);
         throw e;
       }
     }
-    const { configErrors, styleErrors, invalidStyles } = await this.applyProperties();
+    const { configErrors, styleErrors } = await this.applyProperties();
     return {
       configErrors,
       styleErrors,
-      invalidStyles,
       rootContainers: [...this.rootContainers]
     };
   }
@@ -5086,31 +5113,11 @@ var initBuildCompositionsTool = (reg) => {
         compositionBuilder.setElementConfig(elementConfig);
         compositionBuilder.setStylesConfig(stylesConfig);
         compositionBuilder.setCustomCSS(customCSS);
-        const {
-          invalidStyles,
-          configErrors,
-          rootContainers: generatedRootContainers
-        } = await compositionBuilder.build(targetContainer);
+        const { configErrors, rootContainers: generatedRootContainers } = await compositionBuilder.build(targetContainer);
         rootContainers.push(...generatedRootContainers);
         generatedXML = new XMLSerializer().serializeToString(compositionBuilder.getXML());
         if (configErrors.length) {
           errors.push(...configErrors.map((msg) => new Error(msg)));
-        } else {
-          Object.entries(invalidStyles).forEach(([elementId, rawCssRules]) => {
-            const customCss = {
-              value: rawCssRules.join(";\n")
-            };
-            doUpdateElementProperty({
-              elementId,
-              propertyName: "_styles",
-              propertyValue: {
-                _styles: {
-                  custom_css: customCss
-                }
-              },
-              elementType: "widget"
-            });
-          });
         }
       } catch (error) {
         errors.push(error);

package/dist/index.mjs

@@ -4283,8 +4283,28 @@ import {
   updateElementStyle
 } from "@elementor/editor-elements";
 import { getPropSchemaFromCache, Schema as Schema2 } from "@elementor/editor-props";
-import { getStylesSchema as getStylesSchema3 } from "@elementor/editor-styles";
+import { getStylesSchema as getStylesSchema3, getVariantByMeta } from "@elementor/editor-styles";
 import { __privateRunCommandSync as runCommandSync2 } from "@elementor/editor-v1-adapters";
+
+// src/mcp/utils/merge-custom-css.ts
+var CUSTOM_CSS_SEPARATOR = "\n";
+var mergeCustomCssText = (...cssParts) => cssParts.map((cssPart) => cssPart?.trim()).filter((cssPart) => !!cssPart).join(CUSTOM_CSS_SEPARATOR);
+var readStoredCustomCssText = (raw) => {
+  if (!raw) {
+    return "";
+  }
+  try {
+    return atob(raw);
+  } catch {
+    return "";
+  }
+};
+
+// src/mcp/utils/do-update-element-property.ts
+var LOCAL_STYLE_META = {
+  breakpoint: "desktop",
+  state: null
+};
 function resolvePropValue(value, forceKey) {
   const Utils = window.elementorV2.editorVariables.Utils;
   return Schema2.adjustLlmPropValueSchema(value, {
@@ -4293,7 +4313,7 @@ function resolvePropValue(value, forceKey) {
   });
 }
 var doUpdateElementProperty = (params) => {
-  const { elementId, propertyName, propertyValue, elementType } = params;
+  const { elementId, propertyName, propertyValue, elementType, customCssWriteMode = "replace" } = params;
   if (propertyName === "_styles") {
     const elementStyles = getElementStyles(elementId) || {};
     const propertyMapValue = propertyValue;
@@ -4310,6 +4330,8 @@ var doUpdateElementProperty = (params) => {
         return [key, resolvePropValue(val, propKey2)];
       })
     );
+    const localStyle = Object.values(elementStyles).find((style) => style.label === "local");
+    const existingCustomCssText = localStyle ? readStoredCustomCssText(getVariantByMeta(localStyle, LOCAL_STYLE_META)?.custom_css?.raw) : "";
     let customCss;
     Object.keys(propertyMapValue).forEach((stylePropName) => {
       const propertyRawSchema = styleSchema[stylePropName];
@@ -4321,9 +4343,14 @@ var doUpdateElementProperty = (params) => {
         if (!customCssValue) {
           customCssValue = "";
         }
-        customCss = {
-          raw: btoa(customCssValue)
-        };
+        const customCssText = customCssWriteMode === "merge-with-stored" ? mergeCustomCssText(existingCustomCssText, customCssValue) : String(customCssValue);
+        if (customCssText) {
+          customCss = {
+            raw: btoa(customCssText)
+          };
+        } else {
+          customCss = { raw: btoa("") };
+        }
         return;
       }
       const isSupported = !!propertyRawSchema;
@@ -4341,7 +4368,6 @@ var doUpdateElementProperty = (params) => {
       }
     });
     delete transformedStyleValues.custom_css;
-    const localStyle = Object.values(elementStyles).find((style) => style.label === "local");
     if (!localStyle) {
       createElementStyle({
         elementId,
@@ -4644,7 +4670,6 @@ var CompositionBuilder = class _CompositionBuilder {
   async applyProperties() {
     const configErrors = [];
     const styleErrors = [];
-    const invalidStyles = {};
     const allConfigIds = /* @__PURE__ */ new Set([
       ...Object.keys(this.elementConfig),
       ...Object.keys(this.elementStylesConfig),
@@ -4680,17 +4705,18 @@ var CompositionBuilder = class _CompositionBuilder {
         }
       }
       const styleConfig = this.elementStylesConfig[configId];
+      let hasInvalidStyles = false;
       if (styleConfig) {
         const validStylesPropValues = {};
         for (const [styleName, stylePropValue] of Object.entries(styleConfig)) {
+          if (styleName === "$intention") {
+            continue;
+          }
           const { valid, errors: validationErrors } = validateInput.validateStyles({
             [styleName]: stylePropValue
           });
           if (!valid) {
-            if (styleConfig.$intention) {
-              invalidStyles[element.id] = invalidStyles[element.id] || [];
-              invalidStyles[element.id].push(styleName);
-            }
+            hasInvalidStyles = true;
             styleErrors.push(...validationErrors || []);
           } else {
             validStylesPropValues[styleName] = stylePropValue;
@@ -4709,13 +4735,15 @@ var CompositionBuilder = class _CompositionBuilder {
           }
         }
       }
-      const customCSS = this.elementCustomCSS[configId];
-      if (customCSS) {
+      const intentionCss = typeof styleConfig?.$intention === "string" ? styleConfig.$intention.trim() : "";
+      const fallbackCss = hasInvalidStyles && intentionCss ? intentionCss : "";
+      const mergedCustomCss = mergeCustomCssText(this.elementCustomCSS[configId], fallbackCss);
+      if (mergedCustomCss) {
         try {
           this.api.doUpdateElementProperty({
             elementId: element.id,
             propertyName: "_styles",
-            propertyValue: { custom_css: customCSS },
+            propertyValue: { custom_css: mergedCustomCss },
             elementType: node.tagName
           });
         } catch (cssErr) {
@@ -4724,7 +4752,7 @@ var CompositionBuilder = class _CompositionBuilder {
       }
       await this.awaitViewRender(element);
     }
-    return { configErrors, styleErrors, invalidStyles };
+    return { configErrors, styleErrors };
   }
   async build(rootContainer) {
     const widgetsCache = this.api.getWidgetsCache() || {};
@@ -4769,11 +4797,10 @@ ${childTypeErrors.join("\n")}`);
         throw e;
       }
     }
-    const { configErrors, styleErrors, invalidStyles } = await this.applyProperties();
+    const { configErrors, styleErrors } = await this.applyProperties();
     return {
       configErrors,
       styleErrors,
-      invalidStyles,
       rootContainers: [...this.rootContainers]
     };
   }
@@ -5072,31 +5099,11 @@ var initBuildCompositionsTool = (reg) => {
         compositionBuilder.setElementConfig(elementConfig);
         compositionBuilder.setStylesConfig(stylesConfig);
         compositionBuilder.setCustomCSS(customCSS);
-        const {
-          invalidStyles,
-          configErrors,
-          rootContainers: generatedRootContainers
-        } = await compositionBuilder.build(targetContainer);
+        const { configErrors, rootContainers: generatedRootContainers } = await compositionBuilder.build(targetContainer);
         rootContainers.push(...generatedRootContainers);
         generatedXML = new XMLSerializer().serializeToString(compositionBuilder.getXML());
         if (configErrors.length) {
           errors.push(...configErrors.map((msg) => new Error(msg)));
-        } else {
-          Object.entries(invalidStyles).forEach(([elementId, rawCssRules]) => {
-            const customCss = {
-              value: rawCssRules.join(";\n")
-            };
-            doUpdateElementProperty({
-              elementId,
-              propertyName: "_styles",
-              propertyValue: {
-                _styles: {
-                  custom_css: customCss
-                }
-              },
-              elementType: "widget"
-            });
-          });
         }
       } catch (error) {
         errors.push(error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elementor/editor-canvas",
   "description": "Elementor Editor Canvas",
-  "version": "4.2.0-919",
+  "version": "4.2.0-921",
   "private": false,
   "author": "Elementor Team",
   "homepage": "https://elementor.com/",
@@ -37,25 +37,25 @@
     "react-dom": "^18.3.1"
   },
   "dependencies": {
-    "@elementor/editor": "4.2.0-919",
+    "@elementor/editor": "4.2.0-921",
     "dompurify": "^3.2.6",
-    "@elementor/editor-controls": "4.2.0-919",
-    "@elementor/editor-documents": "4.2.0-919",
-    "@elementor/editor-elements": "4.2.0-919",
-    "@elementor/editor-interactions": "4.2.0-919",
-    "@elementor/editor-mcp": "4.2.0-919",
-    "@elementor/editor-notifications": "4.2.0-919",
-    "@elementor/editor-props": "4.2.0-919",
-    "@elementor/editor-responsive": "4.2.0-919",
-    "@elementor/editor-styles": "4.2.0-919",
-    "@elementor/editor-styles-repository": "4.2.0-919",
-    "@elementor/editor-ui": "4.2.0-919",
-    "@elementor/editor-v1-adapters": "4.2.0-919",
-    "@elementor/schema": "4.2.0-919",
-    "@elementor/twing": "4.2.0-919",
+    "@elementor/editor-controls": "4.2.0-921",
+    "@elementor/editor-documents": "4.2.0-921",
+    "@elementor/editor-elements": "4.2.0-921",
+    "@elementor/editor-interactions": "4.2.0-921",
+    "@elementor/editor-mcp": "4.2.0-921",
+    "@elementor/editor-notifications": "4.2.0-921",
+    "@elementor/editor-props": "4.2.0-921",
+    "@elementor/editor-responsive": "4.2.0-921",
+    "@elementor/editor-styles": "4.2.0-921",
+    "@elementor/editor-styles-repository": "4.2.0-921",
+    "@elementor/editor-ui": "4.2.0-921",
+    "@elementor/editor-v1-adapters": "4.2.0-921",
+    "@elementor/schema": "4.2.0-921",
+    "@elementor/twing": "4.2.0-921",
     "@elementor/ui": "1.37.5",
-    "@elementor/utils": "4.2.0-919",
-    "@elementor/wp-media": "4.2.0-919",
+    "@elementor/utils": "4.2.0-921",
+    "@elementor/wp-media": "4.2.0-921",
     "@floating-ui/react": "^0.27.5",
     "@wordpress/i18n": "^5.13.0"
   },

package/src/composition-builder/composition-builder.ts

@@ -12,6 +12,7 @@ import {
 import { type z } from '@elementor/schema';
 
 import { doUpdateElementProperty } from '../mcp/utils/do-update-element-property';
+import { mergeCustomCssText } from '../mcp/utils/merge-custom-css';
 import { validateInput } from '../mcp/utils/validate-input';
 import { RequiredChildrenEnforcer } from './utils/required-children-enforcer';
 import { getRequiredDefaultChildTemplates } from './utils/required-default-child-tags';
@@ -183,7 +184,6 @@ export class CompositionBuilder {
 	private async applyProperties() {
 		const configErrors: string[] = [];
 		const styleErrors: string[] = [];
-		const invalidStyles: Record< string, string[] > = {};
 
 		const allConfigIds = new Set( [
 			...Object.keys( this.elementConfig ),
@@ -223,17 +223,18 @@ export class CompositionBuilder {
 			}
 
 			const styleConfig = this.elementStylesConfig[ configId ];
+			let hasInvalidStyles = false;
 			if ( styleConfig ) {
 				const validStylesPropValues: Record< string, AnyValue > = {};
 				for ( const [ styleName, stylePropValue ] of Object.entries( styleConfig ) ) {
+					if ( styleName === '$intention' ) {
+						continue;
+					}
 					const { valid, errors: validationErrors } = validateInput.validateStyles( {
 						[ styleName ]: stylePropValue,
 					} );
 					if ( ! valid ) {
-						if ( styleConfig.$intention ) {
-							invalidStyles[ element.id ] = invalidStyles[ element.id ] || [];
-							invalidStyles[ element.id ].push( styleName );
-						}
+						hasInvalidStyles = true;
 						styleErrors.push( ...( validationErrors || [] ) );
 					} else {
 						validStylesPropValues[ styleName ] = stylePropValue;
@@ -253,13 +254,15 @@ export class CompositionBuilder {
 				}
 			}
 
-			const customCSS = this.elementCustomCSS[ configId ];
-			if ( customCSS ) {
+			const intentionCss = typeof styleConfig?.$intention === 'string' ? styleConfig.$intention.trim() : '';
+			const fallbackCss = hasInvalidStyles && intentionCss ? intentionCss : '';
+			const mergedCustomCss = mergeCustomCssText( this.elementCustomCSS[ configId ], fallbackCss );
+			if ( mergedCustomCss ) {
 				try {
 					this.api.doUpdateElementProperty( {
 						elementId: element.id,
 						propertyName: '_styles',
-						propertyValue: { custom_css: customCSS },
+						propertyValue: { custom_css: mergedCustomCss },
 						elementType: node.tagName,
 					} );
 				} catch ( cssErr ) {
@@ -270,7 +273,7 @@ export class CompositionBuilder {
 			await this.awaitViewRender( element );
 		}
 
-		return { configErrors, styleErrors, invalidStyles };
+		return { configErrors, styleErrors };
 	}
 
 	async build( rootContainer: V1Element ) {
@@ -322,12 +325,11 @@ export class CompositionBuilder {
 			}
 		}
 
-		const { configErrors, styleErrors, invalidStyles } = await this.applyProperties();
+		const { configErrors, styleErrors } = await this.applyProperties();
 
 		return {
 			configErrors,
 			styleErrors,
-			invalidStyles,
 			rootContainers: [ ...this.rootContainers ],
 		};
 	}

package/src/mcp/tools/build-composition/tool.ts

@@ -11,7 +11,6 @@ import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { CompositionBuilder } from '../../../composition-builder/composition-builder';
 import { AVAILABLE_WIDGETS_URI_V4 } from '../../resources/available-widgets-resource';
 import { BEST_PRACTICES_URI, STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
-import { doUpdateElementProperty } from '../../utils/do-update-element-property';
 import { isWidgetAvailableForLLM } from '../../utils/element-data-util';
 import { getCompositionTargetContainer } from '../../utils/get-composition-target-container';
 import { BUILD_COMPOSITIONS_GUIDE_URI, generatePrompt } from './prompt';
@@ -71,33 +70,14 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 				compositionBuilder.setStylesConfig( stylesConfig );
 				compositionBuilder.setCustomCSS( customCSS );
 
-				const {
-					invalidStyles,
-					configErrors,
-					rootContainers: generatedRootContainers,
-				} = await compositionBuilder.build( targetContainer );
+				const { configErrors, rootContainers: generatedRootContainers } =
+					await compositionBuilder.build( targetContainer );
 
 				rootContainers.push( ...generatedRootContainers );
 				generatedXML = new XMLSerializer().serializeToString( compositionBuilder.getXML() );
 
 				if ( configErrors.length ) {
 					errors.push( ...configErrors.map( ( msg ) => new Error( msg ) ) );
-				} else {
-					Object.entries( invalidStyles ).forEach( ( [ elementId, rawCssRules ] ) => {
-						const customCss = {
-							value: rawCssRules.join( ';\n' ),
-						};
-						doUpdateElementProperty( {
-							elementId,
-							propertyName: '_styles',
-							propertyValue: {
-								_styles: {
-									custom_css: customCss,
-								},
-							},
-							elementType: 'widget',
-						} );
-					} );
 				}
 			} catch ( error ) {
 				errors.push( error as Error );

package/src/mcp/utils/__tests__/do-update-element-property.test.ts

@@ -1,5 +1,11 @@
-import { getWidgetsCache, updateElementSettings } from '@elementor/editor-elements';
+import {
+	getElementStyles,
+	getWidgetsCache,
+	updateElementSettings,
+	updateElementStyle,
+} from '@elementor/editor-elements';
 import { Schema } from '@elementor/editor-props';
+import { getVariantByMeta } from '@elementor/editor-styles';
 import { __privateRunCommandSync } from '@elementor/editor-v1-adapters';
 
 import { doUpdateElementProperty } from '../do-update-element-property';
@@ -22,6 +28,7 @@ jest.mock( '@elementor/editor-props', () => ( {
 
 jest.mock( '@elementor/editor-styles', () => ( {
 	getStylesSchema: jest.fn( () => ( {} ) ),
+	getVariantByMeta: jest.fn(),
 } ) );
 
 jest.mock( '@elementor/editor-v1-adapters', () => ( {
@@ -33,6 +40,9 @@ const ELEMENT_TYPE = 'atomic-heading';
 const EXPECTED_JSON_SCHEMA_SNIPPET = '{"type":"object"}';
 const PROPERTY_NAME = 'title';
 const PROP_SCHEMA_ENTRY = { key: 'titlePropKey' };
+const LOCAL_STYLE_ID = 'local-style-id';
+const EXISTING_CUSTOM_CSS = 'padding: 2rem;';
+const ADDITIONAL_CUSTOM_CSS = 'font-size: 1.5rem;';
 
 const widgetsCacheFixture = {
 	[ ELEMENT_TYPE ]: {
@@ -132,4 +142,77 @@ describe( 'doUpdateElementProperty', () => {
 			{ internal: true }
 		);
 	} );
+
+	it( 'replaces existing local style custom_css by default', () => {
+		// Arrange
+		jest.mocked( getElementStyles ).mockReturnValue( {
+			[ LOCAL_STYLE_ID ]: {
+				id: LOCAL_STYLE_ID,
+				label: 'local',
+				type: 'class',
+				variants: [],
+			},
+		} );
+		jest.mocked( getVariantByMeta ).mockReturnValue( {
+			meta: { breakpoint: 'desktop', state: null },
+			props: {},
+			custom_css: { raw: btoa( EXISTING_CUSTOM_CSS ) },
+		} );
+
+		// Act
+		doUpdateElementProperty( {
+			elementId: ELEMENT_ID,
+			elementType: ELEMENT_TYPE,
+			propertyName: '_styles',
+			propertyValue: {
+				custom_css: ADDITIONAL_CUSTOM_CSS,
+			},
+		} );
+
+		// Assert
+		expect( updateElementStyle ).toHaveBeenCalledWith(
+			expect.objectContaining( {
+				custom_css: {
+					raw: btoa( ADDITIONAL_CUSTOM_CSS ),
+				},
+			} )
+		);
+	} );
+
+	it( 'merges incoming custom_css with stored css when customCssWriteMode is merge-with-stored', () => {
+		// Arrange
+		jest.mocked( getElementStyles ).mockReturnValue( {
+			[ LOCAL_STYLE_ID ]: {
+				id: LOCAL_STYLE_ID,
+				label: 'local',
+				type: 'class',
+				variants: [],
+			},
+		} );
+		jest.mocked( getVariantByMeta ).mockReturnValue( {
+			meta: { breakpoint: 'desktop', state: null },
+			props: {},
+			custom_css: { raw: btoa( EXISTING_CUSTOM_CSS ) },
+		} );
+
+		// Act
+		doUpdateElementProperty( {
+			elementId: ELEMENT_ID,
+			elementType: ELEMENT_TYPE,
+			propertyName: '_styles',
+			propertyValue: {
+				custom_css: ADDITIONAL_CUSTOM_CSS,
+			},
+			customCssWriteMode: 'merge-with-stored',
+		} );
+
+		// Assert
+		expect( updateElementStyle ).toHaveBeenCalledWith(
+			expect.objectContaining( {
+				custom_css: {
+					raw: btoa( `${ EXISTING_CUSTOM_CSS }\n${ ADDITIONAL_CUSTOM_CSS }` ),
+				},
+			} )
+		);
+	} );
 } );

package/src/mcp/utils/__tests__/merge-custom-css.test.ts

@@ -0,0 +1,36 @@
+import { mergeCustomCssText, readStoredCustomCssText } from '../merge-custom-css';
+
+describe( 'mergeCustomCssText', () => {
+	it( 'merges explicit custom CSS with intention fallback CSS', () => {
+		// Arrange
+		const explicitCss = 'padding: 2rem;';
+		const intentionCss = 'font-size: 1.5rem;';
+
+		// Act
+		const merged = mergeCustomCssText( explicitCss, intentionCss );
+
+		// Assert
+		expect( merged ).toBe( 'padding: 2rem;\nfont-size: 1.5rem;' );
+	} );
+
+	it( 'returns a single CSS block when only one part is provided', () => {
+		// Act
+		const merged = mergeCustomCssText( undefined, 'color: red;' );
+
+		// Assert
+		expect( merged ).toBe( 'color: red;' );
+	} );
+} );
+
+describe( 'readStoredCustomCssText', () => {
+	it( 'decodes stored custom CSS text', () => {
+		// Arrange
+		const cssText = 'display: flex;';
+
+		// Act
+		const decoded = readStoredCustomCssText( btoa( cssText ) );
+
+		// Assert
+		expect( decoded ).toBe( cssText );
+	} );
+} );

package/src/mcp/utils/do-update-element-property.ts

@@ -6,18 +6,26 @@ import {
 	updateElementStyle,
 } from '@elementor/editor-elements';
 import { getPropSchemaFromCache, type PropValue, Schema, type TransformablePropValue } from '@elementor/editor-props';
-import { type CustomCss, getStylesSchema } from '@elementor/editor-styles';
+import { type CustomCss, getStylesSchema, getVariantByMeta } from '@elementor/editor-styles';
 import { __privateRunCommandSync as runCommandSync } from '@elementor/editor-v1-adapters';
 import { type Utils as IUtils } from '@elementor/editor-variables';
 import { type z } from '@elementor/schema';
 
+import { mergeCustomCssText, readStoredCustomCssText } from './merge-custom-css';
+
 // TODO: see https://elementor.atlassian.net/browse/ED-22513 for better cross-module access
 type XElementor = z.infer< z.ZodAny >;
+const LOCAL_STYLE_META = {
+	breakpoint: 'desktop',
+	state: null,
+} as const;
+type CustomCssWriteMode = 'replace' | 'merge-with-stored';
 type OwnParams = {
 	elementId: string;
 	elementType: string;
 	propertyName: string;
 	propertyValue: string | PropValue | TransformablePropValue< string, unknown >;
+	customCssWriteMode?: CustomCssWriteMode;
 };
 
 export function resolvePropValue( value: unknown, forceKey?: string ): PropValue {
@@ -35,7 +43,7 @@ export function resolvePropValue( value: unknown, forceKey?: string ): PropValue
  * Also, it supports updating styles "on-the-way" by checking for "_styles" property with PropValue bag that fits the common style schema.
  */
 export const doUpdateElementProperty = ( params: OwnParams ) => {
-	const { elementId, propertyName, propertyValue, elementType } = params;
+	const { elementId, propertyName, propertyValue, elementType, customCssWriteMode = 'replace' } = params;
 	if ( propertyName === '_styles' ) {
 		const elementStyles = getElementStyles( elementId ) || {};
 		const propertyMapValue = propertyValue as Record< string, PropValue >;
@@ -52,6 +60,10 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 				return [ key, resolvePropValue( val, propKey ) ];
 			} )
 		);
+		const localStyle = Object.values( elementStyles ).find( ( style ) => style.label === 'local' );
+		const existingCustomCssText = localStyle
+			? readStoredCustomCssText( getVariantByMeta( localStyle, LOCAL_STYLE_META )?.custom_css?.raw )
+			: '';
 		let customCss: CustomCss | undefined;
 		Object.keys( propertyMapValue as Record< string, unknown > ).forEach( ( stylePropName ) => {
 			const propertyRawSchema = styleSchema[ stylePropName ];
@@ -63,9 +75,17 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 				if ( ! customCssValue ) {
 					customCssValue = '';
 				}
-				customCss = {
-					raw: btoa( customCssValue as string ),
-				};
+				const customCssText =
+					customCssWriteMode === 'merge-with-stored'
+						? mergeCustomCssText( existingCustomCssText, customCssValue as string )
+						: String( customCssValue );
+				if ( customCssText ) {
+					customCss = {
+						raw: btoa( customCssText ),
+					};
+				} else {
+					customCss = { raw: btoa( '' ) };
+				}
 				return;
 			}
 			const isSupported = !! propertyRawSchema;
@@ -83,7 +103,6 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 			}
 		} );
 		delete transformedStyleValues.custom_css;
-		const localStyle = Object.values( elementStyles ).find( ( style ) => style.label === 'local' );
 		if ( ! localStyle ) {
 			createElementStyle( {
 				elementId,

package/src/mcp/utils/merge-custom-css.ts

@@ -0,0 +1,19 @@
+const CUSTOM_CSS_SEPARATOR = '\n';
+
+export const mergeCustomCssText = ( ...cssParts: Array< string | undefined > ): string =>
+	cssParts
+		.map( ( cssPart ) => cssPart?.trim() )
+		.filter( ( cssPart ): cssPart is string => !! cssPart )
+		.join( CUSTOM_CSS_SEPARATOR );
+
+export const readStoredCustomCssText = ( raw: string | undefined ): string => {
+	if ( ! raw ) {
+		return '';
+	}
+
+	try {
+		return atob( raw );
+	} catch {
+		return '';
+	}
+};