@elementor/editor-canvas 3.35.0-353 → 3.35.0-354

package/dist/index.js

@@ -50,7 +50,7 @@ module.exports = __toCommonJS(index_exports);
 var import_editor_v1_adapters = require("@elementor/editor-v1-adapters");
 var BREAKPOINTS_SCHEMA_URI = "elementor://breakpoints/list";
 var initBreakpointsResource = (reg) => {
-  const { mcpServer } = reg;
+  const { mcpServer, sendResourceUpdated } = reg;
   const getBreakpointsList = () => {
     const { breakpoints } = window.elementor?.config?.responsive || {};
     if (!breakpoints) {
@@ -78,7 +78,7 @@ var initBreakpointsResource = (reg) => {
     return buildResourceResponse();
   });
   window.addEventListener((0, import_editor_v1_adapters.v1ReadyEvent)().name, () => {
-    mcpServer.server.sendResourceUpdated({
+    sendResourceUpdated({
       uri: BREAKPOINTS_SCHEMA_URI,
       ...buildResourceResponse()
     });
@@ -93,6 +93,14 @@ var import_editor_styles = require("@elementor/editor-styles");
 var WIDGET_SCHEMA_URI = "elementor://widgets/schema/{widgetType}";
 var STYLE_SCHEMA_URI = "elementor://styles/schema/{category}";
 var BEST_PRACTICES_URI = "elementor://styles/best-practices";
+var checkIfUserHasPro = () => {
+  const extendedWindow = window;
+  const hasPro = extendedWindow.elementor?.helpers?.hasPro;
+  if (typeof hasPro === "function") {
+    return hasPro();
+  }
+  return false;
+};
 var initWidgetsSchemaResource = (reg) => {
   const { mcpServer } = reg;
   mcpServer.resource("styles-best-practices", BEST_PRACTICES_URI, async () => {
@@ -114,7 +122,11 @@ The css string must follow standard CSS syntax, with properties and values separ
     "styles-schema",
     new import_editor_mcp.ResourceTemplate(STYLE_SCHEMA_URI, {
       list: () => {
-        const categories = [...Object.keys((0, import_editor_styles.getStylesSchema)()), "custom_css"];
+        const isPro = checkIfUserHasPro();
+        const categories = [...Object.keys((0, import_editor_styles.getStylesSchema)())];
+        if (!isPro) {
+          categories.push("custom_css");
+        }
         return {
           resources: categories.map((category) => ({
             uri: `elementor://styles/schema/${category}`,
@@ -128,7 +140,7 @@ The css string must follow standard CSS syntax, with properties and values separ
     },
     async (uri, variables) => {
       const category = typeof variables.category === "string" ? variables.category : variables.category?.[0];
-      if (category === "custom_css") {
+      if (category === "custom_css" && checkIfUserHasPro()) {
         return {
           contents: [
             {
@@ -160,7 +172,7 @@ The css string must follow standard CSS syntax, with properties and values separ
       list: () => {
         const cache = (0, import_editor_elements.getWidgetsCache)() || {};
         const availableWidgets = Object.keys(cache || {}).filter(
-          (widgetType) => cache[widgetType]?.atomic_props_schema
+          (widgetType) => cache[widgetType]?.atomic_props_schema && cache[widgetType].meta?.llm_support !== false
         );
         return {
           resources: availableWidgets.map((widgetType) => ({
@@ -175,8 +187,9 @@ The css string must follow standard CSS syntax, with properties and values separ
     },
     async (uri, variables) => {
       const widgetType = typeof variables.widgetType === "string" ? variables.widgetType : variables.widgetType?.[0];
-      const propSchema = (0, import_editor_elements.getWidgetsCache)()?.[widgetType]?.atomic_props_schema;
-      if (!propSchema) {
+      const widgetData = (0, import_editor_elements.getWidgetsCache)()?.[widgetType];
+      const propSchema = widgetData?.atomic_props_schema;
+      if (!propSchema || !widgetData) {
         throw new Error(`No prop schema found for element type: ${widgetType}`);
       }
       const asJson = Object.fromEntries(
@@ -188,6 +201,24 @@ The css string must follow standard CSS syntax, with properties and values separ
       import_editor_props.Schema.nonConfigurablePropKeys.forEach((key) => {
         delete asJson[key];
       });
+      const description = typeof widgetData?.meta?.description === "string" ? widgetData.meta.description : void 0;
+      const defaultStyles = {};
+      const baseStyleSchema = widgetData?.base_styles;
+      if (baseStyleSchema) {
+        Object.values(baseStyleSchema).forEach((stylePropType) => {
+          stylePropType.variants.forEach((variant) => {
+            Object.assign(defaultStyles, variant.props);
+          });
+        });
+      }
+      const hasDefaultStyles = Object.keys(defaultStyles).length > 0;
+      const llmGuidance = {
+        can_have_children: !!widgetData?.meta?.is_container
+      };
+      if (hasDefaultStyles) {
+        llmGuidance.instructions = "These are the default styles applied to the widget. Override only when necessary.";
+        llmGuidance.default_styles = defaultStyles;
+      }
       return {
         contents: [
           {
@@ -195,7 +226,9 @@ The css string must follow standard CSS syntax, with properties and values separ
             mimeType: "application/json",
             text: JSON.stringify({
               type: "object",
-              properties: asJson
+              properties: asJson,
+              description,
+              llm_guidance: llmGuidance
             })
           }
         ]
@@ -2062,9 +2095,9 @@ var validateInput = {
       } else if (!import_editor_props5.Schema.isPropKeyConfigurable(propName)) {
         errors.push(`Property "${propName}" is not configurable.`);
       } else {
-        const { valid, errorMessages } = import_editor_props5.Schema.validatePropValue(propSchema, propValue);
+        const { valid, jsonSchema } = import_editor_props5.Schema.validatePropValue(propSchema, propValue);
         if (!valid) {
-          errors.push(`Invalid property "${propName}": ${errorMessages}`);
+          errors.push(`Invalid property "${propName}". Expected schema: ${jsonSchema}`);
         }
       }
     });
@@ -2126,6 +2159,24 @@ When in doubt between "safe" and "distinctive," choose distinctive - users can a
 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
@@ -2140,11 +2191,11 @@ Prefer this tool over any other tool for building HTML structure, unless you are
 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".
+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.
-9. **CRITICAL - CUSTOM CSS PRIORITY**: Prefer using style schema. Custom CSS is ONLY FOR UNSUPPRTED schema styles.
+9. **CRITICAL - CUSTOM CSS USAGE**: ALWAYS Prefer using style schema. Custom CSS is ONLY FOR UNSUPPRTED schema styles.
    ALWAYS PRIORITIZE using the style schema PropValues for styling elements as they provide better user experience in the editor, and UI features for the end-users.
-   - Use custom_css only for style attributes that ARE NOT SUPPORTED via the style schema.
+   Use custom_css only for style attributes that ARE NOT SUPPORTED via the style schema AFTER YOU CHECK THE [${STYLE_SCHEMA_URI}].
 
 # DESIGN VECTORS - Concrete Implementation Guidance
 
@@ -2363,10 +2414,8 @@ If unsure about the configuration of a specific property, read the schema resour
 
 # 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.
-e-div-block - By default is ceneterd aligned and vertically stacked. To modify this, apply style configuration.
-e-flexbox - By default is a flex container with row direction. To modify this, apply style configuration.
-
 When working with containers, do not forget to apply style schema for controlling the layout.
 
 
@@ -2482,21 +2531,27 @@ var initBuildCompositionsTool = (reg) => {
           throw new Error("Failed to parse XML structure: " + errorNode.textContent);
         }
         const children = Array.from(xml.children);
-        const iterate = (node, containerElement = documentContainer) => {
+        const iterate = async (node, containerElement = documentContainer, childIndex) => {
           const elementTag = node.tagName;
           if (!widgetsCache[elementTag]) {
             errors.push(new Error(`Unknown widget type: ${elementTag}`));
           }
-          const isContainer = elementTag === "e-flexbox" || elementTag === "e-div-block";
+          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 ? (0, import_editor_elements8.createElement)({
-            containerId: containerElement.id,
+            containerId: targetContainerId,
             model: {
               elType: elementTag,
               id: (0, import_editor_elements8.generateElementId)()
             },
             options: { useHistory: false }
           }) : (0, import_editor_elements8.createElement)({
-            containerId: containerElement.id,
+            containerId: targetContainerId,
             model: {
               elType: "widget",
               widgetType: elementTag,
@@ -2536,8 +2591,10 @@ var initBuildCompositionsTool = (reg) => {
               }
             }
             if (isContainer) {
+              let currentChild2 = 0;
               for (const child of node.children) {
-                iterate(child, newElement);
+                iterate(child, newElement, currentChild2);
+                currentChild2++;
               }
             } else {
               node.innerHTML = "";
@@ -2546,8 +2603,10 @@ var initBuildCompositionsTool = (reg) => {
           } finally {
           }
         };
-        for (const childNode of children) {
-          iterate(childNode, documentContainer);
+        let currentChild = 0;
+        for await (const childNode of children) {
+          await iterate(childNode, documentContainer, currentChild);
+          currentChild++;
           try {
           } catch (error) {
             errors.push(error);
@@ -2617,6 +2676,8 @@ When a user requires to change anything in an element, such as updating text, co
 This tool handles elements of type "widget".
 This tool handles styling elements, using the "stylePropertiesToChange" parameter.
 
+To CLEAR a property (i.e., set it to default or none), provide null as a value.
+
 The element's schema must be known before using this tool.
 The style schema must be known before using this tool.
 
@@ -2810,7 +2871,24 @@ var schema = {
 };
 var outputSchema3 = {
   properties: import_schema5.z.record(import_schema5.z.string(), import_schema5.z.any()).describe("A record mapping PropTypes to their corresponding PropValues"),
-  style: import_schema5.z.record(import_schema5.z.string(), import_schema5.z.any()).describe("A record mapping StyleSchema properties to their corresponding PropValues")
+  style: import_schema5.z.record(import_schema5.z.string(), import_schema5.z.any()).describe("A record mapping StyleSchema properties to their corresponding PropValues"),
+  childElements: import_schema5.z.array(
+    import_schema5.z.object({
+      id: import_schema5.z.string(),
+      elementType: import_schema5.z.string(),
+      childElements: import_schema5.z.array(import_schema5.z.any()).describe("An array of child element IDs, when applicable, same structure recursively")
+    })
+  ).describe("An array of child element IDs, when applicable, with recursive structure")
+};
+var structuredElements = (element) => {
+  const children = element.children || [];
+  return children.map((child) => {
+    return {
+      id: child.id,
+      elementType: child.model.get("elType") || child.model.get("widgetType") || "unknown",
+      childElements: structuredElements(child)
+    };
+  });
 };
 var initGetElementConfigTool = (reg) => {
   const { addTool } = reg;
@@ -2858,7 +2936,8 @@ var initGetElementConfigTool = (reg) => {
         },
         style: {
           ...stylePropValues
-        }
+        },
+        childElements: structuredElements(element)
       };
     }
   });
@@ -2878,6 +2957,7 @@ var initCanvasMcp = (reg) => {
 };
 
 // src/mcp/mcp-description.ts
+var ELEMENT_SCHEMA_URI = WIDGET_SCHEMA_URI.replace("{widgetType}", "element-schema");
 var mcpDescription = `Canvas MCP
 This MCP enables everything related to creation, configuration, and styling of elements on the Elementor canvas.
 
@@ -2913,11 +2993,53 @@ The tool accepts both the structure, the styling and the configuration of each e
 
 - First step: Retreive the available widgets by listing the [${WIDGET_SCHEMA_URI}] dynamic resource.
 - Second step: decide which elements to create, and their configuration and styles.
-  Retrieve the used elements configuration schema from the resource [${WIDGET_SCHEMA_URI}/element-name]
+  Retrieve the used elements configuration schema from the resource [${ELEMENT_SCHEMA_URI}]
 - Third step: define the styles for each element, using the common styles schema from the resource [${STYLE_SCHEMA_URI}]. List the resource to see all available style properties.
   For background and complicated layered styles, you can use "custom_css" property, which is supported only for ELEMENTOR PRO users ONLY.
   The custom css is intented to deal with yet unsupported CSS features that ARE NOT PART OF THE STYLE SCHEMA, to enable PRO users to support new CSS features.
 
+## Workflow for build-compositions tool
+1. **Parse user requirements** - Undestand what needs to be built (structure, content, styling).
+2. ** Check global resources FIRST** - Always check before building:
+   - List \`elementor://global-classes\` to see if the needed global classes already exist.
+   - List \`elementor://global-variables\` to see if the needed global variables already exist.
+   - **Preference**: Use existing global classes and variables over creating new inline styles.
+3. **Retreive widget schemas** - For each widget you will use:
+   - List [${WIDGET_SCHEMA_URI}] to see available widgets.
+   - Retrieve configuration schema from [${ELEMENT_SCHEMA_URI}] for each widget to understand required properties.
+   - Understand if a widget is a container (can have children) by checking the "llm_guidance" property in the widget's schema.
+4. **Build XML structure** - Create valid XML width configuration-ids:
+   - Every element has unique configuration-id attribute
+   - No text nodes, classes, IDs in XML.
+   
+5. **Create elementConfig** - For each configuration-id:
+   - Use PropValues with corrent \`$$type\` matching the schema.
+   - **Use global variables** in PropValues where applicable
+
+6. **Create stylesConfig** - For each configuration-id:
+   - Use style schema PropValues from [${STYLE_SCHEMA_URI}]
+   - **Priority**: Use style schema PropValues over custom_css
+   - **Use global variables** for colors, sizes, fonts where applicable
+   - **custom_css (PRO Users Only)**: The property appears only for PRO user. The purpose of custom_css is to support new CSS features not yet available in the style schema.
+     The schema supports multiple layers of background, gradients, filters. Prefer NOT USING custom_css.
+   - **Important**: Global classes are applied AFTER building the composition. Once built, apply classes using the "apply-global-class" tool - after completion of building the composition.
+
+7. **Validate** - Ensure:
+   - XML structure is valid
+   - All PropValues have corrent \`$$type\`
+   - After building a composition, you can retreive each element configuration using the "get-element-configuration-values" tool to verify correctness, using the IDs returned from the build-composition tool.
+
+## Key relationships:
+- **XML structure**: Defines the hierarchy of elements/widgets
+- **elementConfig**: Maps configuration-id to widget PropValues
+- **stylesConfig**: Maps configuration-id to style PropValues
+
+## Using global variables example:
+Existing global variables can be used during composition
+\`\`\`json
+{ "color": { "$$type": "global-color-variable", "value": "global-variable-id" } }
+\`\`\`
+
 # Configuring Elements / Adding Style to Elements
 An element configuration can be retrieved using the "get-element-configuration-values" tool.
 Updating an element requires only the UPDATED properties (including in the styles), as Elementor does a MERGE/PATCH operation.

package/dist/index.mjs

@@ -2,7 +2,7 @@
 import { v1ReadyEvent } from "@elementor/editor-v1-adapters";
 var BREAKPOINTS_SCHEMA_URI = "elementor://breakpoints/list";
 var initBreakpointsResource = (reg) => {
-  const { mcpServer } = reg;
+  const { mcpServer, sendResourceUpdated } = reg;
   const getBreakpointsList = () => {
     const { breakpoints } = window.elementor?.config?.responsive || {};
     if (!breakpoints) {
@@ -30,7 +30,7 @@ var initBreakpointsResource = (reg) => {
     return buildResourceResponse();
   });
   window.addEventListener(v1ReadyEvent().name, () => {
-    mcpServer.server.sendResourceUpdated({
+    sendResourceUpdated({
       uri: BREAKPOINTS_SCHEMA_URI,
       ...buildResourceResponse()
     });
@@ -47,6 +47,14 @@ import { getStylesSchema } from "@elementor/editor-styles";
 var WIDGET_SCHEMA_URI = "elementor://widgets/schema/{widgetType}";
 var STYLE_SCHEMA_URI = "elementor://styles/schema/{category}";
 var BEST_PRACTICES_URI = "elementor://styles/best-practices";
+var checkIfUserHasPro = () => {
+  const extendedWindow = window;
+  const hasPro = extendedWindow.elementor?.helpers?.hasPro;
+  if (typeof hasPro === "function") {
+    return hasPro();
+  }
+  return false;
+};
 var initWidgetsSchemaResource = (reg) => {
   const { mcpServer } = reg;
   mcpServer.resource("styles-best-practices", BEST_PRACTICES_URI, async () => {
@@ -68,7 +76,11 @@ The css string must follow standard CSS syntax, with properties and values separ
     "styles-schema",
     new ResourceTemplate(STYLE_SCHEMA_URI, {
       list: () => {
-        const categories = [...Object.keys(getStylesSchema()), "custom_css"];
+        const isPro = checkIfUserHasPro();
+        const categories = [...Object.keys(getStylesSchema())];
+        if (!isPro) {
+          categories.push("custom_css");
+        }
         return {
           resources: categories.map((category) => ({
             uri: `elementor://styles/schema/${category}`,
@@ -82,7 +94,7 @@ The css string must follow standard CSS syntax, with properties and values separ
     },
     async (uri, variables) => {
       const category = typeof variables.category === "string" ? variables.category : variables.category?.[0];
-      if (category === "custom_css") {
+      if (category === "custom_css" && checkIfUserHasPro()) {
         return {
           contents: [
             {
@@ -114,7 +126,7 @@ The css string must follow standard CSS syntax, with properties and values separ
       list: () => {
         const cache = getWidgetsCache() || {};
         const availableWidgets = Object.keys(cache || {}).filter(
-          (widgetType) => cache[widgetType]?.atomic_props_schema
+          (widgetType) => cache[widgetType]?.atomic_props_schema && cache[widgetType].meta?.llm_support !== false
         );
         return {
           resources: availableWidgets.map((widgetType) => ({
@@ -129,8 +141,9 @@ The css string must follow standard CSS syntax, with properties and values separ
     },
     async (uri, variables) => {
       const widgetType = typeof variables.widgetType === "string" ? variables.widgetType : variables.widgetType?.[0];
-      const propSchema = getWidgetsCache()?.[widgetType]?.atomic_props_schema;
-      if (!propSchema) {
+      const widgetData = getWidgetsCache()?.[widgetType];
+      const propSchema = widgetData?.atomic_props_schema;
+      if (!propSchema || !widgetData) {
         throw new Error(`No prop schema found for element type: ${widgetType}`);
       }
       const asJson = Object.fromEntries(
@@ -142,6 +155,24 @@ The css string must follow standard CSS syntax, with properties and values separ
       Schema.nonConfigurablePropKeys.forEach((key) => {
         delete asJson[key];
       });
+      const description = typeof widgetData?.meta?.description === "string" ? widgetData.meta.description : void 0;
+      const defaultStyles = {};
+      const baseStyleSchema = widgetData?.base_styles;
+      if (baseStyleSchema) {
+        Object.values(baseStyleSchema).forEach((stylePropType) => {
+          stylePropType.variants.forEach((variant) => {
+            Object.assign(defaultStyles, variant.props);
+          });
+        });
+      }
+      const hasDefaultStyles = Object.keys(defaultStyles).length > 0;
+      const llmGuidance = {
+        can_have_children: !!widgetData?.meta?.is_container
+      };
+      if (hasDefaultStyles) {
+        llmGuidance.instructions = "These are the default styles applied to the widget. Override only when necessary.";
+        llmGuidance.default_styles = defaultStyles;
+      }
       return {
         contents: [
           {
@@ -149,7 +180,9 @@ The css string must follow standard CSS syntax, with properties and values separ
             mimeType: "application/json",
             text: JSON.stringify({
               type: "object",
-              properties: asJson
+              properties: asJson,
+              description,
+              llm_guidance: llmGuidance
             })
           }
         ]
@@ -2042,9 +2075,9 @@ var validateInput = {
       } else if (!Schema3.isPropKeyConfigurable(propName)) {
         errors.push(`Property "${propName}" is not configurable.`);
       } else {
-        const { valid, errorMessages } = Schema3.validatePropValue(propSchema, propValue);
+        const { valid, jsonSchema } = Schema3.validatePropValue(propSchema, propValue);
         if (!valid) {
-          errors.push(`Invalid property "${propName}": ${errorMessages}`);
+          errors.push(`Invalid property "${propName}". Expected schema: ${jsonSchema}`);
         }
       }
     });
@@ -2106,6 +2139,24 @@ When in doubt between "safe" and "distinctive," choose distinctive - users can a
 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
@@ -2120,11 +2171,11 @@ Prefer this tool over any other tool for building HTML structure, unless you are
 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".
+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.
-9. **CRITICAL - CUSTOM CSS PRIORITY**: Prefer using style schema. Custom CSS is ONLY FOR UNSUPPRTED schema styles.
+9. **CRITICAL - CUSTOM CSS USAGE**: ALWAYS Prefer using style schema. Custom CSS is ONLY FOR UNSUPPRTED schema styles.
    ALWAYS PRIORITIZE using the style schema PropValues for styling elements as they provide better user experience in the editor, and UI features for the end-users.
-   - Use custom_css only for style attributes that ARE NOT SUPPORTED via the style schema.
+   Use custom_css only for style attributes that ARE NOT SUPPORTED via the style schema AFTER YOU CHECK THE [${STYLE_SCHEMA_URI}].
 
 # DESIGN VECTORS - Concrete Implementation Guidance
 
@@ -2343,10 +2394,8 @@ If unsure about the configuration of a specific property, read the schema resour
 
 # 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.
-e-div-block - By default is ceneterd aligned and vertically stacked. To modify this, apply style configuration.
-e-flexbox - By default is a flex container with row direction. To modify this, apply style configuration.
-
 When working with containers, do not forget to apply style schema for controlling the layout.
 
 
@@ -2462,21 +2511,27 @@ var initBuildCompositionsTool = (reg) => {
           throw new Error("Failed to parse XML structure: " + errorNode.textContent);
         }
         const children = Array.from(xml.children);
-        const iterate = (node, containerElement = documentContainer) => {
+        const iterate = async (node, containerElement = documentContainer, childIndex) => {
           const elementTag = node.tagName;
           if (!widgetsCache[elementTag]) {
             errors.push(new Error(`Unknown widget type: ${elementTag}`));
           }
-          const isContainer = elementTag === "e-flexbox" || elementTag === "e-div-block";
+          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 ? createElement6({
-            containerId: containerElement.id,
+            containerId: targetContainerId,
             model: {
               elType: elementTag,
               id: generateElementId()
             },
             options: { useHistory: false }
           }) : createElement6({
-            containerId: containerElement.id,
+            containerId: targetContainerId,
             model: {
               elType: "widget",
               widgetType: elementTag,
@@ -2516,8 +2571,10 @@ var initBuildCompositionsTool = (reg) => {
               }
             }
             if (isContainer) {
+              let currentChild2 = 0;
               for (const child of node.children) {
-                iterate(child, newElement);
+                iterate(child, newElement, currentChild2);
+                currentChild2++;
               }
             } else {
               node.innerHTML = "";
@@ -2526,8 +2583,10 @@ var initBuildCompositionsTool = (reg) => {
           } finally {
           }
         };
-        for (const childNode of children) {
-          iterate(childNode, documentContainer);
+        let currentChild = 0;
+        for await (const childNode of children) {
+          await iterate(childNode, documentContainer, currentChild);
+          currentChild++;
           try {
           } catch (error) {
             errors.push(error);
@@ -2597,6 +2656,8 @@ When a user requires to change anything in an element, such as updating text, co
 This tool handles elements of type "widget".
 This tool handles styling elements, using the "stylePropertiesToChange" parameter.
 
+To CLEAR a property (i.e., set it to default or none), provide null as a value.
+
 The element's schema must be known before using this tool.
 The style schema must be known before using this tool.
 
@@ -2790,7 +2851,24 @@ var schema = {
 };
 var outputSchema3 = {
   properties: z3.record(z3.string(), z3.any()).describe("A record mapping PropTypes to their corresponding PropValues"),
-  style: z3.record(z3.string(), z3.any()).describe("A record mapping StyleSchema properties to their corresponding PropValues")
+  style: z3.record(z3.string(), z3.any()).describe("A record mapping StyleSchema properties to their corresponding PropValues"),
+  childElements: z3.array(
+    z3.object({
+      id: z3.string(),
+      elementType: z3.string(),
+      childElements: z3.array(z3.any()).describe("An array of child element IDs, when applicable, same structure recursively")
+    })
+  ).describe("An array of child element IDs, when applicable, with recursive structure")
+};
+var structuredElements = (element) => {
+  const children = element.children || [];
+  return children.map((child) => {
+    return {
+      id: child.id,
+      elementType: child.model.get("elType") || child.model.get("widgetType") || "unknown",
+      childElements: structuredElements(child)
+    };
+  });
 };
 var initGetElementConfigTool = (reg) => {
   const { addTool } = reg;
@@ -2838,7 +2916,8 @@ var initGetElementConfigTool = (reg) => {
         },
         style: {
           ...stylePropValues
-        }
+        },
+        childElements: structuredElements(element)
       };
     }
   });
@@ -2858,6 +2937,7 @@ var initCanvasMcp = (reg) => {
 };
 
 // src/mcp/mcp-description.ts
+var ELEMENT_SCHEMA_URI = WIDGET_SCHEMA_URI.replace("{widgetType}", "element-schema");
 var mcpDescription = `Canvas MCP
 This MCP enables everything related to creation, configuration, and styling of elements on the Elementor canvas.
 
@@ -2893,11 +2973,53 @@ The tool accepts both the structure, the styling and the configuration of each e
 
 - First step: Retreive the available widgets by listing the [${WIDGET_SCHEMA_URI}] dynamic resource.
 - Second step: decide which elements to create, and their configuration and styles.
-  Retrieve the used elements configuration schema from the resource [${WIDGET_SCHEMA_URI}/element-name]
+  Retrieve the used elements configuration schema from the resource [${ELEMENT_SCHEMA_URI}]
 - Third step: define the styles for each element, using the common styles schema from the resource [${STYLE_SCHEMA_URI}]. List the resource to see all available style properties.
   For background and complicated layered styles, you can use "custom_css" property, which is supported only for ELEMENTOR PRO users ONLY.
   The custom css is intented to deal with yet unsupported CSS features that ARE NOT PART OF THE STYLE SCHEMA, to enable PRO users to support new CSS features.
 
+## Workflow for build-compositions tool
+1. **Parse user requirements** - Undestand what needs to be built (structure, content, styling).
+2. ** Check global resources FIRST** - Always check before building:
+   - List \`elementor://global-classes\` to see if the needed global classes already exist.
+   - List \`elementor://global-variables\` to see if the needed global variables already exist.
+   - **Preference**: Use existing global classes and variables over creating new inline styles.
+3. **Retreive widget schemas** - For each widget you will use:
+   - List [${WIDGET_SCHEMA_URI}] to see available widgets.
+   - Retrieve configuration schema from [${ELEMENT_SCHEMA_URI}] for each widget to understand required properties.
+   - Understand if a widget is a container (can have children) by checking the "llm_guidance" property in the widget's schema.
+4. **Build XML structure** - Create valid XML width configuration-ids:
+   - Every element has unique configuration-id attribute
+   - No text nodes, classes, IDs in XML.
+   
+5. **Create elementConfig** - For each configuration-id:
+   - Use PropValues with corrent \`$$type\` matching the schema.
+   - **Use global variables** in PropValues where applicable
+
+6. **Create stylesConfig** - For each configuration-id:
+   - Use style schema PropValues from [${STYLE_SCHEMA_URI}]
+   - **Priority**: Use style schema PropValues over custom_css
+   - **Use global variables** for colors, sizes, fonts where applicable
+   - **custom_css (PRO Users Only)**: The property appears only for PRO user. The purpose of custom_css is to support new CSS features not yet available in the style schema.
+     The schema supports multiple layers of background, gradients, filters. Prefer NOT USING custom_css.
+   - **Important**: Global classes are applied AFTER building the composition. Once built, apply classes using the "apply-global-class" tool - after completion of building the composition.
+
+7. **Validate** - Ensure:
+   - XML structure is valid
+   - All PropValues have corrent \`$$type\`
+   - After building a composition, you can retreive each element configuration using the "get-element-configuration-values" tool to verify correctness, using the IDs returned from the build-composition tool.
+
+## Key relationships:
+- **XML structure**: Defines the hierarchy of elements/widgets
+- **elementConfig**: Maps configuration-id to widget PropValues
+- **stylesConfig**: Maps configuration-id to style PropValues
+
+## Using global variables example:
+Existing global variables can be used during composition
+\`\`\`json
+{ "color": { "$$type": "global-color-variable", "value": "global-variable-id" } }
+\`\`\`
+
 # Configuring Elements / Adding Style to Elements
 An element configuration can be retrieved using the "get-element-configuration-values" tool.
 Updating an element requires only the UPDATED properties (including in the styles), as Elementor does a MERGE/PATCH operation.

package/package.json

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

package/src/mcp/mcp-description.ts

@@ -1,5 +1,7 @@
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from './resources/widgets-schema-resource';
 
+const ELEMENT_SCHEMA_URI = WIDGET_SCHEMA_URI.replace( '{widgetType}', 'element-schema' );
+
 export const mcpDescription = `Canvas MCP
 This MCP enables everything related to creation, configuration, and styling of elements on the Elementor canvas.
 
@@ -35,11 +37,53 @@ The tool accepts both the structure, the styling and the configuration of each e
 
 - First step: Retreive the available widgets by listing the [${ WIDGET_SCHEMA_URI }] dynamic resource.
 - Second step: decide which elements to create, and their configuration and styles.
-  Retrieve the used elements configuration schema from the resource [${ WIDGET_SCHEMA_URI }/element-name]
+  Retrieve the used elements configuration schema from the resource [${ ELEMENT_SCHEMA_URI }]
 - Third step: define the styles for each element, using the common styles schema from the resource [${ STYLE_SCHEMA_URI }]. List the resource to see all available style properties.
   For background and complicated layered styles, you can use "custom_css" property, which is supported only for ELEMENTOR PRO users ONLY.
   The custom css is intented to deal with yet unsupported CSS features that ARE NOT PART OF THE STYLE SCHEMA, to enable PRO users to support new CSS features.
 
+## Workflow for build-compositions tool
+1. **Parse user requirements** - Undestand what needs to be built (structure, content, styling).
+2. ** Check global resources FIRST** - Always check before building:
+   - List \`elementor://global-classes\` to see if the needed global classes already exist.
+   - List \`elementor://global-variables\` to see if the needed global variables already exist.
+   - **Preference**: Use existing global classes and variables over creating new inline styles.
+3. **Retreive widget schemas** - For each widget you will use:
+   - List [${ WIDGET_SCHEMA_URI }] to see available widgets.
+   - Retrieve configuration schema from [${ ELEMENT_SCHEMA_URI }] for each widget to understand required properties.
+   - Understand if a widget is a container (can have children) by checking the "llm_guidance" property in the widget's schema.
+4. **Build XML structure** - Create valid XML width configuration-ids:
+   - Every element has unique configuration-id attribute
+   - No text nodes, classes, IDs in XML.
+   
+5. **Create elementConfig** - For each configuration-id:
+   - Use PropValues with corrent \`$$type\` matching the schema.
+   - **Use global variables** in PropValues where applicable
+
+6. **Create stylesConfig** - For each configuration-id:
+   - Use style schema PropValues from [${ STYLE_SCHEMA_URI }]
+   - **Priority**: Use style schema PropValues over custom_css
+   - **Use global variables** for colors, sizes, fonts where applicable
+   - **custom_css (PRO Users Only)**: The property appears only for PRO user. The purpose of custom_css is to support new CSS features not yet available in the style schema.
+     The schema supports multiple layers of background, gradients, filters. Prefer NOT USING custom_css.
+   - **Important**: Global classes are applied AFTER building the composition. Once built, apply classes using the "apply-global-class" tool - after completion of building the composition.
+
+7. **Validate** - Ensure:
+   - XML structure is valid
+   - All PropValues have corrent \`$$type\`
+   - After building a composition, you can retreive each element configuration using the "get-element-configuration-values" tool to verify correctness, using the IDs returned from the build-composition tool.
+
+## Key relationships:
+- **XML structure**: Defines the hierarchy of elements/widgets
+- **elementConfig**: Maps configuration-id to widget PropValues
+- **stylesConfig**: Maps configuration-id to style PropValues
+
+## Using global variables example:
+Existing global variables can be used during composition
+\`\`\`json
+{ "color": { "$$type": "global-color-variable", "value": "global-variable-id" } }
+\`\`\`
+
 # Configuring Elements / Adding Style to Elements
 An element configuration can be retrieved using the "get-element-configuration-values" tool.
 Updating an element requires only the UPDATED properties (including in the styles), as Elementor does a MERGE/PATCH operation.

package/src/mcp/resources/breakpoints-resource.ts

@@ -5,7 +5,7 @@ import { v1ReadyEvent } from '@elementor/editor-v1-adapters';
 export const BREAKPOINTS_SCHEMA_URI = 'elementor://breakpoints/list';
 
 export const initBreakpointsResource = ( reg: MCPRegistryEntry ) => {
-	const { mcpServer } = reg;
+	const { mcpServer, sendResourceUpdated } = reg;
 
 	const getBreakpointsList = () => {
 		const { breakpoints } = ( window as unknown as ExtendedWindow ).elementor?.config?.responsive || {};
@@ -39,7 +39,7 @@ export const initBreakpointsResource = ( reg: MCPRegistryEntry ) => {
 	} );
 
 	window.addEventListener( v1ReadyEvent().name, () => {
-		mcpServer.server.sendResourceUpdated( {
+		sendResourceUpdated( {
 			uri: BREAKPOINTS_SCHEMA_URI,
 			...buildResourceResponse(),
 		} );

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

@@ -3,6 +3,7 @@ import { type MCPRegistryEntry, ResourceTemplate } from '@elementor/editor-mcp';
 import {
 	type ArrayPropType,
 	type ObjectPropType,
+	type Props,
 	type PropType,
 	Schema,
 	type TransformablePropType,
@@ -14,6 +15,21 @@ 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';
 
+const checkIfUserHasPro = () => {
+	const extendedWindow = window as Window & {
+		elementor?: {
+			helpers?: {
+				hasPro?: () => boolean;
+			};
+		};
+	};
+	const hasPro = extendedWindow.elementor?.helpers?.hasPro;
+	if ( typeof hasPro === 'function' ) {
+		return hasPro();
+	}
+	return false;
+};
+
 export const initWidgetsSchemaResource = ( reg: MCPRegistryEntry ) => {
 	const { mcpServer } = reg;
 
@@ -37,7 +53,11 @@ The css string must follow standard CSS syntax, with properties and values separ
 		'styles-schema',
 		new ResourceTemplate( STYLE_SCHEMA_URI, {
 			list: () => {
-				const categories = [ ...Object.keys( getStylesSchema() ), 'custom_css' ];
+				const isPro = checkIfUserHasPro();
+				const categories = [ ...Object.keys( getStylesSchema() ) ];
+				if ( ! isPro ) {
+					categories.push( 'custom_css' );
+				}
 				return {
 					resources: categories.map( ( category ) => ( {
 						uri: `elementor://styles/schema/${ category }`,
@@ -51,7 +71,7 @@ The css string must follow standard CSS syntax, with properties and values separ
 		},
 		async ( uri, variables ) => {
 			const category = typeof variables.category === 'string' ? variables.category : variables.category?.[ 0 ];
-			if ( category === 'custom_css' ) {
+			if ( category === 'custom_css' && checkIfUserHasPro() ) {
 				return {
 					contents: [
 						{
@@ -84,7 +104,8 @@ The css string must follow standard CSS syntax, with properties and values separ
 			list: () => {
 				const cache = getWidgetsCache() || {};
 				const availableWidgets = Object.keys( cache || {} ).filter(
-					( widgetType ) => cache[ widgetType ]?.atomic_props_schema
+					( widgetType ) =>
+						cache[ widgetType ]?.atomic_props_schema && cache[ widgetType ].meta?.llm_support !== false
 				);
 				return {
 					resources: availableWidgets.map( ( widgetType ) => ( {
@@ -100,8 +121,9 @@ The css string must follow standard CSS syntax, with properties and values separ
 		async ( uri, variables ) => {
 			const widgetType =
 				typeof variables.widgetType === 'string' ? variables.widgetType : variables.widgetType?.[ 0 ];
-			const propSchema = getWidgetsCache()?.[ widgetType ]?.atomic_props_schema;
-			if ( ! propSchema ) {
+			const widgetData = getWidgetsCache()?.[ widgetType ];
+			const propSchema = widgetData?.atomic_props_schema;
+			if ( ! propSchema || ! widgetData ) {
 				throw new Error( `No prop schema found for element type: ${ widgetType }` );
 			}
 			const asJson = Object.fromEntries(
@@ -115,6 +137,31 @@ The css string must follow standard CSS syntax, with properties and values separ
 				delete asJson[ key ];
 			} );
 
+			const description =
+				typeof widgetData?.meta?.description === 'string' ? widgetData.meta.description : undefined;
+
+			const defaultStyles: Record< string, Props > = {};
+			const baseStyleSchema = widgetData?.base_styles;
+			if ( baseStyleSchema ) {
+				Object.values( baseStyleSchema ).forEach( ( stylePropType ) => {
+					stylePropType.variants.forEach( ( variant ) => {
+						Object.assign( defaultStyles, variant.props );
+					} );
+				} );
+			}
+
+			// build llm instructions
+			const hasDefaultStyles = Object.keys( defaultStyles ).length > 0;
+			const llmGuidance: Record< string, unknown > = {
+				can_have_children: !! widgetData?.meta?.is_container,
+			};
+
+			if ( hasDefaultStyles ) {
+				llmGuidance.instructions =
+					'These are the default styles applied to the widget. Override only when necessary.';
+				llmGuidance.default_styles = defaultStyles;
+			}
+
 			return {
 				contents: [
 					{
@@ -123,6 +170,8 @@ The css string must follow standard CSS syntax, with properties and values separ
 						text: JSON.stringify( {
 							type: 'object',
 							properties: asJson,
+							description,
+							llm_guidance: llmGuidance,
 						} ),
 					},
 				],

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

@@ -24,6 +24,24 @@ When in doubt between "safe" and "distinctive," choose distinctive - users can a
 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
@@ -38,11 +56,11 @@ Prefer this tool over any other tool for building HTML structure, unless you are
 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".
+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.
-9. **CRITICAL - CUSTOM CSS PRIORITY**: Prefer using style schema. Custom CSS is ONLY FOR UNSUPPRTED schema styles.
+9. **CRITICAL - CUSTOM CSS USAGE**: ALWAYS Prefer using style schema. Custom CSS is ONLY FOR UNSUPPRTED schema styles.
    ALWAYS PRIORITIZE using the style schema PropValues for styling elements as they provide better user experience in the editor, and UI features for the end-users.
-   - Use custom_css only for style attributes that ARE NOT SUPPORTED via the style schema.
+   Use custom_css only for style attributes that ARE NOT SUPPORTED via the style schema AFTER YOU CHECK THE [${ STYLE_SCHEMA_URI }].
 
 # DESIGN VECTORS - Concrete Implementation Guidance
 
@@ -261,10 +279,8 @@ If unsure about the configuration of a specific property, read the schema resour
 
 # 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.
-e-div-block - By default is ceneterd aligned and vertically stacked. To modify this, apply style configuration.
-e-flexbox - By default is a flex container with row direction. To modify this, apply style configuration.
-
 When working with containers, do not forget to apply style schema for controlling the layout.
 
 

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

@@ -46,15 +46,31 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 				}
 
 				const children = Array.from( xml.children );
-				const iterate = ( node: Element, containerElement: V1Element = documentContainer ) => {
+				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 isContainer = elementTag === 'e-flexbox' || elementTag === 'e-div-block';
+					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: containerElement.id,
+								containerId: targetContainerId,
 								model: {
 									elType: elementTag,
 									id: generateElementId(),
@@ -62,7 +78,7 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 								options: { useHistory: false },
 						  } )
 						: createElement( {
-								containerId: containerElement.id,
+								containerId: targetContainerId,
 								model: {
 									elType: 'widget',
 									widgetType: elementTag,
@@ -103,8 +119,10 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 							}
 						}
 						if ( isContainer ) {
+							let currentChild = 0;
 							for ( const child of node.children ) {
-								iterate( child, newElement );
+								iterate( child, newElement, currentChild );
+								currentChild++;
 							}
 						} else {
 							node.innerHTML = '';
@@ -114,8 +132,10 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 					}
 				};
 
-				for ( const childNode of children ) {
-					iterate( childNode, documentContainer );
+				let currentChild = 0;
+				for await ( const childNode of children ) {
+					await iterate( childNode, documentContainer, currentChild );
+					currentChild++;
 					try {
 					} catch ( error ) {
 						errors.push( error as Error );

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

@@ -26,6 +26,8 @@ When a user requires to change anything in an element, such as updating text, co
 This tool handles elements of type "widget".
 This tool handles styling elements, using the "stylePropertiesToChange" parameter.
 
+To CLEAR a property (i.e., set it to default or none), provide null as a value.
+
 The element's schema must be known before using this tool.
 The style schema must be known before using this tool.
 

package/src/mcp/tools/get-element-config/tool.ts

@@ -1,4 +1,4 @@
-import { getContainer, getElementStyles, getWidgetsCache } from '@elementor/editor-elements';
+import { getContainer, getElementStyles, getWidgetsCache, type V1Element } from '@elementor/editor-elements';
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { type PropValue, Schema } from '@elementor/editor-props';
 import { z } from '@elementor/schema';
@@ -14,6 +14,32 @@ const outputSchema = {
 	style: z
 		.record( z.string(), z.any() )
 		.describe( 'A record mapping StyleSchema properties to their corresponding PropValues' ),
+	childElements: z
+		.array(
+			z.object( {
+				id: z.string(),
+				elementType: z.string(),
+				childElements: z
+					.array( z.any() )
+					.describe( 'An array of child element IDs, when applicable, same structure recursively' ),
+			} )
+		)
+		.describe( 'An array of child element IDs, when applicable, with recursive structure' ),
+};
+type ElementStructure = {
+	id: string;
+	elementType: string;
+	childElements: ElementStructure[];
+};
+const structuredElements = ( element: V1Element ): ElementStructure[] => {
+	const children = element.children || [];
+	return children.map( ( child ) => {
+		return {
+			id: child.id,
+			elementType: child.model.get( 'elType' ) || child.model.get( 'widgetType' ) || 'unknown',
+			childElements: structuredElements( child ),
+		};
+	} );
 };
 
 export const initGetElementConfigTool = ( reg: MCPRegistryEntry ) => {
@@ -71,6 +97,7 @@ export const initGetElementConfigTool = ( reg: MCPRegistryEntry ) => {
 				style: {
 					...stylePropValues,
 				},
+				childElements: structuredElements( element ),
 			};
 		},
 	} );

package/src/mcp/utils/validate-input.ts

@@ -48,9 +48,9 @@ export const validateInput = {
 			} else if ( ! Schema.isPropKeyConfigurable( propName ) ) {
 				errors.push( `Property "${ propName }" is not configurable.` );
 			} else {
-				const { valid, errorMessages } = Schema.validatePropValue( propSchema, propValue as PropValue );
+				const { valid, jsonSchema } = Schema.validatePropValue( propSchema, propValue as PropValue );
 				if ( ! valid ) {
-					errors.push( `Invalid property "${ propName }": ${ errorMessages }` );
+					errors.push( `Invalid property "${ propName }". Expected schema: ${ jsonSchema }` );
 				}
 			}
 		} );