@elementor/editor-canvas 4.2.0-875 → 4.2.0-876

package/dist/index.js

@@ -109,6 +109,27 @@ var import_editor_mcp = require("@elementor/editor-mcp");
 var import_editor_props = require("@elementor/editor-props");
 var import_editor_styles = require("@elementor/editor-styles");
 
+// src/composition-builder/utils/required-default-child-tags.ts
+function resolveDefaultChildTemplateTagName(template) {
+  const elementType = template.elType;
+  if (elementType === "widget") {
+    return typeof template.widgetType === "string" ? template.widgetType : "";
+  }
+  return typeof elementType === "string" ? elementType : "";
+}
+function getRequiredDefaultChildTemplates(elementConfig) {
+  const defaultChildren = elementConfig?.default_children;
+  if (!Array.isArray(defaultChildren)) {
+    return [];
+  }
+  return defaultChildren.filter(
+    (child) => !!child?.meta?.required
+  );
+}
+function getRequiredDefaultChildTagNames(elementConfig) {
+  return getRequiredDefaultChildTemplates(elementConfig).map(resolveDefaultChildTemplateTagName).filter((tag) => Boolean(tag));
+}
+
 // src/mcp/utils/element-data-util.ts
 var import_editor_elements = require("@elementor/editor-elements");
 function hasV3Controls(controls) {
@@ -325,6 +346,10 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
           ...allowedParents.length ? { allowed_parents: allowedParents } : {}
         };
       }
+      const requiredDirectChildTags = getRequiredDefaultChildTagNames(widgetData);
+      if (requiredDirectChildTags.length) {
+        llmGuidance.required_direct_children = requiredDirectChildTags;
+      }
       return {
         contents: [
           {
@@ -4091,6 +4116,46 @@ var validateInput = {
   }
 };
 
+// src/composition-builder/utils/required-children-enforcer.ts
+var REQUIRED_CHILD_SCHEMA_HINT = "Use the widget schema resource; under llm_guidance.required_direct_children for V4 widgets.";
+var RequiredChildrenEnforcer = class {
+  elementType;
+  requiredTemplates;
+  constructor(elementType, widgetsCache) {
+    this.elementType = elementType;
+    this.requiredTemplates = getRequiredDefaultChildTemplates(widgetsCache[elementType]);
+  }
+  enforce(xml) {
+    if (this.requiredTemplates.length === 0) {
+      return;
+    }
+    const errors = [];
+    for (const rootNode of Array.from(xml.children)) {
+      this.collectMissingRequiredErrors(rootNode, errors);
+    }
+    if (errors.length) {
+      throw new Error(`${errors.join("\n")}
+${REQUIRED_CHILD_SCHEMA_HINT}`);
+    }
+  }
+  collectMissingRequiredErrors(node, errors) {
+    if (node.tagName === this.elementType) {
+      const existingChildTags = new Set(Array.from(node.children).map((child) => child.tagName));
+      const missingTags = this.requiredTemplates.map(resolveDefaultChildTemplateTagName).filter((tag) => tag && !existingChildTags.has(tag));
+      if (missingTags.length) {
+        const configurationId = node.getAttribute("configuration-id");
+        const location2 = configurationId ? `<${node.tagName} configuration-id="${configurationId}">` : `<${node.tagName}>`;
+        errors.push(
+          `${location2} Missing required direct child element tag(s): ${missingTags.join(", ")}.`
+        );
+      }
+    }
+    for (const childNode of Array.from(node.children)) {
+      this.collectMissingRequiredErrors(childNode, errors);
+    }
+  }
+};
+
 // src/composition-builder/composition-builder.ts
 var CREATE_ELEMENT_INVALID_CONTAINER_MESSAGE = "createElement did not return an element container with a model.";
 var CompositionBuilder = class _CompositionBuilder {
@@ -4294,6 +4359,10 @@ var CompositionBuilder = class _CompositionBuilder {
         throw new Error(`Unknown widget type: ${node.tagName}`);
       }
     });
+    Object.keys(widgetsCache).forEach((elementType) => {
+      const requiredChildrenEnforcer = new RequiredChildrenEnforcer(elementType, widgetsCache);
+      requiredChildrenEnforcer.enforce(this.xml);
+    });
     const childTypeErrors = [];
     for (const rootChild of Array.from(this.xml.children)) {
       childTypeErrors.push(...this.validateChildTypes(rootChild, widgetsCache));
@@ -4372,6 +4441,7 @@ This tool support v4 elements only
 ## NESTED ELEMENTS
 Some elements have internal tree structures (nesting). When using these elements, you MUST build the FULL tree in XML.
 - Check \`llm_guidance.nesting\` in widget schemas for structure requirements
+- \`llm_guidance.required_direct_children\` lists element types that must appear as direct child tags in XML (from widget defaults)
 - \`allowed_child_types\` lists which element types can be nested inside
 - \`allowed_parents\` lists which element types this element can be placed inside
 

package/dist/index.mjs

@@ -52,6 +52,27 @@ import {
 } from "@elementor/editor-props";
 import { getStylesSchema } from "@elementor/editor-styles";
 
+// src/composition-builder/utils/required-default-child-tags.ts
+function resolveDefaultChildTemplateTagName(template) {
+  const elementType = template.elType;
+  if (elementType === "widget") {
+    return typeof template.widgetType === "string" ? template.widgetType : "";
+  }
+  return typeof elementType === "string" ? elementType : "";
+}
+function getRequiredDefaultChildTemplates(elementConfig) {
+  const defaultChildren = elementConfig?.default_children;
+  if (!Array.isArray(defaultChildren)) {
+    return [];
+  }
+  return defaultChildren.filter(
+    (child) => !!child?.meta?.required
+  );
+}
+function getRequiredDefaultChildTagNames(elementConfig) {
+  return getRequiredDefaultChildTemplates(elementConfig).map(resolveDefaultChildTemplateTagName).filter((tag) => Boolean(tag));
+}
+
 // src/mcp/utils/element-data-util.ts
 import { getWidgetsCache } from "@elementor/editor-elements";
 function hasV3Controls(controls) {
@@ -268,6 +289,10 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
           ...allowedParents.length ? { allowed_parents: allowedParents } : {}
         };
       }
+      const requiredDirectChildTags = getRequiredDefaultChildTagNames(widgetData);
+      if (requiredDirectChildTags.length) {
+        llmGuidance.required_direct_children = requiredDirectChildTags;
+      }
       return {
         contents: [
           {
@@ -4086,6 +4111,46 @@ var validateInput = {
   }
 };
 
+// src/composition-builder/utils/required-children-enforcer.ts
+var REQUIRED_CHILD_SCHEMA_HINT = "Use the widget schema resource; under llm_guidance.required_direct_children for V4 widgets.";
+var RequiredChildrenEnforcer = class {
+  elementType;
+  requiredTemplates;
+  constructor(elementType, widgetsCache) {
+    this.elementType = elementType;
+    this.requiredTemplates = getRequiredDefaultChildTemplates(widgetsCache[elementType]);
+  }
+  enforce(xml) {
+    if (this.requiredTemplates.length === 0) {
+      return;
+    }
+    const errors = [];
+    for (const rootNode of Array.from(xml.children)) {
+      this.collectMissingRequiredErrors(rootNode, errors);
+    }
+    if (errors.length) {
+      throw new Error(`${errors.join("\n")}
+${REQUIRED_CHILD_SCHEMA_HINT}`);
+    }
+  }
+  collectMissingRequiredErrors(node, errors) {
+    if (node.tagName === this.elementType) {
+      const existingChildTags = new Set(Array.from(node.children).map((child) => child.tagName));
+      const missingTags = this.requiredTemplates.map(resolveDefaultChildTemplateTagName).filter((tag) => tag && !existingChildTags.has(tag));
+      if (missingTags.length) {
+        const configurationId = node.getAttribute("configuration-id");
+        const location2 = configurationId ? `<${node.tagName} configuration-id="${configurationId}">` : `<${node.tagName}>`;
+        errors.push(
+          `${location2} Missing required direct child element tag(s): ${missingTags.join(", ")}.`
+        );
+      }
+    }
+    for (const childNode of Array.from(node.children)) {
+      this.collectMissingRequiredErrors(childNode, errors);
+    }
+  }
+};
+
 // src/composition-builder/composition-builder.ts
 var CREATE_ELEMENT_INVALID_CONTAINER_MESSAGE = "createElement did not return an element container with a model.";
 var CompositionBuilder = class _CompositionBuilder {
@@ -4289,6 +4354,10 @@ var CompositionBuilder = class _CompositionBuilder {
         throw new Error(`Unknown widget type: ${node.tagName}`);
       }
     });
+    Object.keys(widgetsCache).forEach((elementType) => {
+      const requiredChildrenEnforcer = new RequiredChildrenEnforcer(elementType, widgetsCache);
+      requiredChildrenEnforcer.enforce(this.xml);
+    });
     const childTypeErrors = [];
     for (const rootChild of Array.from(this.xml.children)) {
       childTypeErrors.push(...this.validateChildTypes(rootChild, widgetsCache));
@@ -4367,6 +4436,7 @@ This tool support v4 elements only
 ## NESTED ELEMENTS
 Some elements have internal tree structures (nesting). When using these elements, you MUST build the FULL tree in XML.
 - Check \`llm_guidance.nesting\` in widget schemas for structure requirements
+- \`llm_guidance.required_direct_children\` lists element types that must appear as direct child tags in XML (from widget defaults)
 - \`allowed_child_types\` lists which element types can be nested inside
 - \`allowed_parents\` lists which element types this element can be placed inside
 

package/package.json

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

package/src/composition-builder/__tests__/composition-builder.test.ts

@@ -1,4 +1,4 @@
-import { type V1Element } from '@elementor/editor-elements';
+import { type CreateElementParams, type V1Element, type V1ElementConfig } from '@elementor/editor-elements';
 
 import { CompositionBuilder } from '../composition-builder';
 
@@ -188,3 +188,189 @@ describe( 'CompositionBuilder.build applyProperties after create', () => {
 		expect( doUpdateElementProperty ).not.toHaveBeenCalled();
 	} );
 } );
+
+describe( 'CompositionBuilder.build required children', () => {
+	it( 'rejects build when required direct children are absent from XML', async () => {
+		// Arrange
+		let elementIdSequence = 0;
+		const createdElement = createMockPartialContainer( GENERATED_ELEMENT_ID );
+		const createElementMock = jest.fn().mockReturnValue( createdElement );
+		const formWidgetsCache = {
+			'e-form': {
+				title: 'Form',
+				controls: {},
+				elType: 'widget',
+				default_children: [
+					{
+						elType: 'e-form-success-message',
+						meta: { required: true },
+						elements: [],
+					},
+					{
+						elType: 'e-form-error-message',
+						meta: { required: true },
+						elements: [],
+					},
+					{
+						elType: 'widget',
+						widgetType: 'e-form-input',
+						elements: [],
+					},
+				],
+			},
+			'e-form-error-message': {
+				title: 'Error',
+				controls: {},
+				elType: 'e-form-error-message',
+			},
+			'e-form-input': { title: 'Input', controls: {}, elType: 'widget' },
+			'e-form-success-message': {
+				title: 'Success',
+				controls: {},
+				elType: 'e-form-success-message',
+			},
+		} as Record< string, V1ElementConfig >;
+		const builder = CompositionBuilder.fromXMLString(
+			'<e-form configuration-id="form-1"><e-form-input /></e-form>',
+			{
+				createElement: createElementMock,
+				deleteElement: jest.fn(),
+				getContainer: jest.fn(),
+				generateElementId: jest.fn().mockImplementation( () => `form-comp-${ ++elementIdSequence }` ),
+				getWidgetsCache: jest.fn().mockReturnValue( formWidgetsCache ),
+				doUpdateElementProperty: jest.fn(),
+			}
+		);
+
+		// Act & Assert
+		await expect( builder.build( createMockRootContainer() ) ).rejects.toThrow(
+			/Missing required direct child element tag\(s\): e-form-success-message, e-form-error-message/
+		);
+		expect( createElementMock ).not.toHaveBeenCalled();
+	} );
+
+	it( 'rejects build when only some required direct children exist', async () => {
+		// Arrange
+		let elementIdSequence = 0;
+		const createdElement = createMockPartialContainer( GENERATED_ELEMENT_ID );
+		const createElementMock = jest.fn().mockReturnValue( createdElement );
+		const formWidgetsCache = {
+			'e-form': {
+				title: 'Form',
+				controls: {},
+				elType: 'widget',
+				default_children: [
+					{
+						elType: 'e-form-success-message',
+						meta: { required: true },
+						elements: [],
+					},
+					{
+						elType: 'e-form-error-message',
+						meta: { required: true },
+						elements: [],
+					},
+					{
+						elType: 'widget',
+						widgetType: 'e-form-input',
+						elements: [],
+					},
+				],
+			},
+			'e-form-error-message': {
+				title: 'Error',
+				controls: {},
+				elType: 'e-form-error-message',
+			},
+			'e-form-input': { title: 'Input', controls: {}, elType: 'widget' },
+			'e-form-success-message': {
+				title: 'Success',
+				controls: {},
+				elType: 'e-form-success-message',
+			},
+		} as Record< string, V1ElementConfig >;
+		const builder = CompositionBuilder.fromXMLString(
+			'<e-form configuration-id="form-1"><e-form-success-message /><e-form-input /></e-form>',
+			{
+				createElement: createElementMock,
+				deleteElement: jest.fn(),
+				getContainer: jest.fn(),
+				generateElementId: jest.fn().mockImplementation( () => `form-comp-${ ++elementIdSequence }` ),
+				getWidgetsCache: jest.fn().mockReturnValue( formWidgetsCache ),
+				doUpdateElementProperty: jest.fn(),
+			}
+		);
+
+		// Act & Assert
+		await expect( builder.build( createMockRootContainer() ) ).rejects.toThrow(
+			/Missing required direct child element tag\(s\): e-form-error-message/
+		);
+		expect( createElementMock ).not.toHaveBeenCalled();
+	} );
+
+	it( 'creates elements when XML includes all required direct children', async () => {
+		// Arrange
+		let elementIdSequence = 0;
+		const createdElement = createMockPartialContainer( GENERATED_ELEMENT_ID );
+		const createElementMock = jest.fn().mockReturnValue( createdElement );
+		const formWidgetsCache = {
+			'e-form': {
+				title: 'Form',
+				controls: {},
+				elType: 'widget',
+				default_children: [
+					{
+						elType: 'e-form-success-message',
+						meta: { required: true },
+						elements: [],
+					},
+					{
+						elType: 'e-form-error-message',
+						meta: { required: true },
+						elements: [],
+					},
+					{
+						elType: 'widget',
+						widgetType: 'e-form-input',
+						elements: [],
+					},
+				],
+			},
+			'e-form-error-message': {
+				title: 'Error',
+				controls: {},
+				elType: 'e-form-error-message',
+			},
+			'e-form-input': { title: 'Input', controls: {}, elType: 'widget' },
+			'e-form-success-message': {
+				title: 'Success',
+				controls: {},
+				elType: 'e-form-success-message',
+			},
+		} as Record< string, V1ElementConfig >;
+		const builder = CompositionBuilder.fromXMLString(
+			'<e-form configuration-id="form-1">' +
+				'<e-form-success-message /><e-form-error-message /><e-form-input />' +
+				'</e-form>',
+			{
+				createElement: createElementMock,
+				deleteElement: jest.fn(),
+				getContainer: jest.fn(),
+				generateElementId: jest.fn().mockImplementation( () => `form-comp-${ ++elementIdSequence }` ),
+				getWidgetsCache: jest.fn().mockReturnValue( formWidgetsCache ),
+				doUpdateElementProperty: jest.fn(),
+			}
+		);
+
+		// Act
+		await builder.build( createMockRootContainer() );
+
+		// Assert
+		const createArgs = createElementMock.mock.calls[ 0 ]?.[ 0 ] as CreateElementParams;
+		const childElements = ( createArgs.model?.elements || [] ) as Array< { elType?: string; widgetType?: string } >;
+
+		expect( childElements.filter( ( child ) => child.elType === 'e-form-success-message' ).length ).toBe( 1 );
+		expect( childElements.filter( ( child ) => child.elType === 'e-form-error-message' ).length ).toBe( 1 );
+		expect( childElements.some( ( child ) => child.widgetType === 'e-form-input' ) ).toBe( true );
+	} );
+} );

package/src/composition-builder/composition-builder.ts

@@ -13,6 +13,7 @@ import { type z } from '@elementor/schema';
 
 import { doUpdateElementProperty } from '../mcp/utils/do-update-element-property';
 import { validateInput } from '../mcp/utils/validate-input';
+import { RequiredChildrenEnforcer } from './utils/required-children-enforcer';
 
 type AnyValue = z.infer< z.ZodTypeAny >;
 type AnyConfig = Record< string, Record< string, AnyValue > >;
@@ -280,6 +281,11 @@ export class CompositionBuilder {
 			}
 		} );
 
+		Object.keys( widgetsCache ).forEach( ( elementType ) => {
+			const requiredChildrenEnforcer = new RequiredChildrenEnforcer( elementType, widgetsCache );
+			requiredChildrenEnforcer.enforce( this.xml );
+		} );
+
 		const childTypeErrors: string[] = [];
 		for ( const rootChild of Array.from( this.xml.children ) ) {
 			childTypeErrors.push( ...this.validateChildTypes( rootChild, widgetsCache ) );

package/src/composition-builder/utils/__tests__/required-children-enforcer.test.ts

@@ -0,0 +1,79 @@
+import { type V1ElementConfig } from '@elementor/editor-elements';
+
+import { RequiredChildrenEnforcer } from '../required-children-enforcer';
+
+describe( 'RequiredChildrenEnforcer', () => {
+	const FULL_FORM_DIRECT_CHILD_COUNT = 3;
+
+	const createWidgetsCache = (): Record< string, V1ElementConfig > => ( {
+		'e-form': {
+			title: 'Form',
+			controls: {},
+			elType: 'widget',
+			default_children: [
+				{
+					elType: 'e-form-success-message',
+					meta: { required: true },
+					elements: [],
+				},
+				{
+					elType: 'e-form-error-message',
+					meta: { required: true },
+					elements: [],
+				},
+				{
+					elType: 'widget',
+					widgetType: 'e-form-input',
+					elements: [],
+				},
+			],
+		} as V1ElementConfig,
+		'e-form-input': { title: 'Input', controls: {}, elType: 'widget' } as V1ElementConfig,
+		'e-form-success-message': {
+			title: 'Success',
+			controls: {},
+			elType: 'e-form-success-message',
+		} as V1ElementConfig,
+		'e-form-error-message': {
+			title: 'Error',
+			controls: {},
+			elType: 'e-form-error-message',
+		} as V1ElementConfig,
+	} );
+
+	it( 'throws when required direct children are missing', () => {
+		// Arrange
+		const xml = new DOMParser().parseFromString( '<e-form><e-form-input /></e-form>', 'application/xml' );
+		const enforcer = new RequiredChildrenEnforcer( 'e-form', createWidgetsCache() );
+
+		// Act & Assert
+		expect( () => enforcer.enforce( xml ) ).toThrow(
+			/Missing required direct child element tag\(s\): e-form-success-message, e-form-error-message/
+		);
+	} );
+
+	it( 'throws when only some required direct children exist', () => {
+		// Arrange
+		const xml = new DOMParser().parseFromString( '<e-form><e-form-success-message /></e-form>', 'application/xml' );
+		const enforcer = new RequiredChildrenEnforcer( 'e-form', createWidgetsCache() );
+
+		// Act & Assert
+		expect( () => enforcer.enforce( xml ) ).toThrow(
+			/Missing required direct child element tag\(s\): e-form-error-message/
+		);
+	} );
+
+	it( 'does not throw when all required direct children exist', () => {
+		// Arrange
+		const xmlStr = '<e-form><e-form-success-message /><e-form-error-message /><e-form-input /></e-form>';
+		const xml = new DOMParser().parseFromString( xmlStr, 'application/xml' );
+		const enforcer = new RequiredChildrenEnforcer( 'e-form', createWidgetsCache() );
+
+		// Act
+		expect( () => enforcer.enforce( xml ) ).not.toThrow();
+
+		// Assert
+		const form = xml.querySelector( 'e-form' );
+		expect( form?.children.length ).toBe( FULL_FORM_DIRECT_CHILD_COUNT );
+	} );
+} );

package/src/composition-builder/utils/__tests__/required-default-child-tags.test.ts

@@ -0,0 +1,46 @@
+import { type V1ElementConfig } from '@elementor/editor-elements';
+
+import { getRequiredDefaultChildTagNames, resolveDefaultChildTemplateTagName } from '../required-default-child-tags';
+
+describe( 'required-default-child-tags', () => {
+	it( 'returns XML tag names for default children marked meta.required', () => {
+		// Arrange
+		const config = {
+			title: 'Form',
+			controls: {},
+			default_children: [
+				{
+					elType: 'e-form-success-message',
+					meta: { required: true },
+					elements: [],
+				},
+				{
+					elType: 'widget',
+					widgetType: 'e-form-input',
+					meta: { required: true },
+				},
+				{
+					elType: 'e-form-label',
+					elements: [],
+				},
+			],
+		} as unknown as V1ElementConfig;
+
+		// Act
+		const tags = getRequiredDefaultChildTagNames( config );
+
+		// Assert
+		expect( tags ).toEqual( [ 'e-form-success-message', 'e-form-input' ] );
+	} );
+
+	it( 'resolveDefaultChildTemplateTagName uses widgetType when elType is widget', () => {
+		// Arrange
+		const template = { elType: 'widget', widgetType: 'e-form-submit-button' };
+
+		// Act
+		const tag = resolveDefaultChildTemplateTagName( template );
+
+		// Assert
+		expect( tag ).toBe( 'e-form-submit-button' );
+	} );
+} );

package/src/composition-builder/utils/required-children-enforcer.ts

@@ -0,0 +1,60 @@
+import { type V1ElementConfig } from '@elementor/editor-elements';
+
+import {
+	type DefaultChildTemplate,
+	getRequiredDefaultChildTemplates,
+	resolveDefaultChildTemplateTagName,
+} from './required-default-child-tags';
+
+const REQUIRED_CHILD_SCHEMA_HINT =
+	'Use the widget schema resource; under llm_guidance.required_direct_children for V4 widgets.';
+
+export class RequiredChildrenEnforcer {
+	private readonly elementType: string;
+	private readonly requiredTemplates: DefaultChildTemplate[];
+
+	constructor( elementType: string, widgetsCache: Record< string, V1ElementConfig > ) {
+		this.elementType = elementType;
+		this.requiredTemplates = getRequiredDefaultChildTemplates( widgetsCache[ elementType ] );
+	}
+
+	enforce( xml: Document ) {
+		if ( this.requiredTemplates.length === 0 ) {
+			return;
+		}
+
+		const errors: string[] = [];
+
+		for ( const rootNode of Array.from( xml.children ) ) {
+			this.collectMissingRequiredErrors( rootNode, errors );
+		}
+
+		if ( errors.length ) {
+			throw new Error( `${ errors.join( '\n' ) }\n${ REQUIRED_CHILD_SCHEMA_HINT }` );
+		}
+	}
+
+	private collectMissingRequiredErrors( node: Element, errors: string[] ) {
+		if ( node.tagName === this.elementType ) {
+			const existingChildTags = new Set( Array.from( node.children ).map( ( child ) => child.tagName ) );
+			const missingTags = this.requiredTemplates
+				.map( resolveDefaultChildTemplateTagName )
+				.filter( ( tag ) => tag && ! existingChildTags.has( tag ) ) as string[];
+
+			if ( missingTags.length ) {
+				const configurationId = node.getAttribute( 'configuration-id' );
+				const location = configurationId
+					? `<${ node.tagName } configuration-id="${ configurationId }">`
+					: `<${ node.tagName }>`;
+
+				errors.push(
+					`${ location } Missing required direct child element tag(s): ${ missingTags.join( ', ' ) }.`
+				);
+			}
+		}
+
+		for ( const childNode of Array.from( node.children ) ) {
+			this.collectMissingRequiredErrors( childNode, errors );
+		}
+	}
+}

package/src/composition-builder/utils/required-default-child-tags.ts

@@ -0,0 +1,31 @@
+import { type V1ElementConfig } from '@elementor/editor-elements';
+
+export type DefaultChildTemplate = Record< string, unknown >;
+
+export function resolveDefaultChildTemplateTagName( template: DefaultChildTemplate ): string {
+	const elementType = template.elType;
+
+	if ( elementType === 'widget' ) {
+		return typeof template.widgetType === 'string' ? template.widgetType : '';
+	}
+
+	return typeof elementType === 'string' ? elementType : '';
+}
+
+export function getRequiredDefaultChildTemplates( elementConfig: V1ElementConfig | undefined ): DefaultChildTemplate[] {
+	const defaultChildren = elementConfig?.default_children;
+
+	if ( ! Array.isArray( defaultChildren ) ) {
+		return [];
+	}
+
+	return defaultChildren.filter(
+		( child ): child is DefaultChildTemplate => !! ( child as { meta?: { required?: boolean } } )?.meta?.required
+	);
+}
+
+export function getRequiredDefaultChildTagNames( elementConfig: V1ElementConfig | undefined ): string[] {
+	return getRequiredDefaultChildTemplates( elementConfig )
+		.map( resolveDefaultChildTemplateTagName )
+		.filter( ( tag ) => Boolean( tag ) );
+}

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

@@ -11,6 +11,7 @@ import {
 } from '@elementor/editor-props';
 import { getStylesSchema } from '@elementor/editor-styles';
 
+import { getRequiredDefaultChildTagNames } from '../../composition-builder/utils/required-default-child-tags';
 import { hasV3Controls, isWidgetAvailableForLLM } from '../utils/element-data-util';
 
 const V3_LAYOUT_CONTROL_TYPES = new Set( [ 'section', 'tab', 'tabs' ] );
@@ -222,6 +223,11 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
 				};
 			}
 
+			const requiredDirectChildTags = getRequiredDefaultChildTagNames( widgetData );
+			if ( requiredDirectChildTags.length ) {
+				llmGuidance.required_direct_children = requiredDirectChildTags;
+			}
+
 			return {
 				contents: [
 					{

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

@@ -30,6 +30,7 @@ This tool support v4 elements only
 ## NESTED ELEMENTS
 Some elements have internal tree structures (nesting). When using these elements, you MUST build the FULL tree in XML.
 - Check \`llm_guidance.nesting\` in widget schemas for structure requirements
+- \`llm_guidance.required_direct_children\` lists element types that must appear as direct child tags in XML (from widget defaults)
 - \`allowed_child_types\` lists which element types can be nested inside
 - \`allowed_parents\` lists which element types this element can be placed inside