• File: document-mutation-links.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/elementor/modules/mcp/abilities/utils/document-mutation-links.php
  • Date Modified: 11/16/2026 12:03 PM
  • File size: 3.81 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

namespace Elementor\Modules\Mcp\Abilities\Utils;

use Elementor\Core\Base\Document;
use Elementor\Modules\Components\Documents\Component as Component_Document;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

class Document_Mutation_Links {

	public static function preview_schema_property(): array {
		return Document_Preview_Url::output_schema_property();
	}

	public static function llm_instructions_schema_property(): array {
		return [
			'type' => 'string',
			'description' => 'Mandatory next step: include this text (with the preview or editor link) in your reply to the user.',
		];
	}
	public static function staged_schema_property(): array {
		return [
			'type' => 'boolean',
			'description' => 'True when the document is a draft copy of a published page: changes are not live until elementor/publish-document.',
		];
	}

	public static function staged_write_instructions( Document $document ): string {
		if ( $document instanceof Component_Document ) {
			return __( 'Change saved to a draft copy of the component. Pages using it are unchanged until you call elementor/manage-component with action=publish.', 'elementor' );
		}

		return __( 'Change saved to a draft copy. The live page is unchanged until you call elementor/publish-document.', 'elementor' );
	}

	public static function staged_read_instructions(): string {
		return __( 'This structure includes staged changes that are not live yet. The live page shows them only after you call elementor/publish-document.', 'elementor' );
	}

	public static function undo_revision_id_schema_property(): array {
		return [
			'type' => [ 'integer', 'null' ],
			'description' => 'Revision holding the document state from before this change. Pass it as revision_id to elementor/manage-revisions with action=restore to undo the change. Null when revisions are disabled for this post.',
		];
	}

	public static function undo_instructions( int $post_id, ?int $undo_revision_id ): string {
		if ( null === $undo_revision_id ) {
			return __( 'Undo is unavailable for this change because revisions are disabled for this post.', 'elementor' );
		}

		return sprintf(
			/* translators: 1: Post ID, 2: Revision ID. */
			__( 'To undo this change, call elementor/manage-revisions with action=restore, post_id %1$d and revision_id %2$d.', 'elementor' ),
			$post_id,
			$undo_revision_id
		);
	}

	public static function for_document( Document $document, ?string $success_message = null ): array {
		$prefix = $success_message ?? __( 'Change saved.', 'elementor' );
		$preview_url = Document_Preview_Url::for_document( $document );

		if ( '' === $preview_url ) {
			return self::for_editor_link( $prefix, (string) $document->get_edit_url() );
		}

		return [
			'preview_url' => $preview_url,
			'llm_instructions' => self::build_preview_link_instructions( $prefix, $preview_url ),
		];
	}

	private static function for_editor_link( string $prefix, string $edit_url ): array {
		if ( '' === $edit_url ) {
			return [ 'llm_instructions' => $prefix ];
		}

		return [
			'edit_url' => $edit_url,
			'llm_instructions' => self::build_edit_link_instructions( $prefix, $edit_url ),
		];
	}

	private static function build_preview_link_instructions( string $prefix, string $preview_url ): string {
		return sprintf(
			/* translators: 1: Success message, 2: Preview URL the LLM must share with the user. */
			__( '%1$s You MUST show the user this preview link in your reply (they must be logged into WordPress as an editor): %2$s', 'elementor' ),
			$prefix,
			$preview_url
		);
	}

	private static function build_edit_link_instructions( string $prefix, string $edit_url ): string {
		return sprintf(
			/* translators: 1: Success message, 2: Elementor editor URL the LLM must share with the user. */
			__( '%1$s You MUST show the user this link to review the change in the Elementor editor: %2$s', 'elementor' ),
			$prefix,
			$edit_url
		);
	}
}