<?php
namespace AdvancedAddons;

use WP_Error;
use WordPress\AiClient\Messages\DTO\Message;
use WordPress\AiClient\Messages\DTO\MessagePart;
use WordPress\AiClient\Tools\DTO\FunctionCall;
use WordPress\AiClient\Tools\DTO\FunctionDeclaration;
use WordPress\AiClient\Tools\DTO\FunctionResponse;
use AdvancedAddons\Tools\Add_Blocks_To_Page_Tool;
use AdvancedAddons\Tools\Call_WordPress_Rest_Api_Tool;
use AdvancedAddons\Tools\Edit_Full_Page_Tool;
use AdvancedAddons\Tools\Generate_Blocks_Tool;
use AdvancedAddons\Tools\Get_Page_Content_Tool;
use AdvancedAddons\Tools\Replace_Selected_Blocks_Tool;
use AdvancedAddons\Tools\Search_Unsplash_Image_Tool;
use AdvancedAddons\Tools\Elementor_Generate_Html_Tool;
use AdvancedAddons\Tools\Elementor_Add_Html_To_Page_Tool;
use AdvancedAddons\Tools\Elementor_Replace_Selection_Tool;
use AdvancedAddons\Tools\Elementor_Edit_Full_Page_Tool;
use AdvancedAddons\Elementor_Html_Converter;

class AI_Service {
	private const CHAT_MAX_OUTPUT_TOKENS = 8192;
	private const ELEMENTOR_MAX_TOOL_STEPS = 20;
	private const ELEMENTOR_MAX_TOOL_COUNT = 80;
	private const ELEMENTOR_MAX_TOOL_DESCRIPTION_LENGTH = 3200;
	private const ELEMENTOR_MAX_TOOL_SCHEMA_BYTES = 32768;
	private const ELEMENTOR_MAX_TOOL_CATALOG_BYTES = 262144;
	private const ELEMENTOR_MAX_TOOL_RESULT_BYTES = 32768;
	private const ELEMENTOR_MAX_RESOURCE_BYTES = 65536;
	private const ELEMENTOR_MAX_RESOURCES_TOTAL_BYTES = 131072;
	private const ELEMENTOR_NATIVE_ERROR_FALLBACK_THRESHOLD = 3;
	private const ELEMENTOR_MAX_NARRATION_NUDGES = 2;
	private const RATE_LIMIT_RETRY_MAX_ATTEMPTS = 4;
	private const RATE_LIMIT_RETRY_MAX_DELAY_MS = 5000;

	/**
	 * Model/provider selected for this request.
	 */
	private ?string $provider = null;
	private ?string $model   = null;

	/**
	 * Attachments from the initial user message. Consumed on the first AI call.
	 */
	private array $attachments = array();

	/**
	 * Live page content (serialized blocks) sent from the editor.
	 * Falls back to get_post() when not provided.
	 */
	private ?string $page_content = null;

	/**
	 * Whether to include global theme guidance in system prompts (set via the
	 * chat UI toggle).
	 */
	private bool $use_global_theme = false;

	/**
	 * Editor type (gutenberg or elementor).
	 */
	private string $editor = "gutenberg";

	/**
	 * Requested Gutenberg output mode: auto, tailwind, or native.
	 */
	private string $block_type_preference = 'auto';

	/** @var array<int,array{name:string,description:string,inputSchema:array}> */
	private array $editor_tools = array();

	/** @var array<int,array{uri:string,content:string}> Preloaded editor resources (Elementor). */
	private array $editor_resources = array();

	/** Whether legacy HTML conversion tools are available in this Elementor pass. */
	private bool $allow_elementor_html_fallback = true;

	/** @var array{key:string,lock_key:string,envelope_hash:string,results_hash:string}|null */
	private ?array $continuation_claim = null;

	private function is_available(): bool {
		return Compat::supports_ai();
	}

	/**
	 * Ensure the current user may edit the given post when a post ID is present.
	 *
	 * @param int|null $post_id Post ID or null.
	 * @return true|WP_Error
	 */
	private function assert_can_edit_optional_post( ?int $post_id ) {
		if ( $post_id && ! Security::can_edit_post( $post_id ) ) {
			return new WP_Error(
				'edit_forbidden',
				__( 'Sorry, you are not allowed to edit this post.', 'advanced-animation' )
			);
		}
		return true;
	}

	/**
	 * Track Unsplash downloads when generated HTML embeds Unsplash CDN images.
	 *
	 * @param string|WP_Error $html Generated HTML or error.
	 * @return string|WP_Error
	 */
	private function track_unsplash_in_html( $html ) {
		if ( ! is_wp_error( $html ) && is_string( $html ) && '' !== $html ) {
			\AdvancedAddons\Tools\Search_Unsplash_Image_Tool::track_downloads_in_content( $html );
		}
		return $html;
	}

	/**
	 * Run the agent loop.
	 *
	 * @param string   $prompt      Current user prompt.
	 * @param string|null $provider AI provider ID.
	 * @param string|null $model    AI model ID.
	 * @param array    $attachments Files/images attached to the current message.
	 * @param array    $messages    Previous conversation history.
	 * @param array|null $selection Current editor selection context.
	 * @param int|null   $post_id   Current editor post ID.
	 * @param string|null $page_content Live page content from the editor.
	 * @return array|WP_Error Result envelope with optional tool_calls log.
	 */
	public function run( string $prompt, ?string $provider = null, ?string $model = null, array $attachments = [], array $messages = [], ?array $selection = null, ?int $post_id = null, ?string $page_content = null, bool $use_global_theme = false, string $editor = "gutenberg", string $block_type_preference = 'auto', array $editor_tools = array(), ?array $continuation = null, array $editor_tool_results = array(), array $editor_resources = array() ) {
		if ( ! $this->is_available() ) {
			return new WP_Error(
				'ai_unavailable',
				__( 'WordPress AI Client is not available on this site.', 'advanced-animation' )
			);
		}

		if ( $post_id && ! Security::can_edit_post( $post_id ) ) {
			return new WP_Error(
				'edit_forbidden',
				__( 'Sorry, you are not allowed to edit this post.', 'advanced-animation' )
			);
		}

		$this->provider    = $provider;
		$this->model       = $model;
		$this->attachments = $attachments;
		$this->page_content = $page_content;
		$this->use_global_theme = $use_global_theme;
		$this->editor = $editor;
		$this->block_type_preference = $this->normalize_block_type_preference( $block_type_preference );
		$this->editor_tools = 'elementor' === $editor
			? $this->sanitize_editor_tools( $editor_tools )
			: array();
		$this->editor_resources = 'elementor' === $editor
			? $this->sanitize_editor_resources( $editor_resources )
			: array();

		$direct_result = empty( $this->editor_tools )
			? $this->maybe_run_direct_editor_action( $prompt, $selection, $post_id, $attachments )
			: null;
		if ( is_wp_error( $direct_result ) ) {
			return $direct_result;
		}
		if ( is_array( $direct_result ) ) {
			return $direct_result;
		}

		$continuation_state = $this->restore_editor_continuation(
			$continuation,
			$editor_tool_results,
			$post_id
		);
		if ( is_wp_error( $continuation_state ) ) {
			return $continuation_state;
		}

		$native_error_count = $this->next_native_error_count( $continuation_state, $editor_tool_results );
		$this->allow_elementor_html_fallback = 'elementor' !== $editor
			|| empty( $this->editor_tools )
			|| ( null !== $continuation && $native_error_count >= self::ELEMENTOR_NATIVE_ERROR_FALLBACK_THRESHOLD );

		$registry     = $this->build_tool_registry();
		$declarations = $this->build_function_declarations( $registry );

		if ( $continuation_state ) {
			$conversation = $continuation_state['conversation'];
			$tool_log     = $continuation_state['tool_log'];
			$start_step   = $continuation_state['step'];
			$use_native   = $continuation_state['use_native'];
		} else {
			$conversation = array_merge(
				$this->normalize_history( $messages ),
				array( $this->build_user_message( $prompt, $attachments ) )
			);
			$initial_text = $this->message_to_text( end( $conversation ) ?: array() );
			$use_native   = $this->detect_native_support( $initial_text, $declarations );
			$tool_log     = array();
			$start_step   = 0;
		}

		$system_prompt = $this->build_system_prompt( $registry, $selection, $use_native, $post_id );

		$max_steps = self::ELEMENTOR_MAX_TOOL_STEPS;
		$narration_nudges = 0;

		for ( $step = $start_step; $step < $max_steps; $step++ ) {
			$ai_turn = $this->call_ai_with_rate_limit_retry( $system_prompt, $conversation, 0 === $step && ! $continuation_state, $declarations, $use_native );

			if ( is_wp_error( $ai_turn ) ) {
				$this->release_editor_continuation_claim();
				return $ai_turn;
			}
			$this->consume_editor_continuation_claim();

			// Native function-call turn.
			if ( 'function_calls' === $ai_turn['type'] ) {
				$model_parts     = array();
				$response_parts  = array();
				$deferred_calls  = array();

				foreach ( $ai_turn['calls'] as $call ) {
					$tool_name = $call['name'] ?? '';
					$call_id   = sanitize_text_field( strval( $call['id'] ?? '' ) );
					if ( '' === $call_id ) {
						$call_id = wp_generate_uuid4();
					}
					$call_args = is_array( $call['args'] ?? null ) ? $call['args'] : array();
					$tool      = $registry->get( $tool_name );

					if ( ! $tool ) {
						$tool_result = array(
							'success' => false,
							/* translators: %s: tool name requested by the AI model */
							'error'   => sprintf( __( 'Unknown tool requested: %s', 'advanced-animation' ), $tool_name ),
						);
					} elseif ( $tool instanceof Deferred_Editor_Tool ) {
						$tool_result = null;
						$deferred_calls[] = array(
							'id'   => $call_id,
							'name' => $tool_name,
							'args' => $call_args,
						);
					} else {
						$arguments   = $call_args;
						$tool_context = array(
							'post_id'        => $post_id,
							'selection'      => $selection,
							'page_content'   => $this->page_content,
							'editor'         => $this->editor,
							'block_type_preference' => $this->block_type_preference,
							'request_source' => 'chat',
						);
						$tool_result = $tool->execute( $arguments, $tool_context );
					}

					if ( ! ( $tool instanceof Deferred_Editor_Tool ) ) {
						$tool_log[] = array(
							'tool'      => $tool_name,
							'arguments' => $call_args,
							'result'    => $tool_result,
						);
					}

					$model_part = array(
						'type'         => 'functionCall',
						'functionCall' => array(
							'id'   => $call_id,
							'name' => $tool_name,
							'args' => $call_args,
						),
					);
					if ( ! empty( $call['thoughtSignature'] ) ) {
						$model_part['thoughtSignature'] = $call['thoughtSignature'];
					}
					$model_parts[] = $model_part;

					if ( ! ( $tool instanceof Deferred_Editor_Tool ) ) {
						$response_parts[] = array(
							'type'             => 'functionResponse',
							'functionResponse' => array(
								'id'       => $call_id,
								'name'     => $tool_name,
								'response' => $tool_result,
							),
						);
					}
				}

				$conversation[] = array(
					'role'  => 'model',
					'parts' => $model_parts,
				);
				if ( ! empty( $deferred_calls ) ) {
					return $this->build_editor_tool_calls_response(
						$deferred_calls,
						$conversation,
						$response_parts,
						$tool_log,
						$step + 1,
						$use_native,
						$post_id,
						'native',
						$native_error_count
					);
				}
				foreach ( $response_parts as $response_part ) {
					$conversation[] = array(
						'role'  => 'user',
						'parts' => array( $response_part ),
					);
				}

				continue;
			}

			// Text response (native final answer or manual fallback).
			$ai_response = $ai_turn['text'] ?? '';
			$parsed      = $this->parse_response( $ai_response );

			if ( is_wp_error( $parsed ) ) {
				return $parsed;
			}

			$action = $parsed['action'] ?? '';

			if ( 'final' === $action ) {
				$result = $parsed['result'] ?? array();
				if ( ! is_array( $result ) ) {
					$result = array( 'type' => 'message', 'message' => strval( $result ) );
				}

				// Elementor builds must end in a tool call or a result envelope.
				// When the model only narrates the steps it is about to take
				// (e.g. "Fetching the required Elementor resources first, then
				// I'll build one complete hero section composition."), feed the
				// narration back and force it to actually act. The max-steps
				// guard keeps the loop bounded.
				if (
					'elementor' === $this->editor
					&& 'message' === ( $result['type'] ?? '' )
					&& $narration_nudges < self::ELEMENTOR_MAX_NARRATION_NUDGES
					&& $this->is_narration_message( strval( $result['message'] ?? '' ) )
				) {
					$narration_nudges++;
					$conversation[] = array(
						'role'  => 'model',
						'parts' => array(
							array( 'type' => 'text', 'text' => $ai_response ),
						),
					);
					$conversation[] = array(
						'role'  => 'user',
						'parts' => array(
							array(
								'type' => 'text',
								'text' => 'You only described the next step but did not perform it. Continue now and complete the user\'s request: call the required tool(s) or return the final result envelope (e.g. {"action":"tool_call","tool":"...","arguments":{...}} or {"type":"blocks","html":"..."}). Do not narrate what you will do — perform the action now.',
							),
						),
					);
					continue;
				}

				$result['tool_calls'] = $tool_log;
				return $result;
			}

			if ( 'tool_call' === $action ) {
				$tool_name = $parsed['tool'] ?? '';
				$arguments = $parsed['arguments'] ?? array();
				$tool      = $registry->get( $tool_name );

				if ( ! $tool ) {
					return new WP_Error(
						'unknown_tool',
						/* translators: %s: tool name requested by the AI model */
						sprintf( __( 'Unknown tool requested: %s', 'advanced-animation' ), $tool_name )
					);
				}

				if ( $tool instanceof Deferred_Editor_Tool ) {
					$conversation[] = array(
						'role'  => 'model',
						'parts' => array(
							array( 'type' => 'text', 'text' => wp_json_encode( $parsed ) ),
						),
					);
					return $this->build_editor_tool_calls_response(
						array(
							array(
								'id'   => 'manual-' . wp_generate_uuid4(),
								'name' => $tool_name,
								'args' => $arguments,
							),
						),
						$conversation,
						array(),
						$tool_log,
						$step + 1,
						false,
						$post_id,
						'manual',
						$native_error_count
					);
				}

				$tool_context = array(
					'post_id'        => $post_id,
					'selection'      => $selection,
					'page_content'   => $this->page_content,
					'editor'         => $this->editor,
					'block_type_preference' => $this->block_type_preference,
					'request_source' => 'chat',
				);
				$tool_result = $tool->execute( $arguments, $tool_context );

				$tool_log[] = array(
					'tool'      => $tool_name,
					'arguments' => $arguments,
					'result'    => $tool_result,
				);

				$conversation[] = array(
					'role'  => 'model',
					'parts' => array(
						array( 'type' => 'text', 'text' => json_encode( $parsed ) ),
					),
				);
				$conversation[] = array(
					'role'  => 'user',
					'parts' => array(
						array(
							'type' => 'text',
							'text' => json_encode(
								array(
									'tool_result' => $tool_result,
								)
							),
						),
					),
				);

				continue;
			}

			return new WP_Error(
				'invalid_action',
				__( 'AI response did not contain a valid action.', 'advanced-animation' )
			);
		}

		return new WP_Error(
			'max_steps',
			__( 'The AI reached the maximum number of tool steps.', 'advanced-animation' )
		);
	}

	/**
	 * Deterministically handle obvious editor mutations before entering the
	 * agent loop. This lets smaller models generate content without requiring
	 * them to reliably orchestrate tool calls.
	 *
	 * @return array|WP_Error|null Direct tool result, error, or null to use the agent loop.
	 */
	private function maybe_run_direct_editor_action( string $prompt, ?array $selection, ?int $post_id, array $attachments ) {
		if ( ! empty( $attachments ) ) {
			return null;
		}

		$intent = $this->classify_editor_intent( $prompt, $selection );
		if ( null === $intent ) {
			return null;
		}

		if ( empty( $post_id ) && in_array( $intent['action'], array( 'add', 'full_page' ), true ) ) {
			return new WP_Error(
				'no_current_post',
				__( 'No current post ID available for this editor action.', 'advanced-animation' )
			);
		}

		if ( 'replace' === $intent['action'] && empty( $selection ) ) {
			return array(
				'type'    => 'error',
				'message' => __( 'Select a block or element in the editor first, then ask me to replace or update it.', 'advanced-animation' ),
			);
		}

		$tool = $this->tool_for_direct_intent( $intent['action'] );
		if ( ! $tool ) {
			return null;
		}

		$arguments = array(
			'description' => $this->build_direct_description( $prompt, $intent ),
		);

		if ( 'add' === $intent['action'] ) {
			$arguments['position'] = $intent['position'];
			if ( 'gutenberg' === $this->editor ) {
				$arguments['block_type'] = $this->resolve_block_type_for_prompt( $prompt );
			}
		} elseif ( 'replace' === $intent['action'] && 'gutenberg' === $this->editor ) {
			$arguments['block_type'] = $this->resolve_block_type_for_prompt( $prompt );
		}

		$context = array(
			'post_id'        => $post_id,
			'selection'      => $selection,
			'page_content'   => $this->page_content,
			'editor'         => $this->editor,
			'block_type_preference' => $this->block_type_preference,
			'request_source' => 'chat',
		);

		$result = $tool->execute( $arguments, $context );
		$result['tool_calls'] = array(
			array(
				'tool'          => $tool->name(),
				'arguments'     => $arguments,
				'result'        => $result,
				'orchestration' => 'direct',
			),
		);

		if ( empty( $result['message'] ) ) {
			$result['message'] = $this->direct_success_message( $intent['action'] );
		}

		return $result;
	}

	/**
	 * Classify common editor commands that should not depend on model tool calling.
	 */
	private function classify_editor_intent( string $prompt, ?array $selection ): ?array {
		$text = strtolower( trim( wp_strip_all_tags( $prompt ) ) );
		if ( '' === $text ) {
			return null;
		}

		if ( $this->contains_any( $text, array( 'do not insert', "don't insert", 'without inserting', 'preview only', 'just show', 'show me html', 'raw html' ) ) ) {
			return null;
		}

		$mutation_words = array(
			'add', 'insert', 'create', 'generate', 'build', 'make', 'put',
			'replace', 'update', 'change', 'edit', 'modify', 'restyle',
			'redesign', 'rewrite', 'turn', 'convert', 'transform',
		);
		if ( ! $this->contains_any( $text, $mutation_words ) ) {
			return null;
		}

		if ( $this->contains_any( $text, array( 'whole page', 'entire page', 'full page', 'all sections', 'every section', 'all blocks', 'all headings', 'every heading', 'all text', 'every text', 'everything', 'sitewide', 'reorder', 'rearrange', 'swap sections', 'rewrite the page', 'redesign the page' ) ) ) {
			return array(
				'action'   => 'full_page',
				'position' => 'end',
			);
		}

		$replace_words = array( 'replace', 'update', 'change', 'edit', 'modify', 'restyle', 'redesign', 'rewrite', 'turn', 'convert', 'transform', 'make' );
		$selected_refs = array( 'selected', 'selection', 'this', 'that', 'this block', 'this section', 'this element', 'current block', 'current section', 'current element', 'it', 'dark mode', 'light mode' );
		if ( ! empty( $selection ) && $this->contains_any( $text, $replace_words ) && $this->contains_any( $text, $selected_refs ) ) {
			return array(
				'action'   => 'replace',
				'position' => 'end',
			);
		}

		if ( ! empty( $selection ) && $this->contains_any( $text, array( 'dark mode', 'light mode', 'make it dark', 'make it light' ) ) ) {
			return array(
				'action'   => 'replace',
				'position' => 'end',
			);
		}

		$add_words   = array( 'add', 'insert', 'create', 'generate', 'build', 'make', 'put' );
		$add_targets = array( 'section', 'hero', 'banner', 'cta', 'call to action', 'feature', 'features', 'pricing', 'testimonial', 'card', 'cards', 'gallery', 'faq', 'footer', 'header', 'component', 'block' );
		if ( $this->contains_any( $text, $add_words ) && $this->contains_any( $text, $add_targets ) ) {
			return array(
				'action'   => 'add',
				'position' => $this->detect_insert_position( $text ),
			);
		}

		return null;
	}

	private function tool_for_direct_intent( string $action ): ?Tool {
		if ( 'elementor' === $this->editor ) {
			if ( 'add' === $action ) {
				return new Elementor_Add_Html_To_Page_Tool( $this );
			}
			if ( 'replace' === $action ) {
				return new Elementor_Replace_Selection_Tool( $this );
			}
			if ( 'full_page' === $action ) {
				return new Elementor_Edit_Full_Page_Tool( $this );
			}
			return null;
		}

		if ( 'add' === $action ) {
			return new Add_Blocks_To_Page_Tool( $this );
		}
		if ( 'replace' === $action ) {
			return new Replace_Selected_Blocks_Tool( $this );
		}
		if ( 'full_page' === $action ) {
			return new Edit_Full_Page_Tool( $this );
		}

		return null;
	}

	private function detect_insert_position( string $text ): string {
		if ( $this->contains_any( $text, array( 'at the top', 'to the top', 'above everything', 'before everything', 'beginning of the page', 'start of the page' ) ) ) {
			return 'start';
		}

		if ( $this->contains_any( $text, array( 'before selected', 'before this', 'above selected', 'above this' ) ) ) {
			return 'before_selection';
		}

		if ( $this->contains_any( $text, array( 'after selected', 'after this', 'below selected', 'below this', 'under selected', 'under this' ) ) ) {
			return 'after_selection';
		}

		return 'end';
	}

	private function detect_native_block_request( string $prompt ): bool {
		$text = strtolower( $prompt );
		return $this->contains_any(
			$text,
			array(
				'blog posts',
				'latest posts',
				'post list',
				'wordpress native block',
				'wordpress native blocks',
				'native block',
				'native blocks',
				'gutenberg block',
				'gutenberg blocks',
				'core block',
				'core blocks',
				'wordpress block',
				'wordpress blocks',
				'query loop',
				'archive',
				'search form',
				'navigation',
				'menu',
				'post content',
				'dynamic',
			)
		);
	}

	private function normalize_block_type_preference( string $preference ): string {
		$preference = strtolower( trim( $preference ) );
		return in_array( $preference, array( 'auto', 'tailwind', 'native' ), true ) ? $preference : 'auto';
	}

	private function resolve_block_type_for_prompt( string $prompt ): string {
		if ( 'native' === $this->block_type_preference ) {
			return 'native';
		}
		if ( 'tailwind' === $this->block_type_preference ) {
			return 'tailwind';
		}
		return $this->detect_native_block_request( $prompt ) ? 'native' : 'tailwind';
	}

	private function build_direct_description( string $prompt, array $intent ): string {
		$description = trim( $prompt );

		if ( 'replace' === $intent['action'] ) {
			return $description . "\n\nGenerate a complete replacement for the current selection. Preserve the original purpose and content unless the user explicitly asks to change it.";
		}

		if ( 'full_page' === $intent['action'] ) {
			return $description . "\n\nApply this request to the complete current page.";
		}

		return $description;
	}

	private function direct_success_message( string $action ): string {
		if ( 'replace' === $action ) {
			return __( 'Selected content updated.', 'advanced-animation' );
		}

		if ( 'full_page' === $action ) {
			return __( 'Page updated.', 'advanced-animation' );
		}

		return __( 'Content added to the page.', 'advanced-animation' );
	}

	private function contains_any( string $text, array $needles ): bool {
		foreach ( $needles as $needle ) {
			if ( '' !== $needle && false !== strpos( $text, $needle ) ) {
				return true;
			}
		}

		return false;
	}

	/**
	 * Detect a text-only assistant response that describes an upcoming action
	 * instead of performing it, e.g. "Fetching the required Elementor resources
	 * first, then I'll build one complete hero section composition."
	 *
	 * In the Elementor builder a narration is never a usable final answer, so
	 * the agent loop nudges the model to continue. Completed summaries and
	 * clarification questions are left alone.
	 *
	 * @param string $message Text-only assistant response.
	 * @return bool True when the message is an unfinished plan of action.
	 */
	private function is_narration_message( string $message ): bool {
		$text = strtolower( trim( $message ) );
		if ( '' === $text ) {
			return true;
		}
		if ( '?' === substr( $text, -1 ) ) {
			return false;
		}
		// Real answers are long (summaries, explanations, lists); narrations
		// are short promises of the next step. Never nudge long responses.
		if ( strlen( $text ) > 350 ) {
			return false;
		}
		// Completed work reports must never be treated as narration.
		$completed = array(
			'is built and live', 'fully built', 'has been built', 'is now built',
			'built and verified', 'is live on', 'are live on', 'is now live',
			"here's what i", 'here is what i', 'what would you like to build',
			'what would you like next', 'has been added', 'added to the page',
			'inserted into the page', 'updated successfully',
		);
		if ( $this->contains_any( $text, $completed ) ) {
			return false;
		}

		$plans = array(
			'i will', "i'll", "i'm going", 'i am going', 'let me', 'i need to',
			'i have to', 'i want to', 'going to', 'about to', 'one moment',
			'in a moment', 'just a moment', 'give me a moment', 'please wait',
			'hold on', 'one second',
		);
		$actions = array(
			'fetching', 'fetch', 'gathering', 'gather', 'loading', 'load',
			'preparing', 'prepare', 'retrieving', 'retrieve', 'getting',
			'get the required', 'checking', 'check', 'inspecting', 'inspect',
			'pulling', 'pull', 'reading', 'read the', 'looking at',
			'examining', 'examine',
		);
		$sequences = array(
			'first', 'before', 'then', 'next', 'start by', 'begin by',
			'after that', 'so i can', 'in order to', 'and then', 'while i',
			'once i', 'after i',
		);

		$has_plan    = $this->contains_any( $text, $plans );
		$has_action  = $this->contains_any( $text, $actions );
		$has_sequenc = $this->contains_any( $text, $sequences );

		return ( $has_plan && $has_action ) || ( $has_plan && $has_sequenc ) || ( $has_action && $has_sequenc );
	}

	/**
	 * Generate raw Tailwind HTML for a given description.
	 *
	 * @param string     $description Prompt describing the HTML to generate.
	 * @param array|null $selection   Optional selected block context.
	 * @param int|null   $post_id     Current post ID for full-page context.
	 * @return string|WP_Error HTML string or error.
	 */
	public function generate_html( string $description, ?array $selection = null, ?int $post_id = null ) {
		if ( ! $this->is_available() ) {
			return new WP_Error(
				'ai_unavailable',
				__( 'WordPress AI Client is not available on this site.', 'advanced-animation' )
			);
		}
		$auth = $this->assert_can_edit_optional_post( $post_id );
		if ( is_wp_error( $auth ) ) {
			return $auth;
		}

		$contextual = $this->build_contextual_prompt( $description, $selection, $post_id );

		$system = 'You are a web developer building WordPress content. ' .
			'Respond with a complete HTML document or section. ' .
			'Use Tailwind CSS v4 utility classes for ALL styling (layout, typography, colors, spacing, responsive design). ' .
			'Do NOT use <style> tags, <link> stylesheets, or inline style attributes. ' .
			'When you need a custom CSS value, use Tailwind arbitrary value utilities instead of style="" (for example: w-[37px], bg-[#123456], text-[clamp(2rem,6vw,5rem)], [box-shadow:0_20px_60px_rgba(0,0,0,0.18)], bg-[url("...")], [transform:rotate(-2deg)]). ' .
			'Apply Tailwind classes directly to HTML elements. Use modern design. ' .
			'Return ONLY the HTML code. No explanations, no markdown fences.' .
			$this->build_theme_context();

		$messages = array(
			$this->build_user_message( $contextual, array() ),
		);

		$html = $this->generate_text( $system, $messages, false );
		return $this->track_unsplash_in_html( $html );
	}

	/**
	 * Generate native HTML with <style> CSS for Elementor (no Tailwind).
	 *
	 * @param string     $description Prompt describing the HTML to generate.
	 * @param array|null $selection   Optional selected element context.
	 * @param int|null   $post_id     Current post ID for full-page context.
	 * @return string|WP_Error HTML string with embedded <style> or error.
	 */
	public function generate_elementor_html( string $description, ?array $selection = null, ?int $post_id = null ) {
		if ( ! $this->is_available() ) {
			return new WP_Error(
				'ai_unavailable',
				__( 'WordPress AI Client is not available on this site.', 'advanced-animation' )
			);
		}
		$this->editor = 'elementor';
		$auth = $this->assert_can_edit_optional_post( $post_id );
		if ( is_wp_error( $auth ) ) {
			return $auth;
		}

		$contextual = $this->build_contextual_prompt( $description, $selection, $post_id );

		$system = 'You are a web developer building Elementor content. ' .
			'Respond with a complete HTML section or document using native HTML with CSS. ' .
			'When PRELOADED EDITOR RESOURCES include global classes or global variables, use the exact existing global class IDs in class attributes and the exact CSS custom-property names with var(--name); never invent replacement class names or hard-code values that a supplied global token provides. ' .
			'Elementor V4 variable labels are canonical CSS names: label "color-primary" must be written as var(--color-primary). Never use the legacy --e-global-* namespace, even if it appears in older Elementor CSS, and prefer preloaded V4 resources over legacy kit-theme token hints. ' .
				'CRITICAL: Include a single <style> tag at the top of your response containing ALL CSS rules. ' .
				'Put every layout, typography, color, border, spacing, and responsive rule inside that one <style> tag. Do not create or update page-level CSS; the HTML payload is the complete styling input for the converter. ' .
				'The embedded <style> block is converted into native Elementor properties, not raw custom CSS. Direct selectors targeting the styled element with :hover, :focus, :active, or :focus-visible become native Elementor state variants. Do not generate pseudo-elements, & nesting, or complex ancestor/descendant state selectors because they are unsupported and will be dropped. ' .
				'Use semantic class names (like .hero, .card, .btn, .container) and define styles inside the <style> tag. ' .
			'Do NOT use Tailwind CSS classes. Do NOT use any CSS framework. ' .
			'Use modern, clean design with good typography, spacing, and colors. ' .
			'Use responsive widths (max-width, percentages, flexbox, grid). ' .
			'Use semantic HTML elements: div, section, header, footer, nav, h1-h6, p, img, a, button, ul/ol/li, span. ' .
			'Return ONLY the HTML + <style> block. No explanations, no markdown fences.' .
			$this->build_theme_context() .
			$this->build_elementor_variable_policy() .
			$this->build_preloaded_resources_note();

		$messages = array(
			$this->build_user_message( $contextual, array() ),
		);

		$html = $this->generate_text( $system, $messages, false );
		return $this->track_unsplash_in_html( $html );
	}

	/**
	 * Generate native WordPress block markup for a given description.
	 *
	 * Use this for dynamic or native components such as blog post lists,
	 * navigation menus, post content, query loops, archives, etc.
	 *
	 * @param string     $description Prompt describing the native blocks to generate.
	 * @param array|null $selection   Optional selected block context.
	 * @param int|null   $post_id     Current post ID for full-page context.
	 * @return string|WP_Error Serialized block markup string or error.
	 */
	public function generate_native_blocks( string $description, ?array $selection = null, ?int $post_id = null ) {
		if ( ! $this->is_available() ) {
			return new WP_Error(
				'ai_unavailable',
				__( 'WordPress AI Client is not available on this site.', 'advanced-animation' )
			);
		}
		$auth = $this->assert_can_edit_optional_post( $post_id );
		if ( is_wp_error( $auth ) ) {
			return $auth;
		}

		$contextual = $this->build_contextual_prompt( $description, $selection, $post_id );

		$system = 'You are a WordPress developer building Gutenberg content. ' .
			'Respond with serialized WordPress block markup using HTML comments. ' .
			'Use native core blocks such as core/query, core/post-template, core/post-title, core/post-excerpt, core/post-date, core/post-featured-image, ' .
			'core/navigation, core/page-list, core/navigation-link, core/search, core/cover, core/group, core/columns, core/column, core/buttons, core/button, etc. ' .
			'whenever the user asks for dynamic content (blog posts, archives, post content, search forms). ' .
			'Prefer common stable core blocks and simple attributes over experimental or version-specific block features. ' .
			'Do NOT use Tailwind CSS classes; use only native block attributes for layout and styling. ' .
			'Return ONLY the serialized block markup. No explanations, no markdown fences, no HTML wrappers outside the block comments.\n\n' .

			// --- Block serialization grammar ---
			'BLOCK SERIALIZATION RULES:\n' .
			'- Paired blocks: <!-- wp:block-name {"attr":"value"} -->\n' .
			'  <tag class="wp-block-block-name">Content</tag>\n' .
			'  <!-- /wp:block-name -->\n' .
			'- Self-closing blocks (no inner HTML): <!-- wp:block-name {"attr":"value"} /--> (space before /-->)\n' .
			'- Core blocks use core/ namespace but the prefix is OMITTED in delimiter comments: <!-- wp:paragraph --> NOT <!-- wp:core/paragraph -->\n' .
			'- JSON attributes MUST be valid JSON: no trailing commas, double quotes only, no JS comments.\n' .
			'- Omit the JSON object entirely (not even {}) when all attributes are at defaults.\n' .
			'- Opening/closing block names MUST match exactly.\n' .
			'- HTML attribute values MUST match JSON comment attributes for sourced attributes (e.g. image url, src).\n' .
			'- NEVER include any freestanding HTML comment that is not a valid block delimiter. Only <!-- wp:... -->, <!-- /wp:... -->, <!-- wp:... /--> are allowed. ONLY two exceptions: <!--more--> inside wp:more and <!--nextpage--> inside wp:nextpage.\n\n' .

			// --- CRITICAL gotchas that cause block recovery ---
			'CRITICAL GOTCHAS — these cause block recovery if violated:\n' .
			'- NEVER use style.typography.color — it does NOT exist in Gutenberg. Use style.color.text for custom hex text colors.\n' .
			'- NEVER add wp-block-paragraph class to <p> tags. Paragraph save() does NOT output this class.\n' .
			'- For wp:cover: element order is <img> FIRST, then <span> overlay, then <div class="wp-block-cover__inner-container">. Do NOT reverse this.\n' .
			'- Buttons: always include has-custom-font-size class on <a> when ANY fontSize is set. Always include has-border-color when any border color is set. Order CSS on <a> as: border → color → spacing → typography.\n' .
			'- wp:details: do NOT add style="color:..." to <summary> — WordPress strips it. Use style.color.text hex on the <details> wrapper instead.\n' .
			'- heading level must be integer (2), not string ("2"). Default level is 2.\n' .
			'- wp:image: <figure class="wp-block-image"> is required wrapper. <img> must have wp-image-{id} class when id set. url in JSON must match src.\n' .
			'- wp:list-item MUST be inside wp:list. wp:column MUST be inside wp:columns. wp:button MUST be inside wp:buttons.\n' .
			'- separator always needs has-alpha-channel-opacity class.\n' .
			'- wp:list-item renders <li> with content inline — do NOT wrap content in <p>.\n\n' .

			// --- Color and style patterns ---
			'COLOR & STYLE PATTERNS:\n' .
			'- Named text color: "textColor":"white" → <p class="has-white-color has-text-color">\n' .
			'- Custom hex text: "style":{"color":{"text":"#fff"}} → <p class="has-text-color" style="color:#fff">\n' .
			'- Named background: "backgroundColor":"pale-pink" → has-pale-pink-background-color has-background\n' .
			'- Custom hex background: "style":{"color":{"background":"#000"}} → has-background style="background-color:#000"\n' .
			'- Font size preset: "fontSize":"large" → has-large-font-size class\n' .
			'- Custom font size: "style":{"typography":{"fontSize":"22px"}} → style="font-size:22px"\n' .
			'- Text alignment: "style":{"typography":{"textAlign":"center"}} → has-text-align-center class (NOT top-level align attribute for text)\n' .
			'- Block alignment (wide/full): "align":"wide" → alignwide class on outer element\n' .
			'- Padding: "style":{"spacing":{"padding":{"top":"2em","bottom":"2em","left":"2em","right":"2em"}}} → style="padding-top:2em;..."\n\n' .

			// --- Block-specific patterns ---
			'BLOCK REFERENCE:\n' .
			'paragraph: default uses no attrs. <p> gets has-text-align-* for alignment, has-drop-cap for dropCap. Supports <strong>, <em>, <a>, <code>, <mark> inline.\n' .
			'heading: <h2> default (level 2). Class is wp-block-heading. Level must match tag.\n' .
			'image: <figure class="wp-block-image size-{slug}"> wrapping <img class="wp-image-{id}">. Optional <figcaption class="wp-element-caption">. sizeSlug adds size-{slug} to figure. is-resized when width/height set.\n' .
			'gallery: <figure class="wp-block-gallery has-nested-images columns-{n} is-cropped"> containing wp:image inner blocks.\n' .
			'group: <div class="wp-block-group"> with layout.type "constrained", "flex", or "default". Include layout in JSON. For flex row: {"layout":{"type":"flex","flexWrap":"nowrap"}}. Stack: add "orientation":"vertical".\n' .
			'columns: <div class="wp-block-columns"> only accepts wp:column children. Column width: {"width":"33.33%"} → style="flex-basis:33.33%".\n' .
			'cover: <div class="wp-block-cover"><img class="wp-block-cover__image-background wp-image-{id}" src="..." data-object-fit="cover"/><span aria-hidden="true" class="wp-block-cover__background has-{slug}-background-color has-background-dim-{n} has-background-dim"></span><div class="wp-block-cover__inner-container">...blocks...</div></div>. dimRatio maps to has-background-dim-{value} AND has-background-dim (both required). isDark=false adds is-light class.\n' .
			'buttons: <div class="wp-block-buttons"> wrapping wp:button children.\n' .
			'button: <div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="...">Label</a></div>. Fill style is default. Outline: add className "is-style-outline" to get <div class="wp-block-button is-style-outline">.\n' .
			'list: <ul class="wp-block-list"> or <ol>. ordered:true → <ol>. Contains wp:list-item children.\n' .
			'list-item: <li> with content inline (not in <p>). Nested lists go as inner blocks inside the parent list-item.\n' .
			'quote: <blockquote class="wp-block-quote"> with inner blocks (paragraphs). <cite> for citation inside blockquote after inner blocks.\n' .
			'pullquote: <figure class="wp-block-pullquote"><blockquote><p>text</p><cite>author</cite></blockquote></figure>. Uses value/citation attrs directly, NOT inner blocks.\n' .
			'separator: <hr class="wp-block-separator has-alpha-channel-opacity"/>. Uses paired block syntax. Styles: is-style-wide, is-style-dots.\n' .
			'details: <details class="wp-block-details"><summary>label</summary>...inner blocks...</details>. showContent:true adds open attribute.\n' .
			'table: <figure class="wp-block-table"><table class="has-fixed-layout"><thead><tr><th>...</th></tr></thead><tbody><tr><td>...</td></tr></tbody></table><figcaption class="wp-element-caption">caption</figcaption></figure>.\n' .
			'spacer: <div style="height:100px" aria-hidden="true" class="wp-block-spacer"></div>. Paired block syntax.\n' .
			'media-text: <div class="wp-block-media-text is-stacked-on-mobile"><figure class="wp-block-media-text__media"><img .../></figure><div class="wp-block-media-text__content">...blocks...</div></div>. mediaPosition:right adds has-media-on-the-right and swaps order.\n' .
			'embed: <figure class="wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube"><div class="wp-block-embed__wrapper">\nURL\n</div></figure>. URL on its own line.\n' .
			'shortcode: [shortcode text] directly between delimiters. No wrapper.\n' .
			'pattern: self-closing <!-- wp:pattern {"slug":"theme/name"} /-->.\n' .
			'template-part: self-closing <!-- wp:template-part {"slug":"header","theme":"my-theme"} /-->.\n\n' .

			// --- Query loop patterns ---
			'QUERY LOOP PATTERNS:\n' .
			'<!-- wp:query {"query":{"postType":"post","perPage":6,"order":"desc","orderBy":"date"},"displayLayout":{"type":"flex","columns":3},"layout":{"type":"constrained"}} -->\n' .
			'<div class="wp-block-query">\n' .
			'<!-- wp:post-template -->\n' .
			'<!-- wp:post-featured-image {"isLink":true} /-->\n' .
			'<!-- wp:post-title {"isLink":true,"level":3} /-->\n' .
			'<!-- wp:post-excerpt /-->\n' .
			'<!-- wp:post-date /-->\n' .
			'<!-- /wp:post-template -->\n' .
			'<!-- wp:query-pagination -->\n' .
			'<!-- wp:query-pagination-previous /-->\n' .
			'<!-- wp:query-pagination-numbers /-->\n' .
			'<!-- wp:query-pagination-next /-->\n' .
			'<!-- /wp:query-pagination -->\n' .
			'<!-- wp:query-no-results -->\n' .
			'<!-- wp:paragraph -->\n<p>No posts found.</p>\n<!-- /wp:paragraph -->\n' .
			'<!-- /wp:query-no-results -->\n' .
			'</div>\n' .
			'<!-- /wp:query -->\n\n' .

			// --- Navigation ---
			'Site navigation:\n' .
			'<!-- wp:navigation -->\n' .
			'<!-- wp:page-list /-->\n' .
			'<!-- /wp:navigation -->\n\n' .

			'WHAT CAUSES BLOCK RECOVERY (avoid these):\n' .
			'- Mismatched open/close block names\n' .
			'- Invalid JSON (trailing commas, single quotes, unquoted keys)\n' .
			'- Missing required HTML structure (e.g. <figure> for image)\n' .
			'- Wrong attribute types (string "2" instead of integer 2 for heading level)\n' .
			'- Attribute/HTML mismatch (JSON url differs from <img src>)\n' .
			'- Wrong nesting (column outside columns, button outside buttons)\n' .
			'- Missing required CSS classes (has-custom-font-size on buttons, has-alpha-channel-opacity on separator, has-custom-css when style.css is set)\n' .
			'- style.typography.color instead of style.color.text\n' .
			'- Adding wp-block-paragraph class to <p>\n' .
			'- Freestanding HTML comments that are not block delimiters\n' .
			'- Incorrect CSS property order on button <a> elements (must be border → color → spacing → typography)';

		$messages = array(
			$this->build_user_message( $contextual, array() ),
		);

		return $this->generate_text( $system, $messages, false );
	}

	/**
	 * Edit the full page by sending the current page HTML and a description of
	 * edits to the AI, which returns the complete edited page HTML.
	 *
	 * Use this only when changes span multiple locations on the page.
	 *
	 * @param string     $description Description of all edits to apply.
	 * @param array|null $selection   Optional selected block context.
	 * @param int|null   $post_id     Current post ID.
	 * @return string|WP_Error Edited page HTML or error.
	 */
	public function edit_full_page( string $description, ?array $selection = null, ?int $post_id = null ) {
		if ( ! $this->is_available() ) {
			return new WP_Error(
				'ai_unavailable',
				__( 'WordPress AI Client is not available on this site.', 'advanced-animation' )
			);
		}
		$auth = $this->assert_can_edit_optional_post( $post_id );
		if ( is_wp_error( $auth ) ) {
			return $auth;
		}

		$page_html = $this->get_page_html( $post_id );
		if ( is_wp_error( $page_html ) ) {
			return $page_html;
		}
		// Empty page: treat full-page edit as create-from-scratch.
		if ( '' === trim( $page_html ) ) {
			return $this->generate_html( $description, $selection, $post_id );
		}

		$selection_note = '';
		if ( $selection && ! empty( $selection['html'] ) ) {
			$selection_note = "\n\nThe user currently has this block selected (it may be one of the areas they want to edit):\n" .
				$selection['html'];
		}

		$prompt = "Here is the current full page HTML:\n\n" .
			$page_html . "\n\n" .
			"Apply the following edits and return the COMPLETE edited page HTML " .
			"(every section, including unchanged ones — do not omit or summarize any part of the page):\n\n" .
			$description .
			$selection_note;

		$system = 'You are a web developer editing an existing WordPress page. ' .
			'You receive the current page HTML and a description of edits to apply. ' .
			'CRITICAL: You must return the COMPLETE edited page HTML containing EVERY section from the original page. ' .
			'Copy unchanged sections verbatim — do not omit, summarize, or abbreviate any part of the page. ' .
			'Only modify the sections that the edits describe. ' .
			'If the original page has a header, hero, features, testimonials, pricing, and footer, your response must contain ALL of them in order. ' .
			'Use Tailwind CSS v4 utility classes for ALL styling (layout, typography, colors, spacing, responsive design). ' .
			'Do NOT use <style> tags, <link> stylesheets, or inline style attributes. ' .
			'When you need a custom CSS value, use Tailwind arbitrary value utilities instead of style="" (for example: w-[37px], bg-[#123456], text-[clamp(2rem,6vw,5rem)], [box-shadow:0_20px_60px_rgba(0,0,0,0.18)], bg-[url("...")], [transform:rotate(-2deg)]). ' .
			'Apply Tailwind classes directly to HTML elements. Use modern design. ' .
			'Return ONLY the HTML code starting with your first HTML element. No explanations, no markdown fences, no text before or after the HTML.' .
			$this->build_theme_context();

		$messages = array(
			$this->build_user_message( $prompt, array() ),
		);

		$html = $this->generate_text( $system, $messages, false );
		return $this->track_unsplash_in_html( $html );
	}

	/**
	 * Edit the full Elementor page by sending the current page HTML and a
	 * description of edits to the AI, which returns the complete edited
	 * page HTML with native CSS (no Tailwind).
	 *
	 * @param string     $description Description of all edits to apply.
	 * @param array|null $selection   Optional selected element context.
	 * @param int|null   $post_id     Current post ID.
	 * @return string|WP_Error Edited page HTML or error.
	 */
	public function edit_elementor_full_page( string $description, ?array $selection = null, ?int $post_id = null ) {
		if ( ! $this->is_available() ) {
			return new WP_Error(
				'ai_unavailable',
				__( 'WordPress AI Client is not available on this site.', 'advanced-animation' )
			);
		}
		$this->editor = 'elementor';
		$auth = $this->assert_can_edit_optional_post( $post_id );
		if ( is_wp_error( $auth ) ) {
			return $auth;
		}

		$page_html = $this->get_page_html( $post_id );
		if ( is_wp_error( $page_html ) ) {
			return $page_html;
		}
		// Empty Elementor document: treat full-page edit as create-from-scratch
		// so "build a hero on a blank page" still succeeds.
		if ( '' === trim( $page_html ) ) {
			return $this->generate_elementor_html( $description, $selection, $post_id );
		}

		$selection_note = '';
		if ( $selection && ! empty( $selection['html'] ) ) {
			$selection_note = "\n\nThe user currently has this element selected (it may be one of the areas they want to edit):\n" .
				$selection['html'];
		}

		$prompt = "Here is the current full page content:\n\n" .
			$page_html . "\n\n" .
			"Apply the following edits and return the COMPLETE edited page HTML " .
			"(every section, including unchanged ones — do not omit or summarize any part of the page):\n\n" .
			$description .
			$selection_note;

		$system = 'You are a web developer editing an existing Elementor page. ' .
			'You receive the current page content and a description of edits to apply. ' .
			'When PRELOADED EDITOR RESOURCES include global classes or global variables, preserve the exact existing global class IDs and CSS custom-property references with var(--name); never replace supplied tokens with invented classes or hard-coded values. ' .
			'Elementor V4 variable labels are canonical CSS names: label "color-primary" must be written as var(--color-primary). Never use the legacy --e-global-* namespace, even if it appears in older Elementor CSS, and prefer preloaded V4 resources over legacy kit-theme token hints. ' .
			'CRITICAL: You must return the COMPLETE edited page HTML containing EVERY section from the original page. ' .
			'Copy unchanged sections verbatim — do not omit, summarize, or abbreviate any part of the page. ' .
			'Only modify the sections that the edits describe. ' .
				'Include a single <style> tag at the top with ALL CSS. ' .
				'Put every layout, typography, color, border, spacing, and responsive rule inside that one <style> tag. Do not create or update page-level CSS; the HTML payload is the complete styling input for the converter. ' .
				'The embedded <style> block is converted into native Elementor properties, not raw custom CSS. Direct selectors targeting the styled element with :hover, :focus, :active, or :focus-visible become native Elementor state variants. Do not generate pseudo-elements, & nesting, or complex ancestor/descendant state selectors because they are unsupported and will be dropped. ' .
				'Use native HTML with semantic class names (NO Tailwind CSS). ' .
			'Return ONLY the HTML + <style> block. No explanations, no markdown fences.' .
			$this->build_theme_context() .
			$this->build_elementor_variable_policy() .
			$this->build_preloaded_resources_note();

		$messages = array(
			$this->build_user_message( $prompt, array() ),
		);

		$html = $this->generate_text( $system, $messages, false );
		return $this->track_unsplash_in_html( $html );
	}

	/**
	 * Whether live/saved page content has nothing meaningful to edit.
	 *
	 * Elementor empty documents are exported as "[]".
	 *
	 * @param string|null $raw_content Raw page content.
	 * @return bool
	 */
	private function is_empty_page_content( ?string $raw_content ): bool {
		if ( null === $raw_content ) {
			return true;
		}

		$trimmed = trim( $raw_content );
		if ( '' === $trimmed || '[]' === $trimmed || '{}' === $trimmed ) {
			return true;
		}

		// Elementor live export: JSON array of element models.
		if ( 'elementor' === $this->editor && str_starts_with( $trimmed, '[' ) ) {
			$decoded = json_decode( $trimmed, true );
			return is_array( $decoded ) && 0 === count( $decoded );
		}

		return false;
	}

	/**
	 * Get the current page rendered as HTML (Tailwind blocks as raw HTML,
	 * native blocks rendered via render_block).
	 *
	 * For Elementor, the live editor snapshot is a JSON export of models —
	 * return that snapshot directly when non-empty.
	 *
	 * @param int|null $post_id Current post ID.
	 * @return string|WP_Error Page HTML string, empty string, or error.
	 */
	private function get_page_html( ?int $post_id ) {
		$raw_content = $this->resolve_page_content( $post_id );

		if ( null === $raw_content ) {
			return new WP_Error(
				'no_post',
				__( 'No current post ID available and no live page content provided.', 'advanced-animation' )
			);
		}

		if ( $this->is_empty_page_content( $raw_content ) ) {
			return '';
		}

		// Elementor editor sends a live JSON snapshot of the document tree.
		if ( 'elementor' === $this->editor ) {
			return trim( $raw_content );
		}

		$blocks = parse_blocks( $raw_content );
		$blocks = array_values(
			array_filter(
				$blocks,
				function ( $b ) {
					return ! empty( $b['blockName'] );
				}
			)
		);

		if ( empty( $blocks ) ) {
			return '';
		}

		// parse_blocks() returns blocks with 'blockName'/'attrs' keys, but
		// BlocksToHtml::convert_blocks() expects 'name'/'attributes'. Remap.
		$blocks = $this->normalize_parsed_blocks( $blocks );

		return BlocksToHtml::convert_blocks( $blocks );
	}

	/**
	 * Public page-content accessor used by the get_page_content tool.
	 *
	 * Returns the live editor snapshot (preferred) or the saved post content,
	 * rendered through the same BlocksToHtml pipeline as edit_full_page.
	 *
	 * @param int|null $post_id      Current post ID.
	 * @param string|null $live_content Optional serialized editor content from the live editor state.
	 * @return array|WP_Error
	 */
	public function get_page_content( ?int $post_id, ?string $live_content = null ) {
		$auth = $this->assert_can_edit_optional_post( $post_id );
		if ( is_wp_error( $auth ) ) {
			return $auth;
		}

		if ( null !== $live_content ) {
			$raw_content = $live_content;
		} else {
			$raw_content = $this->resolve_page_content( $post_id );

			if ( null === $raw_content ) {
				return new WP_Error(
					'no_post',
					__( 'No current post ID available and no live page content provided.', 'advanced-animation' )
				);
			}
		}

		if ( '' === trim( $raw_content ) ) {
			return array(
				'content'         => '',
				'total_blocks'    => 0,
				'returned_blocks' => 0,
			);
		}

		$raw_blocks = parse_blocks( $raw_content );
		$filtered   = array();
		foreach ( $raw_blocks as $idx => $block ) {
			if ( ! empty( $block['blockName'] ) ) {
				$filtered[] = array(
					'block'        => $block,
					'raw_index'    => $idx,
					'render_index' => count( $filtered ),
				);
			}
		}

		if ( empty( $filtered ) ) {
			return array(
				'content'         => '',
				'total_blocks'    => 0,
				'returned_blocks' => 0,
			);
		}

		$blocks = $this->normalize_parsed_blocks( array_column( $filtered, 'block' ) );

		// Add render_index and raw_index to each normalized block so tools can
		// map the rendered view back to the exact parse_blocks() position.
		foreach ( $blocks as $i => &$block ) {
			$block['render_index'] = $filtered[ $i ]['render_index'];
			$block['raw_index']    = $filtered[ $i ]['raw_index'];
		}
		unset( $block );

		return array(
			'content'         => BlocksToHtml::convert_blocks( $blocks ),
			'total_blocks'    => count( $blocks ),
			'returned_blocks' => count( $blocks ),
		);
	}

	/**
	 * Convert blocks from the WordPress parser format (blockName/attrs) to
	 * the format BlocksToHtml expects (name/attributes), recursively.
	 *
	 * @param array $blocks Blocks from parse_blocks().
	 * @return array Blocks in the {name, attributes, innerBlocks} format.
	 */
	private function normalize_parsed_blocks( array $blocks ): array {
		return array_map(
			function ( $block ) {
				return array(
					'name'        => $block['blockName'] ?? '',
					'attributes'  => $block['attrs'] ?? array(),
					'innerBlocks' => isset( $block['innerBlocks'] )
						? $this->normalize_parsed_blocks( $block['innerBlocks'] )
						: array(),
					'innerHTML'   => $block['innerHTML'] ?? '',
				);
			},
			$blocks
		);
	}

	/**
	 * Resolve the page content to use, preferring live editor content sent
	 * from the client over the database post_content.
	 *
	 * Returns null when no source is available, or an empty/string content.
	 *
	 * @param int|null $post_id Current post ID (used as DB fallback).
	 * @return string|null
	 */
	private function resolve_page_content( ?int $post_id ): ?string {
		if ( ! empty( $this->page_content ) ) {
			return $this->page_content;
		}

		if ( ! $post_id ) {
			return null;
		}

		$post = get_post( $post_id );
		if ( ! $post ) {
			return null;
		}

		return $post->post_content ?: '';
	}

	/**
	 * Get schemas for all registered tools.
	 */
	public function get_tool_schemas(): array {
		$registry = $this->build_tool_registry();
		return $registry->get_schemas();
	}

	/**
	 * Build the registry of available tools.
	 */
	private function build_tool_registry(): Tool_Registry {
		Tool_Registry::clear();
		$registry = new Tool_Registry();

		if ( 'elementor' === $this->editor && $this->allow_elementor_html_fallback ) {
			$registry->register( new Elementor_Generate_Html_Tool( $this ) );
		} elseif ( 'elementor' !== $this->editor ) {
			$registry->register( new Generate_Blocks_Tool( $this ) );
		}

		$default_whitelist = array(
			'/wp/v2/posts',
			'/wp/v2/pages',
			'/wp/v2/media',
			'/wp/v2/users/me',
			'/wp/v2/categories',
			'/wp/v2/tags',
			'/wp/v2/search',
			'/wp/v2/types',
			'/wp/v2/blocks',
		);

		$allowed_routes = apply_filters( 'advanced_addons_rest_api_tool_whitelist', $default_whitelist );
		$registry->register( new Call_WordPress_Rest_Api_Tool( $allowed_routes ) );

		$registry->register( new Search_Unsplash_Image_Tool() );

		if ( 'elementor' === $this->editor && $this->allow_elementor_html_fallback ) {
			$registry->register( new Elementor_Add_Html_To_Page_Tool( $this ) );
			$registry->register( new Elementor_Replace_Selection_Tool( $this ) );
			$registry->register( new Elementor_Edit_Full_Page_Tool( $this ) );
		} elseif ( 'elementor' !== $this->editor ) {
			$registry->register( new Add_Blocks_To_Page_Tool( $this ) );
			$registry->register( new Replace_Selected_Blocks_Tool( $this ) );
			$registry->register( new Edit_Full_Page_Tool( $this ) );
		}
		$registry->register( new Get_Page_Content_Tool( $this ) );

		if ( 'elementor' === $this->editor ) {
			foreach ( $this->editor_tools as $editor_tool ) {
				$registry->register(
					new Deferred_Editor_Tool(
						$editor_tool['name'],
						$editor_tool['description'],
						$editor_tool['inputSchema']
					)
				);
			}
		}

		apply_filters( 'advanced_addons_register_tools', $registry );

		return $registry;
	}

	/** Return true when a browser-owned native tool failed in this continuation. */
	private function editor_tool_results_have_errors( array $results ): bool {
		foreach ( $results as $result ) {
			if ( is_array( $result ) && ! empty( $result['is_error'] ) ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Track consecutive native tool failure rounds across a continuation.
	 *
	 * A failing round increments the restored counter; a clean round resets it
	 * so the HTML converter fallback only engages after consecutive failures.
	 *
	 * @param array|null $continuation_state Restored continuation state or null.
	 * @param array      $results            Browser-owned tool results for this round.
	 * @return int Consecutive native error round count.
	 */
	private function next_native_error_count( ?array $continuation_state, array $results ): int {
		$previous = $continuation_state
			? max( 0, intval( $continuation_state['native_error_count'] ?? 0 ) )
			: 0;
		if ( $this->editor_tool_results_have_errors( $results ) ) {
			return $previous + 1;
		}
		return 0;
	}

	/**
	 * Validate the JSON-only catalog supplied by the open Elementor editor.
	 * Native handlers never cross the HTTP boundary.
	 */
	private function sanitize_editor_tools( array $tools ): array {
		if ( count( $tools ) > self::ELEMENTOR_MAX_TOOL_COUNT ) {
			$tools = array_slice( $tools, 0, self::ELEMENTOR_MAX_TOOL_COUNT );
		}
		$sanitized = array();
		$total_size = 0;
		foreach ( $tools as $tool ) {
			if ( ! is_array( $tool ) ) {
				continue;
			}
			$name = sanitize_key( strval( $tool['name'] ?? '' ) );
			if ( ! $name || strlen( $name ) > 128 || ! preg_match( '/^[a-z0-9_-]+$/', $name ) ) {
				continue;
			}
			// Provider and Codex turns must leave persistence to Elementor's UI.
			if ( preg_match( '/(^|[-_])(save|publish)([-_]|$)/i', $name ) ) {
				continue;
			}
			$description = sanitize_textarea_field( strval( $tool['description'] ?? '' ) );
			$description = substr( $description, 0, self::ELEMENTOR_MAX_TOOL_DESCRIPTION_LENGTH );
			$schema      = is_array( $tool['inputSchema'] ?? null )
				? $tool['inputSchema']
				: array( 'type' => 'object', 'properties' => array() );
			$schema      = $this->normalize_editor_json_schema( $schema );
			$schema_json = wp_json_encode( $schema );
			if ( false === $schema_json || strlen( $schema_json ) > self::ELEMENTOR_MAX_TOOL_SCHEMA_BYTES ) {
				continue;
			}
			$total_size += strlen( $name ) + strlen( $description ) + strlen( $schema_json );
			if ( $total_size > self::ELEMENTOR_MAX_TOOL_CATALOG_BYTES ) {
				break;
			}
			$sanitized[ $name ] = array(
				'name'        => $name,
				'description' => $description,
				'inputSchema' => $schema,
			);
		}
		return array_values( $sanitized );
	}

	/**
	 * Validate the preloaded Elementor resources supplied by the browser.
	 *
	 * Each resource carries an elementor:// URI and its fetched text content.
	 * Individual and total sizes are capped so a misbehaving resource cannot
	 * blow up the system prompt.
	 *
	 * @param array $resources Raw {uri,content} list from the editor.
	 * @return array<int,array{uri:string,content:string}>
	 */
	private function sanitize_editor_resources( array $resources ): array {
		$sanitized = array();
		$total     = 0;
		foreach ( $resources as $resource ) {
			if ( ! is_array( $resource ) ) {
				continue;
			}
			$uri = trim( strval( $resource['uri'] ?? '' ) );
			if ( ! $uri || ! preg_match( '/^elementor:\/\/[A-Za-z0-9\/\-_.?&=:%]+$/', $uri ) ) {
				continue;
			}
			$content = strval( $resource['content'] ?? '' );
			if ( '' === $content ) {
				continue;
			}
			if ( strlen( $content ) > self::ELEMENTOR_MAX_RESOURCE_BYTES ) {
				// Never send a partial resource to the model. In particular, a
				// truncated JSON design-system payload would look valid enough to
				// hide the records that occur after the cut-off.
				continue;
			}
			$remaining = self::ELEMENTOR_MAX_RESOURCES_TOTAL_BYTES - $total;
			if ( $remaining <= 0 ) {
				continue;
			}
			if ( strlen( $content ) > $remaining ) {
				// Leave this resource out rather than sending a truncated resource.
				continue;
			}
			$total      += strlen( $content );
			$sanitized[] = array(
				'uri'     => $uri,
				'content' => $content,
			);
		}
		return $sanitized;
	}

	/**
	 * Build the Elementor CSS-variable policy shared by native and HTML-fallback
	 * prompts. Page-level custom CSS is intentionally not a design-system input.
	 *
	 * @return string
	 */
	private function build_elementor_variable_policy(): string {
		return "\n\nELEMENTOR DESIGN-SYSTEM VARIABLE RULES:\n" .
			'Only use CSS custom-property references (`var(--name)`) when the exact name is present in the preloaded elementor://global-variables resource. ' .
			'Never copy or infer variables from page-level custom CSS, selection CSS, or other page content, and never invent custom-property names or namespaces such as `--mv-paper`. ' .
			'Elementor V4 labels are canonical CSS names: use each label as `var(--<label>)` (for example, label "color-primary" becomes var(--color-primary)); never use the legacy --e-global-* namespace, even if it appears in older Elementor CSS. ' .
			'When asked to list available design-system tokens, enumerate every record in elementor://global-variables; page content only shows tokens referenced by elements and is not the complete design-system inventory. ' .
			'If a needed resource is missing, use editor-resource-getter when available; never infer tokens from page CSS, computed styles, or legacy names. ' .
			'When no matching design-system variable is available, use a literal CSS value instead of an unknown var() reference or fallback token.';
	}

	/**
	 * Build the "preloaded editor resources" section for the Elementor system
	 * prompts. The browser fetches the catalog-referenced resource bundle before
	 * the task starts; both the native composition flow and the HTML converter
	 * must use it directly instead of inventing editor data.
	 *
	 * @return string Empty when no resources were preloaded.
	 */
	private function build_preloaded_resources_note(): string {
		if ( empty( $this->editor_resources ) || 'elementor' !== $this->editor ) {
			return '';
		}
		$lines = array();
		foreach ( $this->editor_resources as $resource ) {
			$lines[] = $resource['uri'] . ":\n" . $resource['content'];
		}
		return "\n\nAVAILABLE PRELOADED EDITOR RESOURCES (successfully loaded — reuse these design tokens, available V4 widgets, and widget schemas in your output; do NOT invent colors, fonts, classes, widget tags, or prop values). If a required resource URI is not listed, use editor-resource-getter when available. Elementor V4 variable labels are canonical CSS custom-property names: label \"color-primary\" means var(--color-primary). Never use the legacy --e-global-* namespace, even if it appears in older Elementor CSS. These preloaded V4 resources take precedence over legacy kit-theme token hints:\n" .
			implode( "\n---\n", $lines );
	}

	/**
	 * Restore JSON object semantics lost when WordPress decodes JSON as arrays.
	 *
	 * Empty schema maps such as `properties: {}` otherwise become
	 * `properties: []`, which function-calling providers reject.
	 */
	private function normalize_editor_json_schema( array $schema ): array {
		unset( $schema['$schema'], $schema['$id'], $schema['$comment'] );
		$map_keywords = array( 'properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas' );
		$schema_keywords = array( 'additionalProperties', 'unevaluatedProperties', 'propertyNames', 'contains', 'not', 'if', 'then', 'else' );
		$list_keywords = array( 'allOf', 'anyOf', 'oneOf', 'prefixItems' );

		foreach ( $schema as $keyword => $value ) {
			if ( in_array( $keyword, $map_keywords, true ) && is_array( $value ) ) {
				if ( empty( $value ) ) {
					$schema[ $keyword ] = (object) array();
					continue;
				}
				$normalized = array();
				foreach ( $value as $name => $child_schema ) {
					$normalized[ $name ] = is_array( $child_schema )
						? ( empty( $child_schema ) ? (object) array() : $this->normalize_editor_json_schema( $child_schema ) )
						: $child_schema;
				}
				$schema[ $keyword ] = $normalized;
				continue;
			}

			if ( in_array( $keyword, $schema_keywords, true ) && is_array( $value ) ) {
				$schema[ $keyword ] = empty( $value )
					? (object) array()
					: $this->normalize_editor_json_schema( $value );
				continue;
			}

			if ( in_array( $keyword, $list_keywords, true ) && is_array( $value ) ) {
				$schema[ $keyword ] = array_map(
					function ( $child_schema ) {
						if ( ! is_array( $child_schema ) ) {
							return $child_schema;
						}
						return empty( $child_schema )
							? (object) array()
							: $this->normalize_editor_json_schema( $child_schema );
					},
					$value
				);
			}
		}

		if ( empty( $schema ) ) {
			return array(
				'type'       => 'object',
				'properties' => (object) array(),
			);
		}

		return 'google' === $this->provider
			? $this->normalize_google_function_schema( $schema )
			: $schema;
	}

	/**
	 * Reduce JSON Schema to the subset accepted by Gemini function declarations.
	 */
	private function normalize_google_function_schema( array $schema ): array {
		if ( array_key_exists( 'const', $schema ) && ! isset( $schema['enum'] ) ) {
			$schema['enum'] = array( $schema['const'] );
		}

		if ( isset( $schema['oneOf'] ) && ! isset( $schema['anyOf'] ) ) {
			$schema['anyOf'] = $schema['oneOf'];
		}

		if ( isset( $schema['type'] ) && is_array( $schema['type'] ) ) {
			$nullable_types = array_values( array_filter( $schema['type'], static function ( $type ) {
				return 'null' !== $type;
			} ) );
			if ( count( $nullable_types ) < count( $schema['type'] ) ) {
				$schema['nullable'] = true;
			}
			if ( 1 === count( $nullable_types ) ) {
				$schema['type'] = $nullable_types[0];
			} elseif ( count( $nullable_types ) > 1 ) {
				unset( $schema['type'] );
				$schema['anyOf'] = array_map( static function ( $type ) {
					return array( 'type' => $type );
				}, $nullable_types );
			} else {
				$schema['type'] = 'string';
			}
		}

		if ( isset( $schema['properties'] ) && is_array( $schema['properties'] ) ) {
			foreach ( $schema['properties'] as $name => $child_schema ) {
				if ( is_array( $child_schema ) ) {
					$schema['properties'][ $name ] = $this->normalize_google_function_schema( $child_schema );
				}
			}
			if ( ! isset( $schema['type'] ) ) {
				$schema['type'] = 'object';
			}
		}

		if ( isset( $schema['items'] ) && is_array( $schema['items'] ) ) {
			if ( array_values( $schema['items'] ) === $schema['items'] ) {
				$schema['items'] = isset( $schema['items'][0] ) && is_array( $schema['items'][0] )
					? $this->normalize_google_function_schema( $schema['items'][0] )
					: array( 'type' => 'string' );
			} else {
				$schema['items'] = $this->normalize_google_function_schema( $schema['items'] );
			}
		}

		if ( isset( $schema['anyOf'] ) && is_array( $schema['anyOf'] ) ) {
			$schema['anyOf'] = array_values(
				array_map(
					function ( $child_schema ) {
						return is_array( $child_schema )
							? $this->normalize_google_function_schema( $child_schema )
							: array( 'type' => 'string' );
					},
					$schema['anyOf']
				)
			);
		}

		$allowed = array(
			'anyOf', 'description', 'enum', 'format', 'items', 'maxItems',
			'maxLength', 'maxProperties', 'maximum', 'minItems', 'minLength',
			'minProperties', 'minimum', 'nullable', 'pattern', 'properties',
			'propertyOrdering', 'required', 'title', 'type',
		);
		foreach ( array_keys( $schema ) as $keyword ) {
			if ( ! in_array( $keyword, $allowed, true ) ) {
				unset( $schema[ $keyword ] );
			}
		}

		return $schema;
	}

	/** Build the browser execution response and retry-safe continuation state. */
	private function build_editor_tool_calls_response( array $calls, array $conversation, array $response_parts, array $tool_log, int $step, bool $use_native, ?int $post_id, string $mode, int $native_error_count = 0 ) {
		if ( $step >= self::ELEMENTOR_MAX_TOOL_STEPS ) {
			return new WP_Error(
				'max_steps',
				__( 'The AI reached the maximum number of Elementor tool steps before completing the request.', 'advanced-animation' )
			);
		}
		$public_calls = array();
		$call_ids     = array();
		foreach ( $calls as $call ) {
			$name = sanitize_key( strval( $call['name'] ?? '' ) );
			$args = is_array( $call['args'] ?? null ) ? $call['args'] : array();
			$id   = sanitize_text_field( strval( $call['id'] ?? '' ) );
			if ( '' === $id || isset( $call_ids[ $id ] ) ) {
				$id = wp_generate_uuid4();
			}
			$call_ids[ $id ] = true;
			$public_calls[] = array(
				'id'        => $id,
				'name'      => $name,
				'arguments' => $args,
			);
		}
		$token        = wp_generate_uuid4();
		$continuation = array(
			'token'             => $token,
			'editor'            => 'elementor',
			'post_id'           => intval( $post_id ),
			'user_id'           => get_current_user_id(),
			'provider'          => $this->provider,
			'model'             => $this->model,
			'conversation'      => $conversation,
			'response_parts'    => $response_parts,
			'tool_log'          => $tool_log,
			'step'              => $step,
			'use_native'        => $use_native,
			'mode'              => $mode,
			'pending_calls'     => $public_calls,
			'tool_catalog_hash' => $this->editor_tool_catalog_hash(),
			'native_error_count' => max( 0, $native_error_count ),
		);
		$envelope_hash = hash( 'sha256', wp_json_encode( $continuation ) );
		set_transient(
			'wpaddons_elementor_turn_' . hash( 'sha256', $token ),
			array(
				'envelope_hash'   => $envelope_hash,
				'results_hash'    => '',
				'in_flight_until' => 0,
			),
			10 * MINUTE_IN_SECONDS
		);
		return array(
			'type'         => 'editor_tool_calls',
			'calls'        => $public_calls,
			'continuation' => $continuation,
			'step'         => $step,
			'max_steps'    => self::ELEMENTOR_MAX_TOOL_STEPS,
		);
	}

	/**
	 * Validate a continuation and append browser-owned Elementor tool results.
	 *
	 * @return array|WP_Error|null
	 */
	private function restore_editor_continuation( ?array $continuation, array $results, ?int $post_id ) {
		if ( empty( $continuation ) ) {
			return null;
		}
		$encoded = wp_json_encode( $continuation );
		if ( false === $encoded || strlen( $encoded ) > 1048576 ) {
			return new WP_Error( 'invalid_continuation', __( 'The Elementor tool continuation is too large.', 'advanced-animation' ) );
		}
		$token         = sanitize_text_field( strval( $continuation['token'] ?? '' ) );
		$transient_key = 'wpaddons_elementor_turn_' . hash( 'sha256', $token );
		$stored        = '' !== $token ? get_transient( $transient_key ) : false;
		$envelope_hash = hash( 'sha256', $encoded );
		if ( ! is_array( $stored )
			|| ! is_string( $stored['envelope_hash'] ?? null )
			|| ! hash_equals( $stored['envelope_hash'], $envelope_hash ) ) {
			return new WP_Error( 'invalid_continuation_token', __( 'The Elementor tool continuation is invalid, altered, or was already used.', 'advanced-animation' ) );
		}
		if ( 'elementor' !== ( $continuation['editor'] ?? '' )
			|| intval( $continuation['post_id'] ?? 0 ) !== intval( $post_id )
			|| intval( $continuation['user_id'] ?? 0 ) !== get_current_user_id() ) {
			return new WP_Error( 'continuation_binding_mismatch', __( 'The Elementor continuation belongs to another editor or post.', 'advanced-animation' ) );
		}
		$continuation_provider = sanitize_text_field( strval( $continuation['provider'] ?? '' ) );
		$continuation_model    = sanitize_text_field( strval( $continuation['model'] ?? '' ) );
		if ( $this->provider && $continuation_provider && $this->provider !== $continuation_provider ) {
			return new WP_Error( 'continuation_model_mismatch', __( 'The AI provider changed during the Elementor tool turn.', 'advanced-animation' ) );
		}
		if ( $this->model && $continuation_model && $this->model !== $continuation_model ) {
			return new WP_Error( 'continuation_model_mismatch', __( 'The AI model changed during the Elementor tool turn.', 'advanced-animation' ) );
		}
		if ( ! $this->provider && $continuation_provider ) {
			$this->provider = $continuation_provider;
		}
		if ( ! $this->model && $continuation_model ) {
			$this->model = $continuation_model;
		}
		if ( ! hash_equals( strval( $continuation['tool_catalog_hash'] ?? '' ), $this->editor_tool_catalog_hash() ) ) {
			return new WP_Error( 'continuation_catalog_mismatch', __( 'The available Elementor tools changed during this turn.', 'advanced-animation' ) );
		}
		$step = intval( $continuation['step'] ?? 0 );
		if ( $step < 1 || $step >= self::ELEMENTOR_MAX_TOOL_STEPS ) {
			return new WP_Error( 'invalid_continuation_step', __( 'The Elementor tool continuation step is invalid.', 'advanced-animation' ) );
		}
		$pending = is_array( $continuation['pending_calls'] ?? null ) ? $continuation['pending_calls'] : array();
		if ( empty( $pending ) || count( $pending ) !== count( $results ) ) {
			return new WP_Error( 'invalid_tool_results', __( 'Elementor tool results do not match the pending calls.', 'advanced-animation' ) );
		}
		$results_json = wp_json_encode( $results );
		if ( false === $results_json || strlen( $results_json ) > 524288 ) {
			return new WP_Error( 'invalid_tool_results', __( 'The Elementor tool results are too large.', 'advanced-animation' ) );
		}
		$results_hash = hash( 'sha256', $results_json );
		$bound_hash   = strval( $stored['results_hash'] ?? '' );
		if ( '' !== $bound_hash && ! hash_equals( $bound_hash, $results_hash ) ) {
			return new WP_Error( 'continuation_results_mismatch', __( 'A retry must use the same Elementor tool results as the original request.', 'advanced-animation' ) );
		}
		$in_flight_until = intval( $stored['in_flight_until'] ?? 0 );
		if ( $in_flight_until > time() ) {
			return new WP_Error(
				'continuation_in_progress',
				__( 'This Elementor continuation is already being processed.', 'advanced-animation' ),
				array(
					'retryable'     => true,
					'retry_after_ms' => max( 250, ( $in_flight_until - time() ) * 1000 ),
				)
			);
		}
		$result_map = array();
		foreach ( $results as $result ) {
			if ( ! is_array( $result ) ) {
				continue;
			}
			$result_id = strval( $result['id'] ?? '' );
			if ( '' === $result_id || isset( $result_map[ $result_id ] ) ) {
				return new WP_Error( 'invalid_tool_results', __( 'Elementor tool result IDs must be unique.', 'advanced-animation' ) );
			}
			$result_map[ $result_id ] = $result;
		}
		$response_parts = is_array( $continuation['response_parts'] ?? null ) ? $continuation['response_parts'] : array();
		$tool_log = is_array( $continuation['tool_log'] ?? null ) ? $continuation['tool_log'] : array();
		foreach ( $pending as $call ) {
			$id   = strval( $call['id'] ?? '' );
			$name = sanitize_key( strval( $call['name'] ?? '' ) );
			$result = $result_map[ $id ] ?? null;
			if ( ! $result || $name !== sanitize_key( strval( $result['name'] ?? '' ) ) || ! $this->has_editor_tool( $name ) ) {
				return new WP_Error( 'invalid_tool_result', __( 'An Elementor tool result did not match its pending call.', 'advanced-animation' ) );
			}
			$payload = $result['result'] ?? array();
			if ( ! empty( $result['is_error'] ) ) {
				$payload = array( 'success' => false, 'error' => $payload );
			}
			$logged_result  = $payload;
			$model_payload  = $this->compact_editor_tool_result_for_history( $payload );
			$response_parts[] = array(
				'type'             => 'functionResponse',
				'functionResponse' => array(
					'id'       => $id,
					'name'     => $name,
					'response' => $model_payload,
				),
			);
			$tool_log[] = array(
				'tool'      => $name,
				'arguments' => $call['arguments'] ?? array(),
				'result'    => $logged_result,
				'execution' => 'elementor-editor-mcp',
			);
		}
		$conversation = $this->normalize_history( is_array( $continuation['conversation'] ?? null ) ? $continuation['conversation'] : array() );
		if ( empty( $conversation ) ) {
			return new WP_Error( 'invalid_continuation', __( 'The Elementor tool conversation is missing.', 'advanced-animation' ) );
		}
		if ( 'manual' === ( $continuation['mode'] ?? '' ) ) {
			$first = reset( $response_parts );
			$conversation[] = array(
				'role'  => 'user',
				'parts' => array(
					array( 'type' => 'text', 'text' => wp_json_encode( array( 'tool_result' => $first['functionResponse']['response'] ?? array() ) ) ),
				),
			);
		} else {
			foreach ( $response_parts as $response_part ) {
				$conversation[] = array(
					'role'  => 'user',
					'parts' => array( $response_part ),
				);
			}
		}
		// Claim only after the complete envelope and results have passed validation.
		$lock_key = 'wpaddons_elementor_lock_' . hash( 'sha256', $token );
		if ( ! $this->claim_editor_continuation_lock( $lock_key ) ) {
			return new WP_Error(
				'continuation_in_progress',
				__( 'This Elementor continuation is already being processed.', 'advanced-animation' ),
				array( 'retryable' => true, 'retry_after_ms' => 1000 )
			);
		}
		$stored['results_hash']    = $results_hash;
		$stored['in_flight_until'] = time() + 330;
		if ( ! set_transient( $transient_key, $stored, 10 * MINUTE_IN_SECONDS ) ) {
			delete_option( $lock_key );
			return new WP_Error( 'continuation_claim_failed', __( 'The Elementor continuation could not be claimed.', 'advanced-animation' ) );
		}
		$this->continuation_claim = array(
			'key'           => $transient_key,
			'lock_key'      => $lock_key,
			'envelope_hash' => $envelope_hash,
			'results_hash'  => $results_hash,
		);
		return array(
			'conversation'        => $conversation,
			'tool_log'            => $tool_log,
			'step'                => $step,
			'use_native'          => ! empty( $continuation['use_native'] ),
			'native_error_count'  => max( 0, intval( $continuation['native_error_count'] ?? 0 ) ),
		);
	}

	/**
	 * Keep oversized Elementor tool results out of the model's growing history.
	 *
	 * The full result stays in the client-facing tool log, while the model
	 * receives a bounded preview so each continuation request remains small.
	 *
	 * @param array $payload Tool result returned by the Elementor editor.
	 * @return array Payload safe to append to model conversation history.
	 */
	private function compact_editor_tool_result_for_history( array $payload ): array {
		$json = wp_json_encode( $payload );
		if ( false === $json || strlen( $json ) <= self::ELEMENTOR_MAX_TOOL_RESULT_BYTES ) {
			return $payload;
		}

		$preview = substr(
			$json,
			0,
			self::ELEMENTOR_MAX_TOOL_RESULT_BYTES - 512
		);

		return array(
			'success'   => (bool) ( $payload['success'] ?? true ),
			'truncated' => true,
			'preview'   => $preview,
		);
	}

	/** Atomically claim a continuation across concurrent PHP requests. */
	private function claim_editor_continuation_lock( string $lock_key ): bool {
		$expires = time() + 330;
		if ( add_option( $lock_key, $expires, '', 'no' ) ) {
			return true;
		}
		if ( intval( get_option( $lock_key, 0 ) ) <= time() ) {
			delete_option( $lock_key );
			return (bool) add_option( $lock_key, $expires, '', 'no' );
		}
		return false;
	}

	/** Release a claimed continuation after a failed model lookup or generation. */
	private function release_editor_continuation_claim(): void {
		if ( ! $this->continuation_claim ) {
			return;
		}
		$claim  = $this->continuation_claim;
		$stored = get_transient( $claim['key'] );
		if ( is_array( $stored )
			&& hash_equals( $claim['envelope_hash'], strval( $stored['envelope_hash'] ?? '' ) )
			&& hash_equals( $claim['results_hash'], strval( $stored['results_hash'] ?? '' ) ) ) {
			$stored['in_flight_until'] = 0;
			set_transient( $claim['key'], $stored, 10 * MINUTE_IN_SECONDS );
		}
		delete_option( $claim['lock_key'] );
		$this->continuation_claim = null;
	}

	/** Consume a claimed continuation after the model returned a usable response. */
	private function consume_editor_continuation_claim(): void {
		if ( ! $this->continuation_claim ) {
			return;
		}
		delete_transient( $this->continuation_claim['key'] );
		delete_option( $this->continuation_claim['lock_key'] );
		$this->continuation_claim = null;
	}

	private function has_editor_tool( string $name ): bool {
		foreach ( $this->editor_tools as $tool ) {
			if ( $name === $tool['name'] ) {
				return true;
			}
		}
		return false;
	}

	private function editor_tool_catalog_hash(): string {
		return hash( 'sha256', wp_json_encode( $this->editor_tools ) );
	}

	/**
	 * Build WordPress AI Client FunctionDeclaration objects from the tool registry.
	 *
	 * @return FunctionDeclaration[]
	 */
	private function build_function_declarations( Tool_Registry $registry ): array {
		$declarations = array();

		foreach ( $registry->all() as $tool ) {
			$schema = $tool->input_schema();

			$declarations[] = new FunctionDeclaration(
				$tool->name(),
				$tool->description(),
				! empty( $schema ) ? $schema : null
			);
		}

		return $declarations;
	}

	/**
	 * Detect whether the configured provider/model supports native function calling.
	 */
	private function detect_native_support( string $prompt_text, array $declarations ): bool {
		if ( empty( $declarations ) ) {
			return false;
		}
		if (
			in_array(
				strtolower( (string) $this->provider ),
				array( 'openrouter', 'deepseek' ),
				true
			)
		) {
			return true;
		}

		$builder = Compat::ai_client_prompt( $prompt_text );
		if ( is_wp_error( $builder ) ) {
			return false;
		}

		$builder = $builder
			->using_system_instruction( 'You are a helpful assistant.' )
			->using_function_declarations( ...$declarations );

		$builder = $this->apply_provider_model( $builder );

		if ( is_wp_error( $builder ) ) {
			return false;
		}

		return (bool) $builder->is_supported_for_text_generation();
	}

	/**
	 * Build the system prompt that explains the tool protocol.
	 */
	/**
	 * Build the Elementor-specific system prompt.
	 */


	/**
	 * Convert a selected element's JSON data to rendered HTML + CSS context
	 * for inclusion in the AI system prompt.
	 */
	private function render_selection_context( array $element_data ): string {
		try {
			$converter = new Elementor_Html_Converter();
			$result    = $converter->convert( $element_data );

			if ( empty( $result['html'] ) ) {
				return '';
			}

			$context = $result['html'];

			if ( ! empty( $result['css'] ) ) {
				$context .= "\n\n<style>\n" . $result['css'] . "\n</style>";
			}

			return $context;
		} catch ( \Exception $e ) {
			return '';
		}
	}

	/**
	 * Build a compact native-tool index for the Elementor system prompt.
	 *
	 * Native tool schemas are already sent through function declarations, so
	 * repeating the full JSON schemas in the system instruction only doubles
	 * token consumption.
	 *
	 * @param Tool_Registry $registry Tool registry for the current pass.
	 * @return string Compact one-line-per-tool index.
	 */
	private function build_compact_elementor_tool_index( Tool_Registry $registry ): string {
		$lines = array();
		foreach ( $registry->all() as $tool ) {
			$description = trim( strval( $tool->description() ) );
			$description = $this->truncate_text( $description, 240 );
			$lines[]     = sprintf( '- %s: %s', $tool->name(), $description );
		}
		return implode( "\n", $lines );
	}


	private function build_elementor_system_prompt( Tool_Registry $registry, ?array $selection, ?int $post_id = null, bool $use_native = false ): string {
		if ( $use_native ) {
			$schemas = $this->build_compact_elementor_tool_index( $registry );
		} else {
			$schemas = wp_json_encode( $registry->get_schemas(), JSON_PRETTY_PRINT );
		}

		$selection_note = '';
		if ( $selection && ! empty( $selection['elementData'] ) ) {
			$rendered = $this->render_selection_context( $selection['elementData'] );
			if ( ! empty( $rendered ) ) {
				$selection_note = "\n\nCurrently selected element in the Elementor editor (rendered HTML + CSS context):\n" . $rendered;
			}
		} elseif ( $selection && ! empty( $selection['html'] ) ) {
			$selection_note = "\n\nCurrently selected element in the Elementor editor (use as context):\n" .
				$selection['html'];
		}

		$page_context = $this->build_page_context( $post_id, $selection );

		$image_note = "\n- When building a section that needs images (hero backgrounds, feature images, cards, galleries), " .
			"FIRST call search_unsplash_image with descriptive keywords, then pass the returned image URLs to the applicable editor tool. " .
			"Do NOT invent placeholder image URLs.";

		$theme_context = $this->build_theme_context();
		$has_native_tools = ! empty( $this->editor_tools );
		if ( $has_native_tools && ! $this->allow_elementor_html_fallback ) {
			$resource_workflow = empty( $this->editor_resources )
				? '- Before composing or styling, call editor-resource-getter for every resource named by the applicable tool, then inspect the available V4 widget inventory, relevant schemas, and guides.\n'
				: '- The editor resources listed in AVAILABLE PRELOADED EDITOR RESOURCES are already loaded into this prompt, including the available V4 widget inventory and catalog-referenced widget schemas. Use those URIs directly; call editor-resource-getter only for a required URI that is not listed.\n';
			$design_system_workflow = empty( $this->editor_resources )
				? '- Read the design-system resources before composing: elementor://global-classes (reuse existing global classes) and elementor://global-variables (the only global variables allowed).\n'
				: '- The design-system resources (elementor://global-classes and elementor://global-variables) are included in PRELOADED EDITOR RESOURCES below — reuse those global classes and variables instead of inventing colors, fonts, or classes.\n';
			$editor_workflow =
				'- Native Elementor MCP tools are available and are the only page-editing tools enabled for this pass.\n' .
				$resource_workflow .
				$design_system_workflow .
				'- Reference global design tokens (globals/colors?id=..., globals/typography?id=...) and existing global classes in the xmlStructure instead of inventing colors, fonts, or classes.\n' .
				'- Request independent resources and schema reads together in the same function-calling turn so they can be resolved as one batch.\n' .
				'- For a new section, prefer one complete build-compositions call containing the full hierarchy and settings instead of creating elements over many rounds.\n' .
				'- Use native class and configuration tools afterward only for changes that cannot be represented in build-compositions.\n' .
				'- Do not generate HTML or ask to use HTML conversion while native tools are available.\n' .
				'- Native changes remain unsaved in the live editor. Never attempt to save or publish.\n' .
				"BUILD-COMPOSITIONS XML RULES (strict):\n" .
				"- xmlStructure must be well-formed XML with exactly ONE root element and unique configuration-id values.\n" .
				"- Escape every raw '&' as '&amp;' in text content and attributes; never write raw '<' or '>' inside text.\n" .
				"- Do not include HTML, markdown fences, comments, or a trailing newline structure — only the XML string.\n" .
				"- Widget tags and prop values must come exactly from the widget schemas: enum props (e.g. flexbox html_tag) accept ONLY the listed values; a value like 'nav' or 'main' is rejected.\n" .
				"- If a tool call returns an XML parse error, read the parser reason in the error and fix the exact string before retrying.\n";
			$fallback_tool_help = '';
			$fallback_flow = '';
		} else {
			$editor_workflow = $has_native_tools
				? '- A native Elementor MCP operation failed during this turn. HTML conversion is now enabled as a compatibility fallback.\n'
				: '- Elementor MCP is unavailable. Use the HTML generation and conversion tools described below.\n';
			$fallback_tool_help =
				"- generate_elementor_html — generate a new HTML section for preview.\n" .
				"- add_elementor_html_to_page — generate HTML and insert a new section into the page.\n" .
				"- replace_elementor_selection — replace the selected element using converted HTML.\n" .
				"- edit_elementor_full_page — regenerate the entire page using converted HTML.\n";
			$fallback_flow =
				"\nHTML FALLBACK RULES:\n" .
				"- For one new section use add_elementor_html_to_page. For a selected-element edit use replace_elementor_selection.\n" .
				"- Use edit_elementor_full_page only for a whole-page rewrite.\n" .
				"- Always return renderable semantic HTML with one top-level <style> block.\n" .
					"- Put every layout, typography, color, border, spacing, and responsive rule in that one embedded <style> block.\n" .
					"- CSS class selectors are temporary converter selectors for local styles; use existing preloaded global classes when applicable, and do not invent persisted classes.\n" .
					"- The embedded <style> block is converted into native Elementor properties, not raw custom CSS. Direct .target:hover, .target:focus, .target:active, and .target:focus-visible rules become native state variants.\n" .
					"- Do not generate pseudo-elements, '&' nesting, or complex ancestor/descendant state selectors; unsupported state rules are dropped.\n" .
					"- Never split component CSS into page-level CSS; include all styling in the HTML payload.\n";
		}

		return 'You are an AI assistant that helps users build websites in the Elementor editor.\n\n' .
			'HOW THE SYSTEM WORKS:\n' .
			'- The Elementor editor uses native widgets (headings, paragraphs, images, buttons, div blocks, SVGs, etc.).\n' .
			'- Never narrate or promise upcoming steps. If you need a resource, call the required tool immediately in the same turn. A reply that only describes what you are about to do is treated as incomplete and you will be asked to continue.\n' .
			$editor_workflow .
			$theme_context . "\n" .
			$this->build_elementor_variable_policy() .
			"You have access to the following tools. Call them in order to complete the user's request:\n" .
			$schemas . "\n" .
			"AVAILABLE TOOLS — what to use and when:\n" .
			$fallback_tool_help .
			"- search_unsplash_image — search for real photos on Unsplash before creating a layout that needs images.\n" .
			$image_note . "\n\n" .
			"- get_page_content — read the current page when native resources do not already provide the required context.\n" .
			"- call_wordpress_rest_api — call any WordPress REST API endpoint.\n" .
			$fallback_flow . "\n" .
			"When responding to design requests, create a clean, modern, responsive result with good spacing, typography, and color choices." .
			$page_context .
			$selection_note .
			$this->build_preloaded_resources_note();
	}

	private function build_system_prompt( Tool_Registry $registry, ?array $selection, bool $use_native, ?int $post_id = null ): string {
		// Elementor editor — native HTML with <style> CSS, no Tailwind.
		if ( 'elementor' === $this->editor ) {
			return $this->build_elementor_system_prompt( $registry, $selection, $post_id, $use_native );
		}

		$schemas = wp_json_encode( $registry->get_schemas(), JSON_PRETTY_PRINT );

		$selection_note = '';
		if ( $selection && ! empty( $selection['elementData'] ) ) {
			$rendered = $this->render_selection_context( $selection['elementData'] );
			if ( ! empty( $rendered ) ) {
				$selection_note = "\n\nCurrently selected element (rendered HTML + CSS context):\n" . $rendered;
			}
		} elseif ( $selection && ! empty( $selection['html'] ) ) {
			$selection_note = "\n\nCurrently selected blocks in the editor (use as context):\n" .
				$selection['html'];
		}

		$page_context = $this->build_page_context( $post_id, $selection );

		$final_types = wp_json_encode(
			array(
				'blocks'               => array( 'type' => 'blocks', 'html' => '...', 'blocks' => array() ),
				'blocks_updated'       => array( 'type' => 'blocks_updated', 'message' => '...', 'post_id' => 0 ),
				'page_updated'         => array( 'type' => 'page_updated', 'message' => '...', 'post_id' => 0 ),
				'message'              => array( 'type' => 'message', 'message' => '...' ),
				'post_created'         => array( 'type' => 'post_created', 'post_id' => 0, 'url' => '...', 'message' => '...' ),
				'image'                => array( 'type' => 'image', 'url' => '...', 'thumb' => '...', 'message' => '...' ),
				'image_search_results' => array( 'type' => 'image_search_results', 'images' => array() ),
				'error'                => array( 'type' => 'error', 'message' => '...' ),
			),
			JSON_PRETTY_PRINT
		);

		$native_block_note = "\n- When the request is for dynamic or native WordPress content (blog posts, navigation, post content, archives, search forms, menus), " .
			"set the tool argument block_type to 'native' so the generated blocks are native WordPress blocks. " .
			"For static sections, hero areas, cards, buttons, and custom layouts, use block_type 'tailwind' (default).";

		if ( 'native' === $this->block_type_preference ) {
			$native_block_note = "\n- The user selected Block Type: Native Gutenberg. You MUST generate native WordPress/Gutenberg blocks. " .
				"When calling generate_blocks, add_blocks_to_page, or replace_selected_blocks, set block_type to 'native'. Do not generate tailwind/html blocks.";
		} elseif ( 'tailwind' === $this->block_type_preference ) {
			$native_block_note = "\n- The user selected Block Type: Tailwind/HTML. Use tailwind/html blocks for Gutenberg generation. " .
				"When calling generate_blocks, add_blocks_to_page, or replace_selected_blocks, set block_type to 'tailwind'.";
		}

		$image_note = "\n- When building a section that needs images (hero backgrounds, feature images, cards, galleries, testimonials with photos), " .
			"FIRST call search_unsplash_image with descriptive keywords to find suitable images, then pass the returned image URLs " .
			"in your generate_blocks / add_blocks_to_page description so the generated HTML uses real image URLs. " .
			"Do NOT invent placeholder image URLs.";

		$position_note = "\n- When calling add_blocks_to_page, choose position based on the user's intent: " .
			"'start' to add a header/section at the very top of the page (e.g. 'add a header at the top', 'add a hero above everything'), " .
			"'end' (default) to append at the bottom, " .
			"'before_selection' or 'after_selection' to insert immediately before/after the block the user currently has selected in the editor " .
			"(e.g. 'add a section after this', 'insert a CTA above the selected block', 'add a section in the middle of the page'). " .
			"For before_selection/after_selection the user MUST have a block selected; if nothing is selected, ask them to select an anchor block first instead of calling the tool.";

		$full_page_note = "\n- Call edit_full_page ONLY when the requested changes affect more than one location on the page " .
			"(e.g. 'reorder the sections', 'change all headings', 'add a CTA after every section', 'swap the hero and the features section', 'rewrite the whole page'). " .
			"Do NOT use edit_full_page for a single new section (use add_blocks_to_page) or for editing one selected block (use replace_selected_blocks); " .
			"edit_full_page regenerates the entire page and is heavier, so prefer the more targeted tools whenever the change is in a single place.";

		$get_page_note = "\n- Call get_page_content when the compact page outline above is not detailed enough " .
			"(e.g. to match the exact Tailwind classes of an existing section, to verify the current page, " .
			"or to plan a multi-section edit). For single-block edits use replace_selected_blocks, " .
			"for adding a single new section use add_blocks_to_page — they do not need this tool.";

		$tailwind_style_note = "\n- For Tailwind/static sections, never use inline style attributes, <style> tags, or <link> stylesheets. " .
			"Use Tailwind CSS v4 classes for every visual style. When a custom value is needed, use arbitrary value utilities such as " .
			"w-[37px], bg-[#123456], text-[clamp(2rem,6vw,5rem)], [box-shadow:0_20px_60px_rgba(0,0,0,0.18)], bg-[url(\"...\")], or [transform:rotate(-2deg)].";

		$theme_context = $this->build_theme_context();

		if ( $use_native ) {
			return "You are a WordPress AI assistant with tools. " .
				"Use the available functions to interact with the site or generate content. " .
				"When you are done, return a final JSON envelope and no extra text.\n\n" .
				"Available functions:\n" . $schemas . "\n\n" .
				"Final result envelopes you may use:\n" . $final_types . "\n\n" .
				"Rules:\n" .
				"- If the user wants to add a new section/hero/component to the current page, call add_blocks_to_page. Choose position based on where the user wants it (top/bottom/before/after the selected block).\n" .
				"- If the user wants to change/update/edit the currently selected block(s), call replace_selected_blocks. Do not call generate_blocks first.\n" .
				"- If the requested changes affect MORE THAN ONE location on the page (reordering sections, restyling multiple areas, rewriting the whole page), call edit_full_page. Do not use it for single-place changes.\n" .
				"- If the user asks for a preview or raw HTML/blocks without inserting, call generate_blocks.\n" .
				"- If the user asks for posts, pages, media, users, categories, tags, or site data, call call_wordpress_rest_api.\n" .
				"- If the user asks for stock images, call search_unsplash_image.\n" .
				"- You may call multiple functions in one turn.\n" .
				"- Always finish with a final result envelope in JSON." .
				$native_block_note .
				$image_note .
				$position_note .
				$full_page_note .
				$get_page_note .
				$tailwind_style_note .
				$page_context .
				$selection_note .
				$theme_context;
		}

		return "You are a WordPress AI assistant with tools. " .
			"Respond with exactly one JSON object and no extra text.\n\n" .
			"To call a tool:\n" .
			wp_json_encode( array( 'action' => 'tool_call', 'tool' => 'TOOL_NAME', 'arguments' => array() ) ) . "\n\n" .
			"To return a final answer:\n" .
			wp_json_encode( array( 'action' => 'final', 'result' => array( 'type' => '...' ) ) ) . "\n\n" .
			"Available tools:\n" . $schemas . "\n\n" .
			"Final result envelopes you may use:\n" . $final_types . "\n\n" .
			"Rules:\n" .
			"- If the user wants to add a new section/hero/component to the current page, use add_blocks_to_page with a description. Choose position based on where the user wants it (top/bottom/before/after the selected block).\n" .
			"- If the user wants to change/update/edit the currently selected block(s), use replace_selected_blocks with a description. Do not call generate_blocks first.\n" .
			"- If the requested changes affect MORE THAN ONE location on the page (reordering sections, restyling multiple areas, rewriting the whole page), use edit_full_page with a description. Do not use it for single-place changes.\n" .
			"- If the user asks for a preview or raw HTML/blocks without inserting, use generate_blocks.\n" .
			"- If the user asks for posts, pages, media, users, categories, tags, or site data, use call_wordpress_rest_api.\n" .
			"- If the user asks for stock images, use search_unsplash_image.\n" .
			"- You may call multiple tools in sequence.\n" .
			"- Always finish with a final result envelope." .
			$native_block_note .
			$image_note .
			$position_note .
			$full_page_note .
			$get_page_note .
			$tailwind_style_note .
			$page_context .
			$selection_note .
			$theme_context;
	}

	/**
	 * Send a conversation to the AI and return either a text response or a list of function calls.
	 *
	 * @return array|WP_Error Array with keys 'type' => 'text'|'function_calls' and either 'text' or 'calls'.
	 */
	private function call_ai_with_rate_limit_retry( string $system_prompt, array $messages, bool $include_attachments, array $declarations, bool $use_native ) {
		$attempt = 0;
		while ( $attempt < self::RATE_LIMIT_RETRY_MAX_ATTEMPTS ) {
			$result = $this->call_ai( $system_prompt, $messages, $include_attachments, $declarations, $use_native );
			if ( ! is_wp_error( $result ) || ! $this->is_rate_limit_error( $result ) ) {
				return $result;
			}
			$attempt++;
			if ( $attempt >= self::RATE_LIMIT_RETRY_MAX_ATTEMPTS ) {
				return $result;
			}
			usleep( $this->rate_limit_retry_delay_ms( $result ) * 1000 );
		}

		return $result ?? new WP_Error( 'ai_rate_limited', __( 'The AI provider rate limit was not resolved after retries.', 'advanced-animation' ) );
	}

	/** Whether an AI error indicates a provider rate limit (HTTP 429). */
	private function is_rate_limit_error( \WP_Error $error ): bool {
		$message = strtolower( (string) $error->get_error_message() );
		return (bool) preg_match( '/(\b429\b|too many requests|rate\s*limit|tokens?\s+per\s+(min|minute))/', $message );
	}

	/** Extract the provider-suggested wait from a rate-limit error, falling back to a fixed backoff. */
	private function rate_limit_retry_delay_ms( \WP_Error $error ): int {
		$message = (string) $error->get_error_message();
		if ( preg_match( '/retry.?after[\s:]+(\d+)/i', $message, $m ) ) {
			return min( self::RATE_LIMIT_RETRY_MAX_DELAY_MS, max( 250, (int) $m[1] * 1000 ) );
		}
		if ( preg_match( '/(?:try again|retry) in\s+([\d.]+)\s*(ms|s)/i', $message, $m ) ) {
			$delay = (float) $m[1];
			return (int) min( self::RATE_LIMIT_RETRY_MAX_DELAY_MS, max( 250, 's' === strtolower( $m[2] ) ? $delay * 1000 : $delay ) );
		}
		return 1000;
	}

	/**
	 * Send a conversation to the AI and return either a text response or a list of function calls.
	 *
	 * @return array|WP_Error Array with keys 'type' => 'text'|'function_calls' and either 'text' or 'calls'.
	 */
	private function call_ai( string $system_prompt, array $messages, bool $include_attachments, array $declarations, bool $use_native ) {
		if ( empty( $messages ) ) {
			return new WP_Error(
				'no_messages',
				__( 'No messages to send to the AI.', 'advanced-animation' )
			);
		}

		// The last message becomes the current prompt; everything before is history.
		$current_message = array_pop( $messages );

		$history_messages = array_filter(
			array_map(
				function ( $message ) {
					try {
						return Message::fromArray( $message );
					} catch ( \Exception $e ) {
						return null;
					}
				},
				$messages
			)
		);

		if ( $use_native ) {
			try {
				$prompt = Message::fromArray( $current_message );
			} catch ( \Exception $e ) {
				return new WP_Error(
					'invalid_message',
					sprintf(
						/* translators: %s: error message */
						__( 'Could not parse conversation message: %s', 'advanced-animation' ),
						$e->getMessage()
					)
				);
			}

			$builder = Compat::ai_client_prompt( $prompt );
			if ( is_wp_error( $builder ) ) {
				return $builder;
			}
			$builder = $builder
				->using_system_instruction( $system_prompt )
				->using_function_declarations( ...$declarations );
		} else {
			$prompt_text = $this->message_to_text( $current_message );

			$builder = Compat::ai_client_prompt( $prompt_text );
			if ( is_wp_error( $builder ) ) {
				return $builder;
			}
			$builder = $builder
				->using_system_instruction( $system_prompt );
		}

		if ( ! empty( $history_messages ) ) {
			$builder = $builder->with_history( ...array_values( $history_messages ) );
		}

		$builder = $this->apply_provider_and_attachments( $builder, $include_attachments );

		if ( is_wp_error( $builder ) ) {
			return $builder;
		}

		if ( ! $builder->is_supported_for_text_generation() && ! $this->has_explicit_provider_model() ) {
			return new WP_Error(
				'ai_no_text_provider',
				__( 'No AI provider with text generation is configured. Install an AI provider plugin and set your API key in Settings > Connectors.', 'advanced-animation' )
			);
		}

		$increase_timeout = function ( array $args ): array {
			$args['timeout'] = 300;
			return $args;
		};

		add_filter( 'http_request_args', $increase_timeout );

		if ( $use_native ) {
			$result = $builder->generate_text_result();

			if ( is_wp_error( $result ) ) {
				remove_filter( 'http_request_args', $increase_timeout );
				return $result;
			}

			$calls = $this->extract_function_calls( $result );
			if ( ! empty( $calls ) ) {
				remove_filter( 'http_request_args', $increase_timeout );
				return array(
					'type'  => 'function_calls',
					'calls' => $calls,
				);
			}

			$text = $this->extract_text_from_result( $result );
			remove_filter( 'http_request_args', $increase_timeout );

			if ( is_wp_error( $text ) ) {
				return $text;
			}

			return array(
				'type' => 'text',
				'text' => $text,
			);
		}

		$result = $builder->generate_text();
		remove_filter( 'http_request_args', $increase_timeout );

		if ( is_wp_error( $result ) ) {
			return $result;
		}

		return array(
			'type' => 'text',
			'text' => $result,
		);
	}

	/**
	 * Plain text generation without tools.
	 */
	private function generate_text( string $system_prompt, array $messages, bool $include_attachments ) {
		if ( empty( $messages ) ) {
			return new WP_Error(
				'no_messages',
				__( 'No messages to send to the AI.', 'advanced-animation' )
			);
		}

		$current_message = array_pop( $messages );
		$prompt_text     = $this->message_to_text( $current_message );

		$builder = Compat::ai_client_prompt( $prompt_text );
		if ( is_wp_error( $builder ) ) {
			return $builder;
		}
		$builder = $builder
			->using_system_instruction( $system_prompt );

		$history_messages = array_filter(
			array_map(
				function ( $message ) {
					try {
						return Message::fromArray( $message );
					} catch ( \Exception $e ) {
						return null;
					}
				},
				$messages
			)
		);

		if ( ! empty( $history_messages ) ) {
			$builder = $builder->with_history( ...array_values( $history_messages ) );
		}

		$builder = $this->apply_provider_and_attachments( $builder, $include_attachments );

		if ( is_wp_error( $builder ) ) {
			return $builder;
		}

		if ( ! $builder->is_supported_for_text_generation() && ! $this->has_explicit_provider_model() ) {
			return new WP_Error(
				'ai_no_text_provider',
				__( 'No AI provider with text generation is configured. Install an AI provider plugin and set your API key in Settings > Connectors.', 'advanced-animation' )
			);
		}

		$increase_timeout = function ( array $args ): array {
			$args['timeout'] = 300;
			return $args;
		};

		add_filter( 'http_request_args', $increase_timeout );
		$result = $builder->generate_text();
		remove_filter( 'http_request_args', $increase_timeout );

		return $result;
	}

	/**
	 * Apply provider/model selection and attachments to a builder.
	 *
	 * @param \WP_AI_Client_Prompt_Builder $builder
	 * @return \WP_AI_Client_Prompt_Builder
	 */
	private function apply_provider_and_attachments( $builder, bool $include_attachments ) {
		$builder = $this->apply_provider_model( $builder );
		if ( is_wp_error( $builder ) ) {
			return $builder;
		}

		/**
		 * Limit the provider's reserved output budget. Some OpenAI-compatible
		 * providers otherwise inherit the model maximum (for example 65,536),
		 * which can trigger credit rejection before generation starts.
		 */
		$max_tokens = (int) apply_filters(
			'advanced_addons_ai_max_output_tokens',
			self::CHAT_MAX_OUTPUT_TOKENS,
			$this->editor,
			$this->provider,
			$this->model
		);
		$max_tokens = max( 512, min( 16384, $max_tokens ) );
		$builder    = $builder->using_max_tokens( $max_tokens );

		if ( ! $include_attachments ) {
			return $builder;
		}

		foreach ( $this->attachments as $attachment ) {
			$type = $attachment['type'] ?? '';
			$mime = $attachment['mimeType'] ?? '';
			$data = $attachment['data'] ?? '';
			$name = $attachment['name'] ?? '';

			if ( empty( $data ) ) {
				continue;
			}

			if ( 'image' === $type ) {
				$builder = $builder->with_file( $data, $mime ?: 'image/png' );
			} elseif ( 'file' === $type ) {
				if ( 0 === strpos( $mime, 'text/' ) || 'application/json' === $mime ) {
					$builder = $builder->with_text( "\n\n[Attached file: {$name}]\n{$data}" );
				} else {
					$builder = $builder->with_file( $data, $mime ?: 'application/octet-stream' );
				}
			}
		}

		return $builder;
	}

	/**
	 * Apply provider/model selection to a builder.
	 *
	 * @param \WP_AI_Client_Prompt_Builder $builder
	 * @return \WP_AI_Client_Prompt_Builder
	 */
	private function apply_provider_model( $builder ) {
		if ( $this->model && $this->provider && class_exists( '\WordPress\AiClient\AiClient' ) ) {
			try {
				$model_instance = \WordPress\AiClient\AiClient::defaultRegistry()->getProviderModel( $this->provider, $this->model );
				return $builder->using_model( $model_instance );
			} catch ( \Throwable $e ) {
				if ( $this->is_model_lookup_network_error( $e ) ) {
					return new WP_Error(
						'ai_model_lookup_network',
						sprintf(
							/* translators: %s: network error message */
							__( 'Could not verify the selected AI model because the provider model list could not be reached: %s', 'advanced-animation' ),
							$e->getMessage()
						),
						array(
							'retryable'       => true,
							'retry_delays_ms' => array( 500, 1500 ),
						)
					);
				}
				return new WP_Error(
					'ai_model_unavailable',
					sprintf(
						/* translators: %s: error message */
						__( 'Selected model is not available: %s', 'advanced-animation' ),
						$e->getMessage()
					)
				);
			}
		} elseif ( $this->provider ) {
			return $builder->using_provider( $this->provider );
		}

		return $builder;
	}

	/** Whether model resolution failed due to transport rather than an unknown model. */
	private function is_model_lookup_network_error( \Throwable $error ): bool {
		$message = strtolower( $error->getMessage() );
		$markers = array(
			'curl error',
			'network error',
			'timed out',
			'timeout',
			'could not resolve',
			'name resolution',
			'connection refused',
			'failed to connect',
			'connection reset',
			'no route to host',
		);
		foreach ( $markers as $marker ) {
			if ( false !== strpos( $message, $marker ) ) {
				return true;
			}
		}
		return false;
	}

	/** Whether the editor explicitly selected a concrete provider model. */
	private function has_explicit_provider_model(): bool {
		return ! empty( $this->provider )
			&& ! empty( $this->model )
			&& class_exists( '\WordPress\AiClient\AiClient' );
	}

	/**
	 * Extract function calls from a native AI result.
	 *
	 * @return array<int, array{id?: string|null, name: string|null, args: mixed}>
	 */
	private function extract_function_calls( \WordPress\AiClient\Results\DTO\GenerativeAiResult $result ): array {
		$calls   = array();
		$message = $result->toMessage();

		foreach ( $message->getParts() as $part ) {
			if ( $part->getType()->isFunctionCall() ) {
				$function_call = $part->getFunctionCall();

				if ( null === $function_call ) {
					continue;
				}

				$calls[] = array(
					'id'              => $function_call->getId(),
					'name'            => $function_call->getName(),
					'args'            => $function_call->getArgs(),
					'thoughtSignature' => $part->getThoughtSignature(),
				);
			}
		}

		return $calls;
	}

	/**
	 * Extract the final text from a native AI result.
	 */
	private function extract_text_from_result( \WordPress\AiClient\Results\DTO\GenerativeAiResult $result ) {
		try {
			return $result->toText();
		} catch ( \Exception $e ) {
			return new WP_Error(
				'no_text_content',
				sprintf(
					/* translators: %s: error message */
					__( 'AI response did not contain text content: %s', 'advanced-animation' ),
					$e->getMessage()
				)
			);
		}
	}

	/**
	 * Parse an AI response into a tool_call or final action.
	 *
	 * Accepts the strict JSON envelope, a bare result envelope, a type-keyed
	 * result wrapper, plain text, or raw HTML. Anything that is not recognised
	 * is surfaced as a message.
	 */
	private function parse_response( string $response ) {
		$text = trim( $response );

		// Strip markdown code fences if present.
		if ( preg_match( '/^```(?:json)?\s*(.+?)\s*```$/s', $text, $matches ) ) {
			$text = trim( $matches[1] );
		}

		$decoded = json_decode( $text, true );

		if ( JSON_ERROR_NONE === json_last_error() ) {
			if ( ! empty( $decoded['action'] ) ) {
				return $decoded;
			}

			// Bare result envelope, e.g. {"type":"message","message":"..."}
			if ( ! empty( $decoded['type'] ) ) {
				return array(
					'action' => 'final',
					'result' => $decoded,
				);
			}

			// Result-keyed object, e.g. {"blocks_updated":{"message":"..."},"blocks":{"html":"..."}}
			if ( is_array( $decoded ) ) {
				$known_types = array(
					'blocks_updated',
					'page_updated',
					'post_created',
					'image',
					'image_search_results',
					'blocks',
					'message',
					'error',
				);

				foreach ( $known_types as $type ) {
					if ( isset( $decoded[ $type ] ) && is_array( $decoded[ $type ] ) ) {
						$result = $decoded[ $type ];
						if ( empty( $result['type'] ) ) {
							$result['type'] = $type;
						}

						return array(
							'action' => 'final',
							'result' => $result,
						);
					}
				}
			}

			// Valid JSON but not an envelope; surface it as a message.
			return array(
				'action' => 'final',
				'result' => array(
					'type'    => 'message',
					'message' => $text,
				),
			);
		}

		$embedded = $this->extract_json_envelope( $text );
		if ( null !== $embedded ) {
			return $embedded;
		}

		// Fallback: if the response looks like HTML, treat it as a generate_blocks result.
		if ( strpos( $text, '<' ) !== false && strpos( $text, '>' ) !== false ) {
			$blocks = HtmlToBlocks::convert( $text );
			return array(
				'action' => 'final',
				'result' => array(
					'type'   => 'blocks',
					'html'   => $text,
					'blocks' => $blocks,
				),
			);
		}

		// Plain text answer.
		return array(
			'action' => 'final',
			'result' => array(
				'type'    => 'message',
				'message' => $text,
			),
		);
	}

	/**
	 * Find a valid JSON action envelope embedded inside explanatory text.
	 *
	 * Some models prepend narration before the requested JSON tool call. The
	 * agent loop still needs to execute the envelope instead of returning that
	 * whole response as a plain chat message.
	 */
	private function extract_json_envelope( string $text ): ?array {
		if ( ! preg_match_all( '/\{(?:[^{}"\\\\]|"(?:\\\\.|[^"\\\\])*"|(?R))*\}/s', $text, $matches ) ) {
			return null;
		}

		foreach ( $matches[0] as $candidate ) {
			$decoded = json_decode( $candidate, true );
			if ( JSON_ERROR_NONE !== json_last_error() || ! is_array( $decoded ) ) {
				continue;
			}

			if ( ! empty( $decoded['action'] ) ) {
				return $decoded;
			}

			if ( ! empty( $decoded['type'] ) ) {
				return array(
					'action' => 'final',
					'result' => $decoded,
				);
			}
		}

		return null;
	}

	/**
	 * Convert client history messages to the format expected by the AI client.
	 */
	private function normalize_history( array $messages ): array {
		return array_values(
			array_filter(
				$messages,
				function ( $message ) {
					return isset( $message['role'] ) && isset( $message['parts'] ) && is_array( $message['parts'] );
				}
			)
		);
	}

	/**
	 * Build a user message array from a prompt and optional attachments metadata.
	 */
	private function build_user_message( string $prompt, array $attachments ): array {
		$parts = array(
			array( 'type' => 'text', 'text' => $prompt ),
		);

		if ( ! empty( $attachments ) ) {
			foreach ( $attachments as $attachment ) {
				$parts[] = array(
					'type' => 'text',
					'text' => '[Attachment: ' . ( $attachment['name'] ?? 'file' ) . ']',
				);
			}
		}

		return array(
			'role'  => 'user',
			'parts' => $parts,
		);
	}

	/**
	 * Extract plain text from a message array.
	 */
	private function message_to_text( array $message ): string {
		$texts = array();
		foreach ( $message['parts'] ?? array() as $part ) {
			if ( is_array( $part ) && 'text' === ( $part['type'] ?? '' ) ) {
				$texts[] = $part['text'] ?? '';
			}
		}
		return implode( "\n\n", array_filter( $texts ) );
	}

	/**
	 * Append page and selection context to a prompt.
	 *
	 * @param string     $prompt    The user prompt.
	 * @param array|null $selection Current editor selection.
	 * @param int|null   $post_id   Current post ID for full-page context.
	 * @return string
	 */
	private function build_contextual_prompt( string $prompt, ?array $selection, ?int $post_id = null ): string {
		$context = '';

		$page_context = $this->build_page_context( $post_id, $selection );
		if ( $page_context ) {
			$context .= "The following is the current structure of the page you are editing. " .
				"Match its style/sections and avoid duplicating existing content:\n" .
				$page_context . "\n\n";
		}

		if ( $selection && ! empty( $selection['html'] ) ) {
			$context .= "The following HTML/Tailwind block(s) are currently selected in the editor. " .
				"Use them as context for your response:\n\n" .
				$selection['html'] . "\n\n";
		}

		return $context . $prompt;
	}

	/**
	 * Build a compact outline of the current page's top-level blocks.
	 *
	 * Includes each block's index, type, a short label, and marks the
	 * currently selected blocks so the model can reason about position.
	 *
	 * @param int|null   $post_id   Current post ID.
	 * @param array|null $selection Current editor selection (with indices).
	 * @return string Outline text, or empty string if unavailable.
	 */
	private function build_page_context( ?int $post_id, ?array $selection ): string {
		$raw_content = $this->resolve_page_content( $post_id );
		if ( $this->is_empty_page_content( $raw_content ) ) {
			if ( 'elementor' === $this->editor ) {
				if ( ! empty( $this->editor_tools ) && ! $this->allow_elementor_html_fallback ) {
					return "\n\nCURRENT PAGE STATUS: EMPTY — there is no content on the page yet. " .
						"Create the first section with the native Elementor composition workflow. " .
						"Read its required resources and schema before calling the composition tool.";
				}
				return "\n\nCURRENT PAGE STATUS: EMPTY — there is no content on the page yet. " .
					"Use add_elementor_html_to_page to create the first section. " .
					"Do not call replace_elementor_selection — there is nothing to replace.";
			}
			return "\n\nCURRENT PAGE STATUS: EMPTY — there is no content on the page yet. " .
				"To create the first section, call add_blocks_to_page (preferred) or edit_full_page. " .
				"Do not call replace_selected_blocks — there is nothing to replace.";
		}

		// Elementor live export is a JSON snapshot, not Gutenberg block markup.
		if ( 'elementor' === $this->editor ) {
			$decoded = json_decode( (string) $raw_content, true );
			if ( is_array( $decoded ) ) {
				$lines = array();
				foreach ( $decoded as $i => $el ) {
					if ( ! is_array( $el ) ) {
						continue;
					}
					$type    = $el['widgetType'] ?? $el['elType'] ?? 'element';
					$id      = $el['id'] ?? '';
					$lines[] = sprintf( '[%d] %s%s', $i, $type, $id ? " (id: {$id})" : '' );
				}
				if ( ! empty( $lines ) ) {
					return "\n\nFull page structure (top-level Elementor elements in order):\n" .
						implode( "\n", $lines );
				}
			}
			return "\n\nCURRENT PAGE STATUS: page has content (Elementor document).";
		}

		$blocks = parse_blocks( (string) $raw_content );
		$blocks = array_values(
			array_filter(
				$blocks,
				function ( $b ) {
					return ! empty( $b['blockName'] );
				}
			)
		);

		if ( empty( $blocks ) ) {
			return "\n\nCURRENT PAGE STATUS: EMPTY — there is no content on the page yet. " .
				"To create the first section, call add_blocks_to_page (preferred) or edit_full_page.";
		}

		$selected_indices = array();
		if ( $selection && ! empty( $selection['indices'] ) ) {
			$selected_indices = array_map( 'intval', (array) $selection['indices'] );
		}

		$lines = array();
		foreach ( $blocks as $i => $block ) {
			$name    = $block['blockName'] ?? 'unknown';
			$label   = $this->block_label( $block );
			$marker  = in_array( $i, $selected_indices, true ) ? ' [SELECTED]' : '';
			$lines[] = sprintf(
				'[%d] %s%s%s',
				$i,
				$name,
				$label ? ' — ' . $label : '',
				$marker
			);
		}

		return "\n\nFull page structure (top-level blocks in order, from top to bottom):\n" .
			implode( "\n", $lines );
	}

	/**
	 * Build conditional theme guidance so the AI knows which design tokens to
	 * reuse. Gutenberg gets the Tailwind theme (colours + fonts → utility
	 * classes). Elementor gets instructions to use its preloaded V4 resources.
	 *
	 * @return string
	 */
	private function build_theme_context(): string {
		if ( ! $this->use_global_theme ) {
			return '';
		}

		if ( 'elementor' === $this->editor ) {
			return "\n\nELEMENTOR GLOBAL THEME GUIDANCE:\n" .
				'- Reuse matching records from elementor://global-variables and elementor://global-classes whenever they match the requested design.\n' .
				'- Use exact canonical variable labels as var(--<label>) and reuse the exact global class identifiers supplied by Elementor.\n' .
				'- Do not invent variables, classes, legacy --e-global-* names, or fallback tokens.\n' .
				'- If a required resource is not preloaded, use editor-resource-getter when available.\n' .
				'- If no matching global resource exists, use a literal CSS value instead of inventing a variable or class.';
		}

		if ( ! class_exists( Tailwind_Theme_Settings::class ) ) {
			return '';
		}

		$theme = Tailwind_Theme_Settings::get_theme();
		$lines = array();

		if ( ! empty( $theme['colors'] ) ) {
			$colors = array();
			foreach ( $theme['colors'] as $name => $hex ) {
				$colors[] = sprintf( '  %s (%s) → bg-%s, text-%s, border-%s', $name, $hex, $name, $name, $name );
			}
			$lines[] = "Tailwind theme colors:\n" . implode( "\n", $colors );
		}

		if ( ! empty( $theme['fonts'] ) ) {
			$fonts = array();
			foreach ( $theme['fonts'] as $key => $font ) {
				if ( 'Inter' !== $font ) {
					$fonts[] = sprintf( '  %s font: %s → font-%s', $key, $font, $key );
				}
			}
			if ( ! empty( $fonts ) ) {
				$lines[] = "Tailwind theme fonts:\n" . implode( "\n", $fonts );
			}
		}

		if ( empty( $lines ) ) {
			return '';
		}

		return "\n\n" . implode( "\n\n", $lines );
	}

	/**
	 * Derive a short human-readable label for a block.
	 *
	 * Prefers heading/title attributes, then stripped innerHTML text,
	 * then an inner-block count hint.
	 *
	 * @param array $block A parsed block array.
	 * @return string
	 */
	private function block_label( array $block ): string {
		$attrs = $block['attrs'] ?? array();

		foreach ( array( 'content', 'text', 'label', 'placeholder' ) as $key ) {
			if ( ! empty( $attrs[ $key ] ) && is_string( $attrs[ $key ] ) ) {
				$label = $this->truncate_text( wp_strip_all_tags( $attrs[ $key ] ) );
				if ( '' !== $label ) {
					return $label;
				}
			}
		}

		$html = $block['innerHTML'] ?? '';
		if ( ! empty( $html ) ) {
			$text = trim( wp_strip_all_tags( $html ) );
			$text = preg_replace( '/\s+/', ' ', $text );
			if ( '' !== $text && '0' !== $text ) {
				return $this->truncate_text( $text );
			}
		}

		$inner = $block['innerBlocks'] ?? array();
		if ( ! empty( $inner ) ) {
			$count = count( $inner );
			return sprintf( '%d inner block%s', $count, 1 === $count ? '' : 's' );
		}

		return '';
	}

	/**
	 * Trim a string to a maximum length, appending an ellipsis.
	 *
	 * @param string $text Text to truncate.
	 * @param int    $max  Maximum length in characters.
	 * @return string
	 */
	private function truncate_text( string $text, int $max = 80 ): string {
		$text = trim( $text );
		if ( mb_strlen( $text ) <= $max ) {
			return $text;
		}
		return mb_substr( $text, 0, $max ) . '…';
	}
}