@elementor/editor-canvas 3.33.0-99 → 3.34.2

package/src/legacy/create-templated-element-type.ts

@@ -1,13 +1,13 @@
 import type { V1ElementConfig } from '@elementor/editor-elements';
 
 import { type DomRenderer } from '../renderers/create-dom-renderer';
-import { createPropsResolver, type PropsResolver } from '../renderers/create-props-resolver';
+import { createPropsResolver } from '../renderers/create-props-resolver';
 import { settingsTransformersRegistry } from '../settings-transformers-registry';
 import { signalizedProcess } from '../utils/signalized-process';
 import { createElementViewClassDeclaration } from './create-element-type';
 import { type ElementType, type ElementView, type LegacyWindow } from './types';
 
-type CreateTypeOptions = {
+export type CreateTemplatedElementTypeOptions = {
 	type: string;
 	renderer: DomRenderer;
 	element: TemplatedElementConfig;
@@ -17,30 +17,23 @@ type TemplatedElementConfig = Required<
 	Pick< V1ElementConfig, 'twig_templates' | 'twig_main_template' | 'atomic_props_schema' | 'base_styles_dictionary' >
 >;
 
-export function createTemplatedElementType( { type, renderer, element }: CreateTypeOptions ): typeof ElementType {
+export function createTemplatedElementType( {
+	type,
+	renderer,
+	element,
+}: CreateTemplatedElementTypeOptions ): typeof ElementType {
 	const legacyWindow = window as unknown as LegacyWindow;
 
-	Object.entries( element.twig_templates ).forEach( ( [ key, template ] ) => {
-		renderer.register( key, template );
-	} );
-
-	const propsResolver = createPropsResolver( {
-		transformers: settingsTransformersRegistry,
-		schema: element.atomic_props_schema,
-	} );
-
 	return class extends legacyWindow.elementor.modules.elements.types.Widget {
 		getType() {
 			return type;
 		}
 
 		getView() {
-			return createTemplatedElementViewClassDeclaration( {
+			return createTemplatedElementView( {
 				type,
 				renderer,
-				propsResolver,
-				baseStylesDictionary: element.base_styles_dictionary,
-				templateKey: element.twig_main_template,
+				element,
 			} );
 		}
 	};
@@ -55,23 +48,26 @@ export function canBeTemplated( element: Partial< TemplatedElementConfig > ): el
 	);
 }
 
-type CreateViewOptions = {
-	type: string;
-	renderer: DomRenderer;
-	propsResolver: PropsResolver;
-	templateKey: string;
-	baseStylesDictionary: Record< string, string >;
-};
-
-function createTemplatedElementViewClassDeclaration( {
+export function createTemplatedElementView( {
 	type,
 	renderer,
-	propsResolver: resolveProps,
-	templateKey,
-	baseStylesDictionary,
-}: CreateViewOptions ): typeof ElementView {
+	element,
+}: CreateTemplatedElementTypeOptions ): typeof ElementView {
 	const BaseView = createElementViewClassDeclaration();
 
+	const templateKey = element.twig_main_template;
+
+	const baseStylesDictionary = element.base_styles_dictionary;
+
+	Object.entries( element.twig_templates ).forEach( ( [ key, template ] ) => {
+		renderer.register( key, template );
+	} );
+
+	const resolveProps = createPropsResolver( {
+		transformers: settingsTransformersRegistry,
+		schema: element.atomic_props_schema,
+	} );
+
 	return class extends BaseView {
 		#abortController: AbortController | null = null;
 
@@ -83,14 +79,28 @@ function createTemplatedElementViewClassDeclaration( {
 			this.render();
 		}
 
-		// Overriding Marionette original render method to inject our renderer.
-		async _renderTemplate() {
-			this.#beforeRenderTemplate();
-
+		// Override `render` function to support async `_renderTemplate`
+		// Note that `_renderChildren` asynchronity is still NOT supported, so only the parent element rendering can be async
+		render() {
 			this.#abortController?.abort();
 			this.#abortController = new AbortController();
 
 			const process = signalizedProcess( this.#abortController.signal )
+				.then( () => this.#beforeRender() )
+				.then( () => this._renderTemplate() )
+				.then( () => {
+					this._renderChildren();
+					this.#afterRender();
+				} );
+
+			return process.execute();
+		}
+
+		// Overriding Marionette original `_renderTemplate` method to inject our renderer.
+		async _renderTemplate() {
+			this.triggerMethod( 'before:render:template' );
+
+			const process = signalizedProcess( this.#abortController?.signal as AbortSignal )
 				.then( ( _, signal ) => {
 					const settings = this.model.get( 'settings' ).toJSON();
 
@@ -99,12 +109,15 @@ function createTemplatedElementViewClassDeclaration( {
 						signal,
 					} );
 				} )
-				.then( ( resolvedSettings ) => {
+				.then( ( settings ) => {
+					return this.afterSettingsResolve( settings );
+				} )
+				.then( async ( settings ) => {
 					// Same as the Backend.
 					const context = {
 						id: this.model.get( 'id' ),
 						type,
-						settings: resolvedSettings,
+						settings,
 						base_styles: baseStylesDictionary,
 					};
 
@@ -114,18 +127,30 @@ function createTemplatedElementViewClassDeclaration( {
 
 			await process.execute();
 
-			this.#afterRenderTemplate();
+			this.bindUIElements();
+
+			this.triggerMethod( 'render:template' );
 		}
 
-		// Emulating the original Marionette behavior.
-		#beforeRenderTemplate() {
-			this.triggerMethod( 'before:render:template' );
+		afterSettingsResolve( settings: { [ key: string ]: unknown } ) {
+			return settings;
 		}
 
-		#afterRenderTemplate() {
-			this.bindUIElements();
+		#beforeRender() {
+			this._ensureViewIsIntact();
 
-			this.triggerMethod( 'render:template' );
+			this._isRendering = true;
+
+			this.resetChildViewContainer();
+
+			this.triggerMethod( 'before:render', this );
+		}
+
+		#afterRender() {
+			this._isRendering = false;
+			this.isRendered = true;
+
+			this.triggerMethod( 'render', this );
 		}
 	};
 }

package/src/legacy/init-legacy-views.ts

@@ -3,8 +3,24 @@ import { __privateListenTo, v1ReadyEvent } from '@elementor/editor-v1-adapters';
 
 import { createDomRenderer } from '../renderers/create-dom-renderer';
 import { createElementType } from './create-element-type';
-import { canBeTemplated, createTemplatedElementType } from './create-templated-element-type';
-import type { LegacyWindow } from './types';
+import {
+	canBeTemplated,
+	createTemplatedElementType,
+	type CreateTemplatedElementTypeOptions,
+} from './create-templated-element-type';
+import type { ElementType, LegacyWindow } from './types';
+
+type ElementLegacyType = {
+	[ key: string ]: ( options: CreateTemplatedElementTypeOptions ) => typeof ElementType;
+};
+export const elementsLegacyTypes: ElementLegacyType = {};
+
+export function registerElementType(
+	type: string,
+	elementTypeGenerator: ElementLegacyType[ keyof ElementLegacyType ]
+) {
+	elementsLegacyTypes[ type ] = elementTypeGenerator;
+}
 
 export function initLegacyViews() {
 	__privateListenTo( v1ReadyEvent(), () => {
@@ -18,9 +34,15 @@ export function initLegacyViews() {
 				return;
 			}
 
-			const ElementType = canBeTemplated( element )
-				? createTemplatedElementType( { type, renderer, element } )
-				: createElementType( type );
+			let ElementType;
+
+			if ( !! elementsLegacyTypes[ type ] && canBeTemplated( element ) ) {
+				ElementType = elementsLegacyTypes[ type ]( { type, renderer, element } );
+			} else if ( canBeTemplated( element ) ) {
+				ElementType = createTemplatedElementType( { type, renderer, element } );
+			} else {
+				ElementType = createElementType( type );
+			}
 
 			legacyWindow.elementor.elementsManager.registerElementType( new ElementType() );
 		} );

package/src/legacy/types.ts

@@ -2,6 +2,8 @@ import { type Props } from '@elementor/editor-props';
 
 export type LegacyWindow = Window & {
 	elementor: {
+		createBackboneElementsCollection: ( children: unknown ) => BackboneCollection< ElementModel >;
+
 		modules: {
 			elements: {
 				types: {
@@ -36,6 +38,15 @@ export declare class ElementView {
 
 	model: BackboneModel< ElementModel >;
 
+	collection: BackboneCollection< ElementModel >;
+
+	children: {
+		length: number;
+		findByIndex: ( index: number ) => ElementView;
+	};
+
+	constructor( ...args: unknown[] );
+
 	onRender( ...args: unknown[] ): void;
 
 	onDestroy( ...args: unknown[] ): void;
@@ -61,9 +72,29 @@ export declare class ElementView {
 
 	_renderTemplate(): void;
 
-	triggerMethod( method: string ): void;
+	_renderChildren(): void;
+
+	attachBuffer( collectionView: this, buffer: DocumentFragment ): void;
+
+	triggerMethod( method: string, ...args: unknown[] ): void;
 
 	bindUIElements(): void;
+
+	_ensureViewIsIntact(): void;
+
+	_isRendering: boolean;
+
+	resetChildViewContainer(): void;
+
+	isRendered: boolean;
+
+	options?: {
+		model: BackboneModel< ElementModel >;
+	};
+
+	ui(): Record< string, unknown >;
+
+	events(): Record< string, unknown >;
 }
 
 type JQueryElement = {
@@ -72,15 +103,24 @@ type JQueryElement = {
 	get: ( index: number ) => HTMLElement;
 };
 
-type BackboneModel< Model extends object > = {
+export type BackboneModel< Model extends object > = {
 	get: < T extends keyof Model >( key: T ) => Model[ T ];
+	set: < T extends keyof Model >( key: T, value: Model[ T ] ) => void;
 	toJSON: () => ToJSON< Model >;
 };
 
-type ElementModel = {
+type BackboneCollection< Model extends object > = {
+	models: BackboneModel< Model >[];
+	forEach: ( callback: ( model: BackboneModel< Model > ) => void ) => void;
+};
+
+export type ElementModel = {
 	id: string;
 	settings: BackboneModel< Props >;
+	editor_settings: Record< string, unknown >;
 	widgetType: string;
+	editSettings?: BackboneModel< { inactive?: boolean } >;
+	elements?: BackboneCollection< ElementModel >;
 };
 
 type ToJSON< T > = {
@@ -89,5 +129,5 @@ type ToJSON< T > = {
 
 type ContextMenuGroup = {
 	name: string;
-	action: unknown[];
+	actions: unknown[];
 };

package/src/mcp/canvas-mcp.ts

@@ -0,0 +1,17 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+
+import { initWidgetsSchemaResource } from './resources/widgets-schema-resource';
+import { initBuildCompositionsTool } from './tools/build-composition/tool';
+import { initConfigureElementTool } from './tools/configure-element/tool';
+import { initGetElementConfigTool } from './tools/get-element-config/tool';
+
+export const initCanvasMcp = ( reg: MCPRegistryEntry ) => {
+	const { setMCPDescription } = reg;
+	setMCPDescription(
+		'Everything related to creative design, layout, styling and building the pages, specifically element of type "widget"'
+	);
+	initWidgetsSchemaResource( reg );
+	initBuildCompositionsTool( reg );
+	initGetElementConfigTool( reg );
+	initConfigureElementTool( reg );
+};

package/src/mcp/mcp-description.ts

@@ -0,0 +1,40 @@
+import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from './resources/widgets-schema-resource';
+
+export const mcpDescription = `Canvas MCP - Working with widgets and styles: how to use the PropType schemas and generate PropValue structures
+
+# Elementor's PropValue configuration system
+
+Every widget in Elementor has a set of properties that can be configured, defined in a STRICT SCHEMA we call "PropType".
+All widget configuration values are represented using a structure we call "PropValue".
+
+To correctly configure a widget's properties, FOLLOW THE PropType schema defined for that widget. This schema outlines the expected structure and types for each property, ensuring that the values you provide are valid and can be properly interpreted by Elementor.
+Every widget has it's own PropType schema, retreivable from the resource [${ WIDGET_SCHEMA_URI }].
+ALL WIDGETS share a common _styles property with a uniform styles schema, retreivable from the resource [${ STYLE_SCHEMA_URI }].
+The style schema is grouped by categories, such as "typography", "background", "border", etc.
+
+# Tools and usage
+- Use the "get-element-configuration-values" tool to retrieve the current configuration of a specific element, including its PropValues and styles. It is recommended to use this tool when you are required to make changes to an existing element, to ensure you have the correct current configuration schema.
+  If a PropValue changes it's type (only on union PropTypes), read the new schema from the resources mentioned above, and adjust the PropValue structure accordingly.
+- Use the "build-composition" tool to create a NEW ELEMENTS in a composition on the page. You can use this tool to also create a new single element.
+- Use the "configure-element" tool to update the configuration of an EXISTING element on the page.
+
+All array types that can receive union types, are typed as mixed array, which means that each item in the array can be of any of the allowed types defined in the PropType schema.
+Example: the "background" can have a background-overlay property, which can contain multiple overlays, such as color, gradient, image, etc. Each item in the array must follow the PropType schema for each overlay type.
+All _style properties are OPTIONAL. When a _style is defined, we MERGE the values with existing styles, so only the properties you define will be changed, and the rest will remain as is.
+
+# Styling best practices
+Prefer using "em" and "rem" values for text-related sizes, padding and spacing. Use percentages for dynamic sizing relative to parent containers.
+This flexboxes are by default "flex" with "stretch" alignment. To ensure proper layout, define the "justify-content" and "align-items" as in the schema.
+
+Additionaly, some PropTypes have metadata information (meta property) that can help in understaind the PropType usage, such as description or other useful information.
+
+Example of null values:
+{
+  $$type: 'as-defined-for-propValue',
+  value: null
+}
+
+Example of "image" PropValue structure:
+{$$type:'image',value:{src:{$$type:'image-src',value:{url:{$$type:'url',value:'https://example.com/image.jpg'}}},size:{$$type:'string',value:'full'}}}
+
+`;

package/src/mcp/resources/widgets-schema-resource.ts

@@ -0,0 +1,173 @@
+import { getWidgetsCache } from '@elementor/editor-elements';
+import { type MCPRegistryEntry, ResourceTemplate } from '@elementor/editor-mcp';
+import {
+	type ArrayPropType,
+	type ObjectPropType,
+	type PropType,
+	Schema,
+	type TransformablePropType,
+	type UnionPropType,
+} from '@elementor/editor-props';
+import { getStylesSchema } from '@elementor/editor-styles';
+
+export const WIDGET_SCHEMA_URI = 'elementor://widgets/schema/{widgetType}';
+export const STYLE_SCHEMA_URI = 'elementor://styles/schema/{category}';
+export const BEST_PRACTICES_URI = 'elementor://styles/best-practices';
+
+export const initWidgetsSchemaResource = ( reg: MCPRegistryEntry ) => {
+	const { mcpServer } = reg;
+
+	mcpServer.resource( 'styles-best-practices', BEST_PRACTICES_URI, async () => {
+		return {
+			contents: [
+				{
+					uri: BEST_PRACTICES_URI,
+					text: `# Styling best practices
+Prefer using "em" and "rem" values for text-related sizes, padding and spacing. Use percentages for dynamic sizing relative to parent containers.
+This flexboxes are by default "flex" with "stretch" alignment. To ensure proper layout, define the "justify-content" and "align-items" as in the schema, or in custom_css, depends on your needs.
+
+When applicable for styles, use the "custom_css" property for free-form CSS styling. This property accepts a string of CSS rules that will be applied directly to the element.
+The css string must follow standard CSS syntax, with properties and values separated by semicolons, no selectors, or nesting rules allowed.`,
+				},
+			],
+		};
+	} );
+
+	mcpServer.resource(
+		'styles-schema',
+		new ResourceTemplate( STYLE_SCHEMA_URI, {
+			list: () => {
+				const categories = [ ...Object.keys( getStylesSchema() ), 'custom_css' ];
+				return {
+					resources: categories.map( ( category ) => ( {
+						uri: `elementor://styles/schema/${ category }`,
+						name: 'Style schema for ' + category,
+					} ) ),
+				};
+			},
+		} ),
+		{
+			description: 'Common styles schema for the specified category',
+		},
+		async ( uri, variables ) => {
+			const category = typeof variables.category === 'string' ? variables.category : variables.category?.[ 0 ];
+			if ( category === 'custom_css' ) {
+				return {
+					contents: [
+						{
+							uri: uri.toString(),
+							text: 'Free style inline CSS string of properties and their values. Applicable for a single element, only the properties and values are accepted. Use this as a last resort for properties that are not covered with the schema.',
+						},
+					],
+				};
+			}
+			const stylesSchema = getStylesSchema()[ category ];
+			if ( ! stylesSchema ) {
+				throw new Error( `No styles schema found for category: ${ category }` );
+			}
+			const cleanedupPropSchema = cleanupPropType( stylesSchema );
+			const asJson = Schema.propTypeToJsonSchema( cleanedupPropSchema as PropType );
+			return {
+				contents: [
+					{
+						uri: uri.toString(),
+						text: JSON.stringify( asJson ),
+					},
+				],
+			};
+		}
+	);
+
+	mcpServer.resource(
+		'widget-schema-by-type',
+		new ResourceTemplate( WIDGET_SCHEMA_URI, {
+			list: () => {
+				const cache = getWidgetsCache() || {};
+				const availableWidgets = Object.keys( cache || {} ).filter(
+					( widgetType ) => cache[ widgetType ]?.atomic_props_schema
+				);
+				return {
+					resources: availableWidgets.map( ( widgetType ) => ( {
+						uri: `elementor://widgets/schema/${ widgetType }`,
+						name: 'Widget schema for ' + widgetType,
+					} ) ),
+				};
+			},
+		} ),
+		{
+			description: 'PropType schema for the specified widget type',
+		},
+		async ( uri, variables ) => {
+			const widgetType =
+				typeof variables.widgetType === 'string' ? variables.widgetType : variables.widgetType?.[ 0 ];
+			const propSchema = getWidgetsCache()?.[ widgetType ]?.atomic_props_schema;
+			if ( ! propSchema ) {
+				throw new Error( `No prop schema found for element type: ${ widgetType }` );
+			}
+			const cleanedupPropSchema = cleanupPropSchema( propSchema );
+			const asJson = Object.fromEntries(
+				Object.entries( cleanedupPropSchema ).map( ( [ key, propType ] ) => [
+					key,
+					Schema.propTypeToJsonSchema( propType ),
+				] )
+			);
+			Schema.nonConfigurablePropKeys.forEach( ( key ) => {
+				// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+				delete asJson[ key ];
+			} );
+
+			return {
+				contents: [
+					{
+						uri: uri.toString(),
+						text: JSON.stringify( asJson ),
+					},
+				],
+			};
+		}
+	);
+};
+
+function cleanupPropSchema( propSchema: Record< string, PropType > ): Record< string, PropType > {
+	const result: Record< string, Partial< PropType > > = {};
+	Object.keys( propSchema ).forEach( ( propName ) => {
+		result[ propName ] = cleanupPropType( propSchema[ propName ] );
+	} );
+	return result as Record< string, PropType >;
+}
+function cleanupPropType( propType: PropType & { key?: string } ): Partial< PropType > {
+	const result: Partial< PropType > = {};
+	Object.keys( propType ).forEach( ( property ) => {
+		switch ( property ) {
+			case 'key':
+			case 'kind':
+				( result as Record< string, unknown > )[ property ] = propType[ property ];
+				break;
+			case 'meta':
+			case 'settings':
+				{
+					if ( Object.keys( propType[ property ] || {} ).length > 0 ) {
+						( result as Record< string, unknown > )[ property ] = propType[ property ];
+					}
+				}
+				break;
+		}
+	} );
+	if ( result.kind === 'plain' ) {
+		Object.defineProperty( result, 'kind', { value: 'string' } );
+	} else if ( result.kind === 'array' ) {
+		result.item_prop_type = cleanupPropType( ( propType as ArrayPropType ).item_prop_type ) as PropType;
+	} else if ( result.kind === 'object' ) {
+		const shape = ( propType as ObjectPropType ).shape as Record< string, PropType >;
+		const cleanedShape = cleanupPropSchema( shape );
+		result.shape = cleanedShape;
+	} else if ( result.kind === 'union' ) {
+		const propTypes = ( propType as UnionPropType ).prop_types;
+		const cleanedPropTypes: Record< string, Partial< PropType > > = {};
+		Object.keys( propTypes ).forEach( ( key ) => {
+			cleanedPropTypes[ key ] = cleanupPropType( propTypes[ key ] );
+		} );
+		result.prop_types = cleanedPropTypes as Record< string, TransformablePropType >;
+	}
+	return result;
+}

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

@@ -0,0 +1,128 @@
+import { toolPrompts } from '@elementor/editor-mcp';
+
+import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
+
+export const generatePrompt = () => {
+	const buildCompositionsToolPrompt = toolPrompts( 'build-compositions' );
+
+	buildCompositionsToolPrompt.description( `
+Build entire elementor widget comositions representing complex structures of nested elements.
+
+# When to use this tool
+Always prefer this tool when the user requires to build a composition of elements, such as cards, heros, or inspired from other pages or HTML compositions.
+Prefer this tool over any other tool for building HTML structure, unless you are specified to use a different tool.
+
+# **CRITICAL - REQUIRED RESOURCES (Must read before using this tool)**
+1. [${ WIDGET_SCHEMA_URI }]
+   Required to understand which widgets are available, and what are their configuration schemas.
+   Every widgetType (i.e. e-heading, e-button) that is supported has it's own property schema, that you must follow in order to apply property values correctly.
+2. [${ STYLE_SCHEMA_URI }]
+   Required to understand the styles schema for the widgets. All widgets share the same styles schema.
+3. List of allowed custom tags for building the structure is derived from the list of widgets schema resources.
+
+# Instructions
+1. Understand the user requirements carefully.
+2. Build a valid XML structure using only the allowed custom tags provided. For example, if you
+   use the "e-button" element, it would be represented as <e-button></e-button> in the XML structure.
+3. Plan the configuration for each element according to the user requirements, using the configuration schema provided for each custom tag.
+   Every widget type has it's own configuration schema, retreivable from the resource [${ WIDGET_SCHEMA_URI }].
+   PropValues must follow the exact PropType schema provided in the resource.
+4. For every element, provide a "configuration-id" attribute. For example:
+   \`<e-flexbox configuration-id="flex1"><e-heading configuration-id="heading2"></e-heading></e-flexbox>\`
+   In the elementConfig property, provide the actual configuration object for each configuration-id used in the XML structure.
+   In the stylesConfig property, provide the actual styles configuration object for each configuration-id used in the XML structure.
+5. Ensure the XML structure is valid and parsable.
+6. Do not add any attribute nodes, classes, id's, and no text nodes allowed.
+   Layout properties, such as margin, padding, align, etc. must be applied using the [${ STYLE_SCHEMA_URI }] PropValues.
+7. Some elements allow nesting of other elements, and most of the DO NOT. The allowed elements that can have nested children are "e-div-block" and "e-flexbox".
+8. Make sure that non-container elements do NOT have any nested elements.
+9. Unsless the user specifically requires structure only, BE EXPRESSIVE AND VISUALLY CREATIVE AS POSSIBLE IN APPLYING STYLE CONFIGURATION.
+   In the case of doubt, prefer adding more styles to make the composition visually appealing.
+
+# Additional Guidelines
+- Most users expect the structure to be well designed and visually appealing.
+- Use layout properties, ensure "white space" design approach is followed, and make sure the composition is visually balanced.
+- Use appropriate spacing, alignment, and sizing to create a harmonious layout.
+- Consider the visual hierarchy of elements to guide the user's attention effectively.
+- You are encouraged to use colors, typography, and other style properties to enhance the visual appeal, as long as they are part of the configuration schema for the elements used.
+- Always aim for a clean and professional look that aligns with modern design principles.
+- When you are required to create placeholder texts, use texts that have a length that fits the goal. When long texts are required, use longer placeholder texts. When the user specifies exact texts, use the exact texts.
+- Image size does not affect the actual size on the screen, only which quality to use. If you use images, specifically add _styles PropValues to define the image sizes.
+- Attempt to use layout, margin, padding, size properties from the styles schema.
+- If your elements library is limited, encourage use of nesting containers to achieve complex layouts.
+
+# CONSTRAINTS
+When a tool execution fails, retry up to 10 more times, read the error message carefully, and adjust the XML structure or the configurations accordingly.
+If a "$$type" is missing, update the invalid object, if the XML has parsing errors, fix it, etc. and RETRY.
+VALIDATE the XML structure before delivering it as the final result.
+VALIDATE the JSON structure used in the "configuration" attributes for each element before delivering the final result. The configuration must MATCH the PropValue schemas.
+NO LINKS ALLOWED. Never apply links to elements, even if they appear in the PropType schema.
+elementConfig values must align with the widget's PropType schema, available at the resource [${ WIDGET_SCHEMA_URI }].
+stylesConfig values must align with the common styles PropType schema, available at the resource [${ STYLE_SCHEMA_URI }].
+
+# Parameters
+All parameters are MANDATORY.
+- xmlStructure
+- elementConfig
+- stylesConfig
+
+If unsure about the configuration of a specific property, read the schema resources carefully.
+
+
+  ` );
+
+	buildCompositionsToolPrompt.example( `
+A Heading and a button inside a flexbox
+{
+  xmlStructure: "<e-flexbox configuration-id="flex1"><e-heading configuration-id="heading1"></e-heading><e-button configuration-id="button1"></e-button></e-flexbox>"
+  elementConfig: {
+    "flex1": {
+      "tag": {
+        "$$type": "string",
+        "value": "section"
+      },
+  },
+  stylesConfig: {
+    "heading1": {
+      "font-size": {
+        "$$type": "size",
+        "value": {
+          "size": { "$$type": "number", "value": 24 },
+          "unit": { "$$type": "string", "value": "px" }
+        }
+      },
+      "color": {
+        "$$type": "color",
+        "value": { "$$type": "string", "value": "#333" }
+      }
+    }
+  },
+}
+` );
+
+	buildCompositionsToolPrompt.parameter(
+		'xmlStructure',
+		`**MANDATORY** A valid XML structure representing the composition to be built, using custom elementor tags, styling and configuration PropValues.`
+	);
+
+	buildCompositionsToolPrompt.parameter(
+		'elementConfig',
+		`**MANDATORY** A record mapping configuration IDs to their corresponding configuration objects, defining the PropValues for each element created.`
+	);
+
+	buildCompositionsToolPrompt.parameter(
+		'stylesConfig',
+		`**MANDATORY** A record mapping style PropTypes to their corresponding style configuration objects, defining the PropValues for styles to be applied to elements.`
+	);
+
+	buildCompositionsToolPrompt.instruction(
+		`You will be provided the XML structure with element IDs. These IDs represent the actual elementor widgets created on the page/post.
+You should use these IDs as reference for further configuration, styling or changing elements later on.`
+	);
+
+	buildCompositionsToolPrompt.instruction(
+		`You must use styles/variables/classes that are available in the project resources, you should prefer using them over inline styles, and you are welcome to execute relevant tools AFTER this tool execution, to apply global classes to the created elements.`
+	);
+
+	return buildCompositionsToolPrompt.prompt();
+};