@elementor/editor-canvas 4.3.0-992 → 4.3.0-994

package/package.json

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

package/src/index.ts

@@ -44,4 +44,4 @@ export { UnknownStyleTypeError, UnknownStyleStateError } from './renderers/error
 export { useCanvasDocument } from './hooks/use-canvas-document';
 export { useEscapeOnCanvas } from './hooks/use-escape-on-canvas';
 export { doAfterRender } from './utils/after-render';
-export { ELEMENT_ADDED_EVENT, type ElementAddedEvent } from './mcp/tools/build-composition/tool';
+export { ELEMENT_ADDED_EVENT, type ElementAddedEvent } from './sync/element-added-event';

package/src/mcp/canvas-mcp.ts

@@ -10,7 +10,7 @@ import { initEditorStateResource } from './resources/editor-state-resource';
 import { initGeneralContextResource } from './resources/general-context-resource';
 import { initSelectedElementResource } from './resources/selected-element-resource';
 import { initWidgetsSchemaResource } from './resources/widgets-schema-resource';
-import { initBuildCompositionsTool } from './tools/build-composition/tool';
+import { initBuildCompositionTool } from './tools/build-composition/tool';
 import { initConfigureElementTool } from './tools/configure-element/tool';
 import { initCreateElementTool } from './tools/create-element/tool';
 import { initGetElementConfigTool } from './tools/get-element-config/tool';
@@ -29,9 +29,9 @@ export const initCanvasMcp = ( reg: MCPRegistryEntry ) => {
 	initEditorStateResource( reg );
 	initGeneralContextResource( reg );
 	initBestPracticesResource( reg );
-	initBuildCompositionsTool( reg );
 	initGetElementConfigTool( reg );
 	initConfigureElementTool( reg );
 	initCreateElementTool( reg );
+	initBuildCompositionTool( reg );
 	initBreakpointsResource( reg );
 };

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

@@ -1,244 +1,133 @@
-import { getCurrentDocument } from '@elementor/editor-documents';
-import {
-	createElement,
-	deleteElement,
-	getContainer,
-	getWidgetsCache,
-	type V1Element,
-	type V1ElementData,
-} from '@elementor/editor-elements';
+import { getCurrentDocument, reloadCurrentDocument } from '@elementor/editor-documents';
+import { getContainer, selectElement } from '@elementor/editor-elements';
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
-import { dispatchMcpStylesAppliedEvent } from '@elementor/editor-mcp';
-
-import { CompositionBuilder } from '../../../composition-builder/composition-builder';
-import { trackCanvasEvent } from '../../../utils/tracking';
-import { AVAILABLE_WIDGETS_URI_V4 } from '../../resources/available-widgets-resource';
-import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
-import { BEST_PRACTICES_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
-import { convertStyleBlocksToAtomic } from '../../utils/convert-css-to-atomic';
-import { isWidgetAvailableForLLM } from '../../utils/element-data-util';
-import { getCompositionTargetContainer } from '../../utils/get-composition-target-container';
-import { BUILD_COMPOSITIONS_GUIDE_URI, generatePrompt } from './prompt';
-import { inputSchema as schema, outputSchema } from './schema';
-import { adaptLeafRootParams } from './xml-leaf-wrapper';
-
-export type ElementAddedEvent = {
-	element: V1ElementData;
-	executedBy: 'mcp_tool' | 'user';
+import { AxiosError, type HttpResponse, httpService } from '@elementor/http-client';
+import { z } from '@elementor/schema';
+
+const MCP_PROXY_URL = 'elementor/v1/mcp-proxy';
+
+type BuildCompositionResponse = {
+	success: boolean;
+	post_id: number;
+	root_element_ids: string[];
+	preview_url: string;
+	version: string;
+	resolved_xml: string;
+	llm_instructions: string;
+	warnings?: string[];
 };
 
-export const ELEMENT_ADDED_EVENT = 'elementor/canvas/element-added';
-
-export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
-	const { addTool, resource } = reg;
+export const initBuildCompositionTool = ( reg: MCPRegistryEntry ) => {
+	const { addTool } = reg;
 
-	resource(
-		'build-compositions-guide',
-		BUILD_COMPOSITIONS_GUIDE_URI,
-		{
-			title: 'Build Compositions Guide',
-			description: 'Detailed guide for using the build-compositions tool',
-			mimeType: 'text/plain',
+	addTool( {
+		name: 'build-composition',
+		description:
+			'Build a V4 element composition on the Elementor canvas via the server-side MCP ability. ' +
+			'Pass the raw XML tags directly as xmlStructure — do NOT wrap the value in <![CDATA[ ... ]]>, ' +
+			'code fences, or quotes. The document is saved as a draft. Reload the editor after calling ' +
+			'this tool to see the result.',
+		schema: {
+			xmlStructure: z
+				.string()
+				.describe(
+					'Valid XML structure with custom Elementor widget tags. Every element MUST have a unique ' +
+						'configuration-id attribute (e.g. <e-heading configuration-id="hero-title"></e-heading>). ' +
+						'No attributes, classes, IDs, or text nodes in XML. Pass raw XML — do not wrap in CDATA.'
+				),
+			elementConfig: z
+				.record(
+					z.string().describe( 'configuration-id' ),
+					z.record( z.string().describe( 'property name' ), z.any().describe( 'PropValue' ) )
+				)
+				.optional()
+				.describe( 'Map configuration-id → widget PropValues ($$type + value).' ),
+			style: z
+				.record(
+					z.string().describe( 'configuration-id' ),
+					z.record( z.string().describe( 'CSS property name' ), z.string().describe( 'CSS value' ) )
+				)
+				.optional()
+				.describe(
+					'Map configuration-id → raw CSS declarations (property → value strings; no selectors). ' +
+						'Server converts to native styles; unconvertible declarations become the element custom CSS.'
+				),
+			parentId: z
+				.string()
+				.optional()
+				.describe( "ID of the parent container. Omit or pass 'document' to insert at document root." ),
+			dryRun: z
+				.boolean()
+				.optional()
+				.describe( 'If true, validate and return the resolved tree without persisting.' ),
+		},
+		outputSchema: {
+			rootElementIds: z.array( z.string() ),
+			previewUrl: z.string(),
+			version: z.string(),
+			resolvedXml: z.string(),
+			llmInstructions: z.string(),
+			warnings: z.array( z.string() ).optional(),
 		},
-		async ( uri: URL ) => ( {
-			contents: [ { uri: uri.href, mimeType: 'text/plain', text: generatePrompt() } ],
-		} )
-	);
+		handler: async ( { xmlStructure, elementConfig, style, parentId, dryRun } ) => {
+			const document = getCurrentDocument();
 
-	addTool( {
-		name: 'build-compositions',
-		description: 'Build V4 element compositions on the Elementor canvas. Read the guide resource before use.',
-		schema,
-		requiredResources: [
-			{ description: 'Build compositions guide', uri: BUILD_COMPOSITIONS_GUIDE_URI },
-			{ description: 'Widgets schema', uri: WIDGET_SCHEMA_URI },
-			{ description: 'Global Classes', uri: 'elementor://global-classes' },
-			{ description: 'Global Variables', uri: 'elementor://global-variables' },
-			{ description: 'Styles best practices', uri: BEST_PRACTICES_URI },
-			{ description: 'Available widgets for this tool', uri: AVAILABLE_WIDGETS_URI_V4 },
-			{ description: 'Dynamic tags catalog', uri: DYNAMIC_TAGS_URI },
-		],
-		outputSchema,
-		handler: async ( rawParams ) => {
-			assertCompositionXmlUsesV4WidgetsOnly( rawParams.xmlStructure );
-			const { stylesConfig: convertedStyles, customCSS } = await convertCompositionStyles( rawParams.style );
-			const { xmlStructure, elementConfig, stylesConfig } = adaptLeafRootParams( {
-				...rawParams,
-				stylesConfig: convertedStyles,
-				widgetsCache: getWidgetsCache() ?? {},
-			} );
+			if ( ! document?.id ) {
+				throw new Error( 'No active document found.' );
+			}
 
-			let generatedXML: string = '';
-			const errors: Error[] = [];
-			const rootContainers: V1Element[] = [];
-			const documentContainer = getContainer( 'document' ) as unknown as V1Element;
-			const currentDocument = getCurrentDocument();
-			const targetContainer = getCompositionTargetContainer( documentContainer, currentDocument?.type.value );
 			try {
-				const compositionBuilder = CompositionBuilder.fromXMLString( xmlStructure, {
-					createElement,
-					deleteElement,
-					getWidgetsCache,
+				const { data } = await httpService().post< HttpResponse< BuildCompositionResponse > >( MCP_PROXY_URL, {
+					tool: 'build-composition',
+					input: {
+						post_id: document.id,
+						xml_structure: xmlStructure,
+						element_config: elementConfig ?? {},
+						style: style ?? {},
+						parent_id: parentId ?? 'document',
+						dry_run: dryRun ?? false,
+					},
 				} );
-				compositionBuilder.setElementConfig( elementConfig );
-				compositionBuilder.setStylesConfig( stylesConfig );
-				compositionBuilder.setCustomCSS( customCSS );
-
-				const {
-					configErrors,
-					formErrors,
-					rootContainers: generatedRootContainers,
-				} = await compositionBuilder.build( targetContainer );
-
-				rootContainers.push( ...generatedRootContainers );
-				generatedXML = new XMLSerializer().serializeToString( compositionBuilder.getXML() );
 
-				rootContainers.forEach( ( container ) => {
-					const elementData = container.model?.toJSON();
+				if ( ! dryRun ) {
+					await reloadCurrentDocument();
 
-					if ( elementData ) {
-						onElementAdded( elementData as V1ElementData );
+					const [ firstRootId ] = data.data.root_element_ids;
+					if ( firstRootId ) {
+						selectElement( firstRootId );
+						getContainer( firstRootId )?.view?.el?.scrollIntoView( {
+							behavior: 'smooth',
+							block: 'center',
+						} );
 					}
-				} );
-
-				Object.values( stylesConfig ).forEach( ( styleValue ) => {
-					dispatchMcpStylesAppliedEvent( { styleValue } );
-				} );
-
-				if ( configErrors.length ) {
-					errors.push( ...configErrors.map( ( msg ) => new Error( msg ) ) );
 				}
 
-				if ( formErrors.length ) {
-					errors.push( ...formErrors.map( ( msg ) => new Error( msg ) ) );
-				}
+				return {
+					rootElementIds: data.data.root_element_ids,
+					previewUrl: data.data.preview_url,
+					version: data.data.version,
+					resolvedXml: data.data.resolved_xml,
+					llmInstructions: data.data.llm_instructions,
+					warnings: data.data.warnings,
+				};
 			} catch ( error ) {
-				errors.push( error as Error );
-			}
-
-			if ( errors.length ) {
-				rootContainers.forEach( ( rootContainer ) => {
-					deleteElement( {
-						container: rootContainer,
-						options: { useHistory: false },
-					} );
-				} );
-
-				const errorMessages = errors
-					.map( ( e ) => {
-						if ( typeof e === 'string' ) {
-							return e;
-						}
-						if ( e instanceof Error ) {
-							return e.message || String( e );
-						}
-
-						if ( typeof e === 'object' && e !== null ) {
-							return JSON.stringify( e );
-						}
-						return String( e );
-					} )
-					.filter(
-						( msg ) => msg && msg.trim() !== '' && msg !== '{}' && msg !== 'null' && msg !== 'undefined'
-					);
-
-				if ( errorMessages.length === 0 ) {
-					throw new Error(
-						'Failed to build composition: Unknown error occurred. No error details available.'
-					);
-				}
-
-				const errorText = `Failed to build composition with the following errors:\n\n${ errorMessages.join(
-					'\n\n'
-				) }`;
-				throw new Error( errorText );
+				throw new Error( getErrorMessage( error ) );
 			}
-			return {
-				xmlStructure: generatedXML,
-				errors: errors?.length
-					? errors.map( ( e ) => ( typeof e === 'string' ? e : e.message ) ).join( '\n\n' )
-					: undefined,
-				llm_instructions: `The composition was built successfully with element IDs embedded in the XML.
-
-**CRITICAL NEXT STEPS** (Follow in order):
-1. **Apply Global Classes**: Use "apply-global-class" tool to apply the global classes you created BEFORE building this composition
-   - Check the created element IDs in the returned XML
-   - Apply semantic classes (heading-primary, button-cta, etc.) to appropriate elements
-
-2. **Fine-tune if needed**: Use "configure-element" tool only for element-specific adjustments that don't warrant global classes
-
-Remember: Global classes ensure design consistency and reusability. Don't skip applying them!
-`,
-			};
 		},
 	} );
 };
 
-async function convertCompositionStyles( style: Record< string, Record< string, string > > ) {
-	const stylesConfig: Record< string, Record< string, unknown > > = {};
-	const customCSS: Record< string, string > = {};
-
-	if ( ! style || Object.keys( style ).length === 0 ) {
-		return { stylesConfig, customCSS };
-	}
-
-	const results = await convertStyleBlocksToAtomic( style );
-
-	for ( const [ configId, { props, customCss } ] of Object.entries( results ) ) {
-		stylesConfig[ configId ] = props;
-		if ( customCss ) {
-			customCSS[ configId ] = customCss;
+function getErrorMessage( error: unknown ): string {
+	if ( error instanceof AxiosError ) {
+		const data = error.response?.data as { message?: string; code?: string } | undefined;
+		if ( data?.message ) {
+			return data.code ? `${ data.code }: ${ data.message }` : data.message;
 		}
 	}
 
-	return { stylesConfig, customCSS };
-}
-
-function assertCompositionXmlUsesV4WidgetsOnly( xmlStructure: string ) {
-	const doc = new DOMParser().parseFromString( xmlStructure, 'application/xml' );
-	if ( doc.querySelector( 'parsererror' ) ) {
-		throw new Error( 'Failed to parse XML string: ' + doc );
+	if ( error instanceof Error ) {
+		return error.message;
 	}
-	const widgetsCache = getWidgetsCache() ?? {};
-	for ( const node of doc.querySelectorAll( '*' ) ) {
-		const type = node.tagName;
-		const widgetData = widgetsCache[ type ];
 
-		if ( ! widgetData ) {
-			continue;
-		}
-		if ( widgetData.elType !== 'widget' ) {
-			continue;
-		}
-		if ( ! isWidgetAvailableForLLM( widgetData ) || ! widgetData.atomic_props_schema ) {
-			throw new Error( `This tool does not support element type: ${ type }` );
-		}
-	}
-}
-
-function onElementAdded( element: V1ElementData ) {
-	const elType = element.elType ?? '';
-	const widgetType = element.widgetType ?? '';
-	const elementName = elType === 'widget' ? widgetType : elType;
-
-	trackCanvasEvent( {
-		eventName: 'add_element',
-		executed_by: 'mcp_tool',
-		element_name: elementName,
-		element_type: elType,
-		widget_type: widgetType,
-	} );
-
-	const event: ElementAddedEvent = {
-		element,
-		executedBy: 'mcp_tool',
-	};
-
-	window.dispatchEvent( new CustomEvent( ELEMENT_ADDED_EVENT, { detail: event } ) );
-
-	if ( element.elements?.length ) {
-		element.elements?.forEach( ( childElement ) => {
-			onElementAdded( childElement );
-		} );
-	}
+	return 'build-composition failed with an unknown error.';
 }

package/src/sync/element-added-event.ts

@@ -0,0 +1,8 @@
+import { type V1ElementData } from '@elementor/editor-elements';
+
+export const ELEMENT_ADDED_EVENT = 'elementor/canvas/element-added';
+
+export type ElementAddedEvent = {
+	element: V1ElementData;
+	executedBy: 'mcp_tool' | 'user';
+};