@elementor/editor-canvas 4.4.0-1124 → 4.4.0-1125

package/dist/index.js

@@ -195,7 +195,7 @@ var convertCssToAtomic = async (style) => {
 
 // src/init.tsx
 var import_editor = require("@elementor/editor");
-var import_editor_mcp4 = require("@elementor/editor-mcp");
+var import_editor_mcp5 = require("@elementor/editor-mcp");
 
 // src/components/classes-rename.tsx
 var import_react = require("react");
@@ -2572,11 +2572,11 @@ function getVal2(val) {
 var transformOriginTransformer = createTransformer((value) => {
   const x = getVal2(value.x);
   const y = getVal2(value.y);
-  const z3 = getVal2(value.z);
-  if (x === DEFAULT_XY && y === DEFAULT_XY && z3 === DEFAULT_Z) {
+  const z4 = getVal2(value.z);
+  if (x === DEFAULT_XY && y === DEFAULT_XY && z4 === DEFAULT_Z) {
     return null;
   }
-  return `${x} ${y} ${z3}`;
+  return `${x} ${y} ${z4}`;
 });
 
 // src/transformers/styles/transform-rotate-transformer.ts
@@ -4185,6 +4185,11 @@ function initTabsModelExtensions() {
 // src/mcp/canvas-mcp.ts
 var import_editor_props8 = require("@elementor/editor-props");
 
+// src/mcp/icon-library-experiment.ts
+var import_editor_v1_adapters15 = require("@elementor/editor-v1-adapters");
+var ICON_LIBRARY_EXPERIMENT = "e_svg_library";
+var isIconLibraryActive = () => (0, import_editor_v1_adapters15.isExperimentActive)(ICON_LIBRARY_EXPERIMENT);
+
 // src/mcp/resources/available-widgets-resource.ts
 var import_http_client3 = require("@elementor/http-client");
 var MCP_PROXY_URL2 = "elementor/v1/mcp-proxy";
@@ -4261,7 +4266,7 @@ var initBestPracticesResource = (reg) => {
 
 // src/mcp/resources/document-structure-resource.ts
 var import_editor_elements9 = require("@elementor/editor-elements");
-var import_editor_v1_adapters15 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters16 = require("@elementor/editor-v1-adapters");
 var DOCUMENT_STRUCTURE_URI = "elementor://document/structure";
 var initDocumentStructureResource = (reg) => {
   const { resource, sendResourceUpdated } = reg;
@@ -4274,15 +4279,15 @@ var initDocumentStructureResource = (reg) => {
       sendResourceUpdated({ uri: DOCUMENT_STRUCTURE_URI });
     }
   };
-  (0, import_editor_v1_adapters15.__privateListenTo)(
+  (0, import_editor_v1_adapters16.__privateListenTo)(
     [
-      (0, import_editor_v1_adapters15.commandEndEvent)("document/elements/create"),
-      (0, import_editor_v1_adapters15.commandEndEvent)("document/elements/delete"),
-      (0, import_editor_v1_adapters15.commandEndEvent)("document/elements/move"),
-      (0, import_editor_v1_adapters15.commandEndEvent)("document/elements/copy"),
-      (0, import_editor_v1_adapters15.commandEndEvent)("document/elements/paste"),
-      (0, import_editor_v1_adapters15.commandEndEvent)("editor/documents/attach-preview"),
-      (0, import_editor_v1_adapters15.commandEndEvent)("editor/documents/switch")
+      (0, import_editor_v1_adapters16.commandEndEvent)("document/elements/create"),
+      (0, import_editor_v1_adapters16.commandEndEvent)("document/elements/delete"),
+      (0, import_editor_v1_adapters16.commandEndEvent)("document/elements/move"),
+      (0, import_editor_v1_adapters16.commandEndEvent)("document/elements/copy"),
+      (0, import_editor_v1_adapters16.commandEndEvent)("document/elements/paste"),
+      (0, import_editor_v1_adapters16.commandEndEvent)("editor/documents/attach-preview"),
+      (0, import_editor_v1_adapters16.commandEndEvent)("editor/documents/switch")
     ],
     updateDocumentStructure
   );
@@ -4385,7 +4390,7 @@ var initDynamicTagsResource = (reg) => {
 };
 
 // src/mcp/resources/editor-state-resource.ts
-var import_editor_v1_adapters16 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters17 = require("@elementor/editor-v1-adapters");
 var CURRENTLY_VIEWED_SCREEN = "The user is currently viewing the Elementor editor";
 var PAGE_CONTENT_CHARACTER_LIMIT = 500;
 var PREVIEW_TEXT_NODE_MIN_LENGTH = 2;
@@ -4406,8 +4411,8 @@ var initEditorStateResource = (reg) => {
     lastSerializedState = serialized;
     sendResourceUpdated({ uri: EDITOR_STATE_URI });
   };
-  (0, import_editor_v1_adapters16.__privateListenTo)(
-    [(0, import_editor_v1_adapters16.commandEndEvent)("editor/documents/switch"), (0, import_editor_v1_adapters16.commandEndEvent)("editor/documents/attach-preview")],
+  (0, import_editor_v1_adapters17.__privateListenTo)(
+    [(0, import_editor_v1_adapters17.commandEndEvent)("editor/documents/switch"), (0, import_editor_v1_adapters17.commandEndEvent)("editor/documents/attach-preview")],
     notifyIfChanged
   );
   lastSerializedState = JSON.stringify(buildState());
@@ -4481,7 +4486,7 @@ function getPageTitle() {
 }
 
 // src/mcp/resources/general-context-resource.ts
-var import_editor_v1_adapters17 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters18 = require("@elementor/editor-v1-adapters");
 var GENERAL_CONTEXT_URI = "elementor://context/general";
 var initGeneralContextResource = (reg) => {
   const { resource, sendResourceUpdated } = reg;
@@ -4542,11 +4547,11 @@ var initGeneralContextResource = (reg) => {
       };
     }
   );
-  (0, import_editor_v1_adapters17.__privateListenTo)(
+  (0, import_editor_v1_adapters18.__privateListenTo)(
     [
-      (0, import_editor_v1_adapters17.commandEndEvent)("editor/documents/switch"),
-      (0, import_editor_v1_adapters17.commandEndEvent)("editor/documents/attach-preview"),
-      (0, import_editor_v1_adapters17.commandEndEvent)("document/elements/settings")
+      (0, import_editor_v1_adapters18.commandEndEvent)("editor/documents/switch"),
+      (0, import_editor_v1_adapters18.commandEndEvent)("editor/documents/attach-preview"),
+      (0, import_editor_v1_adapters18.commandEndEvent)("document/elements/settings")
     ],
     pushUpdateIfChanged
   );
@@ -4555,7 +4560,7 @@ var initGeneralContextResource = (reg) => {
 
 // src/mcp/resources/selected-element-resource.ts
 var import_editor_elements10 = require("@elementor/editor-elements");
-var import_editor_v1_adapters18 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters19 = require("@elementor/editor-v1-adapters");
 var SELECTED_ELEMENT_URI = "elementor://context/selected-element";
 var initSelectedElementResource = (reg) => {
   const { resource, sendResourceUpdated } = reg;
@@ -4586,11 +4591,11 @@ var initSelectedElementResource = (reg) => {
     }
     publishIfChanged(readSelectionFromEditor());
   };
-  (0, import_editor_v1_adapters18.__privateListenTo)(
+  (0, import_editor_v1_adapters19.__privateListenTo)(
     [
-      (0, import_editor_v1_adapters18.commandEndEvent)("document/elements/select"),
-      (0, import_editor_v1_adapters18.commandEndEvent)("document/elements/deselect-all"),
-      (0, import_editor_v1_adapters18.commandEndEvent)("document/elements/settings")
+      (0, import_editor_v1_adapters19.commandEndEvent)("document/elements/select"),
+      (0, import_editor_v1_adapters19.commandEndEvent)("document/elements/deselect-all"),
+      (0, import_editor_v1_adapters19.commandEndEvent)("document/elements/settings")
     ],
     onCommand
   );
@@ -4708,7 +4713,7 @@ var import_editor_props7 = require("@elementor/editor-props");
 var import_editor_elements12 = require("@elementor/editor-elements");
 var import_editor_props6 = require("@elementor/editor-props");
 var import_editor_styles4 = require("@elementor/editor-styles");
-var import_editor_v1_adapters20 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters21 = require("@elementor/editor-v1-adapters");
 
 // src/mcp/utils/merge-custom-css.ts
 var CUSTOM_CSS_SEPARATOR = "\n";
@@ -4777,11 +4782,11 @@ function resolveCanonicalPropKeys(elementType, props) {
 }
 
 // src/mcp/utils/resolve-dynamic-tag.ts
-var import_editor_v1_adapters19 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters20 = require("@elementor/editor-v1-adapters");
 var DYNAMIC_PROP_TYPE_KEY = "dynamic";
 var OMITTED_DYNAMIC_SETTING_KEYS = ["fallback"];
 var getAtomicDynamicTags = () => {
-  const config = (0, import_editor_v1_adapters19.getElementorConfig)();
+  const config = (0, import_editor_v1_adapters20.getElementorConfig)();
   return config.atomicDynamicTags?.tags ?? {};
 };
 var getDynamicTagNamesByCategories = (categories) => {
@@ -4982,13 +4987,51 @@ Expected Schema: ${jsonSchema}`
     },
     withHistory: false
   });
-  (0, import_editor_v1_adapters20.__privateRunCommandSync)("document/save/set-is-modified", { status: true }, { internal: true });
+  (0, import_editor_v1_adapters21.__privateRunCommandSync)("document/save/set-is-modified", { status: true }, { internal: true });
 };
 
 // src/mcp/tools/configure-element/prompt.ts
 var import_editor_mcp2 = require("@elementor/editor-mcp");
+var ICONS_SECTION = `# Icons (the \`svg\` property on e-svg)
+The \`svg\` property accepts two variants. Prefer a library icon for iconography (carts, arrows, social marks, check marks) \u2014 it needs no upload and inherits \`color\` via \`currentColor\`. Use an uploaded file only for custom artwork such as a brand logo.
+
+Resolve the icon with the \`find-icons\` tool FIRST, then copy its \`value\` and \`library\` verbatim. Never assemble those strings yourself: Font Awesome renamed many icons between major versions (\`shopping-cart\` became \`cart-shopping\`), so a plausible guess renders nothing. \`find-icons\` matches on names, aliases, human search terms, and categories, so describe the intent \u2014 "add to cart" finds \`cart-shopping\`. It takes a batch of \`queries\`, so resolve every icon you need in one call.
+
+Library icon (note the nested PropValues \u2014 \`value\` and \`library\` are each a \`string\` PropValue):
+{ "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, "library": { "$$type": "string", "value": "fa-solid" } } }
+
+Uploaded SVG file:
+{ "$$type": "svg-src", "value": { "id": { "$$type": "image-attachment-id", "value": 123 } } }
+
+Size and colour an e-svg through \`style\` (\`width\`, \`height\`, \`color\`), never through \`propertiesToChange\`.
+`;
+var ICON_EXAMPLE = `
+Setting a Font Awesome icon on an e-svg, after resolving it with \`find-icons\`:
+
+\`\`\`json
+{
+  propertiesToChange: {
+    svg: {
+      $$type: 'icon',
+      value: {
+        value: { $$type: 'string', value: 'fa-solid fa-cart-shopping' },
+        library: { $$type: 'string', value: 'fa-solid' }
+      }
+    }
+  },
+  style: {
+    'width': '1.25rem',
+    'height': '1.25rem',
+    'color': '#1a1a1a'
+  },
+  elementId: 'element-id',
+  elementType: 'e-svg'
+};
+\`\`\`
+`;
 var CONFIGURE_ELEMENT_GUIDE_URI = "elementor://canvas/tools/configure-element-guide";
 var generatePrompt = () => {
+  const iconLibraryActive = isIconLibraryActive();
   const configureElementToolPrompt = (0, import_editor_mcp2.toolPrompts)("configure-element");
   configureElementToolPrompt.description(`
 Configure an existing element on the page.
@@ -5046,7 +5089,8 @@ Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" var
 }
 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.
-`);
+
+${iconLibraryActive ? ICONS_SECTION : ""}`);
   configureElementToolPrompt.parameter("elementId", "The ID of the element to configure. MANDATORY.");
   configureElementToolPrompt.parameter(
     "elementType",
@@ -5083,6 +5127,9 @@ Do NOT send "group" (it is resolved automatically). Use { "settings": {} } only
 };
 \`\`\`
 `);
+  if (iconLibraryActive) {
+    configureElementToolPrompt.example(ICON_EXAMPLE);
+  }
   configureElementToolPrompt.instruction(
     "The $$type property is MANDATORY for every value in propertiesToChange; it is not used in the style parameter (raw CSS only)."
   );
@@ -5256,8 +5303,7 @@ Provide styling as raw CSS via the "style" parameter (a flat map of CSS property
 }`;
 }
 
-// src/mcp/tools/get-page-structure/tool.ts
-var import_editor_documents2 = require("@elementor/editor-documents");
+// src/mcp/tools/find-icons/tool.ts
 var import_http_client7 = require("@elementor/http-client");
 var import_schema3 = require("@elementor/schema");
 
@@ -5276,24 +5322,137 @@ function getMcpErrorMessage(error, toolName) {
   return `${toolName} failed with an unknown error.`;
 }
 
-// src/mcp/tools/get-page-structure/tool.ts
+// src/mcp/tools/find-icons/prompt.ts
+var import_editor_mcp4 = require("@elementor/editor-mcp");
+var findIconsToolPrompt = (0, import_editor_mcp4.toolPrompts)("find-icons");
+findIconsToolPrompt.description(
+  "Finds icons for the `svg` property of an `e-svg` element, across Font Awesome and any icon packs uploaded to this site. Returns the exact `value` and `library` pair to write - never assemble those strings yourself, and never guess an icon name. Call this before placing or configuring an `e-svg`. Nothing has to be uploaded to the Media Library for an icon to work."
+);
+findIconsToolPrompt.instruction(
+  'Call it when the user names an icon ("use the cart-shopping icon") and take the first exact `name` match, and also when the user describes a page and you decide icons belong in it ("create a product page") - in that case pass one query per icon you intend to place, in a single call.'
+);
+findIconsToolPrompt.instruction(
+  'Write queries the way a person would describe the icon ("shopping cart", "credit card", "phone"). Icons are matched on their name, aliases, Font Awesome search terms and category, so plain language works better than guessed icon names.'
+);
+findIconsToolPrompt.instruction(
+  'Results are ordered best first; `matched_on: "name"` is a stronger signal than `matched_on: "term"`. Check each result\'s `license` and only use `free` icons; skip any `pro` entry. Prefer `fa-solid` for UI iconography and keep one style across a page; brand marks only exist in `fa-brands`. An empty `matches` array means no match was found: broaden the phrase instead of inventing a value.'
+);
+findIconsToolPrompt.instruction(
+  'Pass the chosen pair to `configure-element` as the `svg` property: { "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, "library": { "$$type": "string", "value": "fa-solid" } } }. An `e-svg` has no colour or size of its own, so set `width`, `height` and `color` in the same `configure-element` call.'
+);
+findIconsToolPrompt.example(`Icon named by the user:
+{ "queries": ["cart-shopping"] }`);
+findIconsToolPrompt.example(`Every icon a product page needs, in one call:
+{ "queries": ["add to cart", "free shipping", "secure payment", "instagram"] }`);
+findIconsToolPrompt.example(`Browse a category, one style only:
+{ "category": "shopping", "library": "fa-solid", "perPage": 25 }`);
+
+// src/mcp/tools/find-icons/tool.ts
 var MCP_PROXY_URL5 = "elementor/v1/mcp-proxy";
+var MAX_QUERIES = 10;
+var MAX_PER_PAGE = 25;
+var initFindIconsTool = (reg) => {
+  const { addTool } = reg;
+  addTool({
+    name: "find-icons",
+    description: findIconsToolPrompt.prompt(),
+    schema: {
+      queries: import_schema3.z.array(import_schema3.z.string()).max(MAX_QUERIES).optional().describe(
+        'One plain-language phrase per icon you need, for example ["add to cart", "free shipping"]. Batch every icon a page needs into a single call.'
+      ),
+      library: import_schema3.z.string().optional().describe(
+        'Restrict results to one library key reported in "libraries", for example "fa-solid". Omit to search every library installed on the site.'
+      ),
+      category: import_schema3.z.string().optional().describe(
+        'Restrict results to one Font Awesome category reported in "categories", for example "shopping". May be used without a query to browse that category.'
+      ),
+      page: import_schema3.z.number().int().min(1).optional(),
+      perPage: import_schema3.z.number().int().min(1).max(MAX_PER_PAGE).optional()
+    },
+    outputSchema: {
+      results: import_schema3.z.array(
+        import_schema3.z.object({
+          query: import_schema3.z.string(),
+          matches: import_schema3.z.array(
+            import_schema3.z.object({
+              value: import_schema3.z.string(),
+              library: import_schema3.z.string(),
+              name: import_schema3.z.string(),
+              label: import_schema3.z.string(),
+              matched_on: import_schema3.z.enum(["name", "alias", "term", "category", "library"]),
+              license: import_schema3.z.enum(["free", "pro"])
+            })
+          ),
+          total: import_schema3.z.number(),
+          page: import_schema3.z.number(),
+          per_page: import_schema3.z.number(),
+          truncated: import_schema3.z.boolean()
+        })
+      ).describe(
+        'One entry per query, each with ranked "matches". Every match carries the "value" and "library" pair to write on the e-svg icon prop, plus "matched_on" and "license".'
+      ),
+      libraries: import_schema3.z.array(import_schema3.z.string()).optional().describe(
+        "Icon library keys installed on this site. Only sent when nothing matched or when browsing."
+      ),
+      customLibraries: import_schema3.z.record(import_schema3.z.string(), import_schema3.z.string()).optional().describe(
+        "Custom (uploaded) icon libraries keyed by library. Only sent when nothing matched or when browsing."
+      ),
+      categories: import_schema3.z.array(import_schema3.z.string()).optional().describe(
+        'Icon categories for the "category" filter. Only sent when nothing matched or when browsing.'
+      ),
+      truncatedCustomLibraries: import_schema3.z.array(import_schema3.z.string()).optional().describe("Custom libraries with more than 250 icons; only their first 250 icons are searchable."),
+      fontAwesomeVersion: import_schema3.z.string().nullable().describe("Font Awesome version the site renders icons from."),
+      llmInstructions: import_schema3.z.string().optional().describe("Present only when nothing matched, explaining what to do next.")
+    },
+    handler: async ({ queries, library, category, page, perPage }) => {
+      try {
+        const { data } = await (0, import_http_client7.httpService)().post(MCP_PROXY_URL5, {
+          tool: "find-icons",
+          input: {
+            ...queries ? { queries } : {},
+            ...library ? { library } : {},
+            ...category ? { category } : {},
+            ...page ? { page } : {},
+            ...perPage ? { per_page: perPage } : {}
+          }
+        });
+        return {
+          results: data.data.results,
+          ...data.data.libraries ? { libraries: data.data.libraries } : {},
+          ...data.data.custom_libraries ? { customLibraries: data.data.custom_libraries } : {},
+          ...data.data.categories ? { categories: data.data.categories } : {},
+          ...data.data.truncated_custom_libraries ? { truncatedCustomLibraries: data.data.truncated_custom_libraries } : {},
+          fontAwesomeVersion: data.data.font_awesome_version,
+          ...data.data.llm_instructions ? { llmInstructions: data.data.llm_instructions } : {}
+        };
+      } catch (error) {
+        throw new Error(getMcpErrorMessage(error, "find-icons"));
+      }
+    }
+  });
+};
+
+// src/mcp/tools/get-page-structure/tool.ts
+var import_editor_documents2 = require("@elementor/editor-documents");
+var import_http_client8 = require("@elementor/http-client");
+var import_schema4 = require("@elementor/schema");
+var MCP_PROXY_URL6 = "elementor/v1/mcp-proxy";
 var initGetPageStructureTool = (reg) => {
   const { addTool } = reg;
   addTool({
     name: "get-page-structure",
     description: "Returns a lean Elementor element tree skeleton (id, elType, widgetType, title, nested elements) for a post or page. If no postId is provided, uses the currently open document. Optionally scope to a subtree with elementId. Set includeContent=true (requires elementId) to also return each node's settings and styles.",
     schema: {
-      postId: import_schema3.z.number().optional().describe(
+      postId: import_schema4.z.number().optional().describe(
         "WordPress post ID of the Elementor document. If omitted, uses the currently open document."
       ),
-      elementId: import_schema3.z.string().optional().describe("If provided, returns only the subtree rooted at that element id."),
-      includeContent: import_schema3.z.boolean().optional().describe(
+      elementId: import_schema4.z.string().optional().describe("If provided, returns only the subtree rooted at that element id."),
+      includeContent: import_schema4.z.boolean().optional().describe(
         "If true, includes each node's settings and styles (same shape build-composition accepts as input). Requires elementId."
       )
     },
     outputSchema: {
-      elements: import_schema3.z.array(import_schema3.z.any()).describe(
+      elements: import_schema4.z.array(import_schema4.z.any()).describe(
         "Skeleton of Elementor elements (id, elType, widgetType, title, nested elements). When includeContent is true, each node also includes settings and styles."
       )
     },
@@ -5303,7 +5462,7 @@ var initGetPageStructureTool = (reg) => {
         throw new Error("No post ID provided and no active document found.");
       }
       try {
-        const { data } = await (0, import_http_client7.httpService)().post(MCP_PROXY_URL5, {
+        const { data } = await (0, import_http_client8.httpService)().post(MCP_PROXY_URL6, {
           tool: "get-page-structure",
           input: {
             post_id: resolvedPostId,
@@ -5333,6 +5492,9 @@ var initCanvasMcp = (reg) => {
   initGeneralContextResource(reg);
   initBestPracticesResource(reg);
   initConfigureElementTool(reg);
+  if (isIconLibraryActive()) {
+    initFindIconsTool(reg);
+  }
   initGetPageStructureTool(reg);
   initBreakpointsResource(reg);
 };
@@ -5436,14 +5598,14 @@ Note: The "size" property controls image resolution/loading, not visual size. Se
 // src/prevent-link-in-link-commands.ts
 var import_editor_elements14 = require("@elementor/editor-elements");
 var import_editor_notifications3 = require("@elementor/editor-notifications");
-var import_editor_v1_adapters21 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters22 = require("@elementor/editor-v1-adapters");
 var import_i18n4 = require("@wordpress/i18n");
 function initLinkInLinkPrevention() {
-  (0, import_editor_v1_adapters21.blockCommand)({
+  (0, import_editor_v1_adapters22.blockCommand)({
     command: "document/elements/paste",
     condition: blockLinkInLinkPaste
   });
-  (0, import_editor_v1_adapters21.blockCommand)({
+  (0, import_editor_v1_adapters22.blockCommand)({
     command: "document/elements/move",
     condition: blockLinkInLinkMove
   });
@@ -5519,7 +5681,7 @@ function shouldBlock(sourceElements, targetElements) {
 // src/style-commands/paste-style.ts
 var import_editor_elements17 = require("@elementor/editor-elements");
 var import_editor_props10 = require("@elementor/editor-props");
-var import_editor_v1_adapters23 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters24 = require("@elementor/editor-v1-adapters");
 
 // src/utils/command-utils.ts
 var import_editor_elements15 = require("@elementor/editor-elements");
@@ -5566,9 +5728,9 @@ function getTitleForContainers(containers) {
 // src/style-commands/undoable-actions/paste-element-style.ts
 var import_editor_elements16 = require("@elementor/editor-elements");
 var import_editor_styles_repository4 = require("@elementor/editor-styles-repository");
-var import_editor_v1_adapters22 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters23 = require("@elementor/editor-v1-adapters");
 var import_i18n6 = require("@wordpress/i18n");
-var undoablePasteElementStyle = () => (0, import_editor_v1_adapters22.undoable)(
+var undoablePasteElementStyle = () => (0, import_editor_v1_adapters23.undoable)(
   {
     do: ({ containers, newStyle }) => {
       return containers.map((container) => {
@@ -5644,12 +5806,12 @@ var undoablePasteElementStyle = () => (0, import_editor_v1_adapters22.undoable)(
 // src/style-commands/paste-style.ts
 function initPasteStyleCommand() {
   const pasteElementStyleCommand = undoablePasteElementStyle();
-  (0, import_editor_v1_adapters23.blockCommand)({
+  (0, import_editor_v1_adapters24.blockCommand)({
     command: "document/elements/paste-style",
     condition: hasAtomicWidgets
   });
-  (0, import_editor_v1_adapters23.__privateListenTo)(
-    (0, import_editor_v1_adapters23.commandStartEvent)("document/elements/paste-style"),
+  (0, import_editor_v1_adapters24.__privateListenTo)(
+    (0, import_editor_v1_adapters24.commandStartEvent)("document/elements/paste-style"),
     (e) => pasteStyles(e.args, pasteElementStyleCommand)
   );
 }
@@ -5700,14 +5862,14 @@ function pasteClasses(containers, classes) {
 }
 
 // src/style-commands/reset-style.ts
-var import_editor_v1_adapters25 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters26 = require("@elementor/editor-v1-adapters");
 
 // src/style-commands/undoable-actions/reset-element-style.ts
 var import_editor_elements18 = require("@elementor/editor-elements");
 var import_editor_styles_repository5 = require("@elementor/editor-styles-repository");
-var import_editor_v1_adapters24 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters25 = require("@elementor/editor-v1-adapters");
 var import_i18n7 = require("@wordpress/i18n");
-var undoableResetElementStyle = () => (0, import_editor_v1_adapters24.undoable)(
+var undoableResetElementStyle = () => (0, import_editor_v1_adapters25.undoable)(
   {
     do: ({ containers }) => {
       return containers.map((container) => {
@@ -5751,12 +5913,12 @@ var undoableResetElementStyle = () => (0, import_editor_v1_adapters24.undoable)(
 // src/style-commands/reset-style.ts
 function initResetStyleCommand() {
   const resetElementStyles = undoableResetElementStyle();
-  (0, import_editor_v1_adapters25.blockCommand)({
+  (0, import_editor_v1_adapters26.blockCommand)({
     command: "document/elements/reset-style",
     condition: hasAtomicWidgets
   });
-  (0, import_editor_v1_adapters25.__privateListenTo)(
-    (0, import_editor_v1_adapters25.commandStartEvent)("document/elements/reset-style"),
+  (0, import_editor_v1_adapters26.__privateListenTo)(
+    (0, import_editor_v1_adapters26.commandStartEvent)("document/elements/reset-style"),
     (e) => resetStyles(e.args, resetElementStyles)
   );
 }
@@ -5802,7 +5964,7 @@ function init() {
     component: ClassesRename
   });
   initCanvasMcp(
-    (0, import_editor_mcp4.getMCPByDomain)("canvas", {
+    (0, import_editor_mcp5.getMCPByDomain)("canvas", {
       instructions: `Everything related to V4 ( Atomic ) canvas.
 # Canvas workflow
 - Configure element settings and styles with configure-element
@@ -5905,9 +6067,9 @@ function getRectClipPath(rect, viewport) {
 }
 
 // src/hooks/use-canvas-document.ts
-var import_editor_v1_adapters26 = require("@elementor/editor-v1-adapters");
+var import_editor_v1_adapters27 = require("@elementor/editor-v1-adapters");
 function useCanvasDocument() {
-  return (0, import_editor_v1_adapters26.__privateUseListenTo)((0, import_editor_v1_adapters26.commandEndEvent)("editor/documents/attach-preview"), () => (0, import_editor_v1_adapters26.getCanvasIframeDocument)());
+  return (0, import_editor_v1_adapters27.__privateUseListenTo)((0, import_editor_v1_adapters27.commandEndEvent)("editor/documents/attach-preview"), () => (0, import_editor_v1_adapters27.getCanvasIframeDocument)());
 }
 
 // src/hooks/use-escape-on-canvas.ts

package/dist/index.mjs

@@ -2529,11 +2529,11 @@ function getVal2(val) {
 var transformOriginTransformer = createTransformer((value) => {
   const x = getVal2(value.x);
   const y = getVal2(value.y);
-  const z3 = getVal2(value.z);
-  if (x === DEFAULT_XY && y === DEFAULT_XY && z3 === DEFAULT_Z) {
+  const z4 = getVal2(value.z);
+  if (x === DEFAULT_XY && y === DEFAULT_XY && z4 === DEFAULT_Z) {
     return null;
   }
-  return `${x} ${y} ${z3}`;
+  return `${x} ${y} ${z4}`;
 });
 
 // src/transformers/styles/transform-rotate-transformer.ts
@@ -4156,6 +4156,11 @@ function initTabsModelExtensions() {
 // src/mcp/canvas-mcp.ts
 import { Schema as Schema3 } from "@elementor/editor-props";
 
+// src/mcp/icon-library-experiment.ts
+import { isExperimentActive } from "@elementor/editor-v1-adapters";
+var ICON_LIBRARY_EXPERIMENT = "e_svg_library";
+var isIconLibraryActive = () => isExperimentActive(ICON_LIBRARY_EXPERIMENT);
+
 // src/mcp/resources/available-widgets-resource.ts
 import { httpService as httpService3 } from "@elementor/http-client";
 var MCP_PROXY_URL2 = "elementor/v1/mcp-proxy";
@@ -4969,8 +4974,46 @@ Expected Schema: ${jsonSchema}`
 
 // src/mcp/tools/configure-element/prompt.ts
 import { toolPrompts } from "@elementor/editor-mcp";
+var ICONS_SECTION = `# Icons (the \`svg\` property on e-svg)
+The \`svg\` property accepts two variants. Prefer a library icon for iconography (carts, arrows, social marks, check marks) \u2014 it needs no upload and inherits \`color\` via \`currentColor\`. Use an uploaded file only for custom artwork such as a brand logo.
+
+Resolve the icon with the \`find-icons\` tool FIRST, then copy its \`value\` and \`library\` verbatim. Never assemble those strings yourself: Font Awesome renamed many icons between major versions (\`shopping-cart\` became \`cart-shopping\`), so a plausible guess renders nothing. \`find-icons\` matches on names, aliases, human search terms, and categories, so describe the intent \u2014 "add to cart" finds \`cart-shopping\`. It takes a batch of \`queries\`, so resolve every icon you need in one call.
+
+Library icon (note the nested PropValues \u2014 \`value\` and \`library\` are each a \`string\` PropValue):
+{ "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, "library": { "$$type": "string", "value": "fa-solid" } } }
+
+Uploaded SVG file:
+{ "$$type": "svg-src", "value": { "id": { "$$type": "image-attachment-id", "value": 123 } } }
+
+Size and colour an e-svg through \`style\` (\`width\`, \`height\`, \`color\`), never through \`propertiesToChange\`.
+`;
+var ICON_EXAMPLE = `
+Setting a Font Awesome icon on an e-svg, after resolving it with \`find-icons\`:
+
+\`\`\`json
+{
+  propertiesToChange: {
+    svg: {
+      $$type: 'icon',
+      value: {
+        value: { $$type: 'string', value: 'fa-solid fa-cart-shopping' },
+        library: { $$type: 'string', value: 'fa-solid' }
+      }
+    }
+  },
+  style: {
+    'width': '1.25rem',
+    'height': '1.25rem',
+    'color': '#1a1a1a'
+  },
+  elementId: 'element-id',
+  elementType: 'e-svg'
+};
+\`\`\`
+`;
 var CONFIGURE_ELEMENT_GUIDE_URI = "elementor://canvas/tools/configure-element-guide";
 var generatePrompt = () => {
+  const iconLibraryActive = isIconLibraryActive();
   const configureElementToolPrompt = toolPrompts("configure-element");
   configureElementToolPrompt.description(`
 Configure an existing element on the page.
@@ -5028,7 +5071,8 @@ Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" var
 }
 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.
-`);
+
+${iconLibraryActive ? ICONS_SECTION : ""}`);
   configureElementToolPrompt.parameter("elementId", "The ID of the element to configure. MANDATORY.");
   configureElementToolPrompt.parameter(
     "elementType",
@@ -5065,6 +5109,9 @@ Do NOT send "group" (it is resolved automatically). Use { "settings": {} } only
 };
 \`\`\`
 `);
+  if (iconLibraryActive) {
+    configureElementToolPrompt.example(ICON_EXAMPLE);
+  }
   configureElementToolPrompt.instruction(
     "The $$type property is MANDATORY for every value in propertiesToChange; it is not used in the style parameter (raw CSS only)."
   );
@@ -5238,8 +5285,7 @@ Provide styling as raw CSS via the "style" parameter (a flat map of CSS property
 }`;
 }
 
-// src/mcp/tools/get-page-structure/tool.ts
-import { getCurrentDocument } from "@elementor/editor-documents";
+// src/mcp/tools/find-icons/tool.ts
 import { httpService as httpService6 } from "@elementor/http-client";
 import { z as z2 } from "@elementor/schema";
 
@@ -5258,24 +5304,137 @@ function getMcpErrorMessage(error, toolName) {
   return `${toolName} failed with an unknown error.`;
 }
 
-// src/mcp/tools/get-page-structure/tool.ts
+// src/mcp/tools/find-icons/prompt.ts
+import { toolPrompts as toolPrompts2 } from "@elementor/editor-mcp";
+var findIconsToolPrompt = toolPrompts2("find-icons");
+findIconsToolPrompt.description(
+  "Finds icons for the `svg` property of an `e-svg` element, across Font Awesome and any icon packs uploaded to this site. Returns the exact `value` and `library` pair to write - never assemble those strings yourself, and never guess an icon name. Call this before placing or configuring an `e-svg`. Nothing has to be uploaded to the Media Library for an icon to work."
+);
+findIconsToolPrompt.instruction(
+  'Call it when the user names an icon ("use the cart-shopping icon") and take the first exact `name` match, and also when the user describes a page and you decide icons belong in it ("create a product page") - in that case pass one query per icon you intend to place, in a single call.'
+);
+findIconsToolPrompt.instruction(
+  'Write queries the way a person would describe the icon ("shopping cart", "credit card", "phone"). Icons are matched on their name, aliases, Font Awesome search terms and category, so plain language works better than guessed icon names.'
+);
+findIconsToolPrompt.instruction(
+  'Results are ordered best first; `matched_on: "name"` is a stronger signal than `matched_on: "term"`. Check each result\'s `license` and only use `free` icons; skip any `pro` entry. Prefer `fa-solid` for UI iconography and keep one style across a page; brand marks only exist in `fa-brands`. An empty `matches` array means no match was found: broaden the phrase instead of inventing a value.'
+);
+findIconsToolPrompt.instruction(
+  'Pass the chosen pair to `configure-element` as the `svg` property: { "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, "library": { "$$type": "string", "value": "fa-solid" } } }. An `e-svg` has no colour or size of its own, so set `width`, `height` and `color` in the same `configure-element` call.'
+);
+findIconsToolPrompt.example(`Icon named by the user:
+{ "queries": ["cart-shopping"] }`);
+findIconsToolPrompt.example(`Every icon a product page needs, in one call:
+{ "queries": ["add to cart", "free shipping", "secure payment", "instagram"] }`);
+findIconsToolPrompt.example(`Browse a category, one style only:
+{ "category": "shopping", "library": "fa-solid", "perPage": 25 }`);
+
+// src/mcp/tools/find-icons/tool.ts
 var MCP_PROXY_URL5 = "elementor/v1/mcp-proxy";
+var MAX_QUERIES = 10;
+var MAX_PER_PAGE = 25;
+var initFindIconsTool = (reg) => {
+  const { addTool } = reg;
+  addTool({
+    name: "find-icons",
+    description: findIconsToolPrompt.prompt(),
+    schema: {
+      queries: z2.array(z2.string()).max(MAX_QUERIES).optional().describe(
+        'One plain-language phrase per icon you need, for example ["add to cart", "free shipping"]. Batch every icon a page needs into a single call.'
+      ),
+      library: z2.string().optional().describe(
+        'Restrict results to one library key reported in "libraries", for example "fa-solid". Omit to search every library installed on the site.'
+      ),
+      category: z2.string().optional().describe(
+        'Restrict results to one Font Awesome category reported in "categories", for example "shopping". May be used without a query to browse that category.'
+      ),
+      page: z2.number().int().min(1).optional(),
+      perPage: z2.number().int().min(1).max(MAX_PER_PAGE).optional()
+    },
+    outputSchema: {
+      results: z2.array(
+        z2.object({
+          query: z2.string(),
+          matches: z2.array(
+            z2.object({
+              value: z2.string(),
+              library: z2.string(),
+              name: z2.string(),
+              label: z2.string(),
+              matched_on: z2.enum(["name", "alias", "term", "category", "library"]),
+              license: z2.enum(["free", "pro"])
+            })
+          ),
+          total: z2.number(),
+          page: z2.number(),
+          per_page: z2.number(),
+          truncated: z2.boolean()
+        })
+      ).describe(
+        'One entry per query, each with ranked "matches". Every match carries the "value" and "library" pair to write on the e-svg icon prop, plus "matched_on" and "license".'
+      ),
+      libraries: z2.array(z2.string()).optional().describe(
+        "Icon library keys installed on this site. Only sent when nothing matched or when browsing."
+      ),
+      customLibraries: z2.record(z2.string(), z2.string()).optional().describe(
+        "Custom (uploaded) icon libraries keyed by library. Only sent when nothing matched or when browsing."
+      ),
+      categories: z2.array(z2.string()).optional().describe(
+        'Icon categories for the "category" filter. Only sent when nothing matched or when browsing.'
+      ),
+      truncatedCustomLibraries: z2.array(z2.string()).optional().describe("Custom libraries with more than 250 icons; only their first 250 icons are searchable."),
+      fontAwesomeVersion: z2.string().nullable().describe("Font Awesome version the site renders icons from."),
+      llmInstructions: z2.string().optional().describe("Present only when nothing matched, explaining what to do next.")
+    },
+    handler: async ({ queries, library, category, page, perPage }) => {
+      try {
+        const { data } = await httpService6().post(MCP_PROXY_URL5, {
+          tool: "find-icons",
+          input: {
+            ...queries ? { queries } : {},
+            ...library ? { library } : {},
+            ...category ? { category } : {},
+            ...page ? { page } : {},
+            ...perPage ? { per_page: perPage } : {}
+          }
+        });
+        return {
+          results: data.data.results,
+          ...data.data.libraries ? { libraries: data.data.libraries } : {},
+          ...data.data.custom_libraries ? { customLibraries: data.data.custom_libraries } : {},
+          ...data.data.categories ? { categories: data.data.categories } : {},
+          ...data.data.truncated_custom_libraries ? { truncatedCustomLibraries: data.data.truncated_custom_libraries } : {},
+          fontAwesomeVersion: data.data.font_awesome_version,
+          ...data.data.llm_instructions ? { llmInstructions: data.data.llm_instructions } : {}
+        };
+      } catch (error) {
+        throw new Error(getMcpErrorMessage(error, "find-icons"));
+      }
+    }
+  });
+};
+
+// src/mcp/tools/get-page-structure/tool.ts
+import { getCurrentDocument } from "@elementor/editor-documents";
+import { httpService as httpService7 } from "@elementor/http-client";
+import { z as z3 } from "@elementor/schema";
+var MCP_PROXY_URL6 = "elementor/v1/mcp-proxy";
 var initGetPageStructureTool = (reg) => {
   const { addTool } = reg;
   addTool({
     name: "get-page-structure",
     description: "Returns a lean Elementor element tree skeleton (id, elType, widgetType, title, nested elements) for a post or page. If no postId is provided, uses the currently open document. Optionally scope to a subtree with elementId. Set includeContent=true (requires elementId) to also return each node's settings and styles.",
     schema: {
-      postId: z2.number().optional().describe(
+      postId: z3.number().optional().describe(
         "WordPress post ID of the Elementor document. If omitted, uses the currently open document."
       ),
-      elementId: z2.string().optional().describe("If provided, returns only the subtree rooted at that element id."),
-      includeContent: z2.boolean().optional().describe(
+      elementId: z3.string().optional().describe("If provided, returns only the subtree rooted at that element id."),
+      includeContent: z3.boolean().optional().describe(
         "If true, includes each node's settings and styles (same shape build-composition accepts as input). Requires elementId."
       )
     },
     outputSchema: {
-      elements: z2.array(z2.any()).describe(
+      elements: z3.array(z3.any()).describe(
         "Skeleton of Elementor elements (id, elType, widgetType, title, nested elements). When includeContent is true, each node also includes settings and styles."
       )
     },
@@ -5285,7 +5444,7 @@ var initGetPageStructureTool = (reg) => {
         throw new Error("No post ID provided and no active document found.");
       }
       try {
-        const { data } = await httpService6().post(MCP_PROXY_URL5, {
+        const { data } = await httpService7().post(MCP_PROXY_URL6, {
           tool: "get-page-structure",
           input: {
             post_id: resolvedPostId,
@@ -5315,6 +5474,9 @@ var initCanvasMcp = (reg) => {
   initGeneralContextResource(reg);
   initBestPracticesResource(reg);
   initConfigureElementTool(reg);
+  if (isIconLibraryActive()) {
+    initFindIconsTool(reg);
+  }
   initGetPageStructureTool(reg);
   initBreakpointsResource(reg);
 };

package/package.json

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

package/src/mcp/canvas-mcp.ts

@@ -1,6 +1,7 @@
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { Schema } from '@elementor/editor-props';
 
+import { isIconLibraryActive } from './icon-library-experiment';
 import { initAvailableWidgetsResource } from './resources/available-widgets-resource';
 import { initBestPracticesResource } from './resources/best-practices-resource';
 import { initBreakpointsResource } from './resources/breakpoints-resource';
@@ -11,6 +12,7 @@ import { initGeneralContextResource } from './resources/general-context-resource
 import { initSelectedElementResource } from './resources/selected-element-resource';
 import { initWidgetsSchemaResource } from './resources/widgets-schema-resource';
 import { initConfigureElementTool } from './tools/configure-element/tool';
+import { initFindIconsTool } from './tools/find-icons/tool';
 import { initGetPageStructureTool } from './tools/get-page-structure/tool';
 import { getDynamicTagNamesByCategories } from './utils/resolve-dynamic-tag';
 
@@ -28,6 +30,9 @@ export const initCanvasMcp = ( reg: MCPRegistryEntry ) => {
 	initGeneralContextResource( reg );
 	initBestPracticesResource( reg );
 	initConfigureElementTool( reg );
+	if ( isIconLibraryActive() ) {
+		initFindIconsTool( reg );
+	}
 	initGetPageStructureTool( reg );
 	initBreakpointsResource( reg );
 };

package/src/mcp/icon-library-experiment.ts

@@ -0,0 +1,5 @@
+import { isExperimentActive } from '@elementor/editor-v1-adapters';
+
+const ICON_LIBRARY_EXPERIMENT = 'e_svg_library';
+
+export const isIconLibraryActive = () => isExperimentActive( ICON_LIBRARY_EXPERIMENT );

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

@@ -1,11 +1,52 @@
 import { toolPrompts } from '@elementor/editor-mcp';
 
+import { isIconLibraryActive } from '../../icon-library-experiment';
 import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
 import { WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 
+const ICONS_SECTION = `# Icons (the \`svg\` property on e-svg)
+The \`svg\` property accepts two variants. Prefer a library icon for iconography (carts, arrows, social marks, check marks) — it needs no upload and inherits \`color\` via \`currentColor\`. Use an uploaded file only for custom artwork such as a brand logo.
+
+Resolve the icon with the \`find-icons\` tool FIRST, then copy its \`value\` and \`library\` verbatim. Never assemble those strings yourself: Font Awesome renamed many icons between major versions (\`shopping-cart\` became \`cart-shopping\`), so a plausible guess renders nothing. \`find-icons\` matches on names, aliases, human search terms, and categories, so describe the intent — "add to cart" finds \`cart-shopping\`. It takes a batch of \`queries\`, so resolve every icon you need in one call.
+
+Library icon (note the nested PropValues — \`value\` and \`library\` are each a \`string\` PropValue):
+{ "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, "library": { "$$type": "string", "value": "fa-solid" } } }
+
+Uploaded SVG file:
+{ "$$type": "svg-src", "value": { "id": { "$$type": "image-attachment-id", "value": 123 } } }
+
+Size and colour an e-svg through \`style\` (\`width\`, \`height\`, \`color\`), never through \`propertiesToChange\`.
+`;
+
+const ICON_EXAMPLE = `
+Setting a Font Awesome icon on an e-svg, after resolving it with \`find-icons\`:
+
+\`\`\`json
+{
+  propertiesToChange: {
+    svg: {
+      $$type: 'icon',
+      value: {
+        value: { $$type: 'string', value: 'fa-solid fa-cart-shopping' },
+        library: { $$type: 'string', value: 'fa-solid' }
+      }
+    }
+  },
+  style: {
+    'width': '1.25rem',
+    'height': '1.25rem',
+    'color': '#1a1a1a'
+  },
+  elementId: 'element-id',
+  elementType: 'e-svg'
+};
+\`\`\`
+`;
+
 export const CONFIGURE_ELEMENT_GUIDE_URI = 'elementor://canvas/tools/configure-element-guide';
 
 export const generatePrompt = () => {
+	const iconLibraryActive = isIconLibraryActive();
 	const configureElementToolPrompt = toolPrompts( 'configure-element' );
 
 	configureElementToolPrompt.description( `
@@ -64,7 +105,8 @@ Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" var
 }
 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.
-` );
+
+${ iconLibraryActive ? ICONS_SECTION : '' }` );
 
 	configureElementToolPrompt.parameter( 'elementId', 'The ID of the element to configure. MANDATORY.' );
 
@@ -107,6 +149,10 @@ Do NOT send "group" (it is resolved automatically). Use { "settings": {} } only
 \`\`\`
 ` );
 
+	if ( iconLibraryActive ) {
+		configureElementToolPrompt.example( ICON_EXAMPLE );
+	}
+
 	configureElementToolPrompt.instruction(
 		'The $$type property is MANDATORY for every value in propertiesToChange; it is not used in the style parameter (raw CSS only).'
 	);

package/src/mcp/tools/find-icons/__tests__/tool.test.ts

@@ -0,0 +1,143 @@
+import { httpService } from '@elementor/http-client';
+
+import { initFindIconsTool } from '../tool';
+
+jest.mock( '@elementor/http-client', () => ( {
+	httpService: jest.fn(),
+	AxiosError: class AxiosError extends Error {},
+} ) );
+
+const mockedHttpService = httpService as jest.MockedFunction< typeof httpService >;
+
+type ToolConfig = {
+	name: string;
+	description: string;
+	schema: Record< string, unknown >;
+	handler: ( input: Record< string, unknown > ) => Promise< Record< string, unknown > >;
+};
+
+const captureTool = (): ToolConfig => {
+	const addTool = jest.fn();
+	initFindIconsTool( { addTool } as never );
+	return addTool.mock.calls[ 0 ][ 0 ] as ToolConfig;
+};
+
+const serverResponse = {
+	results: [
+		{
+			query: 'add to cart',
+			matches: [
+				{
+					value: 'fa-solid fa-cart-plus',
+					library: 'fa-solid',
+					name: 'cart-plus',
+					label: 'Cart Plus',
+					matched_on: 'term',
+					license: 'free',
+				},
+			],
+			total: 1,
+			page: 1,
+			per_page: 10,
+			truncated: false,
+		},
+	],
+	libraries: [ 'fa-brands', 'fa-regular', 'fa-solid' ],
+	categories: [ 'shopping' ],
+	font_awesome_version: '7.3.1',
+};
+
+const givenServerResponse = ( data: Record< string, unknown > ) => {
+	const post = jest.fn().mockResolvedValue( { data: { data } } );
+	mockedHttpService.mockReturnValue( { post } as never );
+	return post;
+};
+
+describe( 'find-icons tool', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'proxies a batch of queries to the php ability', async () => {
+		// Arrange
+		const post = givenServerResponse( serverResponse );
+		const { handler } = captureTool();
+
+		// Act
+		await handler( { queries: [ 'add to cart', 'free shipping' ] } );
+
+		// Assert
+		expect( post ).toHaveBeenCalledWith( 'elementor/v1/mcp-proxy', {
+			tool: 'find-icons',
+			input: { queries: [ 'add to cart', 'free shipping' ] },
+		} );
+	} );
+
+	it( 'maps per-page to the snake-cased ability input', async () => {
+		// Arrange
+		const post = givenServerResponse( serverResponse );
+		const { handler } = captureTool();
+
+		// Act
+		await handler( {
+			queries: [ 'cart' ],
+			library: 'fa-solid',
+			category: 'shopping',
+			page: 2,
+			perPage: 25,
+		} );
+
+		// Assert
+		expect( post ).toHaveBeenCalledWith( 'elementor/v1/mcp-proxy', {
+			tool: 'find-icons',
+			input: {
+				queries: [ 'cart' ],
+				library: 'fa-solid',
+				category: 'shopping',
+				page: 2,
+				per_page: 25,
+			},
+		} );
+	} );
+
+	it( 'returns the writable icon pair and the site catalog facets', async () => {
+		// Arrange
+		givenServerResponse( serverResponse );
+		const { handler } = captureTool();
+
+		// Act
+		const result = await handler( { queries: [ 'add to cart' ] } );
+
+		// Assert
+		expect( result.results ).toEqual( serverResponse.results );
+		expect( result.libraries ).toEqual( serverResponse.libraries );
+		expect( result.categories ).toEqual( serverResponse.categories );
+		expect( result.fontAwesomeVersion ).toBe( '7.3.1' );
+	} );
+
+	it( 'omits facets the server did not send', async () => {
+		// Arrange
+		givenServerResponse( { results: serverResponse.results, font_awesome_version: '7.3.1' } );
+		const { handler } = captureTool();
+
+		// Act
+		const result = await handler( { queries: [ 'add to cart' ] } );
+
+		// Assert
+		expect( result ).not.toHaveProperty( 'libraries' );
+		expect( result ).not.toHaveProperty( 'customLibraries' );
+		expect( result ).not.toHaveProperty( 'categories' );
+	} );
+
+	it( 'surfaces a server failure as a tool error', async () => {
+		// Arrange
+		const post = jest.fn().mockRejectedValue( new Error( 'The icon catalog is missing on this site.' ) );
+		mockedHttpService.mockReturnValue( { post } as never );
+		const { handler } = captureTool();
+
+		// Act & Assert
+		await expect( handler( { queries: [ 'cart' ] } ) ).rejects.toThrow(
+			'The icon catalog is missing on this site.'
+		);
+	} );
+} );

package/src/mcp/tools/find-icons/prompt.ts

@@ -0,0 +1,43 @@
+import { toolPrompts } from '@elementor/editor-mcp';
+
+export const findIconsToolPrompt = toolPrompts( 'find-icons' );
+
+findIconsToolPrompt.description(
+	'Finds icons for the `svg` property of an `e-svg` element, across Font Awesome and any icon packs uploaded to this site. ' +
+		'Returns the exact `value` and `library` pair to write - never assemble those strings yourself, and never guess an icon name. ' +
+		'Call this before placing or configuring an `e-svg`. Nothing has to be uploaded to the Media Library for an icon to work.'
+);
+
+findIconsToolPrompt.instruction(
+	'Call it when the user names an icon ("use the cart-shopping icon") and take the first exact `name` match, ' +
+		'and also when the user describes a page and you decide icons belong in it ("create a product page") - ' +
+		'in that case pass one query per icon you intend to place, in a single call.'
+);
+
+findIconsToolPrompt.instruction(
+	'Write queries the way a person would describe the icon ("shopping cart", "credit card", "phone"). Icons are matched on ' +
+		'their name, aliases, Font Awesome search terms and category, so plain language works better than guessed icon names.'
+);
+
+findIconsToolPrompt.instruction(
+	'Results are ordered best first; `matched_on: "name"` is a stronger signal than `matched_on: "term"`. ' +
+		"Check each result's `license` and only use `free` icons; skip any `pro` entry. " +
+		'Prefer `fa-solid` for UI iconography and keep one style across a page; brand marks only exist in `fa-brands`. ' +
+		'An empty `matches` array means no match was found: broaden the phrase instead of inventing a value.'
+);
+
+findIconsToolPrompt.instruction(
+	'Pass the chosen pair to `configure-element` as the `svg` property: ' +
+		'{ "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, ' +
+		'"library": { "$$type": "string", "value": "fa-solid" } } }. ' +
+		'An `e-svg` has no colour or size of its own, so set `width`, `height` and `color` in the same `configure-element` call.'
+);
+
+findIconsToolPrompt.example( `Icon named by the user:
+{ "queries": ["cart-shopping"] }` );
+
+findIconsToolPrompt.example( `Every icon a product page needs, in one call:
+{ "queries": ["add to cart", "free shipping", "secure payment", "instagram"] }` );
+
+findIconsToolPrompt.example( `Browse a category, one style only:
+{ "category": "shopping", "library": "fa-solid", "perPage": 25 }` );

package/src/mcp/tools/find-icons/tool.ts

@@ -0,0 +1,153 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { type HttpResponse, httpService } from '@elementor/http-client';
+import { z } from '@elementor/schema';
+
+import { getMcpErrorMessage } from '../../utils/get-mcp-error-message';
+import { findIconsToolPrompt } from './prompt';
+
+const MCP_PROXY_URL = 'elementor/v1/mcp-proxy';
+
+const MAX_QUERIES = 10;
+
+const MAX_PER_PAGE = 25;
+
+type IconMatch = {
+	value: string;
+	library: string;
+	name: string;
+	label: string;
+	matched_on: 'name' | 'alias' | 'term' | 'category' | 'library';
+	license: 'free' | 'pro';
+};
+
+type IconQueryResult = {
+	query: string;
+	matches: IconMatch[];
+	total: number;
+	page: number;
+	per_page: number;
+	truncated: boolean;
+};
+
+// NOTE: shape defined by Find_Icons_Ability::execute() in modules/mcp/abilities/find-icons-ability.php
+type FindIconsResponse = {
+	results: IconQueryResult[];
+	libraries?: string[];
+	custom_libraries?: Record< string, string >;
+	categories?: string[];
+	truncated_custom_libraries?: string[];
+	font_awesome_version: string | null;
+	llm_instructions?: string;
+};
+
+export const initFindIconsTool = ( reg: MCPRegistryEntry ) => {
+	const { addTool } = reg;
+
+	addTool( {
+		name: 'find-icons',
+		description: findIconsToolPrompt.prompt(),
+		schema: {
+			queries: z
+				.array( z.string() )
+				.max( MAX_QUERIES )
+				.optional()
+				.describe(
+					'One plain-language phrase per icon you need, for example ["add to cart", "free shipping"]. Batch every icon a page needs into a single call.'
+				),
+			library: z
+				.string()
+				.optional()
+				.describe(
+					'Restrict results to one library key reported in "libraries", for example "fa-solid". Omit to search every library installed on the site.'
+				),
+			category: z
+				.string()
+				.optional()
+				.describe(
+					'Restrict results to one Font Awesome category reported in "categories", for example "shopping". May be used without a query to browse that category.'
+				),
+			page: z.number().int().min( 1 ).optional(),
+			perPage: z.number().int().min( 1 ).max( MAX_PER_PAGE ).optional(),
+		},
+		outputSchema: {
+			results: z
+				.array(
+					z.object( {
+						query: z.string(),
+						matches: z.array(
+							z.object( {
+								value: z.string(),
+								library: z.string(),
+								name: z.string(),
+								label: z.string(),
+								matched_on: z.enum( [ 'name', 'alias', 'term', 'category', 'library' ] ),
+								license: z.enum( [ 'free', 'pro' ] ),
+							} )
+						),
+						total: z.number(),
+						page: z.number(),
+						per_page: z.number(),
+						truncated: z.boolean(),
+					} )
+				)
+				.describe(
+					'One entry per query, each with ranked "matches". Every match carries the "value" and "library" pair to write on the e-svg icon prop, plus "matched_on" and "license".'
+				),
+			libraries: z
+				.array( z.string() )
+				.optional()
+				.describe(
+					'Icon library keys installed on this site. Only sent when nothing matched or when browsing.'
+				),
+			customLibraries: z
+				.record( z.string(), z.string() )
+				.optional()
+				.describe(
+					'Custom (uploaded) icon libraries keyed by library. Only sent when nothing matched or when browsing.'
+				),
+			categories: z
+				.array( z.string() )
+				.optional()
+				.describe(
+					'Icon categories for the "category" filter. Only sent when nothing matched or when browsing.'
+				),
+			truncatedCustomLibraries: z
+				.array( z.string() )
+				.optional()
+				.describe( 'Custom libraries with more than 250 icons; only their first 250 icons are searchable.' ),
+			fontAwesomeVersion: z.string().nullable().describe( 'Font Awesome version the site renders icons from.' ),
+			llmInstructions: z
+				.string()
+				.optional()
+				.describe( 'Present only when nothing matched, explaining what to do next.' ),
+		},
+		handler: async ( { queries, library, category, page, perPage } ) => {
+			try {
+				const { data } = await httpService().post< HttpResponse< FindIconsResponse > >( MCP_PROXY_URL, {
+					tool: 'find-icons',
+					input: {
+						...( queries ? { queries } : {} ),
+						...( library ? { library } : {} ),
+						...( category ? { category } : {} ),
+						...( page ? { page } : {} ),
+						...( perPage ? { per_page: perPage } : {} ),
+					},
+				} );
+
+				return {
+					results: data.data.results,
+					...( data.data.libraries ? { libraries: data.data.libraries } : {} ),
+					...( data.data.custom_libraries ? { customLibraries: data.data.custom_libraries } : {} ),
+					...( data.data.categories ? { categories: data.data.categories } : {} ),
+					...( data.data.truncated_custom_libraries
+						? { truncatedCustomLibraries: data.data.truncated_custom_libraries }
+						: {} ),
+					fontAwesomeVersion: data.data.font_awesome_version,
+					...( data.data.llm_instructions ? { llmInstructions: data.data.llm_instructions } : {} ),
+				};
+			} catch ( error ) {
+				throw new Error( getMcpErrorMessage( error, 'find-icons' ) );
+			}
+		},
+	} );
+};