@elementor/editor-canvas 3.35.0-470 → 3.35.0-471

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

@@ -6,285 +6,104 @@ export const generatePrompt = () => {
 	const buildCompositionsToolPrompt = toolPrompts( 'build-compositions' );
 
 	buildCompositionsToolPrompt.description( `
-# **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.
-
-# DESIGN QUALITY IMPERATIVE
-You are generating designs for real users who expect distinctive, intentional aesthetics - NOT generic AI output.
-**The Core Challenge**: Large language models naturally converge toward statistically common design patterns during generation. This creates predictable, uninspired results that users describe as "AI slop": safe color schemes, default typography hierarchies, minimal contrast, and timid spacing.
-**Your Mission**: Actively resist distributional convergence by making intentional, distinctive design choices across all aesthetic dimensions. Every design decision should have a clear purpose tied to visual hierarchy, brand personality, or user experience goals.
-When in doubt between "safe" and "distinctive," choose distinctive - users can always request refinements, but they cannot salvage generic foundations.
-
-# 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.
-
-# DESIGN QUALITY IMPERATIVE
-You are generating designs for real users who expect distinctive, intentional aesthetics - NOT generic AI output.
-**The Core Challenge**: Large language models naturally converge toward statistically common design patterns during generation. This creates predictable, uninspired results that users describe as "AI slop": safe color schemes, default typography hierarchies, minimal contrast, and timid spacing.
-**Your Mission**: Actively resist distributional convergence by making intentional, distinctive design choices across all aesthetic dimensions. Every design decision should have a clear purpose tied to visual hierarchy, brand personality, or user experience goals.
-When in doubt between "safe" and "distinctive," choose distinctive - users can always request refinements, but they cannot salvage generic foundations.
-
-# 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.
-
-# 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-tabs", "e-div-block", and "e-flexbox".
-8. Make sure that non-container elements do NOT have any nested elements.
-
-# DESIGN VECTORS - Concrete Implementation Guidance
-
-## 1. Typography & Visual Hierarchy
-
-**Avoid Distributional Defaults:**
-- NO generic sans-serifs as primary typefaces (Inter, Roboto, Arial, Helvetica)
-- NO timid size ratios (1.2x, 1.5x scaling)
-- NO uniform font weights (everything at 400 or 600)
-
-**Intentional Alternatives:**
-- **For Technical/Modern**: Consider monospace headlines (JetBrains Mono, SF Mono) paired with clean body text
-- **For Editorial/Elegant**: Consider serif headlines (Playfair Display, Crimson Text) with sans-serif body
-- **For Playful/Creative**: Consider display fonts with character, paired with highly legible body text
-
-**Scale & Contrast Implementation:**
-- Headline-to-body size ratios: 3x minimum (e.g., 48px headline vs 16px body)
-- Use extreme weight contrasts: pair weight-100 or 200 with weight-800 or 900
-- Line height contrasts: tight headlines (1.1) vs. generous body (1.7)
-- Letter spacing: compressed headlines (-0.02em to -0.05em) vs. open small text (0.03em+)
-
-**Hierarchy Mapping:**
-/* Intentional hierarchy example */
-H1: font-size: 3.5rem; font-weight: 900; line-height: 1.1; letter-spacing: -0.03em;
-H2: font-size: 2rem; font-weight: 200; line-height: 1.2;
-Body: font-size: 1rem; font-weight: 400; line-height: 1.7;
-Caption: font-size: 0.75rem; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase;
-
-## 2. Color & Theme Strategy
-
-**Avoid Distributional Defaults:**
-- NO purple gradients or blue-purple color schemes (massively overrepresented in AI output)
-- NO evenly-distributed color palettes (3-4 colors used equally)
-- NO timid pastels or all-neutral schemes
-- NO #333333, #666666, #999999 grays
-
-**Intentional Alternatives:**
-- **Commit to a Dominant Color**: Choose ONE primary brand color that appears in 60-70% of colored elements
-- **Sharp Accent Strategy**: Use 1-2 high-contrast accent colors sparingly (10-15% of colored elements)
-- **Neutrals with Personality**: Replace pure grays with warm (#3d3228, #f5f1ed) or cool (#2a2f3d, #f0f2f5) tinted neutrals
-
-**Color Psychology Mapping:**
-- Energy/Action → Warm reds, oranges, yellows (NOT purple/blue)
-- Trust/Calm → Deep teals, forest greens (NOT generic blue)
-- Luxury/Premium → Deep burgundy, emerald, charcoal with gold accents
-- Playful/Creative → Unexpected combinations (coral + mint, mustard + navy)
-
-**Implementation:**
-/* Intentional color system example */
---brand-primary: #d84315;        /* Dominant: Deep orange */
---brand-accent: #00bfa5;         /* Accent: Teal (complementary) */
---neutral-dark: #2d2622;         /* Warm dark brown, not #333 */
---neutral-light: #faf8f6;        /* Warm off-white, not pure white */
---background: linear-gradient(135deg, #faf8f6 0%, #f0ebe6 100%); /* Subtle warmth */
-
-## 3. Spatial Design & White Space
-
-**Avoid Distributional Defaults:**
-- NO uniform spacing (everything 16px or 24px)
-- NO cramped layouts that maximize content density
-- NO default container widths (1200px, 1440px)
-
-**Intentional Alternatives:**
-- **Breathing Room**: Use generous white space as a design element (80-120px vertical spacing between sections)
-- **Asymmetric Spacing**: Vary padding dramatically (small: 12px, medium: 48px, large: 96px)
-- **Content Width Strategy**:
-  - Reading content: max 65-75 characters (600-700px)
-  - Hero sections: asymmetric layouts, not centered blocks
-  - Cards/components: vary sizes intentionally, not uniform grids
-
-**Implementation:**
-/* Intentional spacing scale */
---space-xs: 0.5rem;   /* 8px */
---space-sm: 1rem;     /* 16px */
---space-md: 3rem;     /* 48px */
---space-lg: 6rem;     /* 96px */
---space-xl: 10rem;    /* 160px */
-
-/* Use in combinations: */
-padding: var(--space-lg) var(--space-md);  /* Not uniform padding */
-margin-bottom: var(--space-xl);            /* Generous section breaks */
-
-## 4. Backgrounds & Atmospheric Depth
-
-**Avoid Distributional Defaults:**
-- NO solid white or light gray backgrounds
-- NO single-color backgrounds
-- NO generic gradient overlays
-
-**Intentional Alternatives:**
-- **Layered Gradients**: Combine 2-3 subtle gradients for depth
-- **Geometric Patterns**: SVG patterns, mesh gradients, or subtle noise textures
-- **Strategic Contrast**: Alternate between light and dark sections for rhythm
-
-**Implementation:**
-/* Intentional background example */
-background:
-  radial-gradient(circle at 20% 30%, rgba(216, 67, 21, 0.08) 0%, transparent 50%),
-  radial-gradient(circle at 80% 70%, rgba(0, 191, 165, 0.06) 0%, transparent 50%),
-  linear-gradient(135deg, #faf8f6 0%, #f0ebe6 100%);
-
-## 5. Visual Hierarchy Principles
-
-**Clear Priority System:**
-1. **Primary Focus (1 element)**: Largest, highest contrast, most visual weight
-2. **Secondary Elements (2-3 elements)**: 40-60% of primary size, reduced contrast
-3. **Tertiary/Support (everything else)**: Minimal visual weight, muted colors
-
-**Contrast Techniques:**
-- Size: 3x+ differences between hierarchy levels
-- Weight: 300+ difference in font-weight values
-- Color: Primary gets brand color, secondary gets neutral, tertiary gets muted
-- Space: Primary gets 2x+ surrounding white space vs. secondary
-
-## 6. EXAMPLES - Intentional vs. Generic Design
-
-### ❌ GENERIC (Distributional Convergence)
-
-{
-  "xmlStructure": "<e-flexbox configuration-id=\"flex1\"><e-heading configuration-id=\"heading1\"></e-heading><e-button configuration-id=\"button1\"></e-button></e-flexbox>",
-  "elementConfig": {
-    "heading1": {
-      "title": { "$$type": "string", "value": "Welcome to Our Site" }
-    }
-  },
-  "stylesConfig": {
-    "heading1": {
-      "font-size": {
-        "$$type": "size",
-        "value": {
-          "size": { "$$type": "number", "value": 24 },
-          "unit": { "$$type": "string", "value": "px" }
-        }
-      },
-    }
-  }
-}
-
-**Why Generic**: 24px default size, #333 safe gray, 600 weight (middle-ground), purple gradient (AI cliché), uniform 12/24px padding
-
-### ✅ INTENTIONAL (Resisting Convergence)
-{
-  "xmlStructure": "<e-flexbox configuration-id=\"hero-section\"><e-heading configuration-id=\"hero-title\"></e-heading><e-text configuration-id=\"hero-subtitle\"></e-text><e-button configuration-id=\"hero-cta\"></e-button></e-flexbox>",
-  "elementConfig": {
-    "hero-title": {
-      "title": { "$$type": "string", "value": "Transform Your Workflow" }
-    },
-    "hero-subtitle": {
-      "content": { "$$type": "string", "value": "Built for teams who refuse to compromise on quality" }
-    }
-  },
-  "stylesConfig": {
-    "hero-section": {
-      "display": { "$$type": "string", "value": "flex" },
-      "flex-direction": { "$$type": "string", "value": "column" },
-      "align-items": { "$$type": "string", "value": "flex-start" },
-      "background": {
-        "$$type": "color",
-        "value": "#f0ebe6",
-        "$intention": "background: #f0ebe6",
-      }
-    },
-    "hero-title": {
-      "font-size": {
-          "$$type": "size",
-          "value": {
-            "size": { "$$type": "number", "value": 72 },
-            "unit": { "$$type": "string", "value": "px" }
-          }
-        },
-    }
-  }
-}
-
-
-**Why Intentional**:
-- Typography: 4.5rem headline (3.6x body), weight 900 vs 200 contrast, tight leading
-- Color: Warm orange primary (#d84315), warm neutrals (#2d2622, #5a534d) NOT #333/#666
-- Spacing: 10rem vertical padding (generous), 3rem gap, asymmetric alignment
-- Background: Layered gradients with subtle brand color accent
-
-# 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 }].
-
-# DESIGN QUALITY CONSTRAINTS
-
-**Typography Constraints:**
-- NEVER use Inter, Roboto, Arial, or Helvetica as primary display fonts
-- NEVER use font-size ratios smaller than 2.5x between headlines and body
-- NEVER use font-weight values between 500-700 for headlines (go lighter or heavier)
-
-**Color Constraints:**
-- NEVER use purple gradients or blue-purple color schemes
-- NEVER use pure grays (#333, #666, #999) - use tinted neutrals instead
-- NEVER distribute colors evenly - commit to ONE dominant color
-- NEVER use more than 3 core colors (1 dominant, 1-2 accents)
-
-**Spacing Constraints:**
-- NEVER use uniform spacing across all elements
-- NEVER use section padding less than 4rem (64px) for hero/major sections
-- NEVER center everything - use asymmetric layouts for visual interest
-
-**Background Constraints:**
-- NEVER use solid white (#ffffff) or light gray (#f5f5f5) backgrounds without texture/gradients
-- ALWAYS layer at least 2 gradient or color elements for atmospheric depth
-
-# Parameters
-All parameters are MANDATORY.
-- xmlStructure
-- elementConfig
-- stylesConfig
-
-If unsure about the configuration of a specific property, read the schema resources carefully.
-
-# About our widgets
-Most widgets are self-explanatory by their name. Here is some additional information.
-Check for available llm_guidance property in the widget's schema.
-SVG elements are bound to internal content upload. Avoid usage, unless you have tools to upload SVG content.
-When working with containers, do not forget to apply style schema for controlling the layout.
-
-
+# REQUIRED RESOURCES (Read before use)
+1. [${ WIDGET_SCHEMA_URI }] - Widget types, configuration schemas, and PropType definitions
+2. [${ STYLE_SCHEMA_URI }] - Common styles schema shared by all widgets
+3. [elementor://global-classes] - Existing global classes (check FIRST to reuse)
+
+# THREE-PHASE WORKFLOW (MANDATORY)
+
+## Phase 1: Create Global Classes
+1. Analyze requirements → identify reusable patterns (typography, colors, spacing)
+2. Check [elementor://global-classes] for existing classes
+3. Use "create-global-class" tool for NEW reusable styles BEFORE building
+
+## Phase 2: Build Composition (THIS TOOL)
+4. Build valid XML with minimal inline styles (layout/positioning only)
+5. Avoid duplicating styles that should be global classes
+
+## Phase 3: Apply Classes
+6. Use "apply-global-class" tool to apply global classes to elements
+
+# CORE INSTRUCTIONS
+
+**Structure:**
+- Build valid XML using allowed widget tags (e.g., \`<e-button configuration-id="btn1"></e-button>\`)
+- Containers only: "e-flexbox", "e-div-block", "e-tabs"
+- Every element MUST have unique "configuration-id" attribute
+- No attributes, classes, IDs, or text nodes in XML
+
+**Configuration:**
+- Map each configuration-id to elementConfig (widget props) and stylesConfig (styles)
+- Follow exact PropType schemas from resources above
+- All PropValues need \`$$type\` property matching schema
+- Keep stylesConfig MINIMAL - layout only, NOT reusable styles
+
+**Validation:**
+- Parse XML before submission
+- Match all PropValues to schema (\`$$type\` required)
+- NO LINKS in any configuration
+- Retry on errors up to 10x, reading error messages carefully
+
+# DESIGN QUALITY: AVOID AI SLOP
+
+**Problem:** LLMs default to generic patterns (purple gradients, #333 grays, 24px headings, uniform spacing)
+**Solution:** Make intentional, distinctive choices. When unsure, choose bold over safe.
+
+## Typography Rules
+❌ AVOID: Inter/Roboto/Arial, small ratios (1.5x), medium weights (500-700)
+✅ USE: 3x+ size ratios, extreme weight contrasts (100/200 vs 800/900), tight headlines (1.1 line-height)
+
+## Color Rules
+❌ AVOID: Purple gradients, pure grays (#333/#666/#999), even distribution
+✅ USE: ONE dominant color (60-70%), 1-2 accent colors (10-15%), tinted neutrals (warm/cool grays)
+
+## Spacing Rules
+❌ AVOID: Uniform spacing (all 16px/24px), cramped layouts, centered everything
+✅ USE: Generous spacing (80-120px sections), dramatic variation (12px/48px/96px), asymmetric layouts
+
+## Background Rules
+❌ AVOID: Solid white/gray, single colors
+✅ USE: Layered gradients (2-3 layers), subtle patterns, alternating light/dark sections
+
+## Visual Hierarchy
+1. **Primary** (1 element): Largest, highest contrast, most space
+2. **Secondary** (2-3 elements): 40-60% of primary size
+3. **Tertiary** (rest): Minimal weight, muted
+
+**Contrast techniques:** 3x size differences, 300+ weight differences, color hierarchy (brand → neutral → muted)
+
+# DESIGN CONSTRAINTS (NEVER VIOLATE)
+
+**Typography:**
+- NEVER use Inter, Roboto, Arial, Helvetica as primary display fonts
+- NEVER use font-size ratios < 2.5x between headlines and body
+- NEVER use font-weight 500-700 for headlines (go lighter or heavier)
+
+**Color:**
+- PREFER not to use pure grays - use tinted neutrals (#2d2622, #faf8f6, not #333/#f5f5f5)
+- NEVER distribute colors evenly - commit to ONE dominant
+- NEVER use more than 3 core colors - except for info/alert/badges
+
+**Spacing:**
+- NEVER use uniform spacing
+- NEVER use < 4rem (64px) padding for major sections
+- NEVER center everything
+- PRIORITIZE rem based values over pixel based
+
+**Background:**
+- NEVER use solid #ffffff or #f5f5f5 without texture/gradients
+- ALWAYS layer 2+ gradient/color elements
+
+# WIDGET NOTES
+- Check \`llm_guidance\` property in widget schemas for context
+- Avoid SVG widgets (require content upload tools) - when must, prior to execution ensure assets uploaded
+- Apply style schema to containers for layout control
+
+# PARAMETERS (ALL MANDATORY)
+- **xmlStructure**: Valid XML with configuration-id attributes
+- **elementConfig**: Record of configuration-id → widget PropValues
+- **stylesConfig**: Record of configuration-id → style PropValues (layout only)
   ` );
 
 	buildCompositionsToolPrompt.example( `
@@ -337,7 +156,12 @@ You should use these IDs as reference for further configuration, styling or chan
 	);
 
 	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.`
+		`**CRITICAL WORKFLOW REMINDER**:
+1. FIRST: Create reusable global classes for typography, colors, spacing patterns using "create-global-class" tool
+2. SECOND: Use THIS tool with minimal inline styles (only layout & unique properties)
+3. THIRD: Apply global classes to elements using "apply-global-class" tool
+
+This ensures maximum reusability and consistency across your design system. ALWAYS check [elementor://global-classes] for existing classes before creating new ones.`
 	);
 
 	return buildCompositionsToolPrompt.prompt();

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

@@ -35,5 +35,4 @@ export const outputSchema = {
 			'The built XML structure as a string. Must use this XML after completion of building the composition, it contains real IDs.'
 		)
 		.optional(),
-	llmInstructions: z.string().describe( 'Instructions for what to do next, Important to follow these instructions!' ),
 };

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

@@ -1,16 +1,15 @@
 import {
 	createElement,
 	deleteElement,
-	generateElementId,
 	getContainer,
 	getWidgetsCache,
 	type V1Element,
 } from '@elementor/editor-elements';
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
+import { CompositionBuilder } from '../../../composition-builder/composition-builder';
 import { BEST_PRACTICES_URI, 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 { generatePrompt } from './prompt';
 import { inputSchema as schema, outputSchema } from './schema';
 
@@ -23,129 +22,59 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 		schema,
 		requiredResources: [
 			{ description: 'Widgets schema', uri: WIDGET_SCHEMA_URI },
-			{ description: 'Global Classes', uri: 'elementor://global-classes' },
 			{ description: 'Styles schema', uri: STYLE_SCHEMA_URI },
+			{ description: 'Global Classes', uri: 'elementor://global-classes' },
 			{ description: 'Global Variables', uri: 'elementor://global-variables' },
 			{ description: 'Styles best practices', uri: BEST_PRACTICES_URI },
 		],
 		outputSchema,
 		modelPreferences: {
 			hints: [ { name: 'claude-sonnet-4-5' } ],
-			intelligencePriority: 0.95,
-			speedPriority: 0.5,
 		},
 		handler: async ( params ) => {
-			let xml: Document | null = null;
 			const { xmlStructure, elementConfig, stylesConfig } = params;
+			let generatedXML: string = '';
 			const errors: Error[] = [];
-			const softErrors: Error[] = [];
 			const rootContainers: V1Element[] = [];
-			const widgetsCache = getWidgetsCache() || {};
 			const documentContainer = getContainer( 'document' ) as unknown as V1Element;
 			try {
-				const parser = new DOMParser();
-				xml = parser.parseFromString( xmlStructure, 'application/xml' );
-				const errorNode = xml.querySelector( 'parsererror' );
-				if ( errorNode ) {
-					throw new Error( 'Failed to parse XML structure: ' + errorNode.textContent );
-				}
+				const compositionBuilder = CompositionBuilder.fromXMLString( xmlStructure, {
+					createElement,
+					getWidgetsCache,
+				} );
+				compositionBuilder.setElementConfig( elementConfig );
+				compositionBuilder.setStylesConfig( stylesConfig );
 
-				const children = Array.from( xml.children );
-				const iterate = async (
-					node: Element,
-					containerElement: V1Element = documentContainer,
-					childIndex: number
-				) => {
-					const elementTag = node.tagName;
-					if ( ! widgetsCache[ elementTag ] ) {
-						errors.push( new Error( `Unknown widget type: ${ elementTag }` ) );
-					}
-					const CONTAINER_ELEMENTS = Object.values( widgetsCache )
-						.filter( ( widget ) => widget.meta?.is_container )
-						.map( ( widget ) => widget.elType );
-					const isContainer = CONTAINER_ELEMENTS.includes( elementTag );
-					const parentElType = containerElement.model.get( 'elType' );
-					let targetContainerId =
-						parentElType === 'e-tabs'
-							? containerElement.children?.[ 1 ].children?.[ childIndex ]?.id ||
-							  containerElement.children?.[ 1 ].id
-							: containerElement.id;
-					if ( ! targetContainerId ) {
-						targetContainerId = containerElement.id;
-					}
-					const newElement = isContainer
-						? createElement( {
-								containerId: targetContainerId,
-								model: {
-									elType: elementTag,
-									id: generateElementId(),
-								},
-								options: { useHistory: false },
-						  } )
-						: createElement( {
-								containerId: targetContainerId,
-								model: {
-									elType: 'widget',
-									widgetType: elementTag,
-									id: generateElementId(),
-								},
-								options: { useHistory: false },
-						  } );
-					if ( containerElement === documentContainer ) {
-						rootContainers.push( newElement );
-					}
-					node.setAttribute( 'id', newElement.id );
-					const configId = node.getAttribute( 'configuration-id' ) || '';
-					try {
-						const configObject = elementConfig[ configId ] || {};
-						const styleObject = stylesConfig[ configId ] || {};
-						const { errors: propsValidationErrors } = validateInput.validatePropSchema(
-							elementTag,
-							configObject
-						);
-						errors.push( ...( propsValidationErrors || [] ).map( ( msg ) => new Error( msg ) ) );
-						const { errors: stylesValidationErrors } = validateInput.validateStyles( styleObject );
-						errors.push( ...( stylesValidationErrors || [] ).map( ( msg ) => new Error( msg ) ) );
-
-						if ( propsValidationErrors?.length || stylesValidationErrors?.length ) {
-							return;
-						}
-						configObject._styles = styleObject || {};
-						for ( const [ propertyName, propertyValue ] of Object.entries( configObject ) ) {
-							try {
-								doUpdateElementProperty( {
-									elementId: newElement.id,
-									propertyName,
-									propertyValue,
-									elementType: elementTag,
-								} );
-							} catch ( error ) {
-								softErrors.push( error as Error );
-							}
-						}
-						if ( isContainer ) {
-							let currentChild = 0;
-							for ( const child of node.children ) {
-								iterate( child, newElement, currentChild );
-								currentChild++;
-							}
-						} else {
-							node.innerHTML = '';
-							node.removeAttribute( 'configuration' );
-						}
-					} finally {
-					}
-				};
-
-				let currentChild = 0;
-				for await ( const childNode of children ) {
-					await iterate( childNode, documentContainer, currentChild );
-					currentChild++;
-					try {
-					} catch ( error ) {
-						errors.push( error as Error );
-					}
+				const {
+					configErrors,
+					invalidStyles,
+					rootContainers: generatedRootContainers,
+				} = compositionBuilder.build( documentContainer );
+
+				generatedXML = new XMLSerializer().serializeToString( compositionBuilder.getXML() );
+
+				if ( configErrors.length ) {
+					errors.push( ...configErrors.map( ( e ) => new Error( e ) ) );
+					throw new Error( 'Configuration errors occurred during composition building.' );
 				}
+
+				rootContainers.push( ...generatedRootContainers );
+
+				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 );
 			}
@@ -187,26 +116,21 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 				) }\n\n"Missing $$type" errors indicate that the configuration objects are invalid. Try again and apply **ALL** object entries with correct $$type.\nNow that you have these errors, fix them and try again. Errors regarding configuration objects, please check against the PropType schemas`;
 				throw new Error( errorText );
 			}
-			if ( ! xml ) {
-				throw new Error( 'XML structure is null after parsing.' );
-			}
 			return {
-				xmlStructure: new XMLSerializer().serializeToString( xml ),
+				xmlStructure: generatedXML,
 				errors: errors?.length
 					? errors.map( ( e ) => ( typeof e === 'string' ? e : e.message ) ).join( '\n\n' )
 					: undefined,
-				llmInstructions:
-					( softErrors.length
-						? `The composition was built successfully, but there were some issues with the provided configurations:
-
-${ softErrors.map( ( e ) => `- ${ e.message }` ).join( '\n' ) }
-
-Please use configure-element tool to fix these issues. Now that you have information about these issues, use the configure-element tool to fix them!`
-						: '' ) +
-					`
-Next Steps:
-- Use "apply-global-class" tool as there may be global styles ready to be applied to elements.
-- Use "configure-element" tool to further configure elements as needed, including styles.
+				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!
 `,
 			};
 		},