@elementor/editor-canvas 4.1.0-manual → 4.2.0-839

package/src/mcp/resources/document-structure-resource.ts

@@ -1,41 +1,43 @@
+import {
+	type ExtendedWindow as BaseExtendedWindow,
+	type V1Document,
+	type V1DocumentsManager,
+} from '@elementor/editor-documents';
+import {
+	getWidgetsCache,
+	type V1Element,
+	type V1ElementEditorSettingsProps,
+	type V1ElementModelProps,
+} from '@elementor/editor-elements';
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { __privateListenTo as listenTo, commandEndEvent } from '@elementor/editor-v1-adapters';
 
-type ExtendedWindow = Window & {
-	elementor?: {
-		documents?: {
-			getCurrent?: () => {
-				id: number;
-				config: {
-					type: string;
-					settings?: {
-						post_title?: string;
-					};
-				};
-				container: {
-					children?: ElementorContainer[];
-				};
-			};
-		};
+type UnknownVersionElementInstanceData = V1Element & {
+	model: V1Element[ 'model' ] & {
+		attributes: V1ElementModelProps;
+		config?: { atomic?: boolean };
+		editor_settings?: V1ElementEditorSettingsProps;
 	};
+	children?: V1Element[];
 };
 
-type ElementorContainer = {
-	id: string;
-	model: {
-		attributes: {
-			id: string;
-			elType: string;
-			widgetType?: string;
-			title?: string;
-		};
-		editor_settings?: {
-			title?: string;
-		};
+type ContainerWithStructure = V1Document & {
+	config: V1Document[ 'config' ] & {
+		settings?: { post_title?: string };
+	};
+	container: V1Document[ 'container' ] & {
+		children?: UnknownVersionElementInstanceData[];
 	};
-	children?: ElementorContainer[];
 };
 
+interface ExtendedWindow extends BaseExtendedWindow {
+	elementor: Omit< BaseExtendedWindow[ 'elementor' ], 'documents' > & {
+		documents: Omit< V1DocumentsManager, 'getCurrent' > & {
+			getCurrent: () => ContainerWithStructure;
+		};
+	};
+}
+
 export const DOCUMENT_STRUCTURE_URI = 'elementor://document/structure';
 
 export const initDocumentStructureResource = ( reg: MCPRegistryEntry ) => {
@@ -62,6 +64,7 @@ export const initDocumentStructureResource = ( reg: MCPRegistryEntry ) => {
 			commandEndEvent( 'document/elements/copy' ),
 			commandEndEvent( 'document/elements/paste' ),
 			commandEndEvent( 'editor/documents/attach-preview' ),
+			commandEndEvent( 'editor/documents/switch' ),
 		],
 		updateDocumentStructure
 	);
@@ -89,7 +92,7 @@ export const initDocumentStructureResource = ( reg: MCPRegistryEntry ) => {
 };
 
 function getDocumentStructure() {
-	const extendedWindow = window as ExtendedWindow;
+	const extendedWindow = window as unknown as ExtendedWindow;
 	const document = extendedWindow.elementor?.documents?.getCurrent?.();
 
 	if ( ! document ) {
@@ -97,9 +100,7 @@ function getDocumentStructure() {
 	}
 
 	const containers = document.container?.children || [];
-	const elements = ( containers as ElementorContainer[] ).map( ( container: ElementorContainer ) =>
-		extractElementData( container )
-	);
+	const elements = containers.map( ( container ) => extractElementData( container ) );
 
 	return {
 		documentId: document.id,
@@ -109,7 +110,20 @@ function getDocumentStructure() {
 	};
 }
 
-function extractElementData( element: ElementorContainer ): Record< string, unknown > | null {
+function resolveElementVersion( element: UnknownVersionElementInstanceData ): 'v3' | 'v4' {
+	if ( element.model?.config?.atomic ) {
+		return 'v4';
+	}
+
+	const widgetType = element.model?.attributes?.widgetType;
+	if ( widgetType && getWidgetsCache()?.[ widgetType ]?.atomic_props_schema ) {
+		return 'v4';
+	}
+
+	return 'v3';
+}
+
+function extractElementData( element: UnknownVersionElementInstanceData ): Record< string, unknown > | null {
 	if ( ! element || ! element.model ) {
 		return null;
 	}
@@ -119,6 +133,7 @@ function extractElementData( element: ElementorContainer ): Record< string, unkn
 		id: model.id,
 		elType: model.elType,
 		widgetType: model.widgetType || undefined,
+		version: resolveElementVersion( element ),
 	};
 
 	const title = model.title || element.model?.editor_settings?.title;
@@ -129,8 +144,8 @@ function extractElementData( element: ElementorContainer ): Record< string, unkn
 
 	if ( element.children && element.children.length > 0 ) {
 		result.children = element.children
-			.map( ( child: ElementorContainer ) => extractElementData( child ) )
-			.filter( ( child: Record< string, unknown > | null ) => child !== null );
+			.map( ( child ) => extractElementData( child as UnknownVersionElementInstanceData ) )
+			.filter( ( child ) => child !== null );
 	}
 
 	return result;

package/src/mcp/resources/editor-state-resource.ts

@@ -0,0 +1,122 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { __privateListenTo as listenTo, commandEndEvent } from '@elementor/editor-v1-adapters';
+
+const CURRENTLY_VIEWED_SCREEN = 'The user is currently viewing the Elementor editor';
+const PAGE_CONTENT_CHARACTER_LIMIT = 500;
+const PREVIEW_TEXT_NODE_MIN_LENGTH = 2;
+
+export const EDITOR_STATE_URI = 'elementor://context/editor-state';
+
+type ElementorWindow = Window & {
+	elementor?: {
+		$previewContents?: Element[];
+		documents?: {
+			getCurrent?: () => {
+				config?: {
+					settings?: {
+						post_title?: string;
+					};
+				};
+			};
+		};
+	};
+};
+
+export const initEditorStateResource = ( reg: MCPRegistryEntry ) => {
+	const { resource, sendResourceUpdated } = reg;
+
+	let lastSerializedState = '';
+
+	const buildState = () => ( {
+		currentlyViewedScreen: CURRENTLY_VIEWED_SCREEN,
+		pageContent: getPageContentFromPreview(),
+		pageTitle: getPageTitle(),
+	} );
+
+	const notifyIfChanged = () => {
+		const serialized = JSON.stringify( buildState() );
+		if ( serialized === lastSerializedState ) {
+			return;
+		}
+		lastSerializedState = serialized;
+		sendResourceUpdated( { uri: EDITOR_STATE_URI } );
+	};
+
+	listenTo(
+		[ commandEndEvent( 'editor/documents/switch' ), commandEndEvent( 'editor/documents/attach-preview' ) ],
+		notifyIfChanged
+	);
+
+	lastSerializedState = JSON.stringify( buildState() );
+
+	resource(
+		'editor-state',
+		EDITOR_STATE_URI,
+		{
+			description: 'Editor page title, preview text snapshot, and viewed screen label.',
+		},
+		async () => {
+			return {
+				contents: [
+					{
+						uri: EDITOR_STATE_URI,
+						text: JSON.stringify( buildState(), null, 2 ),
+					},
+				],
+			};
+		}
+	);
+};
+
+function getPageContentFromPreview(): string | null {
+	try {
+		const root = ( window as ElementorWindow ).elementor?.$previewContents?.[ 0 ];
+		if ( ! root ) {
+			return null;
+		}
+		const content: string[] = [];
+		const clone = root.cloneNode( true ) as HTMLElement;
+		clone.querySelectorAll( '.elementor-editor-element-settings, #elementor-add-new-section' ).forEach( ( el ) => {
+			el.remove();
+		} );
+		const walk = ( node: Node, insideElementorElement = false ) => {
+			const isInside = ( node as Element ).classList?.contains( 'elementor-element' ) || insideElementorElement;
+			if ( node.nodeType === Node.TEXT_NODE && isInside ) {
+				const text = node.textContent?.trim().replace( /\s+/g, ' ' );
+				if ( text && text.length > PREVIEW_TEXT_NODE_MIN_LENGTH ) {
+					content.push( text );
+				}
+			} else {
+				node.childNodes.forEach( ( child ) => {
+					walk( child, isInside );
+				} );
+			}
+		};
+		walk( clone );
+		const text = content.join( ' ' );
+		if ( text.length > PAGE_CONTENT_CHARACTER_LIMIT ) {
+			return text.slice( 0, PAGE_CONTENT_CHARACTER_LIMIT ) + '...';
+		}
+		return text;
+	} catch {
+		return null;
+	}
+}
+
+function getPageTitle(): string {
+	try {
+		const extendedWindow = window as ElementorWindow;
+		const currentDocument = extendedWindow.elementor?.documents?.getCurrent?.();
+		const postTitle = currentDocument?.config?.settings?.post_title;
+		if ( postTitle ) {
+			return postTitle;
+		}
+
+		let title = document.title || 'Page';
+		title = title.split( /\s*[‹»|–—-]\s*/ )[ 0 ];
+		const trimmed = title.trim();
+		return trimmed || 'Page';
+	} catch {
+		return 'Page';
+	}
+}

package/src/mcp/resources/general-context-resource.ts

@@ -0,0 +1,99 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { __privateListenTo as listenTo, commandEndEvent } from '@elementor/editor-v1-adapters';
+
+type ExtendedWindow = Window & {
+	angieConfig?: {
+		plugins?: Record< string, unknown >;
+	};
+	elementor?: {
+		documents?: {
+			getCurrent?: () => {
+				config?: {
+					settings?: {
+						post_title?: string;
+					};
+				};
+			};
+		};
+	};
+};
+
+export const GENERAL_CONTEXT_URI = 'elementor://context/general';
+
+export const initGeneralContextResource = ( reg: MCPRegistryEntry ) => {
+	const { resource, sendResourceUpdated } = reg;
+
+	let lastSerializedPayload: string | null = null;
+
+	const getPageTitle = (): string | null => {
+		const extendedWindow = window as ExtendedWindow;
+		const title = extendedWindow.elementor?.documents?.getCurrent?.()?.config?.settings?.post_title;
+		if ( ! title?.trim() ) {
+			return null;
+		}
+		return title;
+	};
+
+	const buildPayload = () => {
+		const extendedWindow = window as ExtendedWindow;
+		const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+		const postParam = new URLSearchParams( location.search ).get( 'post' );
+		const parsedPostId = postParam ? Number( postParam ) : null;
+		const postId = parsedPostId !== null && Number.isFinite( parsedPostId ) ? parsedPostId : null;
+		const pageTitle = getPageTitle();
+		const urlObject = new URL( window.location.href );
+		const pageUrl = urlObject.pathname + urlObject.search;
+		const pageName = pageTitle || 'Elementor Editor';
+		const plugins = extendedWindow.angieConfig?.plugins;
+
+		return {
+			timezone,
+			postId,
+			currentPage: {
+				pageName,
+				pageTitle,
+				pageUrl,
+			},
+			...( plugins && { plugins } ),
+		};
+	};
+
+	const pushUpdateIfChanged = () => {
+		const serialized = JSON.stringify( buildPayload() );
+		if ( serialized === lastSerializedPayload ) {
+			return;
+		}
+		lastSerializedPayload = serialized;
+		sendResourceUpdated( { uri: GENERAL_CONTEXT_URI } );
+	};
+
+	resource(
+		'general-context',
+		GENERAL_CONTEXT_URI,
+		{
+			description: 'General context: timezone, post id, and current page.',
+		},
+		async () => {
+			return {
+				contents: [
+					{
+						uri: GENERAL_CONTEXT_URI,
+						mimeType: 'application/json',
+						text: JSON.stringify( buildPayload(), null, 2 ),
+					},
+				],
+			};
+		}
+	);
+
+	listenTo(
+		[
+			commandEndEvent( 'editor/documents/switch' ),
+			commandEndEvent( 'editor/documents/attach-preview' ),
+			commandEndEvent( 'document/elements/settings' ),
+		],
+		pushUpdateIfChanged
+	);
+
+	pushUpdateIfChanged();
+};

package/src/mcp/resources/selected-element-resource.ts

@@ -0,0 +1,217 @@
+import { getContainer, getSelectedElements, getWidgetsCache, type V1Element } from '@elementor/editor-elements';
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import {
+	__privateListenTo as listenTo,
+	commandEndEvent,
+	type CommandEvent,
+	type ListenerEvent,
+} from '@elementor/editor-v1-adapters';
+
+export const SELECTED_ELEMENT_URI = 'elementor://context/selected-element';
+
+type WidgetVersion = 'v3' | 'v4';
+
+type SelectionContainer = V1Element & {
+	type?: string;
+	label?: string;
+	model: V1Element[ 'model' ] & {
+		config?: { atomic?: boolean };
+	};
+	settings: V1Element[ 'settings' ] & {
+		toJSON?: () => Record< string, unknown >;
+	};
+};
+
+type SelectedElementPayload = {
+	elementDisplayName: string | null;
+	elementType: string | null;
+	properties: Record< string, unknown > | null;
+	selectedElementId: string | null;
+	selectedParentId: string | null;
+	version: WidgetVersion | null;
+	widgetType: string | null;
+};
+
+export const initSelectedElementResource = ( reg: MCPRegistryEntry ) => {
+	const { resource, sendResourceUpdated } = reg;
+
+	let currentPayloadText: string | null = null;
+
+	const publishIfChanged = ( payload: SelectedElementPayload ) => {
+		const nextText = JSON.stringify( payload );
+
+		if ( nextText !== currentPayloadText ) {
+			currentPayloadText = nextText;
+			sendResourceUpdated( { uri: SELECTED_ELEMENT_URI } );
+		}
+	};
+
+	const onCommand = ( e: ListenerEvent ) => {
+		if ( e.type !== 'command' ) {
+			return;
+		}
+
+		const commandEvent = e as CommandEvent< { container?: SelectionContainer } >;
+
+		if ( commandEvent.command === 'document/elements/deselect-all' ) {
+			publishIfChanged( createEmptySelectedElementPayload() );
+			return;
+		}
+
+		if (
+			commandEvent.command !== 'document/elements/select' &&
+			commandEvent.command !== 'document/elements/settings'
+		) {
+			return;
+		}
+
+		const { container } = commandEvent.args || {};
+
+		if ( container?.id ) {
+			publishIfChanged( buildPayloadFromContainer( container ) );
+			return;
+		}
+
+		publishIfChanged( readSelectionFromEditor() );
+	};
+
+	listenTo(
+		[
+			commandEndEvent( 'document/elements/select' ),
+			commandEndEvent( 'document/elements/deselect-all' ),
+			commandEndEvent( 'document/elements/settings' ),
+		],
+		onCommand
+	);
+
+	publishIfChanged( readSelectionFromEditor() );
+
+	resource(
+		'selected-element',
+		SELECTED_ELEMENT_URI,
+		{
+			description: 'Currently selected Elementor element context.',
+		},
+		async () => {
+			return {
+				contents: [
+					{
+						uri: SELECTED_ELEMENT_URI,
+						text: JSON.stringify( readSelectionFromEditor(), null, 2 ),
+					},
+				],
+			};
+		}
+	);
+};
+
+function createEmptySelectedElementPayload(): SelectedElementPayload {
+	return {
+		elementDisplayName: null,
+		elementType: null,
+		properties: null,
+		selectedElementId: null,
+		selectedParentId: null,
+		version: null,
+		widgetType: null,
+	};
+}
+
+function readSelectionFromEditor(): SelectedElementPayload {
+	const elements = getSelectedElements();
+
+	if ( elements.length !== 1 ) {
+		return createEmptySelectedElementPayload();
+	}
+
+	const container = getContainer( elements[ 0 ].id );
+
+	return buildPayloadFromContainer( container );
+}
+
+function buildPayloadFromContainer( container: SelectionContainer | null ): SelectedElementPayload {
+	if ( ! container?.id ) {
+		return createEmptySelectedElementPayload();
+	}
+
+	const widgetType = container.model.get( 'widgetType' ) ?? null;
+	const elementType = container.type ?? 'widget';
+
+	return {
+		elementDisplayName: getElementDisplayName( container ),
+		elementType,
+		properties: getElementProperties( container, widgetType ),
+		selectedElementId: container.id,
+		selectedParentId: container.parent?.id ?? null,
+		version: resolveElementVersion( container, widgetType ),
+		widgetType,
+	};
+}
+
+function resolveElementVersion( container: SelectionContainer, widgetType: string | null ): WidgetVersion {
+	if ( container.model?.config?.atomic ) {
+		return 'v4';
+	}
+	if ( widgetType && getWidgetsCache()?.[ widgetType ]?.atomic_props_schema ) {
+		return 'v4';
+	}
+	return 'v3';
+}
+
+function getElementProperties(
+	container: SelectionContainer,
+	widgetType: string | null
+): Record< string, unknown > | null {
+	const settings = container.settings?.toJSON?.();
+	if ( ! settings || typeof settings !== 'object' ) {
+		return null;
+	}
+
+	const widgetConfig = widgetType ? getWidgetsCache()?.[ widgetType ] : null;
+	const controls = widgetConfig?.controls as Record< string, { default?: unknown } > | undefined;
+
+	const filtered: Record< string, unknown > = {};
+
+	for ( const [ key, value ] of Object.entries( settings ) ) {
+		if ( value === undefined || value === null || value === '' ) {
+			continue;
+		}
+
+		const controlDefault = controls?.[ key ]?.default;
+		if ( controlDefault !== undefined && JSON.stringify( value ) === JSON.stringify( controlDefault ) ) {
+			continue;
+		}
+
+		filtered[ key ] = value;
+	}
+
+	return Object.keys( filtered ).length > 0 ? filtered : null;
+}
+
+function getElementDisplayName( container: SelectionContainer ): string {
+	try {
+		if ( container.label ) {
+			return container.label;
+		}
+
+		const widgetType = container.model?.get?.( 'widgetType' );
+
+		if ( widgetType ) {
+			const capitalizedType = widgetType.charAt( 0 ).toUpperCase() + widgetType.slice( 1 );
+
+			return capitalizedType.replace( /-/g, ' ' );
+		}
+
+		if ( container.type === 'container' ) {
+			return 'Container';
+		}
+
+		if ( container.type === 'section' ) {
+			return 'Section';
+		}
+
+		return `Element ${ container.id }`;
+	} catch {
+		return `Element ${ container.id }`;
+	}
+}

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

@@ -11,6 +11,50 @@ import {
 } from '@elementor/editor-props';
 import { getStylesSchema } from '@elementor/editor-styles';
 
+import { hasV3Controls, isWidgetAvailableForLLM } from '../utils/element-data-util';
+
+const V3_LAYOUT_CONTROL_TYPES = new Set( [ 'section', 'tab', 'tabs' ] );
+
+type V3ControlMetadataEntry = {
+	default?: unknown;
+	type?: string;
+	options?: unknown;
+};
+
+function extractV3ControlsMetadata( controls: unknown ): Record< string, V3ControlMetadataEntry > {
+	if ( ! hasV3Controls( controls ) ) {
+		return {};
+	}
+	const result: Record< string, V3ControlMetadataEntry > = {};
+	for ( const [ controlKey, raw ] of Object.entries( controls as Record< string, unknown > ) ) {
+		if ( ! raw || typeof raw !== 'object' ) {
+			continue;
+		}
+		const control = raw as Record< string, unknown >;
+		const controlType = typeof control.type === 'string' ? control.type : undefined;
+		if ( controlType && V3_LAYOUT_CONTROL_TYPES.has( controlType ) ) {
+			continue;
+		}
+		const entry: V3ControlMetadataEntry = {};
+		if ( Object.prototype.hasOwnProperty.call( control, 'default' ) ) {
+			entry.default = control.default;
+		}
+		if ( controlType ) {
+			entry.type = controlType;
+		}
+		if ( Object.prototype.hasOwnProperty.call( control, 'options' ) && control.options !== undefined ) {
+			const options = control.options;
+			if ( options && typeof options === 'object' && ! Array.isArray( options ) ) {
+				entry.options = Object.keys( options as Record< string, unknown > );
+			} else {
+				entry.options = options;
+			}
+		}
+		result[ controlKey ] = entry;
+	}
+	return result;
+}
+
 export const WIDGET_SCHEMA_URI = 'elementor://widgets/schema/{widgetType}';
 export const STYLE_SCHEMA_URI = 'elementor://styles/schema/{category}';
 export const BEST_PRACTICES_URI = 'elementor://styles/best-practices';
@@ -61,7 +105,7 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
 			},
 		} ),
 		{
-			description: 'Common styles schema for the specified category',
+			description: 'Common styles schema for the specified category (applicable for V4 elements only)',
 		},
 		async ( uri, variables ) => {
 			const category = typeof variables.category === 'string' ? variables.category : variables.category?.[ 0 ];
@@ -89,10 +133,10 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
 		new ResourceTemplate( WIDGET_SCHEMA_URI, {
 			list: () => {
 				const cache = getWidgetsCache() || {};
-				const availableWidgets = Object.keys( cache || {} ).filter(
-					( widgetType ) =>
-						cache[ widgetType ]?.atomic_props_schema && cache[ widgetType ].meta?.llm_support !== false
+				const availableWidgets = Object.keys( cache ).filter( ( widgetType ) =>
+					isWidgetAvailableForLLM( cache[ widgetType ] )
 				);
+
 				return {
 					resources: availableWidgets.map( ( widgetType ) => ( {
 						uri: `elementor://widgets/schema/${ widgetType }`,
@@ -108,20 +152,36 @@ Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
 			const widgetType =
 				typeof variables.widgetType === 'string' ? variables.widgetType : variables.widgetType?.[ 0 ];
 			const widgetData = getWidgetsCache()?.[ widgetType ];
-			const propSchema = widgetData?.atomic_props_schema;
-			if ( ! propSchema || ! widgetData ) {
+			if ( ! widgetData ) {
 				throw new Error( `No prop schema found for element type: ${ widgetType }` );
 			}
+			const propSchema = widgetData.atomic_props_schema;
+			if ( ! propSchema ) {
+				if ( ! hasV3Controls( widgetData.controls ) ) {
+					throw new Error( `No prop schema found for element type: ${ widgetType }` );
+				}
+				const controlMetadata = extractV3ControlsMetadata( widgetData.controls );
+				return {
+					contents: [
+						{
+							uri: uri.toString(),
+							mimeType: 'application/json',
+							text: JSON.stringify( {
+								widget_version: 'v3',
+								message:
+									'This widget exists in the editor but has no atomic props schema (V4). Use control_metadata as non-authoritative hints from legacy controls.',
+								fields_note: 'All settings are optional; there is no JSON schema for this widget type.',
+								properties: controlMetadata,
+							} ),
+						},
+					],
+				};
+			}
 			const asJson = Object.fromEntries(
-				Object.entries( propSchema ).map( ( [ key, propType ] ) => [
-					key,
-					Schema.propTypeToJsonSchema( propType ),
-				] )
+				Object.entries( propSchema )
+					.filter( ( [ key, propType ] ) => Schema.isPropKeyConfigurable( key, propType as PropType ) )
+					.map( ( [ key, propType ] ) => [ key, Schema.propTypeToJsonSchema( propType ) ] )
 			);
-			Schema.nonConfigurablePropKeys.forEach( ( key ) => {
-				// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-				delete asJson[ key ];
-			} );
 
 			const description =
 				typeof widgetData?.meta?.description === 'string' ? widgetData.meta.description : undefined;