@elementor/editor-canvas 4.1.0-838 → 4.1.0-beta2

package/src/mcp/tools/configure-element/prompt.ts

@@ -1,6 +1,14 @@
+import { toolPrompts } from '@elementor/editor-mcp';
+
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 
-export const configureElementToolPrompt = `Configure an existing element on the page.
+export const CONFIGURE_ELEMENT_GUIDE_URI = 'elementor://canvas/tools/configure-element-guide';
+
+export const generatePrompt = () => {
+	const configureElementToolPrompt = toolPrompts( 'configure-element' );
+
+	configureElementToolPrompt.description( `
+Configure an existing element on the page.
 
 # **CRITICAL - REQUIRED INFORMATION (Must read before using this tool)**
 1. [${ WIDGET_SCHEMA_URI }]
@@ -15,12 +23,6 @@ Before using this tool, check the definitions of the elements PropTypes at the r
 All widgets share a common _style property for styling, which uses the common styles schema.
 Retrieve and check the common styles schema at the resource list "styles-schema" at editor-canvas__elementor://styles/schema/{category}
 
-# Parameters
-- propertiesToChange: An object containing the properties to change, with their new values. MANDATORY. When updating a style only, provide an empty object.
-- stylePropertiesToChange: An object containing the style properties to change, with their new values. OPTIONAL
-- elementId: The ID of the element to configure. MANDATORY
-- elementType: The type of the element to configure (i.e. e-heading, e-button). MANDATORY
-
 # When to use this tool
 When a user requires to change anything in an element, such as updating text, colors, sizes, or other configurable properties.
 This tool handles elements of type "widget".
@@ -49,7 +51,7 @@ You can use multiple property changes at once by providing multiple entries in t
 Some properties are nested, use the root property name, then objects with nested values inside, as the complete schema suggests.
 
 Make sure you have the "widget-schema-by-type" resource available to retrieve the PropType schema for the element type you are configuring.
-Make sure you have to "styles-schema" resources available to retrieve the common styles schema.
+Make sure you have the "styles-schema" resources available to retrieve the common styles schema.
 
 # How to configure elements
 We use a dedicated PropType Schema for configuring elements, including styles. When you configure an element, you must use the EXACT PropType Value as defined in the schema.
@@ -57,8 +59,26 @@ For styleProperties, use the style schema provided, as it also uses the PropType
 For all non-primitive types, provide the key property as defined in the schema as $$type in the generated object, as it is MANDATORY for parsing.
 
 Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property from the original configuration for every property you are changing.
+` );
+
+	configureElementToolPrompt.parameter( 'elementId', 'The ID of the element to configure. MANDATORY.' );
+
+	configureElementToolPrompt.parameter(
+		'elementType',
+		'The type of the element to configure (i.e. e-heading, e-button). MANDATORY.'
+	);
+
+	configureElementToolPrompt.parameter(
+		'propertiesToChange',
+		'An object containing the properties to change, with their new values. MANDATORY. When updating a style only, provide an empty object.'
+	);
+
+	configureElementToolPrompt.parameter(
+		'stylePropertiesToChange',
+		'An object containing the style properties to change, with their new values. OPTIONAL.'
+	);
 
-# Example
+	configureElementToolPrompt.example( `
 \`\`\`json
 {
   propertiesToChange: {
@@ -74,7 +94,7 @@ Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property fr
   },
   stylePropertiesToChange: {
     'line-height': {
-      $$type: 'size', // MANDATORY do not forget to include the correct $$type for every property
+      $$type: 'size',
       value: {
         size: {
           $$type: 'number',
@@ -91,8 +111,21 @@ Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property fr
   elementType: 'element-type'
 };
 \`\`\`
+` );
 
-<IMPORTANT>
-The $$type property is MANDATORY for every value, it is required to parse the value and apply application-level effects.
-</IMPORTANT>
-`;
+	configureElementToolPrompt.instruction(
+		'The $$type property is MANDATORY for every value; it is required to parse the value and apply application-level effects.'
+	);
+
+	configureElementToolPrompt.instruction( `
+V4 only: If MCP fails, give manual steps using V4 UI.
+
+V4 Editor structure:
+Panel tabs: General (→ Settings section: ID, Tag, Link), Style, Interactions.
+NO Advanced tab. Never mention Advanced tab.
+` );
+
+	return configureElementToolPrompt.prompt();
+};
+
+export const CONFIGURE_ELEMENT_GUIDE_TEXT = generatePrompt();

package/src/mcp/tools/configure-element/tool.ts

@@ -4,20 +4,34 @@ import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 import { doUpdateElementProperty } from '../../utils/do-update-element-property';
 import { validateInput } from '../../utils/validate-input';
-import { configureElementToolPrompt } from './prompt';
+import { CONFIGURE_ELEMENT_GUIDE_URI, generatePrompt } from './prompt';
 import { inputSchema as schema, outputSchema } from './schema';
 
 export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
-	const { addTool } = reg;
+	const { addTool, resource } = reg;
+
+	resource(
+		'configure-element-guide',
+		CONFIGURE_ELEMENT_GUIDE_URI,
+		{
+			title: 'Configure Element Guide',
+			description: 'Detailed guide for using the configure-element tool',
+			mimeType: 'text/plain',
+		},
+		async ( uri: URL ) => ( {
+			contents: [ { uri: uri.href, mimeType: 'text/plain', text: generatePrompt() } ],
+		} )
+	);
 
 	addTool( {
 		name: 'configure-element',
-		description: configureElementToolPrompt,
+		description: "Configure an existing V4 element's properties and styles. Read the guide resource before use.",
 		schema,
 		outputSchema,
 		requiredResources: [
 			{ description: 'Widgets schema', uri: WIDGET_SCHEMA_URI },
 			{ description: 'Styles schema', uri: STYLE_SCHEMA_URI },
+			{ description: 'Configure element guide', uri: CONFIGURE_ELEMENT_GUIDE_URI },
 		],
 		modelPreferences: {
 			hints: [ { name: 'claude-sonnet-4-5' } ],

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

@@ -0,0 +1,135 @@
+import { getWidgetsCache, updateElementSettings } from '@elementor/editor-elements';
+import { Schema } from '@elementor/editor-props';
+import { __privateRunCommandSync } from '@elementor/editor-v1-adapters';
+
+import { doUpdateElementProperty } from '../do-update-element-property';
+
+jest.mock( '@elementor/editor-elements', () => ( {
+	createElementStyle: jest.fn(),
+	getElementStyles: jest.fn(),
+	getWidgetsCache: jest.fn(),
+	updateElementSettings: jest.fn(),
+	updateElementStyle: jest.fn(),
+} ) );
+
+jest.mock( '@elementor/editor-props', () => ( {
+	getPropSchemaFromCache: jest.fn(),
+	Schema: {
+		adjustLlmPropValueSchema: jest.fn( ( value: unknown ) => value ),
+		validatePropValue: jest.fn(),
+	},
+} ) );
+
+jest.mock( '@elementor/editor-styles', () => ( {
+	getStylesSchema: jest.fn( () => ( {} ) ),
+} ) );
+
+jest.mock( '@elementor/editor-v1-adapters', () => ( {
+	__privateRunCommandSync: jest.fn(),
+} ) );
+
+const ELEMENT_ID = 'test-element-id';
+const ELEMENT_TYPE = 'atomic-heading';
+const EXPECTED_JSON_SCHEMA_SNIPPET = '{"type":"object"}';
+const PROPERTY_NAME = 'title';
+const PROP_SCHEMA_ENTRY = { key: 'titlePropKey' };
+
+const widgetsCacheFixture = {
+	[ ELEMENT_TYPE ]: {
+		atomic_props_schema: {
+			[ PROPERTY_NAME ]: PROP_SCHEMA_ENTRY,
+		},
+	},
+};
+
+describe( 'doUpdateElementProperty', () => {
+	beforeEach( () => {
+		Object.assign( window, {
+			elementorV2: {
+				editorVariables: {
+					Utils: {
+						globalVariablesLLMResolvers: [],
+					},
+				},
+			},
+		} );
+		// @ts-ignore: Mock values for test
+		jest.mocked( getWidgetsCache ).mockReturnValue( widgetsCacheFixture );
+		// @ts-ignore: Mock values for test
+		jest.mocked( Schema.adjustLlmPropValueSchema ).mockImplementation( ( value: unknown ) => value );
+		jest.mocked( Schema.validatePropValue ).mockReset();
+	} );
+
+	afterEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'throws when Schema.validatePropValue reports invalid PropValue and does not persist', () => {
+		// Arrange
+		const propertyValue = { invalid: true };
+		jest.mocked( Schema.validatePropValue ).mockReturnValue( {
+			jsonSchema: EXPECTED_JSON_SCHEMA_SNIPPET,
+			valid: false,
+			errorMessages: 'error',
+			errors: [],
+		} );
+
+		// Act
+		let thrown: unknown;
+		try {
+			doUpdateElementProperty( {
+				elementId: ELEMENT_ID,
+				elementType: ELEMENT_TYPE,
+				propertyName: PROPERTY_NAME,
+				propertyValue,
+			} );
+		} catch ( error ) {
+			thrown = error;
+		}
+
+		// Assert
+		expect( thrown ).toBeInstanceOf( Error );
+		expect( ( thrown as Error ).message ).toMatch( /Invalid PropValue/ );
+		expect( ( thrown as Error ).message ).toContain( ELEMENT_ID );
+		expect( ( thrown as Error ).message ).toContain( PROP_SCHEMA_ENTRY.key );
+		expect( ( thrown as Error ).message ).toContain( EXPECTED_JSON_SCHEMA_SNIPPET );
+		expect( Schema.validatePropValue ).toHaveBeenCalledWith( PROP_SCHEMA_ENTRY, propertyValue );
+		expect( updateElementSettings ).not.toHaveBeenCalled();
+		expect( __privateRunCommandSync ).not.toHaveBeenCalled();
+	} );
+
+	it( 'updates settings when Schema.validatePropValue reports valid PropValue', () => {
+		// Arrange
+		const propertyValue = 'resolved-title';
+		jest.mocked( Schema.validatePropValue ).mockReturnValue( {
+			jsonSchema: EXPECTED_JSON_SCHEMA_SNIPPET,
+			valid: true,
+			errorMessages: [],
+			errors: [],
+		} );
+
+		// Act
+		doUpdateElementProperty( {
+			elementId: ELEMENT_ID,
+			elementType: ELEMENT_TYPE,
+			propertyName: PROPERTY_NAME,
+			propertyValue,
+		} );
+
+		// Assert
+		expect( Schema.validatePropValue ).toHaveBeenCalledWith( PROP_SCHEMA_ENTRY, propertyValue );
+		expect( updateElementSettings ).toHaveBeenCalledTimes( 1 );
+		expect( updateElementSettings ).toHaveBeenCalledWith( {
+			id: ELEMENT_ID,
+			props: {
+				[ PROPERTY_NAME ]: propertyValue,
+			},
+			withHistory: false,
+		} );
+		expect( __privateRunCommandSync ).toHaveBeenCalledWith(
+			'document/save/set-is-modified',
+			{ status: true },
+			{ internal: true }
+		);
+	} );
+} );

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

@@ -7,6 +7,7 @@ import {
 } from '@elementor/editor-elements';
 import { getPropSchemaFromCache, type PropValue, Schema, type TransformablePropValue } from '@elementor/editor-props';
 import { type CustomCss, getStylesSchema } 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';
 
@@ -128,6 +129,14 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 	}
 	const propKey = elementPropSchema[ propertyName ].key;
 	const value = resolvePropValue( propertyValue, propKey );
+	const { valid, jsonSchema } = Schema.validatePropValue( elementPropSchema[ propertyName ], propertyValue );
+	if ( ! valid ) {
+		throw new Error(
+			`Invalid PropValue for elementId: ${ elementId }. PropKey: ${ propKey }, PropValue: ${ JSON.stringify(
+				propertyValue
+			) }\nExpected Schema: ${ jsonSchema }`
+		);
+	}
 	updateElementSettings( {
 		id: elementId,
 		props: {
@@ -135,4 +144,5 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 		},
 		withHistory: false,
 	} );
+	runCommandSync( 'document/save/set-is-modified', { status: true }, { internal: true } );
 };

package/src/mcp/utils/element-data-util.ts

@@ -17,6 +17,10 @@ export function isWidgetAvailableForLLM( config: V1ElementConfig | undefined ):
 	if ( config.meta?.llm_support === false ) {
 		return false;
 	}
+	// TODO: Restore component once working in compositions
+	if ( config.title === 'Component' ) {
+		return false;
+	}
 	if ( config.atomic_props_schema ) {
 		return true;
 	}

package/src/sync/global-styles-imported-event.ts

@@ -4,5 +4,5 @@ export const GLOBAL_STYLES_IMPORTED_EVENT = 'elementor/global-styles/imported';
 
 export type ImportedGlobalStylesPayload = {
 	global_variables?: { data: StyleVariables };
-	global_classes?: { items: StyleDefinitionsMap; order: StyleDefinitionID[] };
+	global_classes?: { added_items: StyleDefinitionsMap; added_items_order: StyleDefinitionID[] };
 };