@elementor/editor-canvas 4.2.0-923 → 4.2.0-925

package/dist/index.mjs

@@ -2397,7 +2397,7 @@ function initStyleTransformers() {
 
 // src/legacy/init-legacy-views.ts
 import { getWidgetsCache as getWidgetsCache3 } from "@elementor/editor-elements";
-import { __privateListenTo, v1ReadyEvent as v1ReadyEvent2 } from "@elementor/editor-v1-adapters";
+import { __privateIsReady as isV1Ready, __privateListenTo, v1ReadyEvent as v1ReadyEvent2 } from "@elementor/editor-v1-adapters";
 
 // src/renderers/create-dom-renderer.ts
 import { createArrayLoader, createEnvironment } from "@elementor/twing";
@@ -3698,22 +3698,29 @@ function registerModelExtensions(type, extensions) {
 }
 function registerElementType(type, elementTypeGenerator) {
   elementsLegacyTypes[type] = elementTypeGenerator;
+  if (isV1Ready()) {
+    registerElementInLegacyManager(type, createDomRenderer());
+  }
 }
 function initLegacyViews() {
   __privateListenTo(v1ReadyEvent2(), () => {
     const widgetsCache = getWidgetsCache3() ?? {};
-    const legacyWindow = window;
     const renderer = createDomRenderer();
     registerProPromotionTypes(widgetsCache);
-    Object.entries(widgetsCache).forEach(([type, element]) => {
-      if (!element.atomic) {
-        return;
-      }
-      const ResolvedElementType = resolveElementType(type, renderer, element);
-      tryRegisterElement(legacyWindow, type, element, ResolvedElementType);
+    Object.keys(widgetsCache).forEach((type) => {
+      registerElementInLegacyManager(type, renderer);
     });
   });
 }
+function registerElementInLegacyManager(type, renderer) {
+  const element = (getWidgetsCache3() ?? {})[type];
+  if (!element?.atomic) {
+    return;
+  }
+  const legacyWindow = window;
+  const ResolvedElementType = resolveElementType(type, renderer, element);
+  tryRegisterElement(legacyWindow, type, element, ResolvedElementType);
+}
 function registerProPromotionTypes(widgetsCache) {
   Object.entries(widgetsCache).forEach(([type, element]) => {
     if (element.meta?.is_pro_promotion) {
@@ -3787,6 +3794,9 @@ function initTabsModelExtensions() {
   registerModelExtensions("e-tab", tabModelExtensions);
 }
 
+// src/mcp/canvas-mcp.ts
+import { Schema as Schema6 } from "@elementor/editor-props";
+
 // src/mcp/resources/available-widgets-resource.ts
 import { v1ReadyEvent as v1ReadyEvent3 } from "@elementor/editor-v1-adapters";
 var AVAILABLE_WIDGETS_URI = "elementor://context/available-widgets";
@@ -3938,6 +3948,107 @@ function extractElementData(element) {
   return result;
 }
 
+// src/mcp/resources/dynamic-tags-resource.ts
+import { Schema as Schema2 } from "@elementor/editor-props";
+
+// src/mcp/utils/resolve-dynamic-tag.ts
+import { getElementorConfig } from "@elementor/editor-v1-adapters";
+var DYNAMIC_PROP_TYPE_KEY = "dynamic";
+var OMITTED_DYNAMIC_SETTING_KEYS = ["fallback"];
+var getAtomicDynamicTags = () => {
+  const config = getElementorConfig();
+  return config.atomicDynamicTags?.tags ?? {};
+};
+var getDynamicTagNamesByCategories = (categories) => {
+  if (!categories.length) {
+    return [];
+  }
+  const wanted = new Set(categories);
+  return Object.values(getAtomicDynamicTags()).filter((tag) => tag.categories?.some((category) => wanted.has(category))).map((tag) => tag.name);
+};
+var dynamicTagLLMResolver = (value) => {
+  const input = value ?? {};
+  const tag = input.name ? getAtomicDynamicTags()[input.name] : void 0;
+  if (!tag) {
+    return {
+      $$type: DYNAMIC_PROP_TYPE_KEY,
+      value: { name: input.name ?? "", group: "", settings: {} }
+    };
+  }
+  return {
+    $$type: DYNAMIC_PROP_TYPE_KEY,
+    value: {
+      name: tag.name,
+      group: tag.group,
+      settings: buildStrictSettings(tag.props_schema ?? {}, input.settings ?? {})
+    }
+  };
+};
+var buildStrictSettings = (schema2, provided) => {
+  const settings = {};
+  for (const [key, propType] of Object.entries(schema2)) {
+    if (OMITTED_DYNAMIC_SETTING_KEYS.includes(key)) {
+      continue;
+    }
+    const resolved = provided[key] !== void 0 ? wrapSettingValue(provided[key], propType) : defaultSettingValue(propType);
+    if (resolved !== void 0 && resolved !== null) {
+      settings[key] = resolved;
+    }
+  }
+  return settings;
+};
+var wrapSettingValue = (raw, propType) => {
+  if (raw !== null && typeof raw === "object") {
+    return raw;
+  }
+  return propType.key ? { $$type: propType.key, value: raw } : raw;
+};
+var defaultSettingValue = (propType) => {
+  if (propType.initial_value !== null && propType.initial_value !== void 0) {
+    return propType.initial_value;
+  }
+  if (propType.default !== null && propType.default !== void 0) {
+    return wrapSettingValue(propType.default, propType);
+  }
+  return void 0;
+};
+
+// src/mcp/resources/dynamic-tags-resource.ts
+var DYNAMIC_TAGS_URI = "elementor://dynamic-tags";
+var settingsSchema = (propsSchema) => {
+  return Object.fromEntries(
+    Object.entries(propsSchema ?? {}).filter(([key]) => !OMITTED_DYNAMIC_SETTING_KEYS.includes(key)).map(([key, propType]) => [key, Schema2.propTypeToJsonSchema(propType)])
+  );
+};
+var buildDynamicTagsList = () => {
+  return Object.values(getAtomicDynamicTags()).map((tag) => ({
+    name: tag.name,
+    label: tag.label,
+    categories: tag.categories,
+    settings: settingsSchema(tag.props_schema)
+  }));
+};
+var initDynamicTagsResource = (reg) => {
+  const { resource } = reg;
+  resource(
+    "dynamic-tags",
+    DYNAMIC_TAGS_URI,
+    {
+      description: `List of available dynamic tags. To bind a property to a dynamic source, set its value to { "$$type": "dynamic", "value": { "name": <tag name>, "settings": { ... } } } using a tag whose name appears in that property's allowed list, and populate "settings" per the tag entry here.`,
+      mimeType: "application/json"
+    },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(buildDynamicTagsList())
+        }
+      ]
+    })
+  );
+};
+
 // src/mcp/resources/editor-state-resource.ts
 import { __privateListenTo as listenTo2, commandEndEvent as commandEndEvent5 } from "@elementor/editor-v1-adapters";
 var CURRENTLY_VIEWED_SCREEN = "The user is currently viewing the Elementor editor";
@@ -4282,7 +4393,7 @@ import {
   updateElementSettings,
   updateElementStyle
 } from "@elementor/editor-elements";
-import { getPropSchemaFromCache, Schema as Schema2 } from "@elementor/editor-props";
+import { getPropSchemaFromCache, Schema as Schema3 } from "@elementor/editor-props";
 import { getStylesSchema as getStylesSchema3, getVariantByMeta } from "@elementor/editor-styles";
 import { __privateRunCommandSync as runCommandSync2 } from "@elementor/editor-v1-adapters";
 
@@ -4307,9 +4418,12 @@ var LOCAL_STYLE_META = {
 };
 function resolvePropValue(value, forceKey) {
   const Utils = window.elementorV2.editorVariables.Utils;
-  return Schema2.adjustLlmPropValueSchema(value, {
+  return Schema3.adjustLlmPropValueSchema(value, {
     forceKey,
-    transformers: Utils.globalVariablesLLMResolvers
+    transformers: {
+      ...Utils.globalVariablesLLMResolvers,
+      [DYNAMIC_PROP_TYPE_KEY]: dynamicTagLLMResolver
+    }
   });
 }
 var doUpdateElementProperty = (params) => {
@@ -4412,7 +4526,7 @@ var doUpdateElementProperty = (params) => {
   }
   const propKey = elementPropSchema[propertyName].key;
   const value = resolvePropValue(propertyValue, propKey);
-  const { valid, jsonSchema } = Schema2.validatePropValue(elementPropSchema[propertyName], propertyValue);
+  const { valid, jsonSchema } = Schema3.validatePropValue(elementPropSchema[propertyName], propertyValue);
   if (!valid) {
     throw new Error(
       `Invalid PropValue for elementId: ${elementId}. PropKey: ${propKey}, PropValue: ${JSON.stringify(
@@ -4433,7 +4547,7 @@ Expected Schema: ${jsonSchema}`
 
 // src/mcp/utils/validate-input.ts
 import { getWidgetsCache as getWidgetsCache7 } from "@elementor/editor-elements";
-import { Schema as Schema3 } from "@elementor/editor-props";
+import { Schema as Schema4 } from "@elementor/editor-props";
 import { getStylesSchema as getStylesSchema4 } from "@elementor/editor-styles";
 var _widgetsSchema = null;
 var validateInput = {
@@ -4467,10 +4581,10 @@ var validateInput = {
       if (!propSchema) {
         errors.push(`Property "${propName}" is not defined in the schema.`);
         hasInvalidKey = true;
-      } else if (!Schema3.isPropKeyConfigurable(propName, propSchema)) {
+      } else if (!Schema4.isPropKeyConfigurable(propName, propSchema)) {
         errors.push(`Property "${propName}" is not configurable.`);
       } else {
-        const { valid } = Schema3.validatePropValue(propSchema, propValue);
+        const { valid } = Schema4.validatePropValue(propSchema, propValue);
         if (!valid) {
           errors.push(
             `Invalid property "${propName}". Validate input with resource [${STYLE_SCHEMA_URI.replace(
@@ -4854,6 +4968,13 @@ Some elements have internal tree structures (nesting). When using these elements
 - NO LINKS in configuration
 - Retry on errors up to 10x
 
+# 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\`).
+- Put the dynamic object EXACTLY at that node, in place of the static variant. The variant's \`name\` lists the allowed tags; read [${DYNAMIC_TAGS_URI}] for each tag's settings schema.
+- Provide at that node: \`{ "$$type": "dynamic", "value": { "name": "<allowed tag>", "settings": { ... } } }\`
+- Example (image): \`{ "$$type": "image", "value": { "src": { "$$type": "dynamic", "value": { "name": "<image tag>", "settings": { ... } } } } }\`
+- Do NOT send \`group\` (it is resolved automatically). Populate \`settings\` strictly per the tag's schema; use \`{}\` only when it has none.
+
 Note about configuration ids: These names are visible to the end-user, make sure they make sense, related and relevant.
 
 # DESIGN PHILOSOPHY: CONTEXT-DRIVEN CREATIVITY
@@ -5075,7 +5196,8 @@ var initBuildCompositionsTool = (reg) => {
       { description: "Global Classes", uri: "elementor://global-classes" },
       { description: "Global Variables", uri: "elementor://global-variables" },
       { description: "Styles best practices", uri: BEST_PRACTICES_URI },
-      { description: "Available widgets for this tool", uri: AVAILABLE_WIDGETS_URI_V4 }
+      { description: "Available widgets for this tool", uri: AVAILABLE_WIDGETS_URI_V4 },
+      { description: "Dynamic tags catalog", uri: DYNAMIC_TAGS_URI }
     ],
     outputSchema,
     handler: async (rawParams) => {
@@ -5240,6 +5362,21 @@ For styleProperties, use the style schema provided, as it also uses the PropType
 For all non-primitive types, provide the key property as defined in the schema as $$type in the generated object, as it is MANDATORY for parsing.
 
 Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property from the original configuration for every property you are changing.
+
+# 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.
+1. Read the [${DYNAMIC_TAGS_URI}] resource for each allowed tag's settings schema.
+2. Provide, at that node:
+{
+  "$$type": "dynamic",
+  "value": {
+    "name": "<allowed tag name>",
+    "settings": { /* strictly per the tag's settings schema */ }
+  }
+}
+Image example: { "$$type": "image", "value": { "src": { "$$type": "dynamic", "value": { "name": "<image tag>", "settings": { ... } } } } }
+Do NOT send "group" (it is resolved automatically). Use { "settings": {} } only when the tag has no settings.
 `);
   configureElementToolPrompt.parameter("elementId", "The ID of the element to configure. MANDATORY.");
   configureElementToolPrompt.parameter(
@@ -5347,7 +5484,8 @@ var initConfigureElementTool = (reg) => {
     requiredResources: [
       { description: "Widgets schema", uri: WIDGET_SCHEMA_URI },
       { description: "Styles schema", uri: STYLE_SCHEMA_URI },
-      { description: "Configure element guide", uri: CONFIGURE_ELEMENT_GUIDE_URI }
+      { description: "Configure element guide", uri: CONFIGURE_ELEMENT_GUIDE_URI },
+      { description: "Dynamic tags catalog", uri: DYNAMIC_TAGS_URI }
     ],
     handler: ({ elementId, propertiesToChange, elementType, stylePropertiesToChange }) => {
       const widgetData = getWidgetsCache10()?.[elementType];
@@ -5443,7 +5581,7 @@ Check the styles schema at the resource [${STYLE_SCHEMA_URI.replace(
 
 // src/mcp/tools/get-element-config/tool.ts
 import { getContainer as getContainer6, getElementStyles as getElementStyles2, getWidgetsCache as getWidgetsCache11 } from "@elementor/editor-elements";
-import { Schema as Schema4 } from "@elementor/editor-props";
+import { Schema as Schema5 } from "@elementor/editor-props";
 import { z as z3 } from "@elementor/schema";
 var schema = {
   elementId: z3.string()
@@ -5500,7 +5638,7 @@ var initGetElementConfigTool = (reg) => {
       }
       const propValues = {};
       const stylePropValues = {};
-      Schema4.configurableKeys(propSchema).forEach((key) => {
+      Schema5.configurableKeys(propSchema).forEach((key) => {
         propValues[key] = structuredClone(elementRawSettings.get(key));
       });
       const elementStyles = getElementStyles2(elementId) || {};
@@ -5536,9 +5674,11 @@ var initGetElementConfigTool = (reg) => {
 
 // src/mcp/canvas-mcp.ts
 var initCanvasMcp = (reg) => {
+  Schema6.setDynamicTagNamesResolver(getDynamicTagNamesByCategories);
   initWidgetsSchemaResource(reg);
   initAvailableWidgetsResource(reg);
   initDocumentStructureResource(reg);
+  initDynamicTagsResource(reg);
   initSelectedElementResource(reg);
   initEditorStateResource(reg);
   initGeneralContextResource(reg);

package/package.json

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

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

@@ -0,0 +1,66 @@
+import { mockLegacyElementor } from 'test-utils';
+import { getWidgetsCache } from '@elementor/editor-elements';
+
+import { createTemplatedElementType } from '../create-templated-element-type';
+import { initLegacyViews, registerElementType } from '../init-legacy-views';
+import type { LegacyWindow } from '../types';
+
+jest.mock( '@elementor/editor-elements', () => ( {
+	getWidgetsCache: jest.fn(),
+} ) );
+
+jest.mock( '../../renderers/create-dom-renderer', () => ( {
+	createDomRenderer: jest.fn( () => ( {
+		register: jest.fn(),
+		render: jest.fn(),
+	} ) ),
+} ) );
+
+const MOCK_TYPE = 'test-loop-type';
+
+const createMockAtomicWidget = () => ( {
+	atomic: true,
+	controls: {},
+	title: MOCK_TYPE,
+	twig_templates: {},
+	twig_main_template: 'main',
+	atomic_props_schema: {},
+	base_styles_dictionary: {},
+} );
+
+const createMockElementsManager = () => ( {
+	getElementTypeClass: jest.fn().mockReturnValue( null ),
+	registerElementType: jest.fn(),
+	elementTypes: {} as Record< string, unknown >,
+} );
+
+const attachMockElementsManager = ( elementsManager: ReturnType< typeof createMockElementsManager > ) => {
+	const legacyWindow = window as unknown as LegacyWindow;
+	legacyWindow.elementor.elementsManager =
+		elementsManager as unknown as LegacyWindow[ 'elementor' ][ 'elementsManager' ];
+};
+
+describe( 'initLegacyViews', () => {
+	beforeEach( () => {
+		mockLegacyElementor();
+	} );
+
+	it( 'should register a late element type via the legacy manager without leaking state', () => {
+		// Arrange
+		const elementsManager = createMockElementsManager();
+		attachMockElementsManager( elementsManager );
+
+		jest.mocked( getWidgetsCache ).mockReturnValue( { [ MOCK_TYPE ]: createMockAtomicWidget() } );
+
+		initLegacyViews();
+		elementsManager.registerElementType.mockClear();
+
+		// Act
+		registerElementType( MOCK_TYPE, ( options ) => createTemplatedElementType( options ) );
+
+		// Assert
+		expect( elementsManager.registerElementType ).toHaveBeenCalledTimes( 1 );
+		const [ registeredInstance ] = elementsManager.registerElementType.mock.calls[ 0 ];
+		expect( registeredInstance.getType() ).toBe( MOCK_TYPE );
+	} );
+} );

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

@@ -1,5 +1,5 @@
 import { getWidgetsCache, type V1ElementConfig } from '@elementor/editor-elements';
-import { __privateListenTo, v1ReadyEvent } from '@elementor/editor-v1-adapters';
+import { __privateIsReady as isV1Ready, __privateListenTo, v1ReadyEvent } from '@elementor/editor-v1-adapters';
 
 import { createDomRenderer, type DomRenderer } from '../renderers/create-dom-renderer';
 import { createElementType } from './create-element-type';
@@ -30,28 +30,38 @@ export function registerElementType(
 	elementTypeGenerator: ElementLegacyType[ keyof ElementLegacyType ]
 ) {
 	elementsLegacyTypes[ type ] = elementTypeGenerator;
+
+	if ( isV1Ready() ) {
+		registerElementInLegacyManager( type, createDomRenderer() );
+	}
 }
 
 export function initLegacyViews() {
 	__privateListenTo( v1ReadyEvent(), () => {
 		const widgetsCache = getWidgetsCache() ?? {};
-		const legacyWindow = window as unknown as LegacyWindow;
 		const renderer = createDomRenderer();
 
 		registerProPromotionTypes( widgetsCache );
 
-		Object.entries( widgetsCache ).forEach( ( [ type, element ] ) => {
-			if ( ! element.atomic ) {
-				return;
-			}
-
-			const ResolvedElementType = resolveElementType( type, renderer, element );
-
-			tryRegisterElement( legacyWindow, type, element, ResolvedElementType );
+		Object.keys( widgetsCache ).forEach( ( type ) => {
+			registerElementInLegacyManager( type, renderer );
 		} );
 	} );
 }
 
+function registerElementInLegacyManager( type: string, renderer: DomRenderer ) {
+	const element = ( getWidgetsCache() ?? {} )[ type ];
+
+	if ( ! element?.atomic ) {
+		return;
+	}
+
+	const legacyWindow = window as unknown as LegacyWindow;
+	const ResolvedElementType = resolveElementType( type, renderer, element );
+
+	tryRegisterElement( legacyWindow, type, element, ResolvedElementType );
+}
+
 function registerProPromotionTypes( widgetsCache: Record< string, V1ElementConfig > ) {
 	Object.entries( widgetsCache ).forEach( ( [ type, element ] ) => {
 		if ( element.meta?.is_pro_promotion ) {

package/src/mcp/canvas-mcp.ts

@@ -1,8 +1,10 @@
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { Schema } from '@elementor/editor-props';
 
 import { initAvailableWidgetsResource } from './resources/available-widgets-resource';
 import { initBreakpointsResource } from './resources/breakpoints-resource';
 import { initDocumentStructureResource } from './resources/document-structure-resource';
+import { initDynamicTagsResource } from './resources/dynamic-tags-resource';
 import { initEditorStateResource } from './resources/editor-state-resource';
 import { initGeneralContextResource } from './resources/general-context-resource';
 import { initSelectedElementResource } from './resources/selected-element-resource';
@@ -10,11 +12,14 @@ import { initWidgetsSchemaResource } from './resources/widgets-schema-resource';
 import { initBuildCompositionsTool } from './tools/build-composition/tool';
 import { initConfigureElementTool } from './tools/configure-element/tool';
 import { initGetElementConfigTool } from './tools/get-element-config/tool';
+import { getDynamicTagNamesByCategories } from './utils/resolve-dynamic-tag';
 
 export const initCanvasMcp = ( reg: MCPRegistryEntry ) => {
+	Schema.setDynamicTagNamesResolver( getDynamicTagNamesByCategories );
 	initWidgetsSchemaResource( reg );
 	initAvailableWidgetsResource( reg );
 	initDocumentStructureResource( reg );
+	initDynamicTagsResource( reg );
 	initSelectedElementResource( reg );
 	initEditorStateResource( reg );
 	initGeneralContextResource( reg );

package/src/mcp/resources/__tests__/dynamic-tags-resource.test.ts

@@ -0,0 +1,85 @@
+import { Schema } from '@elementor/editor-props';
+import { getElementorConfig } from '@elementor/editor-v1-adapters';
+
+import { DYNAMIC_TAGS_URI, initDynamicTagsResource } from '../dynamic-tags-resource';
+
+jest.mock( '@elementor/editor-props', () => ( {
+	Schema: {
+		propTypeToJsonSchema: jest.fn( () => ( { mocked: true } ) ),
+	},
+} ) );
+
+jest.mock( '@elementor/editor-v1-adapters', () => ( {
+	getElementorConfig: jest.fn(),
+} ) );
+
+const mockedGetElementorConfig = getElementorConfig as jest.MockedFunction< typeof getElementorConfig >;
+
+type ResourceHandler = ( uri: URL ) => Promise< { contents: { text: string }[] } >;
+
+const captureHandler = (): ResourceHandler => {
+	const resource = jest.fn();
+	initDynamicTagsResource( { resource } as never );
+	return resource.mock.calls[ 0 ][ 3 ] as ResourceHandler;
+};
+
+const readCatalog = async () => {
+	const handler = captureHandler();
+	const result = await handler( new URL( DYNAMIC_TAGS_URI ) );
+	return JSON.parse( result.contents[ 0 ].text );
+};
+
+describe( 'dynamic-tags-resource', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'returns a flat tag list with categories and omits the fallback setting', async () => {
+		// Arrange
+		mockedGetElementorConfig.mockReturnValue( {
+			atomicDynamicTags: {
+				tags: {
+					'post-custom-field': {
+						name: 'post-custom-field',
+						label: 'Post Custom Field',
+						group: 'post',
+						categories: [ 'text', 'url' ],
+						props_schema: {
+							key: { kind: 'string', key: 'string' },
+							before: { kind: 'string', key: 'string' },
+							fallback: { kind: 'string', key: 'string' },
+						},
+					},
+				},
+				groups: { post: { title: 'Post' } },
+			},
+		} as never );
+
+		// Act
+		const catalog = await readCatalog();
+
+		// Assert
+		expect( Array.isArray( catalog ) ).toBe( true );
+		expect( catalog ).toHaveLength( 1 );
+		expect( catalog[ 0 ] ).toMatchObject( {
+			name: 'post-custom-field',
+			label: 'Post Custom Field',
+			categories: [ 'text', 'url' ],
+		} );
+		expect( catalog[ 0 ] ).not.toHaveProperty( 'group' );
+		expect( Object.keys( catalog[ 0 ].settings ) ).toEqual( [ 'key', 'before' ] );
+		expect( catalog[ 0 ].settings ).not.toHaveProperty( 'fallback' );
+	} );
+
+	it( 'returns an empty list when dynamic tags are unavailable', async () => {
+		// Arrange
+		mockedGetElementorConfig.mockReturnValue( {} as never );
+
+		// Act
+		const catalog = await readCatalog();
+
+		// Assert
+		expect( catalog ).toEqual( [] );
+		expect( Schema.propTypeToJsonSchema ).not.toHaveBeenCalled();
+	} );
+} );

package/src/mcp/resources/dynamic-tags-resource.ts

@@ -0,0 +1,52 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { type PropType, Schema } from '@elementor/editor-props';
+
+import {
+	type AtomicDynamicTag,
+	getAtomicDynamicTags,
+	OMITTED_DYNAMIC_SETTING_KEYS,
+} from '../utils/resolve-dynamic-tag';
+
+export const DYNAMIC_TAGS_URI = 'elementor://dynamic-tags';
+
+const settingsSchema = ( propsSchema: AtomicDynamicTag[ 'props_schema' ] ): Record< string, unknown > => {
+	return Object.fromEntries(
+		Object.entries( propsSchema ?? {} )
+			.filter( ( [ key ] ) => ! ( OMITTED_DYNAMIC_SETTING_KEYS as readonly string[] ).includes( key ) )
+			.map( ( [ key, propType ] ) => [ key, Schema.propTypeToJsonSchema( propType as PropType ) ] )
+	);
+};
+
+const buildDynamicTagsList = () => {
+	return Object.values( getAtomicDynamicTags() ).map( ( tag ) => ( {
+		name: tag.name,
+		label: tag.label,
+		categories: tag.categories,
+		settings: settingsSchema( tag.props_schema ),
+	} ) );
+};
+
+export const initDynamicTagsResource = ( reg: MCPRegistryEntry ) => {
+	const { resource } = reg;
+
+	resource(
+		'dynamic-tags',
+		DYNAMIC_TAGS_URI,
+		{
+			description:
+				'List of available dynamic tags. To bind a property to a dynamic source, set its value to ' +
+				'{ "$$type": "dynamic", "value": { "name": <tag name>, "settings": { ... } } } using a tag whose ' +
+				'name appears in that property\'s allowed list, and populate "settings" per the tag entry here.',
+			mimeType: 'application/json',
+		},
+		async ( uri: URL ) => ( {
+			contents: [
+				{
+					uri: uri.href,
+					mimeType: 'application/json',
+					text: JSON.stringify( buildDynamicTagsList() ),
+				},
+			],
+		} )
+	);
+};

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

@@ -1,6 +1,7 @@
 import { toolPrompts } from '@elementor/editor-mcp';
 
 import { AVAILABLE_WIDGETS_URI } from '../../resources/available-widgets-resource';
+import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
 
 export const BUILD_COMPOSITIONS_GUIDE_URI = 'elementor://canvas/tools/build-compositions-guide';
 
@@ -40,6 +41,13 @@ Some elements have internal tree structures (nesting). When using these elements
 - NO LINKS in configuration
 - Retry on errors up to 10x
 
+# 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\`).
+- Put the dynamic object EXACTLY at that node, in place of the static variant. The variant's \`name\` lists the allowed tags; read [${ DYNAMIC_TAGS_URI }] for each tag's settings schema.
+- Provide at that node: \`{ "$$type": "dynamic", "value": { "name": "<allowed tag>", "settings": { ... } } }\`
+- Example (image): \`{ "$$type": "image", "value": { "src": { "$$type": "dynamic", "value": { "name": "<image tag>", "settings": { ... } } } } }\`
+- Do NOT send \`group\` (it is resolved automatically). Populate \`settings\` strictly per the tag's schema; use \`{}\` only when it has none.
+
 Note about configuration ids: These names are visible to the end-user, make sure they make sense, related and relevant.
 
 # DESIGN PHILOSOPHY: CONTEXT-DRIVEN CREATIVITY