@elementor/editor-canvas 4.2.0-935 → 4.2.0-937

package/dist/index.js

@@ -74,18 +74,6 @@ var import_editor_elements2 = require("@elementor/editor-elements");
 var import_editor_mcp = require("@elementor/editor-mcp");
 var import_editor_props = require("@elementor/editor-props");
 
-// src/composition-builder/utils/required-default-child-tags.ts
-function getRequiredDefaultChildTemplates(elementConfig) {
-  const defaultChildren = elementConfig?.default_children;
-  if (!Array.isArray(defaultChildren)) {
-    return [];
-  }
-  return defaultChildren.filter((child) => child?.meta?.required ?? false);
-}
-function getRequiredDefaultChildTypes(elementConfig) {
-  return getRequiredDefaultChildTemplates(elementConfig).map((child) => child.widgetType ?? child.elType ?? "").filter((type) => Boolean(type));
-}
-
 // src/mcp/utils/element-data-util.ts
 var import_editor_elements = require("@elementor/editor-elements");
 function hasV3Controls(controls) {
@@ -122,6 +110,84 @@ function getAvailableWidgets() {
   });
 }
 
+// src/composition-builder/utils/required-default-child-tags.ts
+function getRequiredDefaultChildTemplates(elementConfig) {
+  const defaultChildren = elementConfig?.default_children;
+  if (!Array.isArray(defaultChildren)) {
+    return [];
+  }
+  return defaultChildren.filter((child) => child?.meta?.required ?? false);
+}
+function getRequiredDefaultChildTypes(elementConfig) {
+  return getRequiredDefaultChildTemplates(elementConfig).map((child) => child.widgetType ?? child.elType ?? "").filter((type) => Boolean(type));
+}
+
+// src/mcp/resources/build-llm-guidance.ts
+var DEFAULT_STYLES_INSTRUCTION = "These are the default styles applied to the widget. Override only when necessary.";
+var DEFAULT_SETTINGS_INSTRUCTION = "These are the default settings applied to the widget. Omit them from elementConfig unless the user explicitly asks to change them.";
+var BASE_SETTING_PROP_HINT = "Has a widget default \u2014 omit unless user explicitly requests a change. See llm_guidance.default_settings.";
+function mergeInstructions(existing, additional) {
+  if (typeof existing === "string" && existing.length > 0) {
+    return `${existing} ${additional}`;
+  }
+  return additional;
+}
+function enrichPropertiesWithBaseSettingsHints(properties, baseSettingsKeys) {
+  if (!baseSettingsKeys.length) {
+    return properties;
+  }
+  const enriched = { ...properties };
+  for (const key of baseSettingsKeys) {
+    const propSchema = enriched[key];
+    if (!propSchema) {
+      continue;
+    }
+    enriched[key] = {
+      ...propSchema,
+      description: propSchema.description ? `${propSchema.description} ${BASE_SETTING_PROP_HINT}` : BASE_SETTING_PROP_HINT
+    };
+  }
+  return enriched;
+}
+function buildLlmGuidance(widgetData, widgetType, allWidgets) {
+  const defaultStyles = {};
+  const baseStyleSchema = widgetData?.base_styles;
+  if (baseStyleSchema) {
+    Object.values(baseStyleSchema).forEach((stylePropType) => {
+      stylePropType.variants.forEach((variant) => {
+        Object.assign(defaultStyles, variant.props);
+      });
+    });
+  }
+  const baseSettings = widgetData?.base_settings ?? {};
+  const hasDefaultStyles = Object.keys(defaultStyles).length > 0;
+  const hasDefaultSettings = Object.keys(baseSettings).length > 0;
+  const llmGuidance = {
+    can_have_children: !!widgetData?.meta?.is_container
+  };
+  if (hasDefaultStyles) {
+    llmGuidance.instructions = DEFAULT_STYLES_INSTRUCTION;
+    llmGuidance.default_styles = defaultStyles;
+  }
+  if (hasDefaultSettings) {
+    llmGuidance.instructions = mergeInstructions(llmGuidance.instructions, DEFAULT_SETTINGS_INSTRUCTION);
+    llmGuidance.default_settings = baseSettings;
+  }
+  const allowedChildTypes = widgetData.allowed_child_types;
+  const allowedParents = Object.entries(allWidgets).filter(([, parentConfig]) => parentConfig.allowed_child_types?.includes(widgetType)).map(([parentType]) => parentType);
+  if (allowedChildTypes?.length || allowedParents.length) {
+    llmGuidance.nesting = {
+      ...allowedChildTypes?.length ? { allowed_child_types: allowedChildTypes } : {},
+      ...allowedParents.length ? { allowed_parents: allowedParents } : {}
+    };
+  }
+  const requiredDirectChildTags = getRequiredDefaultChildTypes(widgetData);
+  if (requiredDirectChildTags.length) {
+    llmGuidance.required_direct_children = requiredDirectChildTags;
+  }
+  return llmGuidance;
+}
+
 // src/mcp/resources/widgets-schema-resource.ts
 var V3_LAYOUT_CONTROL_TYPES = /* @__PURE__ */ new Set(["section", "tab", "tabs"]);
 function extractV3ControlsMetadata(controls) {
@@ -238,40 +304,16 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
           ]
         };
       }
-      const asJson = Object.fromEntries(
-        Object.entries(propSchema).filter(([key, propType]) => import_editor_props.Schema.isPropKeyConfigurable(key, propType)).map(([key, propType]) => [key, import_editor_props.Schema.propTypeToJsonSchema(propType)])
+      const baseSettingsKeys = Object.keys(widgetData?.base_settings ?? {});
+      const asJson = enrichPropertiesWithBaseSettingsHints(
+        Object.fromEntries(
+          Object.entries(propSchema).filter(([key, propType]) => import_editor_props.Schema.isPropKeyConfigurable(key, propType)).map(([key, propType]) => [key, import_editor_props.Schema.propTypeToJsonSchema(propType)])
+        ),
+        baseSettingsKeys
       );
       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;
-      }
-      const allowedChildTypes = widgetData.allowed_child_types;
       const allWidgets = (0, import_editor_elements2.getWidgetsCache)() || {};
-      const allowedParents = Object.entries(allWidgets).filter(([, parentConfig]) => parentConfig.allowed_child_types?.includes(widgetType)).map(([parentType]) => parentType);
-      if (allowedChildTypes?.length || allowedParents.length) {
-        llmGuidance.nesting = {
-          ...allowedChildTypes?.length ? { allowed_child_types: allowedChildTypes } : {},
-          ...allowedParents.length ? { allowed_parents: allowedParents } : {}
-        };
-      }
-      const requiredDirectChildTags = getRequiredDefaultChildTypes(widgetData);
-      if (requiredDirectChildTags.length) {
-        llmGuidance.required_direct_children = requiredDirectChildTags;
-      }
+      const llmGuidance = buildLlmGuidance(widgetData, widgetType, allWidgets);
       return {
         contents: [
           {
@@ -5085,6 +5127,7 @@ Some elements have internal tree structures (nesting). When using these elements
 - style is raw CSS (property \u2192 value strings); the server converts it to native styles and stores any unconvertible declarations as the element custom CSS
 - NO LINKS in configuration
 - Retry on errors up to 10x
+- Check \`llm_guidance.default_settings\` in widget schemas \u2014 omit only keys listed there from elementConfig unless the user explicitly asks to change them
 
 # DYNAMIC TAGS
 - A value can be made dynamic wherever its schema exposes a \`"$$type": "dynamic"\` variant. This may be the property root OR a NESTED field (e.g. an image's \`src\`, not the whole \`image\`).
@@ -5163,7 +5206,7 @@ BAD: \`<e-flexbox style="height:100vh"><e-div-block style="height:100vh">overflo
 # HARD CONSTRAINTS
 - Variables ONLY from [elementor://global-variables] (others throw errors)
 - Avoid SVG widgets unless assets are pre-uploaded
-- Check \`llm_guidance\` in widget schemas
+- Check \`llm_guidance\` in widget schemas (\`default_styles\`, nesting, required children)
 
 # PARAMETERS
 - **xmlStructure**: Valid XML with configuration-id attributes
@@ -5565,6 +5608,8 @@ For all non-primitive entries in \`propertiesToChange\`, provide the schema \`ke
 
 Use the EXACT PropType schema given, and ALWAYS include the \`key\` from the schema for every property you are changing in \`propertiesToChange\`.
 
+Check \`llm_guidance.default_settings\` in the widget schema \u2014 include a key in \`propertiesToChange\` only when the user explicitly asks to change it.
+
 # Dynamic tags
 A value can be made dynamic wherever its schema exposes a variant with "$$type": "dynamic". This may be the property root OR a NESTED field: for example an image is made dynamic on its "src" (the root stays "image"), NOT on the whole "image" value.
 Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" variant, in place of the static variant. The variant's "name" enumerates the tags allowed at that node.
@@ -5922,7 +5967,7 @@ Always check existing resources before building:
 For each widget you'll use:
 - List \`${WIDGET_SCHEMA_URI}\` to see available widgets
 - Retrieve configuration schema from \`${ELEMENT_SCHEMA_URI}\` for each widget
-- Check the \`llm_guidance\` property to understand if a widget is a container (can have children)
+- Check the \`llm_guidance\` property for container nesting, \`default_styles\`, and \`default_settings\` (omit default_settings from elementConfig unless the user asks to change them)
 
 ### 4. Build XML Structure
 Create valid XML with configuration-ids:

package/dist/index.mjs

@@ -8,18 +8,6 @@ import {
   Schema
 } from "@elementor/editor-props";
 
-// src/composition-builder/utils/required-default-child-tags.ts
-function getRequiredDefaultChildTemplates(elementConfig) {
-  const defaultChildren = elementConfig?.default_children;
-  if (!Array.isArray(defaultChildren)) {
-    return [];
-  }
-  return defaultChildren.filter((child) => child?.meta?.required ?? false);
-}
-function getRequiredDefaultChildTypes(elementConfig) {
-  return getRequiredDefaultChildTemplates(elementConfig).map((child) => child.widgetType ?? child.elType ?? "").filter((type) => Boolean(type));
-}
-
 // src/mcp/utils/element-data-util.ts
 import { getWidgetsCache } from "@elementor/editor-elements";
 function hasV3Controls(controls) {
@@ -56,6 +44,84 @@ function getAvailableWidgets() {
   });
 }
 
+// src/composition-builder/utils/required-default-child-tags.ts
+function getRequiredDefaultChildTemplates(elementConfig) {
+  const defaultChildren = elementConfig?.default_children;
+  if (!Array.isArray(defaultChildren)) {
+    return [];
+  }
+  return defaultChildren.filter((child) => child?.meta?.required ?? false);
+}
+function getRequiredDefaultChildTypes(elementConfig) {
+  return getRequiredDefaultChildTemplates(elementConfig).map((child) => child.widgetType ?? child.elType ?? "").filter((type) => Boolean(type));
+}
+
+// src/mcp/resources/build-llm-guidance.ts
+var DEFAULT_STYLES_INSTRUCTION = "These are the default styles applied to the widget. Override only when necessary.";
+var DEFAULT_SETTINGS_INSTRUCTION = "These are the default settings applied to the widget. Omit them from elementConfig unless the user explicitly asks to change them.";
+var BASE_SETTING_PROP_HINT = "Has a widget default \u2014 omit unless user explicitly requests a change. See llm_guidance.default_settings.";
+function mergeInstructions(existing, additional) {
+  if (typeof existing === "string" && existing.length > 0) {
+    return `${existing} ${additional}`;
+  }
+  return additional;
+}
+function enrichPropertiesWithBaseSettingsHints(properties, baseSettingsKeys) {
+  if (!baseSettingsKeys.length) {
+    return properties;
+  }
+  const enriched = { ...properties };
+  for (const key of baseSettingsKeys) {
+    const propSchema = enriched[key];
+    if (!propSchema) {
+      continue;
+    }
+    enriched[key] = {
+      ...propSchema,
+      description: propSchema.description ? `${propSchema.description} ${BASE_SETTING_PROP_HINT}` : BASE_SETTING_PROP_HINT
+    };
+  }
+  return enriched;
+}
+function buildLlmGuidance(widgetData, widgetType, allWidgets) {
+  const defaultStyles = {};
+  const baseStyleSchema = widgetData?.base_styles;
+  if (baseStyleSchema) {
+    Object.values(baseStyleSchema).forEach((stylePropType) => {
+      stylePropType.variants.forEach((variant) => {
+        Object.assign(defaultStyles, variant.props);
+      });
+    });
+  }
+  const baseSettings = widgetData?.base_settings ?? {};
+  const hasDefaultStyles = Object.keys(defaultStyles).length > 0;
+  const hasDefaultSettings = Object.keys(baseSettings).length > 0;
+  const llmGuidance = {
+    can_have_children: !!widgetData?.meta?.is_container
+  };
+  if (hasDefaultStyles) {
+    llmGuidance.instructions = DEFAULT_STYLES_INSTRUCTION;
+    llmGuidance.default_styles = defaultStyles;
+  }
+  if (hasDefaultSettings) {
+    llmGuidance.instructions = mergeInstructions(llmGuidance.instructions, DEFAULT_SETTINGS_INSTRUCTION);
+    llmGuidance.default_settings = baseSettings;
+  }
+  const allowedChildTypes = widgetData.allowed_child_types;
+  const allowedParents = Object.entries(allWidgets).filter(([, parentConfig]) => parentConfig.allowed_child_types?.includes(widgetType)).map(([parentType]) => parentType);
+  if (allowedChildTypes?.length || allowedParents.length) {
+    llmGuidance.nesting = {
+      ...allowedChildTypes?.length ? { allowed_child_types: allowedChildTypes } : {},
+      ...allowedParents.length ? { allowed_parents: allowedParents } : {}
+    };
+  }
+  const requiredDirectChildTags = getRequiredDefaultChildTypes(widgetData);
+  if (requiredDirectChildTags.length) {
+    llmGuidance.required_direct_children = requiredDirectChildTags;
+  }
+  return llmGuidance;
+}
+
 // src/mcp/resources/widgets-schema-resource.ts
 var V3_LAYOUT_CONTROL_TYPES = /* @__PURE__ */ new Set(["section", "tab", "tabs"]);
 function extractV3ControlsMetadata(controls) {
@@ -172,40 +238,16 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
           ]
         };
       }
-      const asJson = Object.fromEntries(
-        Object.entries(propSchema).filter(([key, propType]) => Schema.isPropKeyConfigurable(key, propType)).map(([key, propType]) => [key, Schema.propTypeToJsonSchema(propType)])
+      const baseSettingsKeys = Object.keys(widgetData?.base_settings ?? {});
+      const asJson = enrichPropertiesWithBaseSettingsHints(
+        Object.fromEntries(
+          Object.entries(propSchema).filter(([key, propType]) => Schema.isPropKeyConfigurable(key, propType)).map(([key, propType]) => [key, Schema.propTypeToJsonSchema(propType)])
+        ),
+        baseSettingsKeys
       );
       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;
-      }
-      const allowedChildTypes = widgetData.allowed_child_types;
       const allWidgets = getWidgetsCache2() || {};
-      const allowedParents = Object.entries(allWidgets).filter(([, parentConfig]) => parentConfig.allowed_child_types?.includes(widgetType)).map(([parentType]) => parentType);
-      if (allowedChildTypes?.length || allowedParents.length) {
-        llmGuidance.nesting = {
-          ...allowedChildTypes?.length ? { allowed_child_types: allowedChildTypes } : {},
-          ...allowedParents.length ? { allowed_parents: allowedParents } : {}
-        };
-      }
-      const requiredDirectChildTags = getRequiredDefaultChildTypes(widgetData);
-      if (requiredDirectChildTags.length) {
-        llmGuidance.required_direct_children = requiredDirectChildTags;
-      }
+      const llmGuidance = buildLlmGuidance(widgetData, widgetType, allWidgets);
       return {
         contents: [
           {
@@ -5071,6 +5113,7 @@ Some elements have internal tree structures (nesting). When using these elements
 - style is raw CSS (property \u2192 value strings); the server converts it to native styles and stores any unconvertible declarations as the element custom CSS
 - NO LINKS in configuration
 - Retry on errors up to 10x
+- Check \`llm_guidance.default_settings\` in widget schemas \u2014 omit only keys listed there from elementConfig unless the user explicitly asks to change them
 
 # DYNAMIC TAGS
 - A value can be made dynamic wherever its schema exposes a \`"$$type": "dynamic"\` variant. This may be the property root OR a NESTED field (e.g. an image's \`src\`, not the whole \`image\`).
@@ -5149,7 +5192,7 @@ BAD: \`<e-flexbox style="height:100vh"><e-div-block style="height:100vh">overflo
 # HARD CONSTRAINTS
 - Variables ONLY from [elementor://global-variables] (others throw errors)
 - Avoid SVG widgets unless assets are pre-uploaded
-- Check \`llm_guidance\` in widget schemas
+- Check \`llm_guidance\` in widget schemas (\`default_styles\`, nesting, required children)
 
 # PARAMETERS
 - **xmlStructure**: Valid XML with configuration-id attributes
@@ -5551,6 +5594,8 @@ For all non-primitive entries in \`propertiesToChange\`, provide the schema \`ke
 
 Use the EXACT PropType schema given, and ALWAYS include the \`key\` from the schema for every property you are changing in \`propertiesToChange\`.
 
+Check \`llm_guidance.default_settings\` in the widget schema \u2014 include a key in \`propertiesToChange\` only when the user explicitly asks to change it.
+
 # Dynamic tags
 A value can be made dynamic wherever its schema exposes a variant with "$$type": "dynamic". This may be the property root OR a NESTED field: for example an image is made dynamic on its "src" (the root stays "image"), NOT on the whole "image" value.
 Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" variant, in place of the static variant. The variant's "name" enumerates the tags allowed at that node.
@@ -5908,7 +5953,7 @@ Always check existing resources before building:
 For each widget you'll use:
 - List \`${WIDGET_SCHEMA_URI}\` to see available widgets
 - Retrieve configuration schema from \`${ELEMENT_SCHEMA_URI}\` for each widget
-- Check the \`llm_guidance\` property to understand if a widget is a container (can have children)
+- Check the \`llm_guidance\` property for container nesting, \`default_styles\`, and \`default_settings\` (omit default_settings from elementConfig unless the user asks to change them)
 
 ### 4. Build XML Structure
 Create valid XML with configuration-ids:

package/package.json

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

package/src/mcp/mcp-description.ts

@@ -41,7 +41,7 @@ Always check existing resources before building:
 For each widget you'll use:
 - List \`${ WIDGET_SCHEMA_URI }\` to see available widgets
 - Retrieve configuration schema from \`${ ELEMENT_SCHEMA_URI }\` for each widget
-- Check the \`llm_guidance\` property to understand if a widget is a container (can have children)
+- Check the \`llm_guidance\` property for container nesting, \`default_styles\`, and \`default_settings\` (omit default_settings from elementConfig unless the user asks to change them)
 
 ### 4. Build XML Structure
 Create valid XML with configuration-ids:

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

@@ -0,0 +1,95 @@
+import { type V1ElementConfig } from '@elementor/editor-elements';
+
+import { buildLlmGuidance, enrichPropertiesWithBaseSettingsHints, mergeInstructions } from '../build-llm-guidance';
+
+const mockEmailBaseSettings = {
+	email: {
+		$$type: 'emails',
+		value: {
+			to: {
+				$$type: 'string-array',
+				value: [ { $$type: 'string', value: 'admin@example.com' } ],
+			},
+			from: { $$type: 'string', value: 'email@example.com' },
+			message: { $$type: 'string', value: '[all-fields]' },
+		},
+	},
+};
+
+const mockFormWidgetData = {
+	title: 'Form',
+	controls: {},
+	elType: 'widget',
+	meta: { is_container: true },
+	base_settings: mockEmailBaseSettings,
+	atomic_props_schema: {
+		email: { kind: 'object', key: 'emails' },
+		'form-name': { kind: 'string', key: 'string' },
+	},
+} as unknown as V1ElementConfig;
+
+describe( 'build-llm-guidance', () => {
+	it( 'mergeInstructions combines existing and additional instructions', () => {
+		expect( mergeInstructions( 'First.', 'Second.' ) ).toBe( 'First. Second.' );
+		expect( mergeInstructions( undefined, 'Only.' ) ).toBe( 'Only.' );
+	} );
+
+	it( 'buildLlmGuidance exposes default_settings for widgets with base_settings', () => {
+		const guidance = buildLlmGuidance( mockFormWidgetData, 'e-form', {} );
+
+		expect( guidance.default_settings ).toEqual( mockEmailBaseSettings );
+		expect( guidance.instructions ).toContain( 'Omit them from elementConfig unless the user explicitly asks' );
+		expect( guidance.can_have_children ).toBe( true );
+	} );
+
+	it( 'buildLlmGuidance merges style and settings instructions when both exist', () => {
+		const widgetData = {
+			...mockFormWidgetData,
+			base_styles: {
+				'e-form-base': {
+					variants: [
+						{
+							props: {
+								display: { $$type: 'string', value: 'flex' },
+							},
+						},
+					],
+				},
+			},
+		} as unknown as V1ElementConfig;
+
+		const guidance = buildLlmGuidance( widgetData, 'e-form', {} );
+
+		expect( guidance.default_styles ).toEqual( { display: { $$type: 'string', value: 'flex' } } );
+		expect( guidance.default_settings ).toEqual( mockEmailBaseSettings );
+		expect( guidance.instructions ).toContain( 'default styles' );
+		expect( guidance.instructions ).toContain( 'default settings' );
+	} );
+
+	it( 'enrichPropertiesWithBaseSettingsHints adds omit guidance to base setting props', () => {
+		const enriched = enrichPropertiesWithBaseSettingsHints(
+			{
+				email: { type: 'object' },
+				'form-name': { type: 'object' },
+			},
+			[ 'email' ]
+		);
+
+		expect( enriched.email.description ).toContain( 'llm_guidance.default_settings' );
+		expect( enriched[ 'form-name' ].description ).toBeUndefined();
+	} );
+} );
+
+describe( 'widgets-schema-resource base_settings integration', () => {
+	it( 'keeps base setting props in schema while enriching descriptions', () => {
+		const properties = enrichPropertiesWithBaseSettingsHints(
+			{
+				email: { type: 'object', properties: {} },
+			},
+			Object.keys( mockEmailBaseSettings )
+		);
+
+		expect( properties ).toHaveProperty( 'email' );
+		expect( properties.email.description ).toContain( 'omit unless user explicitly requests' );
+	} );
+} );

package/src/mcp/resources/build-llm-guidance.ts

@@ -0,0 +1,110 @@
+import { type V1ElementConfig } from '@elementor/editor-elements';
+import { type Props, type PropValue } from '@elementor/editor-props';
+
+import { getRequiredDefaultChildTypes } from '../../composition-builder/utils/required-default-child-tags';
+
+const DEFAULT_STYLES_INSTRUCTION = 'These are the default styles applied to the widget. Override only when necessary.';
+
+const DEFAULT_SETTINGS_INSTRUCTION =
+	'These are the default settings applied to the widget. Omit them from elementConfig unless the user explicitly asks to change them.';
+
+const BASE_SETTING_PROP_HINT =
+	'Has a widget default — omit unless user explicitly requests a change. See llm_guidance.default_settings.';
+
+export type LlmGuidance = Record< string, unknown >;
+
+export type JsonSchemaProperty = {
+	description?: string;
+	[ key: string ]: unknown;
+};
+
+export function mergeInstructions( existing: unknown, additional: string ): string {
+	if ( typeof existing === 'string' && existing.length > 0 ) {
+		return `${ existing } ${ additional }`;
+	}
+
+	return additional;
+}
+
+export function enrichPropertiesWithBaseSettingsHints(
+	properties: Record< string, JsonSchemaProperty >,
+	baseSettingsKeys: string[]
+): Record< string, JsonSchemaProperty > {
+	if ( ! baseSettingsKeys.length ) {
+		return properties;
+	}
+
+	const enriched: Record< string, JsonSchemaProperty > = { ...properties };
+
+	for ( const key of baseSettingsKeys ) {
+		const propSchema = enriched[ key ];
+
+		if ( ! propSchema ) {
+			continue;
+		}
+
+		enriched[ key ] = {
+			...propSchema,
+			description: propSchema.description
+				? `${ propSchema.description } ${ BASE_SETTING_PROP_HINT }`
+				: BASE_SETTING_PROP_HINT,
+		};
+	}
+
+	return enriched;
+}
+
+export function buildLlmGuidance(
+	widgetData: V1ElementConfig,
+	widgetType: string,
+	allWidgets: Record< string, V1ElementConfig >
+): LlmGuidance {
+	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 );
+			} );
+		} );
+	}
+
+	const baseSettings = ( widgetData?.base_settings ?? {} ) as Record< string, PropValue >;
+	const hasDefaultStyles = Object.keys( defaultStyles ).length > 0;
+	const hasDefaultSettings = Object.keys( baseSettings ).length > 0;
+
+	const llmGuidance: LlmGuidance = {
+		can_have_children: !! widgetData?.meta?.is_container,
+	};
+
+	if ( hasDefaultStyles ) {
+		llmGuidance.instructions = DEFAULT_STYLES_INSTRUCTION;
+		llmGuidance.default_styles = defaultStyles;
+	}
+
+	if ( hasDefaultSettings ) {
+		llmGuidance.instructions = mergeInstructions( llmGuidance.instructions, DEFAULT_SETTINGS_INSTRUCTION );
+		llmGuidance.default_settings = baseSettings;
+	}
+
+	const allowedChildTypes = widgetData.allowed_child_types;
+	const allowedParents = Object.entries( allWidgets )
+		.filter( ( [ , parentConfig ] ) => parentConfig.allowed_child_types?.includes( widgetType ) )
+		.map( ( [ parentType ] ) => parentType );
+
+	if ( allowedChildTypes?.length || allowedParents.length ) {
+		llmGuidance.nesting = {
+			...( allowedChildTypes?.length ? { allowed_child_types: allowedChildTypes } : {} ),
+			...( allowedParents.length ? { allowed_parents: allowedParents } : {} ),
+		};
+	}
+
+	const requiredDirectChildTags = getRequiredDefaultChildTypes( widgetData );
+
+	if ( requiredDirectChildTags.length ) {
+		llmGuidance.required_direct_children = requiredDirectChildTags;
+	}
+
+	return llmGuidance;
+}

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

@@ -3,15 +3,14 @@ import { type MCPRegistryEntry, ResourceTemplate } from '@elementor/editor-mcp';
 import {
 	type ArrayPropType,
 	type ObjectPropType,
-	type Props,
 	type PropType,
 	Schema,
 	type TransformablePropType,
 	type UnionPropType,
 } from '@elementor/editor-props';
 
-import { getRequiredDefaultChildTypes } from '../../composition-builder/utils/required-default-child-tags';
 import { hasV3Controls, isWidgetAvailableForLLM } from '../utils/element-data-util';
+import { buildLlmGuidance, enrichPropertiesWithBaseSettingsHints } from './build-llm-guidance';
 
 const V3_LAYOUT_CONTROL_TYPES = new Set( [ 'section', 'tab', 'tabs' ] );
 
@@ -143,55 +142,22 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
 					],
 				};
 			}
-			const asJson = Object.fromEntries(
-				Object.entries( propSchema )
-					.filter( ( [ key, propType ] ) => Schema.isPropKeyConfigurable( key, propType as PropType ) )
-					.map( ( [ key, propType ] ) => [ key, Schema.propTypeToJsonSchema( propType ) ] )
+			const baseSettingsKeys = Object.keys( widgetData?.base_settings ?? {} );
+
+			const asJson = enrichPropertiesWithBaseSettingsHints(
+				Object.fromEntries(
+					Object.entries( propSchema )
+						.filter( ( [ key, propType ] ) => Schema.isPropKeyConfigurable( key, propType as PropType ) )
+						.map( ( [ key, propType ] ) => [ key, Schema.propTypeToJsonSchema( propType ) ] )
+				),
+				baseSettingsKeys
 			);
 
 			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;
-			}
-
-			const allowedChildTypes = widgetData.allowed_child_types;
-
 			const allWidgets = getWidgetsCache() || {};
-			const allowedParents = Object.entries( allWidgets )
-				.filter( ( [ , parentConfig ] ) => parentConfig.allowed_child_types?.includes( widgetType ) )
-				.map( ( [ parentType ] ) => parentType );
-
-			if ( allowedChildTypes?.length || allowedParents.length ) {
-				llmGuidance.nesting = {
-					...( allowedChildTypes?.length ? { allowed_child_types: allowedChildTypes } : {} ),
-					...( allowedParents.length ? { allowed_parents: allowedParents } : {} ),
-				};
-			}
-
-			const requiredDirectChildTags = getRequiredDefaultChildTypes( widgetData );
-			if ( requiredDirectChildTags.length ) {
-				llmGuidance.required_direct_children = requiredDirectChildTags;
-			}
+			const llmGuidance = buildLlmGuidance( widgetData, widgetType, allWidgets );
 
 			return {
 				contents: [

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

@@ -41,6 +41,7 @@ Some elements have internal tree structures (nesting). When using these elements
 - style is raw CSS (property → value strings); the server converts it to native styles and stores any unconvertible declarations as the element custom CSS
 - NO LINKS in configuration
 - Retry on errors up to 10x
+- Check \`llm_guidance.default_settings\` in widget schemas — omit only keys listed there from elementConfig unless the user explicitly asks to change them
 
 # DYNAMIC TAGS
 - A value can be made dynamic wherever its schema exposes a \`"$$type": "dynamic"\` variant. This may be the property root OR a NESTED field (e.g. an image's \`src\`, not the whole \`image\`).
@@ -119,7 +120,7 @@ BAD: \`<e-flexbox style="height:100vh"><e-div-block style="height:100vh">overflo
 # HARD CONSTRAINTS
 - Variables ONLY from [elementor://global-variables] (others throw errors)
 - Avoid SVG widgets unless assets are pre-uploaded
-- Check \`llm_guidance\` in widget schemas
+- Check \`llm_guidance\` in widget schemas (\`default_styles\`, nesting, required children)
 
 # PARAMETERS
 - **xmlStructure**: Valid XML with configuration-id attributes

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

@@ -50,6 +50,8 @@ For all non-primitive entries in \`propertiesToChange\`, provide the schema \`ke
 
 Use the EXACT PropType schema given, and ALWAYS include the \`key\` from the schema for every property you are changing in \`propertiesToChange\`.
 
+Check \`llm_guidance.default_settings\` in the widget schema — include a key in \`propertiesToChange\` only when the user explicitly asks to change it.
+
 # Dynamic tags
 A value can be made dynamic wherever its schema exposes a variant with "$$type": "dynamic". This may be the property root OR a NESTED field: for example an image is made dynamic on its "src" (the root stays "image"), NOT on the whole "image" value.
 Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" variant, in place of the static variant. The variant's "name" enumerates the tags allowed at that node.