<?php
/**
 * Admin-facing screens: Dashboard, Logs, AI Guidance Files, System Check,
 * AI Deep Review Prompt and Settings, plus the CSV export handler.
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

require_once __DIR__ . '/class-ai-o-optimiser-period-compare.php';

class AI_O_Optimiser_Admin {

	/** @var bool Whether the dashboard section row has been printed on this request. */
	private static $dashboard_tab_nav_rendered = false;

	const CAPABILITY = AI_O_Optimiser_SENSITIVE_CAPABILITY;
	const SENSITIVE_CAPABILITY = AI_O_Optimiser_SENSITIVE_CAPABILITY;

	/** Dependency-free handle that inline admin scripts attach to. */
	const INLINE_HANDLE = 'ai-o-optimiser-admin-inline';

	public function __construct() {
		add_action( 'admin_menu', array( $this, 'register_menu' ) );
		add_action( 'admin_menu', array( $this, 'reorder_menu' ), 9999 );
		add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_assets' ) );
		add_action( 'admin_notices', array( $this, 'render_global_nav' ), 1 );
		add_action( 'ai_o_optimiser_render_secondary_nav', array( __CLASS__, 'render_secondary_nav' ), 10, 2 );
		add_action( 'admin_post_ai_o_optimiser_export_csv', array( $this, 'handle_csv_export' ) );
		add_action( 'admin_post_ai_o_optimiser_save_settings', array( $this, 'handle_save_settings' ) );
		add_action( 'admin_post_ai_o_optimiser_save_traffic_evidence', array( $this, 'handle_save_traffic_evidence' ) );
		add_action( 'admin_post_ai_o_optimiser_ga4_data_connect', array( $this, 'handle_ga4_data_connect' ) );
		add_action( 'admin_post_ai_o_optimiser_ga4_data_oauth_return', array( $this, 'handle_ga4_data_oauth_return' ) );
		add_action( 'admin_post_nopriv_ai_o_optimiser_ga4_data_oauth_return', array( $this, 'handle_ga4_data_oauth_return' ) );
		add_action( 'admin_post_ai_o_optimiser_ga4_data_save_property', array( $this, 'handle_ga4_data_save_property' ) );
		add_action( 'admin_post_ai_o_optimiser_test_ga4', array( $this, 'handle_test_ga4' ) );
		add_action( 'admin_post_ai_o_optimiser_process_visibility_backfill', array( $this, 'handle_process_visibility_backfill' ) );
		add_action( 'admin_post_ai_o_optimiser_add_near_miss_signature', array( $this, 'handle_add_near_miss_signature' ) );
		add_action( 'admin_post_ai_o_optimiser_dismiss_near_miss', array( $this, 'handle_dismiss_near_miss' ) );
		add_action( 'admin_post_ai_o_optimiser_clear_near_misses', array( $this, 'handle_clear_near_misses' ) );
	}

	/**
	 * Default plugin settings, used on first activation.
	 *
	 * @return array
	 */
	public static function default_settings() {
		return AI_O_Optimiser_Settings::defaults();
	}

	/**
	 * Read-only dashboard access for trusted non-admin content managers.
	 * Editors have edit_pages by default; all operational/configuration areas use
	 * the dedicated administrator-only AI-O Optimiser capability. Sites can narrow or
	 * broaden dashboard visibility deliberately with this filter.
	 *
	 * @return string
	 */
	public static function dashboard_capability() {
		return (string) apply_filters( 'ai_o_optimiser_dashboard_capability', 'edit_pages' );
	}

	/**
	 * Register the top-level "AI-O Optimiser" menu and its sub-pages.
	 */
	/**
	 * The AI-O mark, as the admin menu icon.
	 *
	 * WordPress takes a base64 SVG data URI here and paints it as a
	 * background image at 20px, dimmed to 60% until the item is hovered or
	 * current. It does not recolour it, so the mark is drawn in the same
	 * #a7aaad the other menu icons use rather than in brand colour - a
	 * full-colour logo would sit oddly against the rest of the sidebar and
	 * would not respond to those states.
	 *
	 * The SVG is kept here as readable markup and encoded at call time, so
	 * the shape stays inspectable in the source instead of being a base64
	 * blob. It is a simplified mark: the full logo is 294x160 and loses its
	 * detail entirely at 20px, so the swoosh, the ring and two of the dots
	 * carry it.
	 *
	 * The swoosh stops on the ring's band rather than at its centre. Its cap
	 * is round and 1.5 units long, so running it any further pushed the cap
	 * through the ring's inner edge and left a blob sitting in the hole. It
	 * now ends 3.21 from the ring centre, between the hole edge at 2.50 and
	 * the outer edge at 3.90 - close enough to merge with no gap, short
	 * enough to leave the hole clean.
	 *
	 * The ring is deliberately wide and thin-stroked. An earlier version used
	 * r=2.7 with a 1.7 stroke, which left a hole under 4px across at 20px:
	 * legible on a retina screen, closed up by antialiasing on an ordinary
	 * one. r=3.2 with a 1.4 stroke gives a 5px hole that survives at 1x.
	 *
	 * @return string data: URI for add_menu_page().
	 */
	private static function menu_icon() {
		$svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">'
			. '<g fill="none" stroke="#a7aaad" stroke-linecap="round">'
			. '<path d="M1.9 10.6c1.4 4.6 6.4 6.8 10.4 4.3 2.2-1.4 3.5-3.6 3.7-5.6" stroke-width="3"/>'
			. '<circle cx="16" cy="4.6" r="3.2" stroke-width="1.4"/>'
			. '</g>'
			/*
			 * Three dots, matching assets/ai-o-icon.png, which the in-page
			 * navigation uses. The sidebar mark had two, so the same logo drew
			 * differently depending which part of the plugin you looked at.
			 *
			 * Monochrome is deliberate and stays: a full-colour logo in the
			 * admin menu fights every colour scheme WordPress ships.
			 *
			 * The placement is measured, not eyeballed. At 20x20 the ring
			 * already reaches x=19.9, so a third dot beside it collides -- the
			 * first attempt overlapped it by 0.2 units and would have looked
			 * fused at real size. Up and to the left clears by 1.09 units, the
			 * widest gap available without redrawing the composition. Re-measure
			 * anything moved here; at this size the difference between separated
			 * and touching is about one unit.
			 */
			. '<g fill="#a7aaad">'
			. '<circle cx="3.0" cy="5.7" r="1.9"/>'
			. '<circle cx="7.9" cy="3.5" r="1.6"/>'
			. '<circle cx="11.0" cy="1.3" r="1.0"/>'
			. '</g>'
			. '</svg>';

		return 'data:image/svg+xml;base64,' . base64_encode( $svg ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode -- data URI for a menu icon, not obfuscation.
	}

	public function register_menu() {
		add_menu_page(
			__( 'AI-O Optimiser', 'ai-o-optimiser' ),
			__( 'AI-O Optimiser', 'ai-o-optimiser' ),
			self::dashboard_capability(),
			'ai-o-optimiser-dashboard',
			array( $this, 'render_dashboard' ),
			self::menu_icon(),
			80
		);

		add_submenu_page( 'ai-o-optimiser-dashboard', __( 'Dashboard', 'ai-o-optimiser' ), __( 'Dashboard', 'ai-o-optimiser' ), self::dashboard_capability(), 'ai-o-optimiser-dashboard', array( $this, 'render_dashboard' ), 1 );
		add_submenu_page( 'ai-o-optimiser-dashboard', __( 'Metadata', 'ai-o-optimiser' ), __( 'Metadata', 'ai-o-optimiser' ), self::CAPABILITY, 'ai-o-optimiser-optimise', array( $this, 'render_optimise' ), 10 );
		add_submenu_page( 'ai-o-optimiser-dashboard', __( 'Settings', 'ai-o-optimiser' ), __( 'Settings', 'ai-o-optimiser' ), self::SENSITIVE_CAPABILITY, 'ai-o-optimiser-settings', array( $this, 'render_settings' ), 60 );
		add_submenu_page( null, __( 'Notifications', 'ai-o-optimiser' ), __( 'Notifications', 'ai-o-optimiser' ), self::SENSITIVE_CAPABILITY, 'ai-o-optimiser-notifications', array( $this, 'render_notifications' ) );

		// Logs, AI Guidance Files, System Check, Safety Check and the AI Review
		// Prompt are configure-once / check-occasionally screens, not daily
		// workflow screens. They stay fully reachable at their existing URLs
		// (no broken links/emails/bookmarks) but no longer clutter the main
		// sidebar — they're grouped as tabs alongside Settings instead, via a
		// null parent slug (WordPress's documented way to register a page
		// without a visible menu entry).
		add_submenu_page( null, __( 'Logs', 'ai-o-optimiser' ), __( 'Logs', 'ai-o-optimiser' ), self::CAPABILITY, 'ai-o-optimiser-logs', array( $this, 'render_logs' ) );
		/*
		 * The Metadata Workflow slug is registered by the add-on when it is
		 * present (its own real screen, or its own locked state). When it is
		 * not, eleven links elsewhere in this admin still point at the slug --
		 * dashboard priority actions, the API-keys button on Settings,
		 * background-job rows -- so core registers it, hidden, to answer them
		 * with the absent-state presentation rather than "Sorry, you are not
		 * allowed to access this page".
		 */
		if ( ! class_exists( 'AI_O_Optimiser_Extensions' ) || ! AI_O_Optimiser_Extensions::is_available( 'metadata' ) ) {
			add_submenu_page( null, __( 'Metadata', 'ai-o-optimiser' ), __( 'Metadata', 'ai-o-optimiser' ), self::CAPABILITY, 'ai-o-optimiser-metadata-workflow', array( $this, 'render_optimise' ) );
		}
		add_submenu_page( null, __( 'AI Guidance Files', 'ai-o-optimiser' ), __( 'AI Guidance Files', 'ai-o-optimiser' ), self::CAPABILITY, 'ai-o-optimiser-guidance', array( 'AI_O_Optimiser_LLMS_Admin', 'render_admin_page' ) );
		add_submenu_page( null, __( 'Environmental Safety Check', 'ai-o-optimiser' ), __( 'Safety Check', 'ai-o-optimiser' ), self::CAPABILITY, 'ai-o-optimiser-environment-check', array( 'AI_O_Optimiser_Environment_Check', 'render_admin_page' ) );
		add_submenu_page( null, __( 'System Check', 'ai-o-optimiser' ), __( 'System Check', 'ai-o-optimiser' ), self::CAPABILITY, 'ai-o-optimiser-system-check', array( 'AI_O_Optimiser_System_Check', 'render_admin_page' ) );
		add_submenu_page( null, __( 'AI-O Optimiser Review Prompt', 'ai-o-optimiser' ), __( 'AI Review Prompt', 'ai-o-optimiser' ), self::CAPABILITY, 'ai-o-optimiser-deep-review-prompt', array( $this, 'render_deep_review_prompt' ) );
	}

	/**
	 * Force the exact intended sidebar order regardless of registration
	 * timing across plugins. add_submenu_page()'s numeric $position argument
	 * did not reliably produce the intended order once a second plugin
	 * (the legacy Metadata module) was registering into the same top-level menu — so
	 * this runs last, after every plugin's own admin_menu callback, and
	 * rebuilds the submenu array directly by slug instead of trusting
	 * position values to sort correctly across plugin boundaries.
	 */
	public function reorder_menu() {
		global $submenu;
		if ( empty( $submenu['ai-o-optimiser-dashboard'] ) || ! is_array( $submenu['ai-o-optimiser-dashboard'] ) ) {
			return;
		}

		$desired_order = array(
			'ai-o-optimiser-dashboard', // What is happening.
			'ai-o-optimiser-optimise',      // Metadata workflow.
			'ai-o-optimiser-schema-review', // Structured-data workflow.
			'ai-o-optimiser-settings',      // Administrator-only configuration and diagnostics.
		);

		$by_slug = array();
		foreach ( $submenu['ai-o-optimiser-dashboard'] as $item ) {
			$by_slug[ $item[2] ] = $item;
		}

		$ordered = array();
		foreach ( $desired_order as $slug ) {
			if ( isset( $by_slug[ $slug ] ) ) {
				$ordered[] = $by_slug[ $slug ];
				unset( $by_slug[ $slug ] );
			}
		}
		// Workflow/detail pages are registered with a null parent by their owning
		// modules. Do not register them under ai-o-optimiser-dashboard and then remove them
		// here: WordPress uses the parent relationship when validating direct admin
		// URLs, and stripping those submenu rows makes valid detail URLs fail with
		// a permissions error.
		$submenu['ai-o-optimiser-dashboard'] = $ordered;
	}

	/**
	 * Persistent in-window navigation for every AI-O Optimiser screen.
	 *
	 * Dashboard is intentionally the only area available to non-admin viewers.
	 * Operational, technical and configuration pages require the dedicated
	 * administrator capability and carry an explicit advanced-change warning.
	 */
	public function render_global_nav() {
		// phpcs:disable WordPress.Security.NonceVerification.Recommended -- Read-only screen state (filters, tab selection, pagination, redirect result notices). Nothing is written here, so there is no form submission to carry a nonce.
		$page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : '';
		$groups = array(
			'ai-o-optimiser-dashboard'             => 'dashboard',
			'ai-o-optimiser-optimise'              => 'metadata',
			'ai-o-optimiser-metadata-workflow'       => 'metadata',
			'ai-o-optimiser-content-opportunities' => 'metadata',
			'ai-o-optimiser-schema-review'         => 'schema',
			'ai-o-optimiser-system-check'          => 'settings',
			'ai-o-optimiser-guidance'              => 'settings',
			'ai-o-optimiser-environment-check'     => 'settings',
			'ai-o-optimiser-logs'                  => 'settings',
			'ai-o-optimiser-deep-review-prompt'    => 'settings',
			'ai-o-optimiser-settings'              => 'settings',
			'ai-o-optimiser-notifications'          => 'settings',
		);
		if ( ! isset( $groups[ $page ] ) ) {
			return;
		}

		$active   = $groups[ $page ];
		$is_admin = current_user_can( self::CAPABILITY );
		$items    = array(
			'dashboard' => array( 'label' => __( 'Dashboard', 'ai-o-optimiser' ), 'url' => admin_url( 'admin.php?page=ai-o-optimiser-dashboard' ) ),
		);
		if ( $is_admin ) {
			$items['metadata'] = array( 'label' => __( 'Metadata', 'ai-o-optimiser' ), 'url' => admin_url( 'admin.php?page=ai-o-optimiser-optimise' ) );
			$items['schema']   = array( 'label' => __( 'Schema', 'ai-o-optimiser' ), 'url' => admin_url( 'admin.php?page=ai-o-optimiser-schema-review' ) );
			$items['settings'] = array( 'label' => __( 'Settings', 'ai-o-optimiser' ), 'url' => admin_url( 'admin.php?page=ai-o-optimiser-settings' ) );
		}
		?>
		<div class="ai-o-optimiser-global-nav-shell">
			<div class="ai-o-optimiser-global-nav">
				<strong class="ai-o-optimiser-global-nav-brand"><?php esc_html_e( 'AI-O Optimiser', 'ai-o-optimiser' ); ?></strong>
				<nav aria-label="<?php esc_attr_e( 'AI-O Optimiser navigation', 'ai-o-optimiser' ); ?>">
					<?php foreach ( $items as $slug => $item ) : ?>
						<a class="<?php echo $slug === $active ? 'is-active' : ''; ?>" href="<?php echo esc_url( $item['url'] ); ?>"><?php echo esc_html( $item['label'] ); ?></a>
					<?php endforeach; ?>
				</nav>
				<?php if ( ! $is_admin ) : ?><span class="ai-o-optimiser-global-nav-role"><?php esc_html_e( 'Dashboard view', 'ai-o-optimiser' ); ?></span><?php endif; ?>
			</div>
			<?php if ( $is_admin && 'dashboard' !== $active ) : ?>
				<div class="ai-o-optimiser-advanced-change-warning"><strong><?php esc_html_e( 'Advanced admin area', 'ai-o-optimiser' ); ?></strong><span><?php esc_html_e( 'Changes here can affect site behaviour, search visibility, crawler access, tracking or performance. Review the current state and recommendation before changing settings or applying actions.', 'ai-o-optimiser' ); ?></span></div>
			<?php endif; ?>
		</div>
		<?php
		// phpcs:enable WordPress.Security.NonceVerification.Recommended
	}

	/**
	 * Shared tab bar linking Settings, AI Guidance Files, System Check, Safety
	 * Check and the AI Review Prompt — the configure-once/diagnose-occasionally
	 * screens. Each tab is still its own admin page (own hook, own admin_post
	 * actions, own redirects); this only adds a consistent way to move between
	 * them without a full page reload landing back at the top of a long screen.
	 *
	 * @param string $active_slug One of 'settings', 'notifications', 'logs', 'guidance', 'system-check', 'safety-check', 'review-prompt'.
	 */
	/**
	 * Compact queue counts used by the primary area landing pages.
	 *
	 * @return array
	 */
	public static function metadata_queue_counts() {
		global $wpdb;
		$table = $wpdb->prefix . 'ai_o_optimiser_metadata_queue';
		$counts = array( 'queued' => 0, 'processing' => 0, 'suggested' => 0, 'applied' => 0, 'skipped' => 0, 'error' => 0 );
		if ( ! AI_O_Optimiser_Persistence::table_exists( $table ) ) {
			return $counts;
		}
		$rows = AI_O_Optimiser_Persistence::cached_results(
			'metadata_queue_status_counts',
			$wpdb->prepare( 'SELECT status, COUNT(*) AS total FROM %i GROUP BY status', $table ),
			OBJECT,
			30
		);
		foreach ( $rows as $row ) {
			if ( isset( $counts[ $row->status ] ) ) {
				$counts[ $row->status ] = (int) $row->total;
			}
		}
		return $counts;
	}

	/**
	 * Build the compact cross-module notification list for Settings → Notifications.
	 *
	 * @return array
	 */
	private function needs_attention_items() {
		$items  = array();
		$counts = self::metadata_queue_counts();
		$api    = get_option( 'ai_o_optimiser_metadata_api_test', array() );
		$api    = is_array( $api ) ? $api : array();

		if ( ! empty( $counts['error'] ) ) {
			$items[] = array(
				'label' => sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					_n( '%s metadata item failed', '%s metadata items failed', $counts['error'], 'ai-o-optimiser' ), number_format_i18n( $counts['error'] ) ),
				'note'  => __( 'Fix the AI connection once, then re-add the failed batch to the queue.', 'ai-o-optimiser' ),
				'url'   => admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=review&status=error' ),
				'action'=> __( 'Review failures', 'ai-o-optimiser' ),
				'level' => 'warning',
			);
		}
		if ( ! empty( $counts['queued'] ) && isset( $api['status'] ) && ! in_array( $api['status'], array( 'ok', 'not_tested' ), true ) ) {
			$items[] = array(
				'label' => __( 'Metadata generation cannot use the current AI provider', 'ai-o-optimiser' ),
				'note'  => isset( $api['message'] ) ? wp_strip_all_tags( $api['message'] ) : __( 'Reconnect or add a direct provider key.', 'ai-o-optimiser' ),
				'url'   => admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=settings#ai-o-optimiser-metadata-api-keys' ),
				'action'=> __( 'Fix AI connection', 'ai-o-optimiser' ),
				'level' => 'fail',
			);
		}
		if ( '1' === (string) get_option( 'ai_o_optimiser_metadata_queue_paused', '0' ) && ! empty( $counts['queued'] ) ) {
			$items[] = array(
				'label' => __( 'Metadata generation is paused', 'ai-o-optimiser' ),
				'note'  => sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( '%s queued items are waiting.', 'ai-o-optimiser' ), number_format_i18n( $counts['queued'] ) ),
				'url'   => admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow' ),
				'action'=> __( 'Open queue controls', 'ai-o-optimiser' ),
				'level' => 'warning',
			);
		}

		$health = class_exists( 'AI_O_Optimiser_System_Check' ) ? AI_O_Optimiser_System_Check::health_report() : array();
		if ( ! empty( $health['overall'] ) && in_array( $health['overall'], array( 'warning', 'fail' ), true ) ) {
			$items[] = array(
				'label' => __( 'Nightly technical health needs review', 'ai-o-optimiser' ),
				'note'  => __( 'A crawlability, robots, guidance-file or key-page check reported a warning.', 'ai-o-optimiser' ),
				'url'   => admin_url( 'admin.php?page=ai-o-optimiser-system-check' ),
				'action'=> __( 'Review technical health', 'ai-o-optimiser' ),
				'level' => $health['overall'],
			);
		}

		$storage = AI_O_Optimiser_DB::storage_report();
		if ( ! empty( $storage['total_bytes'] ) && (int) $storage['total_bytes'] > 75 * MB_IN_BYTES ) {
			$items[] = array(
				'label' => __( 'AI-O Optimiser storage is above 75 MB', 'ai-o-optimiser' ),
				'note'  => __( 'The v1.17 compact aggregate migration will shrink long-term visibility storage after backfill completes.', 'ai-o-optimiser' ),
				'url'   => admin_url( 'admin.php?page=ai-o-optimiser-settings#ai-o-optimiser-storage-guardrails' ),
				'action'=> __( 'Review storage', 'ai-o-optimiser' ),
				'level' => 'warning',
			);
		}
		return array_slice( $items, 0, 5 );
	}

	/** Render the cross-module notification panel. */
	private function render_needs_attention() {
		if ( ! current_user_can( self::CAPABILITY ) ) { return; }
		$items = $this->needs_attention_items();
		?>
		<section class="ai-o-optimiser-panel ai-o-optimiser-attention-panel">
			<div class="ai-o-optimiser-section-heading-row">
				<div><h2><?php esc_html_e( 'Needs attention', 'ai-o-optimiser' ); ?></h2><p class="description"><?php esc_html_e( 'Only unresolved items that may block useful reporting or scheduled work appear here.', 'ai-o-optimiser' ); ?></p></div>
				<span class="ai-o-optimiser-badge <?php echo empty( $items ) ? 'ai-o-optimiser-badge-allowed' : 'ai-o-optimiser-badge-context'; ?>"><?php echo empty( $items ) ? esc_html__( 'All clear', 'ai-o-optimiser' ) : esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					_n( '%s item', '%s items', count( $items ), 'ai-o-optimiser' ), number_format_i18n( count( $items ) ) ) ); ?></span>
			</div>
			<?php if ( empty( $items ) ) : ?>
				<p><?php esc_html_e( 'No current AI-O Optimiser action is blocking normal monitoring or optimisation work.', 'ai-o-optimiser' ); ?></p>
			<?php else : ?>
				<div class="ai-o-optimiser-attention-list">
					<?php foreach ( $items as $item ) : ?>
						<div class="ai-o-optimiser-attention-item"><div><strong><?php echo esc_html( $item['label'] ); ?></strong><span><?php echo esc_html( $item['note'] ); ?></span></div><a class="button" href="<?php echo esc_url( $item['url'] ); ?>"><?php echo esc_html( $item['action'] ); ?></a></div>
					<?php endforeach; ?>
				</div>
			<?php endif; ?>
		</section>
		<?php
	}

	/**
	 * Render a single background-work overview shared across modules.
	 */
	private function render_background_jobs() {
		if ( ! current_user_can( self::CAPABILITY ) ) { return; }
		$counts = self::metadata_queue_counts();
		$seo_settings = wp_parse_args( get_option( 'ai_o_optimiser_metadata_settings', array() ), array( 'auto_generate_enabled' => '0' ) );
		$paused = '1' === (string) get_option( 'ai_o_optimiser_metadata_queue_paused', '0' );
		$next_metadata = wp_next_scheduled( 'ai_o_optimiser_metadata_auto_generate' );
		$next_health   = wp_next_scheduled( AI_O_Optimiser_NIGHTLY_HEALTH_HOOK );
		$aggregate     = AI_O_Optimiser_DB::aggregate_state();
		$aggregate_total = max( 0, (int) ( $aggregate['max_id'] ?? 0 ) );
		$aggregate_done  = min( $aggregate_total, max( 0, (int) ( $aggregate['last_id'] ?? 0 ) ) );
		?>
		<details class="ai-o-optimiser-panel ai-o-optimiser-background-jobs">
			<summary><strong><?php esc_html_e( 'Background jobs', 'ai-o-optimiser' ); ?></strong> <span class="description"><?php esc_html_e( 'One place to see whether scheduled AI-O Optimiser work is running, paused or waiting.', 'ai-o-optimiser' ); ?></span></summary>
			<div class="ai-o-optimiser-job-grid">
				<div><strong><?php esc_html_e( 'Metadata generation', 'ai-o-optimiser' ); ?></strong><span><?php echo $paused ? esc_html__( 'Paused', 'ai-o-optimiser' ) : ( ! empty( $seo_settings['auto_generate_enabled'] ) ? esc_html__( 'Running', 'ai-o-optimiser' ) : esc_html__( 'Manual', 'ai-o-optimiser' ) ); ?></span><small><?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( '%s queued', 'ai-o-optimiser' ), number_format_i18n( $counts['queued'] ) ) ); ?><?php if ( $next_metadata ) : ?> · <?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( 'next %s', 'ai-o-optimiser' ), wp_date( 'j M, g:i a', $next_metadata, wp_timezone() ) ) ); ?><?php endif; ?></small><a href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow' ) ); ?>"><?php esc_html_e( 'Manage', 'ai-o-optimiser' ); ?></a></div>
				<div><strong><?php esc_html_e( 'Nightly health', 'ai-o-optimiser' ); ?></strong><span><?php echo $next_health ? esc_html__( 'Scheduled', 'ai-o-optimiser' ) : esc_html__( 'Disabled', 'ai-o-optimiser' ); ?></span><small><?php echo $next_health ? esc_html( wp_date( 'j M, g:i a', $next_health, wp_timezone() ) ) : esc_html__( 'Enable in Settings', 'ai-o-optimiser' ); ?></small><a href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-settings#ai-o-optimiser-nightly-health-monitor-setting' ) ); ?>"><?php esc_html_e( 'Manage', 'ai-o-optimiser' ); ?></a></div>
				<div><strong><?php esc_html_e( 'Visibility storage migration', 'ai-o-optimiser' ); ?></strong><span><?php echo ! empty( $aggregate['complete'] ) ? esc_html__( 'Complete', 'ai-o-optimiser' ) : esc_html__( 'Migrating', 'ai-o-optimiser' ); ?></span><small><?php echo ! empty( $aggregate['complete'] ) ? esc_html__( 'Long-term reports use compact daily aggregates.', 'ai-o-optimiser' ) : esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( '%1$s / %2$s historic rows aggregated', 'ai-o-optimiser' ), number_format_i18n( $aggregate_done ), number_format_i18n( $aggregate_total ) ) ); ?></small><a href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-settings#ai-o-optimiser-storage-guardrails' ) ); ?>"><?php esc_html_e( 'Storage', 'ai-o-optimiser' ); ?></a></div>
			</div>
		</details>
		<?php
	}

	/**
	 * Monthly Activity Report panel: pick a month, export AI traffic, Metadata
	 * and Schema activity as CSV, XML or a print-to-PDF page.
	 */
	private function render_monthly_report_panel() {
		if ( ! current_user_can( self::CAPABILITY ) || ! class_exists( 'AI_O_Optimiser_Monthly_Report' ) ) {
			return;
		}
		?>
		<details class="ai-o-optimiser-panel ai-o-optimiser-monthly-report-panel">
			<summary><strong><?php esc_html_e( 'Monthly Activity Report', 'ai-o-optimiser' ); ?></strong> <span class="description"><?php esc_html_e( 'AI traffic, Metadata activity and Schema activity for one month, for sharing as an activity-transparency report.', 'ai-o-optimiser' ); ?></span></summary>
			<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="ai-o-optimiser-monthly-report-form">
				<?php wp_nonce_field( 'ai_o_optimiser_monthly_report' ); ?>
				<input type="hidden" name="action" value="ai_o_optimiser_monthly_report" />
				<label for="ai-o-optimiser-monthly-report-month"><?php esc_html_e( 'Month:', 'ai-o-optimiser' ); ?></label>
				<select id="ai-o-optimiser-monthly-report-month" name="month">
					<?php foreach ( AI_O_Optimiser_Monthly_Report::month_options() as $value => $label ) : ?>
						<option value="<?php echo esc_attr( $value ); ?>"><?php echo esc_html( $label ); ?></option>
					<?php endforeach; ?>
				</select>
				<button type="submit" name="format" value="pdf" formtarget="_blank" class="button button-primary"><?php esc_html_e( 'View / Save as PDF', 'ai-o-optimiser' ); ?></button>
				<button type="submit" name="format" value="csv" class="button"><?php esc_html_e( 'Download CSV', 'ai-o-optimiser' ); ?></button>
				<button type="submit" name="format" value="xml" class="button"><?php esc_html_e( 'Download XML', 'ai-o-optimiser' ); ?></button>
			</form>
			<p class="description"><?php esc_html_e( 'Schema activity is only recorded from the version that added this report onward — earlier months will show no schema data even if scans or fixes happened then.', 'ai-o-optimiser' ); ?></p>
		</details>
		<?php
	}

	/** Process one bounded visibility aggregate backfill batch from Settings. */
	public function handle_process_visibility_backfill() {
		if ( ! current_user_can( self::CAPABILITY ) || ! check_admin_referer( 'ai_o_optimiser_process_visibility_backfill' ) ) {
			wp_die( esc_html__( 'You are not allowed to do that.', 'ai-o-optimiser' ) );
		}

		AI_O_Optimiser_DB::process_aggregate_backfill( 5000 );
		AI_O_Optimiser_DB::ensure_aggregate_backfill_scheduled();
		$state = AI_O_Optimiser_DB::aggregate_state();
		$status = ! empty( $state['complete'] ) ? 'complete' : 'progress';
		$url = add_query_arg( 'ai_o_optimiser_storage_backfill', $status, admin_url( 'admin.php?page=ai-o-optimiser-settings' ) ) . '#ai-o-optimiser-storage-guardrails';
		wp_safe_redirect( $url );
		exit;
	}

	/** Primary Metadata area: metadata, search-demand and content workflows. */
	/**
	 * The Metadata entry point. Core owns the URL; the add-on owns the screen.
	 *
	 * Core ships this method unmodified in the WordPress.org package. What it
	 * renders is whatever the Pro add-on registered for 'metadata' through
	 * AI_O_Optimiser_Extensions (the add-on's own workspace, or its own
	 * workspace-locked state -- that decision is the add-on's), and core's
	 * absent-state presentation when nothing is registered, i.e. when the
	 * add-on is not installed. See class-ai-o-optimiser-extensions.php.
	 */
	public function render_optimise() {
		if ( ! current_user_can( self::CAPABILITY ) ) { return; }
		if ( class_exists( 'AI_O_Optimiser_Extensions' ) && AI_O_Optimiser_Extensions::render( 'metadata' ) ) {
			return;
		}
		$pro_features = AI_O_Optimiser_PLUGIN_DIR . 'includes/class-ai-o-optimiser-pro-features.php';
		if ( is_readable( $pro_features ) ) {
			require_once $pro_features;
			AI_O_Optimiser_Pro_Features::render_workspace( 'metadata' );
		}
	}

	/**
	 * The Metadata hub: the cards and workload summary the add-on registers as
	 * its 'metadata' renderer (modules/metadata/bootstrap.php), kept here as a
	 * static because the queue-count query it opens with is core's, shared
	 * with Settings -> Notifications.
	 *
	 * @param array $counts Queue status counts from metadata_queue_counts().
	 * @return void
	 */
	public static function render_metadata_hub( array $counts ) {
		$metadata_generated = (int) $counts['suggested'] + (int) $counts['error'];
		$metadata_active_total = (int) $counts['queued'] + (int) $counts['processing'] + $metadata_generated;
		$metadata_progress = $metadata_active_total > 0 ? min( 100, (int) round( ( $metadata_generated / $metadata_active_total ) * 100 ) ) : 0;
		?>
		<div class="wrap ai-o-optimiser-wrap"><h1><?php esc_html_e( 'Metadata', 'ai-o-optimiser' ); ?></h1><p class="description"><?php esc_html_e( 'Scan, generate, review and improve search metadata, then use search evidence to identify related content opportunities.', 'ai-o-optimiser' ); ?></p>
			<div class="ai-o-optimiser-area-grid">
				<a class="ai-o-optimiser-area-card" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=scan' ) ); ?>">
					<span class="ai-o-optimiser-area-card-icon dashicons dashicons-search" aria-hidden="true"></span>
					<strong><?php esc_html_e( 'Metadata Scan', 'ai-o-optimiser' ); ?></strong>
					<span class="ai-o-optimiser-area-card-copy"><?php esc_html_e( 'Find weak or missing Rank Math titles, descriptions and focus keywords.', 'ai-o-optimiser' ); ?></span>
					<small><?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
						__( '%s currently queued', 'ai-o-optimiser' ), number_format_i18n( $counts['queued'] ) ) ); ?></small>
					<span class="ai-o-optimiser-area-card-action"><?php esc_html_e( 'Open scan', 'ai-o-optimiser' ); ?><span aria-hidden="true">→</span></span>
				</a>
				<a class="ai-o-optimiser-area-card" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=review' ) ); ?>">
					<span class="ai-o-optimiser-area-card-icon dashicons dashicons-list-view" aria-hidden="true"></span>
					<strong><?php esc_html_e( 'Metadata Queue', 'ai-o-optimiser' ); ?></strong>
					<span class="ai-o-optimiser-area-card-copy"><?php esc_html_e( 'Generate, review, apply or retry metadata suggestions.', 'ai-o-optimiser' ); ?></span>
					<small><?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
						__( '%1$s ready · %2$s failed', 'ai-o-optimiser' ), number_format_i18n( $counts['suggested'] ), number_format_i18n( $counts['error'] ) ) ); ?></small>
					<span class="ai-o-optimiser-area-card-action"><?php esc_html_e( 'Review queue', 'ai-o-optimiser' ); ?><span aria-hidden="true">→</span></span>
				</a>
				<a class="ai-o-optimiser-area-card" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=opportunities' ) ); ?>">
					<span class="ai-o-optimiser-area-card-icon dashicons dashicons-chart-line" aria-hidden="true"></span>
					<strong><?php esc_html_e( 'Search Opportunities', 'ai-o-optimiser' ); ?></strong>
					<span class="ai-o-optimiser-area-card-copy"><?php esc_html_e( 'Connect Google Search Console and Bing Webmaster, then review demand data to decide what content is worth creating or strengthening.', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-area-card-action"><?php esc_html_e( 'Explore opportunities', 'ai-o-optimiser' ); ?><span aria-hidden="true">→</span></span>
				</a>
				<a class="ai-o-optimiser-area-card" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=categories' ) ); ?>">
					<span class="ai-o-optimiser-area-card-icon dashicons dashicons-category" aria-hidden="true"></span>
					<strong><?php esc_html_e( 'Category Review', 'ai-o-optimiser' ); ?></strong>
					<span class="ai-o-optimiser-area-card-copy"><?php esc_html_e( 'Keep categories purposeful and prevent archives from becoming accidental content hubs.', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-area-card-action"><?php esc_html_e( 'Review categories', 'ai-o-optimiser' ); ?><span aria-hidden="true">→</span></span>
				</a>
				<a class="ai-o-optimiser-area-card" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-content-opportunities' ) ); ?>">
					<span class="ai-o-optimiser-area-card-icon dashicons dashicons-media-document" aria-hidden="true"></span>
					<strong><?php esc_html_e( 'Content Opportunities', 'ai-o-optimiser' ); ?></strong>
					<span class="ai-o-optimiser-area-card-copy"><?php esc_html_e( 'Connect Google Search Console (or manage an existing connection) and use its evidence to prioritise pages and queries already close to earning more visibility.', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-area-card-action"><?php esc_html_e( 'View opportunities', 'ai-o-optimiser' ); ?><span aria-hidden="true">→</span></span>
				</a>
			</div>
			<section class="ai-o-optimiser-panel ai-o-optimiser-optimise-workload">
				<div class="ai-o-optimiser-section-heading-row">
					<div><h2><?php esc_html_e( 'Current metadata workload', 'ai-o-optimiser' ); ?></h2><p class="description"><?php esc_html_e( 'A quick operational view of work already in the metadata queue.', 'ai-o-optimiser' ); ?></p></div>
					<span class="ai-o-optimiser-badge <?php echo ! empty( $counts['error'] ) ? 'ai-o-optimiser-badge-context' : 'ai-o-optimiser-badge-allowed'; ?>"><?php echo ! empty( $counts['error'] ) ? esc_html__( 'Review needed', 'ai-o-optimiser' ) : esc_html__( 'On track', 'ai-o-optimiser' ); ?></span>
				</div>
				<?php if ( $metadata_active_total > 0 ) : ?>
					<div class="ai-o-optimiser-work-progress" aria-label="<?php esc_attr_e( 'Metadata generation progress', 'ai-o-optimiser' ); ?>">
						<div class="ai-o-optimiser-work-progress-head"><span><?php esc_html_e( 'Generation progress', 'ai-o-optimiser' ); ?></span><strong><?php echo esc_html( $metadata_progress . '%' ); ?></strong></div>
						<div class="ai-o-optimiser-work-progress-track" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="<?php echo esc_attr( (string) $metadata_progress ); ?>"><span style="width:<?php echo esc_attr( (string) $metadata_progress ); ?>%"></span></div>
						<p class="description"><?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
							__( '%1$s of %2$s active items generated. Ready items are waiting for review; failed items need attention.', 'ai-o-optimiser' ), number_format_i18n( $metadata_generated ), number_format_i18n( $metadata_active_total ) ) ); ?></p>
					</div>
				<?php else : ?>
					<div class="ai-o-optimiser-work-progress ai-o-optimiser-work-progress-empty"><div class="ai-o-optimiser-work-progress-head"><span><?php esc_html_e( 'Generation progress', 'ai-o-optimiser' ); ?></span><strong><?php esc_html_e( 'No active queue', 'ai-o-optimiser' ); ?></strong></div><p class="description"><?php esc_html_e( 'Run a metadata scan to add content for generation and review.', 'ai-o-optimiser' ); ?></p></div>
				<?php endif; ?>
				<div class="ai-o-optimiser-job-grid">
					<div><strong><?php esc_html_e( 'Queued', 'ai-o-optimiser' ); ?></strong><span><?php echo esc_html( number_format_i18n( $counts['queued'] ) ); ?></span><small><?php esc_html_e( 'Waiting for generation', 'ai-o-optimiser' ); ?></small></div>
					<div><strong><?php esc_html_e( 'Ready to review', 'ai-o-optimiser' ); ?></strong><span><?php echo esc_html( number_format_i18n( $counts['suggested'] ) ); ?></span><small><?php esc_html_e( 'Suggestions generated', 'ai-o-optimiser' ); ?></small></div>
					<div><strong><?php esc_html_e( 'Failed', 'ai-o-optimiser' ); ?></strong><span><?php echo esc_html( number_format_i18n( $counts['error'] ) ); ?></span><small><?php esc_html_e( 'Fix provider issues, then retry', 'ai-o-optimiser' ); ?></small></div>
					<div><strong><?php esc_html_e( 'Applied', 'ai-o-optimiser' ); ?></strong><span><?php echo esc_html( number_format_i18n( $counts['applied'] ) ); ?></span><small><?php esc_html_e( 'Written to live SEO metadata', 'ai-o-optimiser' ); ?></small></div>
				</div>
				<p class="ai-o-optimiser-inline-actions"><a class="button button-primary" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=review&status=suggested' ) ); ?>"><?php esc_html_e( 'Review ready metadata', 'ai-o-optimiser' ); ?></a> <a class="button" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=scan' ) ); ?>"><?php esc_html_e( 'Run metadata scan', 'ai-o-optimiser' ); ?></a><?php if ( ! empty( $counts['error'] ) ) : ?> <a class="button" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=review&status=error' ) ); ?>"><?php esc_html_e( 'Review failed items', 'ai-o-optimiser' ); ?></a><?php endif; ?></p>
			</section>
		</div><?php
	}

	/**
	 * Print the Visibility Dash section row.
	 *
	 * These are anchors that scroll the dashboard, not a tab switcher, so they
	 * work with or without JavaScript. What did not was the placement: the row
	 * was printed here and appended to the shared slot by an inline script
	 * after first paint. The primary navigation prints it into the slot now.
	 */
	public static function render_dashboard_tab_nav() {
		if ( self::$dashboard_tab_nav_rendered ) {
			return;
		}
		self::$dashboard_tab_nav_rendered = true;
		$tabs = array(
			'ai-o-optimiser-ai-brands'            => __( 'AI brands', 'ai-o-optimiser' ),
			'ai-o-optimiser-visibility-overview'  => __( 'Overview', 'ai-o-optimiser' ),
			'ai-o-optimiser-ai-league'            => __( 'League table', 'ai-o-optimiser' ),
			'ai-o-optimiser-traffic-impact'       => __( 'Traffic impact', 'ai-o-optimiser' ),
			'ai-o-optimiser-page-detail'          => __( 'Pages', 'ai-o-optimiser' ),
		);
		echo '<nav id="ai-o-optimiser-dashboard-tabs" class="ai-o-optimiser-visibility-tabs" aria-label="' . esc_attr__( 'Visibility dashboard sections', 'ai-o-optimiser' ) . '">';
		$first = true;
		foreach ( $tabs as $anchor => $label ) {
			printf(
				'<a href="#%1$s"%2$s>%3$s</a>',
				esc_attr( $anchor ),
				$first ? ' class="is-active"' : '',
				esc_html( $label )
			);
			$first = false;
		}
		echo '</nav>';
	}

	/**
	 * Print the dashboard row into the shell, on the dashboard only.
	 *
	 * @param string $active Primary navigation group.
	 * @param string $page   Current admin page slug.
	 */
	public static function render_secondary_nav( $active, $page ) {
		if ( 'dashboard' !== $active || 'ai-o-optimiser-dashboard' !== $page ) {
			return;
		}
		self::render_dashboard_tab_nav();
	}

	public static function render_settings_tabs( $active_slug ) {
		// The diagnostic screens live behind the Health section of Settings.
		// Until 1.27.1 they shared one flat strip with a "Settings" link, which
		// read as ten peers once the section tabs were added beside them. Logs
		// and the AI review prompt remain secondary tools rather than navigation
		// items; they simply show Health as the active section.
		//
		// AI Guidance Files was the fourth of them and is not here as of 1.37.1.
		// The rail carries it under Publish, so listing it here printed the same
		// label, marked open, in two navigations about 150px apart -- which is
		// the thing the rail was built to stop rather than to cause. What is left
		// is the screens that belong to the rail's Health & checks item: that is
		// secondary navigation inside one rail item, not a second copy of one.
		// See AI_O_Optimiser_Admin_Rail::groups().
		$tabs = array();
		if ( current_user_can( self::SENSITIVE_CAPABILITY ) ) {
			$tabs['notifications'] = array( 'label' => __( 'Notifications', 'ai-o-optimiser' ), 'url' => admin_url( 'admin.php?page=ai-o-optimiser-notifications' ) );
		}
		$tabs['system-check'] = array( 'label' => __( 'System Check', 'ai-o-optimiser' ), 'url' => admin_url( 'admin.php?page=ai-o-optimiser-system-check' ) );
		$tabs['safety-check'] = array( 'label' => __( 'Environment & storage', 'ai-o-optimiser' ), 'url' => admin_url( 'admin.php?page=ai-o-optimiser-environment-check' ) );

		AI_O_Optimiser_Settings_Navigation::render( $active_slug, $tabs );
	}

	/**
	 * Load the plugin's small admin stylesheet, only on our own screens.
	 *
	 * @param string $hook Current admin page hook.
	 */
	public function enqueue_assets( $hook ) {
		if ( strpos( $hook, 'ai-o-optimiser-' ) === false ) {
			return;
		}
		$css_path = AI_O_Optimiser_PLUGIN_DIR . 'assets/admin.css';
		$css_ver  = file_exists( $css_path ) ? AI_O_Optimiser_VERSION . '.' . filemtime( $css_path ) : AI_O_Optimiser_VERSION;
		wp_enqueue_style( 'ai-o-optimiser-admin', AI_O_Optimiser_PLUGIN_URL . 'assets/admin.css', array(), $css_ver );

		$consistency_path = AI_O_Optimiser_PLUGIN_DIR . 'assets/admin-modules.css';
		$consistency_ver  = file_exists( $consistency_path ) ? AI_O_Optimiser_VERSION . '.' . filemtime( $consistency_path ) : AI_O_Optimiser_VERSION;
		wp_enqueue_style( 'ai-o-optimiser-admin-modules', AI_O_Optimiser_PLUGIN_URL . 'assets/admin-modules.css', array( 'ai-o-optimiser-admin' ), $consistency_ver );

		$guard_path = AI_O_Optimiser_PLUGIN_DIR . 'assets/admin-notice-guard.js';
		$guard_ver  = file_exists( $guard_path ) ? AI_O_Optimiser_VERSION . '.' . filemtime( $guard_path ) : AI_O_Optimiser_VERSION;
		wp_enqueue_script( 'ai-o-optimiser-admin-notice-guard', AI_O_Optimiser_PLUGIN_URL . 'assets/admin-notice-guard.js', array(), $guard_ver, true );

		// Hover and keyboard focus on the signal "?" explainers are pure CSS. This
		// adds only tap-to-toggle and Escape-to-dismiss, so the definitions still
		// work with the script blocked.
		$hints_path = AI_O_Optimiser_PLUGIN_DIR . 'assets/admin-signal-hints.js';
		$hints_ver  = file_exists( $hints_path ) ? AI_O_Optimiser_VERSION . '.' . filemtime( $hints_path ) : AI_O_Optimiser_VERSION;
		wp_enqueue_script( 'ai-o-optimiser-admin-signal-hints', AI_O_Optimiser_PLUGIN_URL . 'assets/admin-signal-hints.js', array(), $hints_ver, true );

		/*
		 * A dependency-free handle that exists only to carry inline scripts.
		 *
		 * Several screens need a few lines of behaviour that depend on a
		 * translated string or on which page is being rendered, so they cannot
		 * be a static .js file. They used to be printed as raw <script> blocks
		 * on admin_footer, which works but bypasses the dependency and
		 * versioning machinery entirely -- and is what the plugin directory
		 * asks authors not to do.
		 *
		 * wp_register_script() with a false src is WordPress's own idiom for
		 * this: no file is fetched, and wp_add_inline_script() has a handle to
		 * attach to. Registered in the footer so the markup it operates on
		 * exists by the time it runs, and inline additions append in the order
		 * they are added, which preserves the ordering the old admin_footer
		 * priorities gave.
		 */
		wp_register_script( self::INLINE_HANDLE, false, array(), AI_O_Optimiser_VERSION, true );
		wp_enqueue_script( self::INLINE_HANDLE );

		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Screen routing only; nothing is written.
		$page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : '';
		if ( 'ai-o-optimiser-dashboard' === $page ) {
			$this->enqueue_visibility_layout_guard();
		}
		if ( in_array( $page, array( 'ai-o-optimiser-local-discovery', 'ai-o-optimiser-schema-review', 'ai-o-optimiser-metadata-workflow', 'ai-o-optimiser-optimise' ), true ) && class_exists( 'AI_O_Optimiser_Workspace_Landing', false ) ) {
			AI_O_Optimiser_Workspace_Landing::enqueue();
		}
		if ( 'ai-o-optimiser-deep-review-prompt' === $page ) {
			$copy_path = AI_O_Optimiser_PLUGIN_DIR . 'assets/admin-deep-review-prompt.js';
			$copy_ver  = file_exists( $copy_path ) ? AI_O_Optimiser_VERSION . '.' . filemtime( $copy_path ) : AI_O_Optimiser_VERSION;
			wp_enqueue_script( 'ai-o-optimiser-admin-deep-review-prompt', AI_O_Optimiser_PLUGIN_URL . 'assets/admin-deep-review-prompt.js', array(), $copy_ver, true );
			wp_add_inline_script(
				'ai-o-optimiser-admin-deep-review-prompt',
				'window.aiOOptimiserDeepReviewPrompt = ' . wp_json_encode(
					array(
						'labels' => array(
							'copied' => __( 'Copied.', 'ai-o-optimiser' ),
							'failed' => __( 'Copy failed. Select the text and copy manually.', 'ai-o-optimiser' ),
						),
					)
				) . ';',
				'before'
			);
		}
	}

	/**
	 * Attach inline CSS to the plugin's own stylesheet.
	 *
	 * A thin wrapper so callers do not each have to know the style handle, and
	 * so a screen that somehow renders without the stylesheet drops its inline
	 * CSS rather than emitting a stray <style> block.
	 *
	 * @param string $css Stylesheet fragment.
	 * @return void
	 */
	public static function add_inline_style( $css ) {
		$css = trim( (string) $css );
		if ( '' === $css || ! wp_style_is( 'ai-o-optimiser-admin', 'enqueued' ) ) {
			return;
		}
		wp_add_inline_style( 'ai-o-optimiser-admin', $css );
	}

	/**
	 * Attach inline JavaScript to the plugin's inline-script handle.
	 *
	 * @param string $js Script body, without <script> tags.
	 * @return void
	 */
	public static function add_inline_script( $js ) {
		$js = trim( (string) $js );
		if ( '' === $js || ! wp_script_is( self::INLINE_HANDLE, 'enqueued' ) ) {
			return;
		}
		wp_add_inline_script( self::INLINE_HANDLE, $js );
	}

	/**
	 * One definition per signal term, used everywhere the term is shown.
	 *
	 * These four words are the vocabulary of every AI activity screen, and until
	 * now the only place they were defined was a single run-on sentence under one
	 * table -- so the league table, the coverage table and the brand cards all
	 * used them with no way to find out what they meant. Defining them once, here,
	 * is also what stops the four screens drifting into four slightly different
	 * definitions of "referral".
	 *
	 * @return array Term key => label and one-sentence meaning.
	 */
	private function signal_glossary() {
		return array(
			'discovery' => array(
				'label' => __( 'Discovery / index', 'ai-o-optimiser' ),
				'text'  => __( 'Automated background access. An AI company\'s crawler reading your pages to build or refresh its index, not in response to anyone asking a question right now. High numbers mean your site is being collected; they do not mean anyone saw it.', 'ai-o-optimiser' ),
			),
			'live'      => array(
				'label' => __( 'Live AI fetch', 'ai-o-optimiser' ),
				'text'  => __( 'Real-time retrieval. An AI service fetched this page while answering someone\'s question, so the page had a chance to shape that answer. This is the signal closest to being cited.', 'ai-o-optimiser' ),
			),
			'referral'  => array(
				'label' => __( 'Referrals', 'ai-o-optimiser' ),
				'text'  => __( 'A person arrived. They followed a link from a recognised AI platform to your site -- the only one of these four signals that is a visitor rather than a machine. Google AI Mode and AI Overviews are missing from this count because they arrive looking exactly like ordinary Google Search.', 'ai-o-optimiser' ),
			),
			'other'     => array(
				'label' => __( 'Other / validation', 'ai-o-optimiser' ),
				'text'  => __( 'Validation and special-purpose bots: link checkers, preview generators and similar one-off fetches run by AI platforms. Counted so the totals add up, but it is the least meaningful of the four.', 'ai-o-optimiser' ),
			),
		);
	}

	/**
	 * Render the "?" that explains one signal term.
	 *
	 * Deliberately a button rather than a title attribute: a title tooltip never
	 * appears on a touch screen, cannot be reached from the keyboard, and is read
	 * inconsistently by screen readers. The bubble is described by aria-describedby
	 * so the definition is announced with the control rather than being decoration
	 * only sighted mouse users get.
	 *
	 * @param string $term Glossary key.
	 * @return void
	 */
	private function render_signal_hint( $term ) {
		$glossary = $this->signal_glossary();
		if ( ! isset( $glossary[ $term ] ) ) {
			return;
		}
		static $seq = 0;
		++$seq;
		$id = 'ai-o-optimiser-hint-' . $term . '-' . $seq;
		?>
		<span class="ai-o-optimiser-hint-wrap">
			<button type="button" class="ai-o-optimiser-hint" aria-describedby="<?php echo esc_attr( $id ); ?>" aria-expanded="false"
				aria-label="<?php echo esc_attr( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( 'What does %s mean?', 'ai-o-optimiser' ), $glossary[ $term ]['label'] ) ); ?>">?</button>
			<?php
			/*
			 * hidden, not merely styled out of view.
			 *
			 * The first version relied on the plugin stylesheet to hide this,
			 * and when that stylesheet does not reach the page the definition
			 * lands in the middle of the screen as body copy -- four of them
			 * per table, in the surrounding label's uppercase. That is the
			 * worst failure this component can have, and it is the one that
			 * actually happened.
			 *
			 * The browser's own stylesheet hides [hidden] with no help from
			 * ours, so the bad case is now a "?" that does nothing rather than
			 * a page full of paragraphs. Script removes the attribute to show
			 * it; aria-describedby still announces the text to a screen reader
			 * while it is hidden, which is the ordinary tooltip pattern.
			 */
			?>
			<span class="ai-o-optimiser-hint-bubble" id="<?php echo esc_attr( $id ); ?>" role="tooltip" hidden>
				<b><?php echo esc_html( $glossary[ $term ]['label'] ); ?></b>
				<?php echo esc_html( $glossary[ $term ]['text'] ); ?>
			</span>
		</span>
		<?php
	}

	/**
	 * Convert a local WordPress date to a UTC MySQL datetime string.
	 *
	 * @param string $date Local date in Y-m-d format.
	 * @param bool   $end_of_day Whether to return 23:59:59 instead of 00:00:00.
	 * @return string UTC datetime in Y-m-d H:i:s format.
	 */
	private function local_date_to_utc_mysql( $date, $end_of_day = false ) {
		$time     = $end_of_day ? '23:59:59' : '00:00:00';
		$datetime = new DateTimeImmutable( $date . ' ' . $time, wp_timezone() );
		return $datetime->setTimezone( new DateTimeZone( 'UTC' ) )->format( 'Y-m-d H:i:s' );
	}

	/**
	 * Validate a Y-m-d date string.
	 *
	 * @param string $date Raw date string.
	 * @return string Sanitised Y-m-d or empty string.
	 */
	private function sanitize_ymd( $date ) {
		$date = sanitize_text_field( $date );
		if ( ! preg_match( '/^\d{4}-\d{2}-\d{2}$/', $date ) ) {
			return '';
		}

		$parsed = DateTimeImmutable::createFromFormat( 'Y-m-d', $date, wp_timezone() );
		if ( ! $parsed || $parsed->format( 'Y-m-d' ) !== $date ) {
			return '';
		}

		return $date;
	}

	/**
	 * Read the "range" query arg shared by Dashboard, Logs and CSV export.
	 *
	 * Last 7/30/90 days are complete periods and intentionally exclude today.
	 * Use the explicit Today option when current-day data is required.
	 *
	 * @return array
	 */
	private function resolve_range() {
		// phpcs:disable WordPress.Security.NonceVerification.Recommended -- Read-only screen state (filters, tab selection, pagination, redirect result notices). Nothing is written here, so there is no form submission to carry a nonce.
		$range   = isset( $_GET['range'] ) ? sanitize_text_field( wp_unslash( $_GET['range'] ) ) : '30';
		$compare = AI_O_Optimiser_Period_Compare::mode( isset( $_GET['compare'] ) ? sanitize_key( wp_unslash( $_GET['compare'] ) ) : 'prev' );
		$map     = array(
			'today'     => __( 'Today', 'ai-o-optimiser' ),
			'yesterday' => __( 'Yesterday', 'ai-o-optimiser' ),
			'7'         => __( 'Last 7 days', 'ai-o-optimiser' ),
			'30'        => __( 'Last 30 days', 'ai-o-optimiser' ),
			'90'        => __( 'Last 90 days', 'ai-o-optimiser' ),
			'custom'    => __( 'Custom range', 'ai-o-optimiser' ),
			'all'       => __( 'All time', 'ai-o-optimiser' ),
		);
		if ( ! isset( $map[ $range ] ) ) {
			$range = '30';
		}

		$today = new DateTimeImmutable( current_time( 'Y-m-d' ), wp_timezone() );

		if ( 'all' === $range ) {
			$chart_end   = $today->modify( '-1 day' );
			$chart_start = $chart_end->modify( '-29 days' );
			return array(
				'since'       => '',
				'until'       => '',
				'label'       => $map['all'],
				'days'        => 0,
				'key'         => 'all',
				'local_start' => $chart_start->format( 'Y-m-d' ),
				'local_end'   => $chart_end->format( 'Y-m-d' ),
				'custom_from' => '',
				'custom_to'   => '',
				'comparison'  => null,
				'compare'     => 'prev',
			);
		}

		if ( 'custom' === $range ) {
			$from = isset( $_GET['custom_from'] ) ? $this->sanitize_ymd( sanitize_text_field( wp_unslash( $_GET['custom_from'] ) ) ) : '';
			$to   = isset( $_GET['custom_to'] ) ? $this->sanitize_ymd( sanitize_text_field( wp_unslash( $_GET['custom_to'] ) ) ) : '';
			if ( empty( $from ) || empty( $to ) ) {
				$range = '30';
			} else {
				$start = new DateTimeImmutable( $from, wp_timezone() );
				$end   = new DateTimeImmutable( $to, wp_timezone() );
				if ( $start > $end ) {
					$tmp   = $start;
					$start = $end;
					$end   = $tmp;
				}
				$days        = (int) $start->diff( $end )->days + 1;
				$local_start = $start->format( 'Y-m-d' );
				$local_end   = $end->format( 'Y-m-d' );
				$comparison  = $this->build_comparison( $compare, $start, $end, $days, __( 'previous period', 'ai-o-optimiser' ) );

				return array(
					'since'       => $this->local_date_to_utc_mysql( $local_start, false ),
					'until'       => $this->local_date_to_utc_mysql( $local_end, true ),
					'label'       => sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
						__( 'Custom: %1$s — %2$s', 'ai-o-optimiser' ), $local_start, $local_end ),
					'days'        => $days,
					'key'         => 'custom',
					'local_start' => $local_start,
					'local_end'   => $local_end,
					'custom_from' => $local_start,
					'custom_to'   => $local_end,
					'comparison'  => $comparison,
					'compare'     => $compare,
				);
			}
		}

		if ( 'today' === $range ) {
			$start      = $today;
			$end        = $today;
			$days       = 1;
			$comparison = $this->build_comparison( $compare, $start, $end, $days, __( 'yesterday', 'ai-o-optimiser' ) );
		} elseif ( 'yesterday' === $range ) {
			$start      = $today->modify( '-1 day' );
			$end        = $start;
			$days       = 1;
			$comparison = $this->build_comparison( $compare, $start, $end, $days, __( 'previous day', 'ai-o-optimiser' ) );
		} else {
			$days       = (int) $range;
			$end        = $today->modify( '-1 day' );
			$start      = $end->modify( '-' . ( $days - 1 ) . ' days' );
			$comparison = $this->build_comparison( $compare, $start, $end, $days, sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
				__( 'previous %d days', 'ai-o-optimiser' ), $days ) );
		}

		$local_start = $start->format( 'Y-m-d' );
		$local_end   = $end->format( 'Y-m-d' );

		return array(
			'since'       => $this->local_date_to_utc_mysql( $local_start, false ),
			'until'       => $this->local_date_to_utc_mysql( $local_end, true ),
			'label'       => $map[ $range ],
			'days'        => $days,
			'key'         => $range,
			'local_start' => $local_start,
			'local_end'   => $local_end,
			'custom_from' => '',
			'custom_to'   => '',
			'comparison'  => $comparison,
			'compare'     => $compare,
		);
		// phpcs:enable WordPress.Security.NonceVerification.Recommended
	}

	/**
	 * Build the immediately preceding comparison period for a selected range.
	 *
	 * @param DateTimeImmutable $start Current local start date.
	 * @param int               $days Number of inclusive days.
	 * @param string            $label Comparison label.
	 * @return array
	 */
	private function build_previous_period( DateTimeImmutable $start, $days, $label ) {
		$previous_end   = $start->modify( '-1 day' );
		$previous_start = $previous_end->modify( '-' . ( max( 1, (int) $days ) - 1 ) . ' days' );

		return array(
			'since'       => $this->local_date_to_utc_mysql( $previous_start->format( 'Y-m-d' ), false ),
			'until'       => $this->local_date_to_utc_mysql( $previous_end->format( 'Y-m-d' ), true ),
			'label'       => $label,
			'local_start' => $previous_start->format( 'Y-m-d' ),
			'local_end'   => $previous_end->format( 'Y-m-d' ),
		);
	}

	/**
	 * Build the comparison period for a selected range and comparison mode.
	 *
	 * prev keeps the long-standing behaviour and labels. mom and yoy compare the
	 * same dates a month or a year earlier. 'covered' says whether this site's own
	 * stored history reaches that far back; GA4 is read from Google and does not
	 * depend on it.
	 *
	 * @param string            $mode  prev, mom or yoy.
	 * @param DateTimeImmutable $start Current local start date.
	 * @param DateTimeImmutable $end   Current local end date.
	 * @param int               $days  Number of inclusive days.
	 * @param string            $label Label used for the previous-period mode.
	 * @return array
	 */
	private function build_comparison( $mode, DateTimeImmutable $start, DateTimeImmutable $end, $days, $label ) {
		if ( 'prev' === $mode ) {
			$out            = $this->build_previous_period( $start, $days, $label );
			$out['mode']    = 'prev';
			$out['covered'] = true;
			return $out;
		}
		$dates = AI_O_Optimiser_Period_Compare::dates( $mode, $start->format( 'Y-m-d' ), $end->format( 'Y-m-d' ) );
		if ( null === $dates ) {
			return $this->build_previous_period( $start, $days, $label ) + array( 'mode' => 'prev', 'covered' => true );
		}
		return array(
			'since'       => $this->local_date_to_utc_mysql( $dates['start'], false ),
			'until'       => $this->local_date_to_utc_mysql( $dates['end'], true ),
			'label'       => AI_O_Optimiser_Period_Compare::label( $mode ),
			'local_start' => $dates['start'],
			'local_end'   => $dates['end'],
			'mode'        => $mode,
			'covered'     => AI_O_Optimiser_Period_Compare::history_covers( $dates['start'], AI_O_Optimiser_DB::earliest_day() ),
		);
	}

	/**
	 * Build filter args for a range and source type.
	 *
	 * @param array  $range Resolved range.
	 * @param string $source_type crawler, referral, guidance or empty for all.
	 * @return array
	 */
	private function filters_for_range( $range, $source_type = '' ) {
		$filters = array(
			'since' => $range['since'],
			'until' => $range['until'],
		);

		if ( in_array( $source_type, array( 'crawler', 'referral', 'guidance' ), true ) ) {
			$filters['source_type'] = $source_type;
		}

		return $filters;
	}

	/**
	 * Count matching rows for the previous comparison period.
	 *
	 * @param array  $range Resolved range.
	 * @param string $source_type Optional source type.
	 * @param array  $extra_filters Additional filters.
	 * @return int|null
	 */
	private function comparison_count( $range, $source_type = '', $extra_filters = array() ) {
		if ( empty( $range['comparison'] ) || ( isset( $range['comparison']['covered'] ) && ! $range['comparison']['covered'] ) ) {
			return null;
		}

		$filters = array(
			'since' => $range['comparison']['since'],
			'until' => $range['comparison']['until'],
		);

		if ( in_array( $source_type, array( 'crawler', 'referral', 'guidance' ), true ) ) {
			$filters['source_type'] = $source_type;
		}

		return AI_O_Optimiser_DB::count( array_merge( $filters, $extra_filters ) );
	}

	/**
	 * Render a compact comparison line.
	 *
	 * @param int      $current Current count.
	 * @param int|null $previous Previous count or null.
	 * @param string   $label Comparison label.
	 */
	private function render_comparison_line( $current, $previous, $label ) {
		if ( null === $previous ) {
			return;
		}

		$change = (int) $current - (int) $previous;
		if ( $previous > 0 ) {
			$percent = round( ( $change / $previous ) * 100, 1 );
			$text    = sprintf( '%+d (%+.1f%%) vs %s', $change, $percent, $label );
		} elseif ( $current > 0 ) {
			$text = sprintf( '%+d vs %s', $change, $label );
		} else {
			$text = sprintf( 'No change vs %s', $label );
		}

		$class  = 'ai-o-optimiser-card-sub ai-o-optimiser-change';
		$prefix = '';
		if ( $change > 0 ) {
			$class .= ' ai-o-optimiser-change-up';
			$prefix = '▲ ';
		} elseif ( $change < 0 ) {
			$class .= ' ai-o-optimiser-change-down';
			$prefix = '▼ ';
		}

		echo '<span class="' . esc_attr( $class ) . '">' . esc_html( $prefix . $text ) . '</span>';
	}

	/**
	 * Format a UTC timestamp into the site's timezone.
	 *
	 * @param string $utc UTC MySQL datetime.
	 * @return string
	 */
	private function format_site_time( $utc ) {
		if ( empty( $utc ) ) {
			return '';
		}

		try {
			return ( new DateTimeImmutable( $utc, new DateTimeZone( 'UTC' ) ) )->setTimezone( wp_timezone() )->format( 'Y-m-d H:i:s T' );
		} catch ( Exception $e ) {
			return $utc;
		}
	}

	/**
	 * Small form used on Dashboard and Logs to switch date range and refresh.
	 *
	 * @param string $current_page The page slug to keep when the form submits.
	 * @param array  $extra_fields Extra query fields to preserve.
	 */
	private function render_range_picker( $current_page, $extra_fields = array() ) {
		// phpcs:disable WordPress.Security.NonceVerification.Recommended -- Read-only screen state (filters, tab selection, pagination, redirect result notices). Nothing is written here, so there is no form submission to carry a nonce.
		$range       = isset( $_GET['range'] ) ? sanitize_text_field( wp_unslash( $_GET['range'] ) ) : '30';
		$custom_from = isset( $_GET['custom_from'] ) ? $this->sanitize_ymd( sanitize_text_field( wp_unslash( $_GET['custom_from'] ) ) ) : '';
		$custom_to   = isset( $_GET['custom_to'] ) ? $this->sanitize_ymd( sanitize_text_field( wp_unslash( $_GET['custom_to'] ) ) ) : '';
		$compare     = AI_O_Optimiser_Period_Compare::mode( isset( $_GET['compare'] ) ? sanitize_key( wp_unslash( $_GET['compare'] ) ) : 'prev' );
		?>
		<form method="get" class="ai-o-optimiser-range-form">
			<input type="hidden" name="page" value="<?php echo esc_attr( $current_page ); ?>" />
			<?php foreach ( $extra_fields as $field_name => $field_value ) : ?>
				<?php if ( '' !== $field_value ) : ?>
					<input type="hidden" name="<?php echo esc_attr( $field_name ); ?>" value="<?php echo esc_attr( $field_value ); ?>" />
				<?php endif; ?>
			<?php endforeach; ?>
			<label for="ai-o-optimiser-range"><?php esc_html_e( 'Date range:', 'ai-o-optimiser' ); ?></label>
			<select name="range" id="ai-o-optimiser-range">
				<option value="today" <?php selected( $range, 'today' ); ?>><?php esc_html_e( 'Today', 'ai-o-optimiser' ); ?></option>
				<option value="yesterday" <?php selected( $range, 'yesterday' ); ?>><?php esc_html_e( 'Yesterday', 'ai-o-optimiser' ); ?></option>
				<option value="7" <?php selected( $range, '7' ); ?>><?php esc_html_e( 'Last 7 days', 'ai-o-optimiser' ); ?></option>
				<option value="30" <?php selected( $range, '30' ); ?>><?php esc_html_e( 'Last 30 days', 'ai-o-optimiser' ); ?></option>
				<option value="90" <?php selected( $range, '90' ); ?>><?php esc_html_e( 'Last 90 days', 'ai-o-optimiser' ); ?></option>
				<option value="custom" <?php selected( $range, 'custom' ); ?>><?php esc_html_e( 'Custom range', 'ai-o-optimiser' ); ?></option>
				<option value="all" <?php selected( $range, 'all' ); ?>><?php esc_html_e( 'All time', 'ai-o-optimiser' ); ?></option>
			</select>
			<?php if ( 'ai-o-optimiser-dashboard' === $current_page ) : ?>
				<label for="ai-o-optimiser-compare"><?php esc_html_e( 'Compare with:', 'ai-o-optimiser' ); ?></label>
				<select name="compare" id="ai-o-optimiser-compare">
					<option value="prev" <?php selected( $compare, 'prev' ); ?>><?php esc_html_e( 'Previous period', 'ai-o-optimiser' ); ?></option>
					<option value="mom" <?php selected( $compare, 'mom' ); ?>><?php esc_html_e( 'Same dates last month', 'ai-o-optimiser' ); ?></option>
					<option value="yoy" <?php selected( $compare, 'yoy' ); ?>><?php esc_html_e( 'Same dates last year', 'ai-o-optimiser' ); ?></option>
				</select>
			<?php endif; ?>
			<label for="ai-o-optimiser-custom-from"><?php esc_html_e( 'From:', 'ai-o-optimiser' ); ?></label>
			<input type="date" id="ai-o-optimiser-custom-from" name="custom_from" value="<?php echo esc_attr( $custom_from ); ?>" />
			<label for="ai-o-optimiser-custom-to"><?php esc_html_e( 'To:', 'ai-o-optimiser' ); ?></label>
			<input type="date" id="ai-o-optimiser-custom-to" name="custom_to" value="<?php echo esc_attr( $custom_to ); ?>" />
			<button type="submit" class="button button-primary"><?php esc_html_e( 'Apply', 'ai-o-optimiser' ); ?></button>
			<button type="submit" class="button" name="ai_o_optimiser_refresh" value="1"><?php esc_html_e( 'Refresh', 'ai-o-optimiser' ); ?></button>
		</form>
		<?php
		if ( 'ai-o-optimiser-dashboard' === $current_page && 'prev' !== $compare ) {
			$resolved = $this->resolve_range();
			if ( ! empty( $resolved['comparison'] ) && empty( $resolved['comparison']['covered'] ) ) {
				echo '<p class="ai-o-optimiser-refresh-note">' . esc_html( sprintf( /* translators: 1: comparison label, 2: first date of the comparison period. */
					__( 'This site has no stored AI visibility history for the %1$s (from %2$s), so counts are not compared. GA4 figures, if connected, are still compared.', 'ai-o-optimiser' ), $resolved['comparison']['label'], $resolved['comparison']['local_start'] ) ) . '</p>';
			}
		}
		?>
		<p class="ai-o-optimiser-refresh-note">
			<?php
			/*
			 * This is the moment the page read its figures, which is what the
			 * reader needs on a tab that has been open a while. It used to be
			 * labelled "Last refreshed", implying a refresh cycle running behind
			 * the page; there is none. AI-O's own counts are read live on every
			 * load, and Refresh now also re-reads the one cached slice (GA4), so
			 * the sentence is true of everything on the screen.
			 */
			echo esc_html( sprintf( /* translators: %s: the time this page loaded, in the site's timezone. */
				__( 'Figures read when this page loaded, at %s. Use Refresh to read them again.', 'ai-o-optimiser' ), $this->format_site_time( current_time( 'mysql', true ) ) ) );
			?>
		</p>
		<?php
		// phpcs:enable WordPress.Security.NonceVerification.Recommended
	}


	/**
	 * Stable option key for a dashboard range's manual GA4 fallback evidence.
	 *
	 * Evidence is stored per selected local date range so a client-facing
	 * interpretation never silently reuses metrics from a different period.
	 *
	 * @param array $range Resolved dashboard range.
	 * @return string
	 */
	private function traffic_evidence_key( $range ) {
		if ( 'all' === $range['key'] ) {
			return 'all';
		}

		$start = isset( $range['local_start'] ) ? sanitize_text_field( $range['local_start'] ) : '';
		$end   = isset( $range['local_end'] ) ? sanitize_text_field( $range['local_end'] ) : '';
		$suffix = ! empty( $range['comparison']['mode'] ) && 'prev' !== $range['comparison']['mode'] ? '__vs_' . $range['comparison']['mode'] : '';
		return $start && $end ? $start . '__' . $end . $suffix : sanitize_key( $range['key'] );
	}

	/**
	 * Return GA4 Direct-traffic evidence for the selected range, preferring the Data API.
	 *
	 * @param array $range Resolved dashboard range.
	 * @return array
	 */
	private function traffic_evidence_for_range( $range ) {
		$settings = AI_O_Optimiser_Connector_Client::settings();
		if ( ! empty( $settings['ga4_property'] ) && ! empty( $range['comparison'] ) && 'all' !== $range['key'] ) {
			$cache_key = 'ai_o_optimiser_ga4_impact_' . md5( $settings['ga4_property'] . '|' . $range['local_start'] . '|' . $range['local_end'] . '|' . $range['comparison']['local_start'] . '|' . $range['comparison']['local_end'] );
			// Refresh is an explicit administrator action, so it bypasses the
			// 15-minute GA4 snapshot rather than re-rendering the same cached
			// numbers under a new timestamp.
			$force_refresh = ! empty( $_GET['ai_o_optimiser_refresh'] ); // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Read-only screen state (page slug, tab, redirect result notices). Nothing is written here, so there is no form submission to carry a nonce.
			$cached    = $force_refresh ? false : get_transient( $cache_key );
			if ( is_array( $cached ) ) {
				return $cached;
			}

			$data = AI_O_Optimiser_Connector_Client::analytics_direct_impact(
				$settings['ga4_property'],
				$range['local_start'],
				$range['local_end'],
				$range['comparison']['local_start'],
				$range['comparison']['local_end']
			);
			if ( ! is_wp_error( $data ) && ! empty( $data['current'] ) && ! empty( $data['previous'] ) ) {
				$snapshot = array(
					'range_label'                 => $range['label'],
					'range_start'                 => $range['local_start'],
					'range_end'                   => $range['local_end'],
					'comparison_label'            => $range['comparison']['label'],
					'direct_sessions_current'     => isset( $data['current']['sessions'] ) ? (float) $data['current']['sessions'] : 0,
					'direct_sessions_previous'    => isset( $data['previous']['sessions'] ) ? (float) $data['previous']['sessions'] : 0,
					'engagement_seconds_current'  => isset( $data['current']['average_session_duration'] ) ? (float) $data['current']['average_session_duration'] : 0,
					'engagement_seconds_previous' => isset( $data['previous']['average_session_duration'] ) ? (float) $data['previous']['average_session_duration'] : 0,
					'conversions_current'         => isset( $data['current']['key_events'] ) ? (float) $data['current']['key_events'] : 0,
					'conversions_previous'        => isset( $data['previous']['key_events'] ) ? (float) $data['previous']['key_events'] : 0,
					'note'                        => __( 'Read automatically from GA4 Direct via the Google Analytics Data API.', 'ai-o-optimiser' ),
					'source'                      => 'ga4_data_api',
					'updated_at'                  => current_time( 'mysql', true ),
				);
				set_transient( $cache_key, $snapshot, 15 * MINUTE_IN_SECONDS );
				AI_O_Optimiser_Connector_Client::update_settings( array( 'ga4_last_sync' => current_time( 'mysql', true ), 'ga4_last_error' => '' ) );
				return $snapshot;
			}
			if ( is_wp_error( $data ) ) {
				AI_O_Optimiser_Connector_Client::update_settings( array( 'ga4_last_error' => sanitize_text_field( $data->get_error_message() ) ) );
			}
		}

		// Manual snapshots remain as a bounded fallback for sites where the
		// Analytics Data API is not yet connected or temporarily unavailable.
		$all = get_option( 'ai_o_optimiser_traffic_evidence_snapshots', array() );
		if ( ! is_array( $all ) ) {
			return array();
		}

		$key = $this->traffic_evidence_key( $range );
		return isset( $all[ $key ] ) && is_array( $all[ $key ] ) ? $all[ $key ] : array();
	}

	/**
	 * Convert an optional posted metric to a non-negative float or null.
	 *
	 * @param string $key POST field name.
	 * @return float|null
	 */
	private function posted_optional_metric( $key ) {
		// phpcs:disable WordPress.Security.NonceVerification.Missing -- Called only from handle_save_traffic_evidence(), which verifies the nonce with check_admin_referer() before this runs; PHPCS cannot follow the call.
		if ( ! isset( $_POST[ $key ] ) ) {
			return null;
		}

		$raw = trim( sanitize_text_field( wp_unslash( $_POST[ $key ] ) ) );
		if ( '' === $raw ) {
			return null;
		}

		$raw = str_replace( array( ',', ' ' ), '', $raw );
		if ( ! is_numeric( $raw ) ) {
			return null;
		}

		return max( 0, (float) $raw );
		// phpcs:enable WordPress.Security.NonceVerification.Missing
	}

	/**
	 * Start read-only Google Analytics reporting authorisation through the Hub.
	 */
	public function handle_ga4_data_connect() {
		if ( ! current_user_can( self::CAPABILITY ) ) {
			wp_die( esc_html__( 'You do not have permission to connect Google Analytics.', 'ai-o-optimiser' ) );
		}
		check_admin_referer( 'ai_o_optimiser_ga4_data_connect' );

		$return_url = admin_url( 'admin-post.php?action=ai_o_optimiser_ga4_data_oauth_return' );
		$url        = AI_O_Optimiser_Connector_Client::analytics_connect_url( $return_url );
		if ( is_wp_error( $url ) ) {
			AI_O_Optimiser_Connector_Client::update_settings( array( 'ga4_last_error' => sanitize_text_field( $url->get_error_message() ) ) );
			wp_safe_redirect( add_query_arg( array( 'page' => 'ai-o-optimiser-dashboard', 'ai_o_optimiser_ga4' => 'error' ), admin_url( 'admin.php' ) ) . '#ai-o-optimiser-traffic-impact' );
			exit;
		}
		wp_redirect( $url ); // phpcs:ignore WordPress.Security.SafeRedirect.wp_redirect_wp_redirect -- validated Google OAuth URL returned by the configured Connector Hub.
		exit;
	}

	/**
	 * Verify the Hub's signed Google OAuth return and go back to Traffic Impact.
	 */
	public function handle_ga4_data_oauth_return() {
		if ( ! current_user_can( self::CAPABILITY ) ) {
			auth_redirect();
			exit;
		}
		$result = AI_O_Optimiser_Connector_Client::verify_oauth_return( $_GET ); // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- signed Hub callback.
		if ( is_wp_error( $result ) ) {
			AI_O_Optimiser_Connector_Client::update_settings( array( 'ga4_last_error' => sanitize_text_field( $result->get_error_message() ) ) );
			wp_safe_redirect( add_query_arg( array( 'page' => 'ai-o-optimiser-dashboard', 'ai_o_optimiser_ga4' => 'error' ), admin_url( 'admin.php' ) ) . '#ai-o-optimiser-traffic-impact' );
			exit;
		}
		AI_O_Optimiser_Connector_Client::update_settings( array( 'ga4_last_error' => '' ) );
		wp_safe_redirect( add_query_arg( array( 'page' => 'ai-o-optimiser-dashboard', 'ai_o_optimiser_ga4' => 'connected' ), admin_url( 'admin.php' ) ) . '#ai-o-optimiser-traffic-impact' );
		exit;
	}

	/**
	 * Save the GA4 property used for automatic Direct-channel evidence.
	 */
	public function handle_ga4_data_save_property() {
		if ( ! current_user_can( self::CAPABILITY ) ) {
			wp_die( esc_html__( 'You do not have permission to select a Google Analytics property.', 'ai-o-optimiser' ) );
		}
		check_admin_referer( 'ai_o_optimiser_ga4_data_save_property' );
		$property = isset( $_POST['ga4_property'] ) ? sanitize_text_field( wp_unslash( $_POST['ga4_property'] ) ) : '';
		if ( $property && ! preg_match( '#^properties/\d+$#', $property ) ) {
			wp_die( esc_html__( 'The selected GA4 property identifier is invalid.', 'ai-o-optimiser' ) );
		}
		AI_O_Optimiser_Connector_Client::update_settings( array( 'ga4_property' => $property, 'ga4_last_sync' => '', 'ga4_last_error' => '' ) );
		wp_safe_redirect( add_query_arg( array( 'page' => 'ai-o-optimiser-dashboard', 'ai_o_optimiser_ga4' => 'property-saved' ), admin_url( 'admin.php' ) ) . '#ai-o-optimiser-traffic-impact' );
		exit;
	}

	/**
	 * Return GA4 properties with a short cache to avoid repeated Admin API calls.
	 *
	 * @return array|WP_Error
	 */
	private function ga4_properties() {
		$cached = get_transient( 'ai_o_optimiser_ga4_properties' );
		if ( is_array( $cached ) ) {
			return $cached;
		}
		$properties = AI_O_Optimiser_Connector_Client::analytics_properties();
		if ( ! is_wp_error( $properties ) ) {
			set_transient( 'ai_o_optimiser_ga4_properties', $properties, 15 * MINUTE_IN_SECONDS );
		}
		return $properties;
	}

	/**
	 * Save a GA4 Direct-traffic comparison snapshot for the selected dashboard range.
	 *
	 * Manual fallback retained for environments where the read-only GA4 Data API
	 * connection is unavailable. Automatic API evidence takes precedence.
	 */
	public function handle_save_traffic_evidence() {
		if ( ! current_user_can( self::CAPABILITY ) ) {
			wp_die( esc_html__( 'You do not have permission to update traffic evidence.', 'ai-o-optimiser' ) );
		}

		check_admin_referer( 'ai_o_optimiser_save_traffic_evidence' );

		$range_key   = isset( $_POST['range'] ) ? sanitize_text_field( wp_unslash( $_POST['range'] ) ) : '30';
		$custom_from = isset( $_POST['custom_from'] ) ? $this->sanitize_ymd( sanitize_text_field( wp_unslash( $_POST['custom_from'] ) ) ) : '';
		$custom_to   = isset( $_POST['custom_to'] ) ? $this->sanitize_ymd( sanitize_text_field( wp_unslash( $_POST['custom_to'] ) ) ) : '';
		$compare     = AI_O_Optimiser_Period_Compare::mode( isset( $_POST['compare'] ) ? sanitize_key( wp_unslash( $_POST['compare'] ) ) : 'prev' );

		// Reuse the normal range resolver so the stored snapshot is bound to the
		// exact period the dashboard will render after redirect.
		$_GET['range']   = $range_key;
		$_GET['compare'] = $compare;
		if ( $custom_from ) {
			$_GET['custom_from'] = $custom_from;
		}
		if ( $custom_to ) {
			$_GET['custom_to'] = $custom_to;
		}
		$range = $this->resolve_range();

		$snapshot = array(
			'range_label'                => $range['label'],
			'range_start'                => isset( $range['local_start'] ) ? $range['local_start'] : '',
			'range_end'                  => isset( $range['local_end'] ) ? $range['local_end'] : '',
			'comparison_label'           => ! empty( $range['comparison']['label'] ) ? $range['comparison']['label'] : '',
			'direct_sessions_current'    => $this->posted_optional_metric( 'direct_sessions_current' ),
			'direct_sessions_previous'   => $this->posted_optional_metric( 'direct_sessions_previous' ),
			'engagement_seconds_current' => $this->posted_optional_metric( 'engagement_seconds_current' ),
			'engagement_seconds_previous'=> $this->posted_optional_metric( 'engagement_seconds_previous' ),
			'conversions_current'        => $this->posted_optional_metric( 'conversions_current' ),
			'conversions_previous'       => $this->posted_optional_metric( 'conversions_previous' ),
			'note'                       => isset( $_POST['traffic_evidence_note'] ) ? sanitize_textarea_field( wp_unslash( $_POST['traffic_evidence_note'] ) ) : '',
			'updated_at'                 => current_time( 'mysql', true ),
		);

		$all = get_option( 'ai_o_optimiser_traffic_evidence_snapshots', array() );
		if ( ! is_array( $all ) ) {
			$all = array();
		}
		$all[ $this->traffic_evidence_key( $range ) ] = $snapshot;

		// Keep the option bounded. Custom periods can otherwise grow forever.
		if ( count( $all ) > 24 ) {
			uasort(
				$all,
				function( $a, $b ) {
					return strcmp( isset( $b['updated_at'] ) ? $b['updated_at'] : '', isset( $a['updated_at'] ) ? $a['updated_at'] : '' );
				}
			);
			$all = array_slice( $all, 0, 24, true );
		}
		update_option( 'ai_o_optimiser_traffic_evidence_snapshots', $all, false );

		$args = array(
			'page'                  => 'ai-o-optimiser-dashboard',
			'range'                 => $range['key'],
			'ai_o_optimiser_traffic_evidence'  => 'saved',
		);
		if ( 'prev' !== $compare ) {
			$args['compare'] = $compare;
		}
		if ( 'custom' === $range['key'] ) {
			$args['custom_from'] = $range['custom_from'];
			$args['custom_to']   = $range['custom_to'];
		}

		wp_safe_redirect( add_query_arg( $args, admin_url( 'admin.php' ) ) . '#ai-o-optimiser-traffic-impact' );
		exit;
	}

	/**
	 * Calculate percentage change when a comparable previous value exists.
	 *
	 * @param float|int|null $current Current value.
	 * @param float|int|null $previous Previous value.
	 * @return float|null
	 */
	private function evidence_percent_change( $current, $previous ) {
		if ( null === $current || null === $previous || (float) $previous <= 0 ) {
			return null;
		}
		return round( ( ( (float) $current - (float) $previous ) / (float) $previous ) * 100, 1 );
	}

	/**
	 * Trend direction for two supplied values, including 0 → positive cases.
	 *
	 * @param float|int|null $current Current value.
	 * @param float|int|null $previous Previous value.
	 * @return int|null 1 up, -1 down, 0 flat, null when not comparable.
	 */
	private function evidence_direction( $current, $previous ) {
		if ( null === $current || null === $previous ) {
			return null;
		}
		if ( (float) $current > (float) $previous ) {
			return 1;
		}
		if ( (float) $current < (float) $previous ) {
			return -1;
		}
		return 0;
	}

	/**
	 * Human-readable percentage change, preserving "not supplied" honestly.
	 *
	 * @param float|int|null $current Current value.
	 * @param float|int|null $previous Previous value.
	 * @return string
	 */
	private function evidence_change_text( $current, $previous ) {
		if ( null === $current || null === $previous ) {
			return __( 'Comparison not supplied', 'ai-o-optimiser' );
		}
		$change = $this->evidence_percent_change( $current, $previous );
		if ( null === $change ) {
			if ( (float) $previous <= 0 && (float) $current > 0 ) {
				return __( 'New vs 0', 'ai-o-optimiser' );
			}
			return __( 'No percentage comparison', 'ai-o-optimiser' );
		}
		return sprintf( '%+.1f%%', $change );
	}

	/**
	 * Build a cautious, client-facing traffic-impact interpretation.
	 *
	 * Direct traffic is supporting evidence only. It includes bookmarks,
	 * untagged links and other unattributed sources, so this method never
	 * estimates the percentage of Direct traffic caused by AI.
	 *
	 * @param int      $crawler_hits Current crawler hits.
	 * @param int|null $prev_crawler_hits Previous crawler hits.
	 * @param int      $referral_hits Current measured AI referral visits.
	 * @param int|null $prev_referral_hits Previous measured AI referral visits.
	 * @param array    $evidence Optional GA4 Direct metrics.
	 * @return array
	 */
	private function build_traffic_impact( $crawler_hits, $prev_crawler_hits, $referral_hits, $prev_referral_hits, $evidence ) {
		$crawler_change  = $this->evidence_percent_change( $crawler_hits, $prev_crawler_hits );
		$referral_change = $this->evidence_percent_change( $referral_hits, $prev_referral_hits );

		$metrics = array(
			'sessions' => array(
				'current'  => isset( $evidence['direct_sessions_current'] ) ? $evidence['direct_sessions_current'] : null,
				'previous' => isset( $evidence['direct_sessions_previous'] ) ? $evidence['direct_sessions_previous'] : null,
			),
			'engagement' => array(
				'current'  => isset( $evidence['engagement_seconds_current'] ) ? $evidence['engagement_seconds_current'] : null,
				'previous' => isset( $evidence['engagement_seconds_previous'] ) ? $evidence['engagement_seconds_previous'] : null,
			),
			'conversions' => array(
				'current'  => isset( $evidence['conversions_current'] ) ? $evidence['conversions_current'] : null,
				'previous' => isset( $evidence['conversions_previous'] ) ? $evidence['conversions_previous'] : null,
			),
		);

		$available_direct = 0;
		$positive_direct  = 0;
		$negative_direct  = 0;
		foreach ( $metrics as $metric ) {
			$direction = $this->evidence_direction( $metric['current'], $metric['previous'] );
			if ( null === $direction ) {
				continue;
			}
			$available_direct++;
			if ( $direction > 0 ) {
				$positive_direct++;
			} elseif ( $direction < 0 ) {
				$negative_direct++;
			}
		}

		$crawler_direction  = $this->evidence_direction( $crawler_hits, $prev_crawler_hits );
		$referral_direction = $this->evidence_direction( $referral_hits, $prev_referral_hits );
		$ai_positive = ( null !== $crawler_direction && $crawler_direction > 0 )
			|| ( null !== $referral_direction && $referral_direction > 0 )
			|| ( $referral_hits > 0 );

		$level = 'not_assessed';
		if ( $available_direct >= 3 && $positive_direct >= 3 && $ai_positive ) {
			$level = 'strong';
		} elseif ( $available_direct >= 2 && $positive_direct >= 2 && $ai_positive && 0 === $negative_direct ) {
			$level = 'moderate';
		} elseif ( $available_direct >= 2 ) {
			$level = 'mixed';
		}

		$labels = array(
			'strong'       => __( 'Strong', 'ai-o-optimiser' ),
			'moderate'     => __( 'Moderate', 'ai-o-optimiser' ),
			'mixed'        => __( 'Mixed', 'ai-o-optimiser' ),
			'not_assessed' => __( 'Not assessed', 'ai-o-optimiser' ),
		);

		if ( 'strong' === $level ) {
			$summary = __( 'AI discovery/referral signals and all available Direct-traffic quality metrics are moving positively together. This is strong supporting evidence that AI-assisted discovery may be contributing to website growth, but it is not proof that the Direct sessions came from AI.', 'ai-o-optimiser' );
		} elseif ( 'moderate' === $level ) {
			$summary = __( 'AI signals and multiple available Direct-traffic metrics are moving positively together. The pattern is consistent with AI-assisted discovery contributing to traffic, but Direct remains an unattributed channel and causation is not proven.', 'ai-o-optimiser' );
		} elseif ( 'mixed' === $level ) {
			$summary = __( 'The available Direct-traffic metrics do not move consistently with the AI visibility signals. Treat AI as one possible contributor, not the explanation for the traffic change, and review landing pages and attribution in GA4.', 'ai-o-optimiser' );
		} else {
			$summary = __( 'AI-O Optimiser can measure AI crawler activity and identifiable AI referrals, but it cannot infer Direct traffic from those counts alone. Connect GA4 reporting, or add the matching Direct comparison manually, to assess whether sessions, average session duration and key events are moving in the same direction.', 'ai-o-optimiser' );
		}

		$evidence_bits = array();
		if ( null !== $crawler_change ) {
			$evidence_bits[] = sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
				__( 'AI crawler activity %+.1f%%', 'ai-o-optimiser' ), $crawler_change );
		} elseif ( null !== $crawler_direction && $crawler_direction > 0 ) {
			$evidence_bits[] = __( 'AI crawler activity increased from a zero baseline', 'ai-o-optimiser' );
		}
		if ( null !== $referral_change ) {
			$evidence_bits[] = sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
				__( 'measured AI referrals %+.1f%%', 'ai-o-optimiser' ), $referral_change );
		} elseif ( null !== $referral_direction && $referral_direction > 0 ) {
			$evidence_bits[] = __( 'measured AI referrals increased from a zero baseline', 'ai-o-optimiser' );
		}
		$metric_labels = array(
			'sessions'    => __( 'Direct sessions', 'ai-o-optimiser' ),
			'engagement'  => __( 'Direct avg session duration', 'ai-o-optimiser' ),
			'conversions' => __( 'Direct key events', 'ai-o-optimiser' ),
		);
		foreach ( $metrics as $metric_key => $metric ) {
			$change = $this->evidence_percent_change( $metric['current'], $metric['previous'] );
			$direction = $this->evidence_direction( $metric['current'], $metric['previous'] );
			if ( null !== $change ) {
				$evidence_bits[] = sprintf( '%1$s %2$+.1f%%', $metric_labels[ $metric_key ], $change );
			} elseif ( null !== $direction && $direction > 0 ) {
				$evidence_bits[] = sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( '%s increased from zero', 'ai-o-optimiser' ), $metric_labels[ $metric_key ] );
			}
		}

		return array(
			'level'           => $level,
			'label'           => $labels[ $level ],
			'summary'         => $summary,
			'evidence_line'   => ! empty( $evidence_bits ) ? implode( ' · ', $evidence_bits ) : __( 'Connect GA4 reporting or add a comparable GA4 Direct snapshot to strengthen the traffic interpretation.', 'ai-o-optimiser' ),
			'crawler_change'  => $crawler_change,
			'referral_change' => $referral_change,
			'metrics'         => $metrics,
		);
	}

	/**
	 * Roll bot-level totals up into the reporting groups defined in AI_O_Optimiser_Bots.
	 *
	 * @param array $by_bot Rows from AI_O_Optimiser_DB::totals_by_bot().
	 * @return array
	 */
	private function group_totals_from_bot_rows( $by_bot ) {
		$totals = array();
		foreach ( AI_O_Optimiser_Bots::group_definitions() as $group => $label ) {
			$totals[ $group ] = array(
				'label'     => $label,
				'total'     => 0,
				'bot_count' => 0,
				'last_seen' => '',
			);
		}

		foreach ( $by_bot as $row ) {
			$group = AI_O_Optimiser_Bots::group_for_slug( $row->bot_slug );
			if ( ! isset( $totals[ $group ] ) ) {
				$group = 'other';
			}

			$totals[ $group ]['total'] += (int) $row->total;
			$totals[ $group ]['bot_count']++;
			if ( empty( $totals[ $group ]['last_seen'] ) || $row->last_seen > $totals[ $group ]['last_seen'] ) {
				$totals[ $group ]['last_seen'] = $row->last_seen;
			}
		}

		return $totals;
	}


	/**
	 * Known AI brand labels used to roll bot and referral rows into a client-facing view.
	 *
	 * @return array
	 */
	private function brand_definitions() {
		return array(
			'openai'      => __( 'OpenAI / ChatGPT', 'ai-o-optimiser' ),
			'anthropic'   => __( 'Anthropic / Claude', 'ai-o-optimiser' ),
			'perplexity'  => __( 'Perplexity', 'ai-o-optimiser' ),
			'google'      => __( 'Google / Gemini', 'ai-o-optimiser' ),
			'microsoft'   => __( 'Microsoft / Copilot', 'ai-o-optimiser' ),
			'meta'        => __( 'Meta AI', 'ai-o-optimiser' ),
			'bytedance'   => __( 'ByteDance', 'ai-o-optimiser' ),
			'amazon'      => __( 'Amazon', 'ai-o-optimiser' ),
			'apple'       => __( 'Apple Intelligence', 'ai-o-optimiser' ),
			'cohere'      => __( 'Cohere', 'ai-o-optimiser' ),
			'duckduckgo'  => __( 'DuckDuckGo / DuckAssist', 'ai-o-optimiser' ),
			'youcom'      => __( 'You.com', 'ai-o-optimiser' ),
			'commoncrawl' => __( 'Common Crawl', 'ai-o-optimiser' ),
			'quora'       => __( 'Quora / Poe', 'ai-o-optimiser' ),
			'brave'       => __( 'Brave Search / Leo', 'ai-o-optimiser' ),
			'phind'       => __( 'Phind', 'ai-o-optimiser' ),
			'diffbot'     => __( 'Diffbot', 'ai-o-optimiser' ),
			'mistral'     => __( 'Mistral AI / Le Chat', 'ai-o-optimiser' ),
			'deepseek'    => __( 'DeepSeek', 'ai-o-optimiser' ),
			'xai'         => __( 'xAI / Grok', 'ai-o-optimiser' ),
			'ai2'         => __( 'Allen Institute for AI', 'ai-o-optimiser' ),
			'other'       => __( 'Other / custom AI', 'ai-o-optimiser' ),
		);
	}


	/**
	 * Short logo-style text for brand cards. Uses lightweight text marks instead of bundled image assets.
	 *
	 * @param string $brand_key Brand key.
	 * @param string $label Brand label.
	 * @return string
	 */
	private function brand_mark_text( $brand_key, $label = '' ) {
		$marks = array(
			'openai'      => 'AI',
			'anthropic'   => 'C',
			'perplexity'  => 'P',
			'google'      => 'G',
			'microsoft'   => 'Co',
			'meta'        => 'M',
			'bytedance'   => 'B',
			'amazon'      => 'Az',
			'apple'       => '',
			'cohere'      => 'Co',
			'duckduckgo'  => 'D',
			'youcom'      => 'Y',
			'commoncrawl' => 'CC',
			'quora'       => 'Poe',
			'brave'       => 'B',
			'phind'       => 'Ph',
			'diffbot'     => 'Df',
			'mistral'     => 'Mi',
			'deepseek'    => 'DS',
			'xai'         => 'G',
			'ai2'         => 'AI2',
			'other'       => 'AI',
		);

		if ( isset( $marks[ $brand_key ] ) ) {
			return $marks[ $brand_key ];
		}

		$label = trim( wp_strip_all_tags( (string) $label ) );
		return $label ? strtoupper( substr( $label, 0, 2 ) ) : 'AI';
	}

	/**
	 * Client-facing brand logo label for dashboard cards.
	 *
	 * Uses lightweight, bundled text logos rather than external image calls.
	 *
	 * @param string $brand_key Brand key.
	 * @param string $label Brand label.
	 * @return string
	 */
	private function brand_logo_label( $brand_key, $label = '' ) {
		$logos = array(
			'openai'      => 'ChatGPT',
			'anthropic'   => 'Claude',
			'perplexity'  => 'Perplexity',
			'google'      => 'Gemini',
			'microsoft'   => 'Copilot',
			'meta'        => 'Meta AI',
			'bytedance'   => 'ByteDance',
			'amazon'      => 'Amazon',
			'apple'       => 'Apple',
			'cohere'      => 'Cohere',
			'duckduckgo'  => 'DuckAssist',
			'youcom'      => 'You.com',
			'commoncrawl' => 'Common Crawl',
			'quora'       => 'Poe',
			'brave'       => 'Brave',
			'phind'       => 'Phind',
			'diffbot'     => 'Diffbot',
			'mistral'     => 'Le Chat',
			'deepseek'    => 'DeepSeek',
			'xai'         => 'Grok',
			'ai2'         => 'AI2',
			'other'       => 'AI',
		);

		if ( isset( $logos[ $brand_key ] ) ) {
			return $logos[ $brand_key ];
		}

		$label = trim( wp_strip_all_tags( (string) $label ) );
		return $label ? $label : __( 'AI', 'ai-o-optimiser' );
	}

	/**
	 * Render the compact logo-style mark for an AI brand.
	 *
	 * @param array $brand Brand data.
	 */
	private function render_brand_mark( $brand ) {
		$key   = isset( $brand['key'] ) ? sanitize_html_class( $brand['key'] ) : 'other';
		$text  = $this->brand_mark_text( $key, isset( $brand['label'] ) ? $brand['label'] : '' );
		$label = $this->brand_logo_label( $key, isset( $brand['label'] ) ? $brand['label'] : '' );
		?>
		<span class="ai-o-optimiser-brand-logo ai-o-optimiser-brand-logo-<?php echo esc_attr( $key ); ?>" aria-label="<?php echo esc_attr( $label ); ?>">
			<span class="ai-o-optimiser-brand-mark ai-o-optimiser-brand-mark-<?php echo esc_attr( $key ); ?>" aria-hidden="true"><?php echo esc_html( $text ); ?></span>
			<span class="ai-o-optimiser-brand-logo-name"><?php echo esc_html( $label ); ?></span>
		</span>
		<?php
	}

	/**
	 * Resolve a bot slug/label to an AI brand key.
	 *
	 * @param string $slug Bot slug.
	 * @param string $label Bot label.
	 * @return string
	 */
	private function brand_for_bot( $slug, $label = '' ) {
		$slug  = sanitize_key( $slug );
		$label = strtolower( (string) $label );

		$map = array(
			'claudebot'        => 'anthropic',
			'claude-searchbot' => 'anthropic',
			'claude-user'      => 'anthropic',
			'anthropic-ai'     => 'anthropic',
			'gptbot'           => 'openai',
			'chatgpt-user'     => 'openai',
			'oai-searchbot'    => 'openai',
			'oai-adsbot'       => 'openai',
			'perplexitybot'    => 'perplexity',
			'perplexity-user'  => 'perplexity',
			'ccbot'            => 'commoncrawl',
			'bytespider'       => 'bytedance',
			'amazonbot'        => 'amazon',
			'applebot'         => 'apple',
			// Kept so history recorded under the retired slug still rolls up to
			// Apple rather than dropping into Other.
			'applebot-ext'     => 'apple',
			'meta-extagent'    => 'meta',
			'meta-extfetcher'  => 'meta',
			'cohere-ai'        => 'cohere',
			'duckassistbot'    => 'duckduckgo',
			'youbot'           => 'youcom',
			'diffbot'              => 'diffbot',
			'google-agent'          => 'google',
			'google-gemininotebook' => 'google',
			'google-notebooklm'     => 'google',
			'google-cloudvertexbot' => 'google',
			'mistralai-user'         => 'mistral',
			'deepseekbot'            => 'deepseek',
			'xai-grok'               => 'xai',
			'ai2bot'                 => 'ai2',
			'googleother'            => 'google',
			'googleother-image'      => 'google',
			'googleother-video'      => 'google',
			'petalbot'               => 'other',
			'pangubot'               => 'other',
			'tiktokspider'           => 'bytedance',
			'timpibot'               => 'other',
			'imagesiftbot'           => 'other',
			'omgili'                 => 'other',
			'webzio'                 => 'other',
			'icc-crawler'            => 'other',
			'kangaroo-bot'           => 'other',
		);

		if ( isset( $map[ $slug ] ) ) {
			return $map[ $slug ];
		}

		return $this->brand_for_label( $label );
	}

	/**
	 * Resolve an AI referral source to a brand key.
	 *
	 * @param string $slug Source slug.
	 * @param string $label Source label.
	 * @return string
	 */
	private function brand_for_referrer( $slug, $label = '' ) {
		$slug = sanitize_key( $slug );
		$map  = array(
			'chatgpt'    => 'openai',
			'perplexity' => 'perplexity',
			'claude'     => 'anthropic',
			'gemini'     => 'google',
			'notebooklm' => 'google',
			'copilot'    => 'microsoft',
			'metaai'     => 'meta',
			'deepseek'   => 'deepseek',
			'grok'       => 'xai',
			'mistral'    => 'mistral',
			'youcom'     => 'youcom',
			'poe'        => 'quora',
			'phind'      => 'phind',
			'brave'      => 'brave',
		);

		if ( isset( $map[ $slug ] ) ) {
			return $map[ $slug ];
		}

		return $this->brand_for_label( strtolower( (string) $label ) );
	}

	/**
	 * Keyword fallback for custom bot/referrer labels.
	 *
	 * @param string $label Lowercase source label.
	 * @return string
	 */
	private function brand_for_label( $label ) {
		$checks = array(
			'openai'      => array( 'openai', 'chatgpt', 'gptbot', 'oai-' ),
			'anthropic'   => array( 'anthropic', 'claude' ),
			'perplexity'  => array( 'perplexity' ),
			'google'      => array( 'google', 'gemini' ),
			'microsoft'   => array( 'microsoft', 'copilot', 'bing' ),
			'meta'        => array( 'meta', 'facebook' ),
			'bytedance'   => array( 'bytedance', 'bytespider', 'tiktok' ),
			'amazon'      => array( 'amazon' ),
			'apple'       => array( 'apple' ),
			'cohere'      => array( 'cohere' ),
			'duckduckgo'  => array( 'duckduckgo', 'duckassist' ),
			'youcom'      => array( 'you.com', 'youcom', 'youbot' ),
			'commoncrawl' => array( 'common crawl', 'ccbot' ),
			'quora'       => array( 'quora', 'poe' ),
			'brave'       => array( 'brave' ),
			'phind'       => array( 'phind' ),
			'diffbot'     => array( 'diffbot' ),
			'mistral'     => array( 'mistral', 'le chat' ),
			'deepseek'    => array( 'deepseek' ),
			'xai'         => array( 'xai', 'grok' ),
			'ai2'         => array( 'allen institute', 'ai2bot', 'dolma' ),
		);

		foreach ( $checks as $brand => $needles ) {
			foreach ( $needles as $needle ) {
				if ( false !== strpos( $label, $needle ) ) {
					return $brand;
				}
			}
		}

		return 'other';
	}



	/**
	 * Build brand-first visibility data from crawler and AI referral rows.
	 *
	 * @param array $by_bot Bot totals.
	 * @param array $by_referrer AI referral source totals.
	 * @return array
	 */
	private function build_brand_intelligence( $by_bot, $by_referrer ) {
		$brand_labels = $this->brand_definitions();
		$brands       = array();

		foreach ( $brand_labels as $key => $label ) {
			$brands[ $key ] = array(
				'key'              => $key,
				'label'            => $label,
				'total'            => 0,
				'crawler_hits'     => 0,
				'referral_hits'    => 0,
				'training_hits'    => 0,
				'user_hits'        => 0,
				'other_hits'       => 0,
				'bot_count'        => 0,
				'referrer_count'   => 0,
				'last_seen'        => '',
				'top_bot'          => '',
				'top_bot_hits'     => 0,
				'top_referrer'     => '',
				'top_referrer_hits'=> 0,
			);
		}

		foreach ( (array) $by_bot as $row ) {
			$brand = $this->brand_for_bot( $row->bot_slug, $row->bot_label );
			if ( ! isset( $brands[ $brand ] ) ) {
				$brand = 'other';
			}

			$hits  = isset( $row->total ) ? (int) $row->total : 0;
			$group = AI_O_Optimiser_Bots::group_for_slug( $row->bot_slug );

			$brands[ $brand ]['total']        += $hits;
			$brands[ $brand ]['crawler_hits'] += $hits;
			$brands[ $brand ]['bot_count']++;
			if ( 'training' === $group ) {
				$brands[ $brand ]['training_hits'] += $hits;
			} elseif ( 'user' === $group ) {
				$brands[ $brand ]['user_hits'] += $hits;
			} else {
				$brands[ $brand ]['other_hits'] += $hits;
			}

			if ( empty( $brands[ $brand ]['last_seen'] ) || $row->last_seen > $brands[ $brand ]['last_seen'] ) {
				$brands[ $brand ]['last_seen'] = $row->last_seen;
			}

			if ( $hits > $brands[ $brand ]['top_bot_hits'] ) {
				$brands[ $brand ]['top_bot_hits'] = $hits;
				$brands[ $brand ]['top_bot']      = $row->bot_label;
			}
		}

		foreach ( (array) $by_referrer as $row ) {
			$brand = $this->brand_for_referrer( $row->source_slug, $row->source_label );
			if ( ! isset( $brands[ $brand ] ) ) {
				$brand = 'other';
			}

			$hits = isset( $row->total ) ? (int) $row->total : 0;
			$brands[ $brand ]['total']         += $hits;
			$brands[ $brand ]['referral_hits'] += $hits;
			$brands[ $brand ]['referrer_count']++;

			if ( empty( $brands[ $brand ]['last_seen'] ) || $row->last_seen > $brands[ $brand ]['last_seen'] ) {
				$brands[ $brand ]['last_seen'] = $row->last_seen;
			}

			if ( $hits > $brands[ $brand ]['top_referrer_hits'] ) {
				$brands[ $brand ]['top_referrer_hits'] = $hits;
				$brands[ $brand ]['top_referrer']      = $row->source_label;
			}
		}

		$brands = array_values(
			array_filter(
				$brands,
				function( $row ) {
					return ! empty( $row['total'] );
				}
			)
		);

		usort(
			$brands,
			function( $a, $b ) {
				if ( $a['total'] === $b['total'] ) {
					return strcmp( $a['label'], $b['label'] );
				}
				return ( $a['total'] < $b['total'] ) ? 1 : -1;
			}
		);

		return $brands;
	}

	/**
	 * Provider-level measurement coverage used for the client-facing methodology panel.
	 *
	 * This describes what AI-O Optimiser can identify when the relevant request reaches WordPress.
	 * It is not a promise that every provider request exposes one of these signals.
	 *
	 * @return array
	 */
	private function provider_signal_coverage() {
		return array(
			'openai' => array(
				'label'     => __( 'ChatGPT', 'ai-o-optimiser' ),
				'discovery' => 'measured',
				'live'      => 'measured',
				'referral'  => 'measured',
				'note'      => __( 'Dedicated OpenAI discovery/search crawlers, ChatGPT live fetches and recognised ChatGPT referrals can be identified when they reach the site.', 'ai-o-optimiser' ),
			),
			'anthropic' => array(
				'label'     => __( 'Claude', 'ai-o-optimiser' ),
				'discovery' => 'measured',
				'live'      => 'measured',
				'referral'  => 'measured',
				'note'      => __( 'Claude discovery/search crawlers, Claude live fetches and recognised Claude referrals can be identified when they reach the site.', 'ai-o-optimiser' ),
			),
			'perplexity' => array(
				'label'     => __( 'Perplexity', 'ai-o-optimiser' ),
				'discovery' => 'measured',
				'live'      => 'measured',
				'referral'  => 'measured',
				'note'      => __( 'Perplexity discovery/search crawling, live fetches and recognised Perplexity referrals can be identified when they reach the site.', 'ai-o-optimiser' ),
			),
			'google' => array(
				'label'     => __( 'Gemini', 'ai-o-optimiser' ),
				'discovery' => 'context',
				'live'      => 'measured',
				'referral'  => 'measured',
				'note'      => __( 'Googlebot is shown as Search / AI Search eligibility context and is excluded from AI totals. Identifiable Google AI live fetchers and Gemini, NotebookLM and AI Studio referrals are measured separately. Visits from AI Mode and AI Overviews are not shown: Google sends them with the same google.com referrer as ordinary Search, so counting them would mean counting ordinary search traffic as AI.', 'ai-o-optimiser' ),
			),
			'microsoft' => array(
				'label'     => __( 'Copilot', 'ai-o-optimiser' ),
				'discovery' => 'not_measured',
				'live'      => 'not_measured',
				'referral'  => 'measured',
				'note'      => __( 'Recognised Copilot referrals can be measured. AI-O Optimiser does not currently attribute a dedicated Microsoft AI crawler or live-fetch signature to Copilot totals.', 'ai-o-optimiser' ),
			),
			'meta' => array(
				'label'     => __( 'Meta AI', 'ai-o-optimiser' ),
				'discovery' => 'measured',
				'live'      => 'measured',
				'referral'  => 'measured',
				'note'      => __( 'Meta-ExternalAgent and Meta-ExternalFetcher can be measured, as can visits referred from meta.ai.', 'ai-o-optimiser' ),
			),
		);
	}

	/**
	 * Render one signal-coverage state.
	 *
	 * @param string $capability Capability type.
	 * @param int    $observed Observed count in the selected period.
	 */
	private function render_provider_coverage_state( $capability, $observed ) {
		if ( 'measured' === $capability ) {
			if ( $observed > 0 ) {
				echo '<span class="ai-o-optimiser-coverage-state ai-o-optimiser-coverage-observed">' . esc_html__( 'Observed', 'ai-o-optimiser' ) . '</span>';
			} else {
				echo '<span class="ai-o-optimiser-coverage-state ai-o-optimiser-coverage-not-seen">' . esc_html__( 'Not observed', 'ai-o-optimiser' ) . '</span>';
			}
			return;
		}

		if ( 'context' === $capability ) {
			echo '<span class="ai-o-optimiser-coverage-state ai-o-optimiser-coverage-context">' . esc_html__( 'Context only', 'ai-o-optimiser' ) . '</span>';
			return;
		}

		echo '<span class="ai-o-optimiser-coverage-state ai-o-optimiser-coverage-unavailable">' . esc_html__( 'Not directly measured', 'ai-o-optimiser' ) . '</span>';
	}

	/**
	 * Render compact provider measurement coverage and observed-vs-sampled methodology.
	 *
	 * @param array $brand_rows Current brand rollup.
	 */
	private function render_provider_coverage_panel( $brand_rows ) {
		$by_key = array();
		foreach ( (array) $brand_rows as $brand ) {
			if ( ! empty( $brand['key'] ) ) {
				$by_key[ $brand['key'] ] = $brand;
			}
		}
		?>
		<details class="ai-o-optimiser-panel ai-o-optimiser-provider-coverage">
			<summary>
				<strong><?php esc_html_e( 'What AI-O Optimiser can measure by platform', 'ai-o-optimiser' ); ?></strong>
				<span class="description"><?php esc_html_e( 'Observed website signals versus AI-answer sampling', 'ai-o-optimiser' ); ?></span>
			</summary>
			<div class="ai-o-optimiser-provider-coverage-body">
				<div class="ai-o-optimiser-observed-sampled-note" role="note">
					<strong><?php esc_html_e( 'Observed vs sampled', 'ai-o-optimiser' ); ?></strong>
					<span><?php esc_html_e( 'AI-O Optimiser records signals that reach this website. It does not run LLM benchmark prompts. If sampled AI-answer evidence is connected from an external service later, it must remain separate from these observed totals.', 'ai-o-optimiser' ); ?></span>
				</div>
				<div class="ai-o-optimiser-provider-coverage-scroll">
				<table class="widefat striped ai-o-optimiser-provider-coverage-table">
					<thead><tr>
						<th><?php esc_html_e( 'Platform', 'ai-o-optimiser' ); ?></th>
						<th><?php esc_html_e( 'Discovery / index', 'ai-o-optimiser' ); ?><?php $this->render_signal_hint( 'discovery' ); ?></th>
						<th><?php esc_html_e( 'Live AI fetch', 'ai-o-optimiser' ); ?><?php $this->render_signal_hint( 'live' ); ?></th>
						<th><?php esc_html_e( 'Referral', 'ai-o-optimiser' ); ?><?php $this->render_signal_hint( 'referral' ); ?></th>
						<th><?php esc_html_e( 'AI answer sampling', 'ai-o-optimiser' ); ?></th>
					</tr></thead>
					<tbody>
					<?php foreach ( $this->provider_signal_coverage() as $key => $provider ) :
						$observed = isset( $by_key[ $key ] ) ? $by_key[ $key ] : array();
						$training = isset( $observed['training_hits'] ) ? (int) $observed['training_hits'] : 0;
						$live     = isset( $observed['user_hits'] ) ? (int) $observed['user_hits'] : 0;
						$referral = isset( $observed['referral_hits'] ) ? (int) $observed['referral_hits'] : 0;
					?>
						<tr>
							<td><strong><?php echo esc_html( $provider['label'] ); ?></strong><small><?php echo esc_html( $provider['note'] ); ?></small></td>
							<td><?php $this->render_provider_coverage_state( $provider['discovery'], $training ); ?></td>
							<td><?php $this->render_provider_coverage_state( $provider['live'], $live ); ?></td>
							<td><?php $this->render_provider_coverage_state( $provider['referral'], $referral ); ?></td>
							<td><span class="ai-o-optimiser-coverage-state ai-o-optimiser-coverage-external"><?php esc_html_e( 'Outside AI-O Optimiser', 'ai-o-optimiser' ); ?></span></td>
						</tr>
					<?php endforeach; ?>
					</tbody>
				</table>
				</div>
				<p class="description"><?php esc_html_e( '“Not observed” means no matching signal reached AI-O Optimiser in this selected period. It does not prove the platform did not use, mention or recommend the site.', 'ai-o-optimiser' ); ?></p>
			</div>
		</details>
		<?php
	}

	/**
	 * Build a plain-language signal summary for the current brand rollup.
	 *
	 * @param array $brand_rows Brand rows.
	 * @return string
	 */
	private function brand_signal_summary( $brand_rows ) {
		$active_brands   = 0;
		$referral_brands = 0;
		$discovery_only  = 0;
		foreach ( (array) $brand_rows as $brand ) {
			$active = (int) $brand['user_hits'] + (int) $brand['referral_hits'];
			if ( $active > 0 ) {
				$active_brands++;
			}
			if ( (int) $brand['referral_hits'] > 0 ) {
				$referral_brands++;
			}
			if ( $active <= 0 && (int) $brand['training_hits'] > 0 ) {
				$discovery_only++;
			}
		}

		if ( $active_brands > 0 ) {
			$active_text = sprintf(
				/* translators: Placeholder values are replaced with contextual values shown in this message. */
					_n( '%d AI platform showed live-fetch or referral signals in this period', '%d AI platforms showed live-fetch or referral signals in this period', $active_brands, 'ai-o-optimiser' ),
				$active_brands
			);
			$referral_text = $referral_brands > 0
				? sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					_n( '%d platform generated a measurable referral visit', '%d platforms generated measurable referral visits', $referral_brands, 'ai-o-optimiser' ), $referral_brands )
				: __( 'No recognised AI referral visits were measured', 'ai-o-optimiser' );
			$discovery_text = $discovery_only > 0
				? sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					_n( '%d platform was discovery-only', '%d platforms were discovery-only', $discovery_only, 'ai-o-optimiser' ), $discovery_only ) . __( ', meaning automated access was observed but no live-fetch or referral signal reached the site', 'ai-o-optimiser' )
				: __( 'No measured platform was discovery-only', 'ai-o-optimiser' );

			return $active_text . '. ' . $referral_text . '. ' . $discovery_text . '.';
		}

		if ( $discovery_only > 0 ) {
			return __( 'Measured activity in this period was discovery-only. That means automated AI access was observed, not that people did not use those AI platforms. No live-fetch or recognised AI-referral signal reached the site in this period.', 'ai-o-optimiser' );
		}

		return __( 'No directly measurable AI platform activity was observed in this period.', 'ai-o-optimiser' );
	}

	/**
	 * Render one AI brand card.
	 *
	 * @param array $brand Brand data.
	 * @param int   $rank Ranking position.
	 * @param bool  $large Whether to render the larger top-three format.
	 */
	/**
	 * One line per platform: what it is, and how its activity reaches you.
	 *
	 * Shown on hover over a brand card. The dashboard names two dozen AI
	 * companies, and a small business owner has heard of maybe four of them -
	 * so each one says plainly whether it crawls, fetches live, sends
	 * visitors, or some combination.
	 *
	 * Built once per request: the dashboard renders up to two dozen cards and
	 * every one of them asks for this list.
	 *
	 * @return array Brand key => explanation.
	 */
	private function brand_explainers() {
		static $explainers = null;
		if ( null !== $explainers ) {
			return $explainers;
		}
		$explainers = array(
			'openai'      => __( 'ChatGPT. Crawls in bulk as GPTBot, fetches pages live as ChatGPT-User when someone asks about you, and indexes for ChatGPT search as OAI-SearchBot. Referrals arrive from chatgpt.com.', 'ai-o-optimiser' ),
			'anthropic'   => __( 'Claude. Crawls as ClaudeBot and fetches live as Claude-User when someone asks a question your page can answer. Referrals arrive from claude.ai.', 'ai-o-optimiser' ),
			'perplexity'  => __( 'An answer engine that cites its sources. Crawls as PerplexityBot and fetches live as Perplexity-User. It sends more referral traffic than most, because answers link out.', 'ai-o-optimiser' ),
			'google'      => __( 'Gemini and AI Overviews. Both are fed by ordinary Googlebot crawling rather than a separate AI crawler, so activity here is Google AI fetchers and Gemini referrals only - Googlebot is counted separately.', 'ai-o-optimiser' ),
			'microsoft'   => __( 'Copilot, built on Bing. Bingbot crawling feeds it, so crawl activity appears under ordinary search rather than as an AI bot.', 'ai-o-optimiser' ),
			'meta'        => __( 'Meta AI, across Facebook, Instagram and WhatsApp. Crawls as meta-externalagent and facebookexternalhit.', 'ai-o-optimiser' ),
			'bytedance'   => __( 'TikTok\'s parent company. Crawls as Bytespider, usually in bulk and often heavily.', 'ai-o-optimiser' ),
			'amazon'      => __( 'Alexa and Amazon\'s AI products. Crawls as Amazonbot.', 'ai-o-optimiser' ),
			'apple'       => __( 'Apple Intelligence and Siri. Crawls as Applebot; Applebot-Extended is the separate policy token for AI training.', 'ai-o-optimiser' ),
			'cohere'      => __( 'An enterprise AI company. Crawls as cohere-ai, mostly for training data.', 'ai-o-optimiser' ),
			'duckduckgo'  => __( 'DuckAssist, DuckDuckGo\'s answer feature. Draws on its own index and on Bing.', 'ai-o-optimiser' ),
			'youcom'      => __( 'An AI search engine. Crawls as YouBot and links out to sources.', 'ai-o-optimiser' ),
			'commoncrawl' => __( 'Not an AI company - an open web archive, crawling as CCBot, that many AI models are trained from. Blocking it blocks a lot of downstream training at once.', 'ai-o-optimiser' ),
			'quora'       => __( 'Poe, Quora\'s multi-model chat product. Crawls as Quora-Bot.', 'ai-o-optimiser' ),
			'brave'       => __( 'Leo, Brave\'s assistant, built on Brave\'s own independent search index.', 'ai-o-optimiser' ),
			'phind'       => __( 'An answer engine aimed at developers. Most relevant if you publish technical content.', 'ai-o-optimiser' ),
			'diffbot'     => __( 'A commercial crawler that sells structured web data to other companies, including AI firms.', 'ai-o-optimiser' ),
			'mistral'     => __( 'Le Chat, from the French AI company Mistral. Crawls as MistralAI-User.', 'ai-o-optimiser' ),
			'deepseek'    => __( 'A Chinese AI lab whose models are widely reused by other products.', 'ai-o-optimiser' ),
			'xai'         => __( 'Grok, the assistant built into X. Crawls as xAI\'s own agent.', 'ai-o-optimiser' ),
			'ai2'         => __( 'A non-profit research institute. Crawls for open research datasets rather than a commercial product.', 'ai-o-optimiser' ),
			'other'       => __( 'An AI agent identified by its user agent but not matched to a known company. Often a self-hosted tool or a new product.', 'ai-o-optimiser' ),
		);
		return $explainers;
	}

	private function render_brand_card( $brand, $rank, $large = false ) {
		$classes = $large ? 'ai-o-optimiser-brand-card ai-o-optimiser-brand-card-large' : 'ai-o-optimiser-brand-card ai-o-optimiser-brand-card-small';
		$classes .= ' ai-o-optimiser-brand-card-' . sanitize_html_class( isset( $brand['key'] ) ? $brand['key'] : 'other' );
		$direct_use_hits = (int) $brand['user_hits'] + (int) $brand['referral_hits'];
		if ( (int) $brand['user_hits'] > 0 && (int) $brand['referral_hits'] > 0 ) {
			$signal_badge = sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
				__( '%1$s live fetches · %2$s referrals', 'ai-o-optimiser' ), number_format_i18n( $brand['user_hits'] ), number_format_i18n( $brand['referral_hits'] ) );
			$signal_badge_class = 'ai-o-optimiser-brand-signal-badge ai-o-optimiser-brand-signal-badge-direct';
		} elseif ( (int) $brand['user_hits'] > 0 ) {
			$signal_badge = sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
				_n( '%s live fetch request', '%s live fetch requests', (int) $brand['user_hits'], 'ai-o-optimiser' ), number_format_i18n( $brand['user_hits'] ) );
			$signal_badge_class = 'ai-o-optimiser-brand-signal-badge ai-o-optimiser-brand-signal-badge-direct';
		} elseif ( (int) $brand['referral_hits'] > 0 ) {
			$signal_badge = sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
				_n( '%s referral', '%s referrals', (int) $brand['referral_hits'], 'ai-o-optimiser' ), number_format_i18n( $brand['referral_hits'] ) );
			$signal_badge_class = 'ai-o-optimiser-brand-signal-badge ai-o-optimiser-brand-signal-badge-direct';
		} elseif ( ! empty( $brand['training_hits'] ) ) {
			$signal_badge = __( 'Discovery activity', 'ai-o-optimiser' );
			$signal_badge_class = 'ai-o-optimiser-brand-signal-badge ai-o-optimiser-brand-signal-badge-discovery';
		} else {
			$signal_badge = __( 'Automated AI activity', 'ai-o-optimiser' );
			$signal_badge_class = 'ai-o-optimiser-brand-signal-badge ai-o-optimiser-brand-signal-badge-other';
		}
		$top_source = $brand['top_referrer_hits'] >= $brand['top_bot_hits'] && ! empty( $brand['top_referrer'] ) ? $brand['top_referrer'] : $brand['top_bot'];
		if ( empty( $top_source ) ) {
			$top_source = __( 'No source yet', 'ai-o-optimiser' );
		}
		$last_seen = $brand['last_seen'] ? $this->format_site_time( $brand['last_seen'] ) : __( 'Not seen yet', 'ai-o-optimiser' );
		?>
		<?php
		$explainers = $this->brand_explainers();
		$explainer  = isset( $explainers[ $brand['key'] ] ) ? $explainers[ $brand['key'] ] : '';
		?>
		<div class="<?php echo esc_attr( $classes ); ?>"<?php echo $explainer ? ' title="' . esc_attr( $explainer ) . '"' : ''; ?>>
			<div class="ai-o-optimiser-brand-card-head">
				<?php $this->render_brand_mark( $brand ); ?>
				<div class="ai-o-optimiser-brand-title-block">
					<span class="ai-o-optimiser-brand-rank"><?php echo esc_html( '#' . (int) $rank ); ?></span>
					<h3><?php echo esc_html( $brand['label'] ); ?></h3>
					<span><?php echo $large ? esc_html__( 'Top AI performer', 'ai-o-optimiser' ) : esc_html__( 'AI brand signal', 'ai-o-optimiser' ); ?></span>
				</div>
			</div>

			<?php if ( $large && $explainer ) : ?>
				<p class="ai-o-optimiser-brand-explainer description"><?php echo esc_html( $explainer ); ?></p>
			<?php endif; ?>

			<div class="ai-o-optimiser-brand-primary-metric">
				<div>
					<strong><?php echo esc_html( number_format_i18n( $brand['total'] ) ); ?></strong>
					<span class="ai-o-optimiser-signal-label"><?php esc_html_e( 'total signals', 'ai-o-optimiser' ); ?></span>
				</div>
				<span class="<?php echo esc_attr( $signal_badge_class ); ?>"><?php echo esc_html( $signal_badge ); ?></span>
			</div>

			<div class="ai-o-optimiser-brand-mini-stats" aria-label="<?php esc_attr_e( 'AI brand summary', 'ai-o-optimiser' ); ?>">
				<span class="ai-o-optimiser-brand-mini-stat-discovery"><b><?php echo esc_html( number_format_i18n( $brand['training_hits'] ) ); ?></b><span class="ai-o-optimiser-signal-label"><?php esc_html_e( 'Discovery / index', 'ai-o-optimiser' ); ?></span></span>
				<span class="ai-o-optimiser-brand-mini-stat-live"><b><?php echo esc_html( number_format_i18n( $brand['user_hits'] ) ); ?></b><span class="ai-o-optimiser-signal-label"><?php esc_html_e( 'Live AI fetch', 'ai-o-optimiser' ); ?></span></span>
				<span class="ai-o-optimiser-brand-mini-stat-referral"><b><?php echo esc_html( number_format_i18n( $brand['referral_hits'] ) ); ?></b><span class="ai-o-optimiser-signal-label"><?php esc_html_e( 'Referrals', 'ai-o-optimiser' ); ?></span></span>
				<span class="ai-o-optimiser-brand-mini-stat-other"><b><?php echo esc_html( number_format_i18n( $brand['other_hits'] ) ); ?></b><span class="ai-o-optimiser-signal-label"><?php esc_html_e( 'Other', 'ai-o-optimiser' ); ?></span></span>
			</div>


			<div class="ai-o-optimiser-brand-footnote">
				<span><?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( 'Top source: %s', 'ai-o-optimiser' ), $top_source ) ); ?></span>
				<span><?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( 'Last seen %s', 'ai-o-optimiser' ), $last_seen ) ); ?></span>
			</div>
		</div>
		<?php
	}

	/**
	 * Validate a requested bot group filter.
	 *
	 * @param string $group Group key.
	 * @return string Valid group key or empty string.
	 */
	private function sanitize_group_filter( $group ) {
		$group  = sanitize_key( $group );
		$groups = AI_O_Optimiser_Bots::group_definitions();
		return isset( $groups[ $group ] ) ? $group : '';
	}

	/**
	 * Validate a requested source type filter.
	 *
	 * @param string $source_type Source type key.
	 * @return string Source type or empty string.
	 */
	private function sanitize_source_type( $source_type ) {
		$source_type = sanitize_key( $source_type );
		return in_array( $source_type, array( 'crawler', 'referral', 'guidance' ), true ) ? $source_type : '';
	}

	/* ----------------------------------------------------------------
	 * Page intelligence helpers
	 * ---------------------------------------------------------------- */

	/**
	 * Build a lightweight interpretation layer for the top crawler page table.
	 *
	 * @param array $rows Top page rows from AI_O_Optimiser_DB::top_pages().
	 * @return array
	 */
	private function build_page_intelligence( $rows ) {
		$intel = array(
			'total_hits'        => 0,
			'utility_hits'      => 0,
			'content_hits'      => 0,
			'issue_hits'        => 0,
			'row_count'         => 0,
			'normalised_count'  => 0,
			'duplicate_groups'  => 0,
			'slug_groups'       => 0,
			'rows'              => array(),
			'recommendations'   => array(),
		);

		$normalised_map = array();
		$slug_map       = array();

		foreach ( (array) $rows as $row ) {
			$raw      = isset( $row->request_uri ) ? (string) $row->request_uri : '';
			$hits     = isset( $row->total ) ? (int) $row->total : 0;
			$analysis = $this->analyse_crawler_page_path( $raw );

			$intel['total_hits'] += $hits;
			$intel['row_count']++;
			$intel['rows'][] = array_merge(
				$analysis,
				array(
					'raw'  => $raw,
					'hits' => $hits,
				)
			);

			if ( 'utility' === $analysis['bucket'] ) {
				$intel['utility_hits'] += $hits;
			} elseif ( 'content' === $analysis['bucket'] ) {
				$intel['content_hits'] += $hits;
			} else {
				$intel['issue_hits'] += $hits;
			}

			$key = $analysis['normalised'];
			if ( ! isset( $normalised_map[ $key ] ) ) {
				$normalised_map[ $key ] = array(
					'total' => 0,
					'raws'  => array(),
				);
			}
			$normalised_map[ $key ]['total']      += $hits;
			$normalised_map[ $key ]['raws'][ $raw ] = true;

			if ( 'content' === $analysis['bucket'] ) {
				$slug = $this->final_path_slug( $analysis['normalised'] );
				if ( '' !== $slug ) {
					if ( ! isset( $slug_map[ $slug ] ) ) {
						$slug_map[ $slug ] = array();
					}
					$slug_map[ $slug ][ $analysis['normalised'] ] = true;
				}
			}
		}

		$intel['normalised_count'] = count( $normalised_map );

		foreach ( $normalised_map as $path => $group ) {
			if ( count( $group['raws'] ) > 1 ) {
				$intel['duplicate_groups']++;
			}
		}

		foreach ( $slug_map as $slug => $paths ) {
			if ( count( $paths ) > 1 ) {
				$intel['slug_groups']++;
			}
		}

		if ( $intel['total_hits'] > 0 ) {
			$utility_ratio = $intel['utility_hits'] / $intel['total_hits'];
			$content_ratio = $intel['content_hits'] / $intel['total_hits'];

			if ( $utility_ratio >= 0.6 ) {
				$intel['recommendations'][] = array(
					'level' => 'neutral',
					'text'  => __( 'Most bot activity is discovery behaviour: robots.txt, sitemap files, llms.txt or similar. That is normal early crawler behaviour, but it means these hits do not yet prove content-level visibility.', 'ai-o-optimiser' ),
				);
			}

			if ( $content_ratio > 0 ) {
				$intel['recommendations'][] = array(
					'level' => 'pass',
					'text'  => __( 'AI crawlers are reaching content URLs. Review these pages first for clear headings, concise answers, entity references, citations, schema and internal links.', 'ai-o-optimiser' ),
				);
			} else {
				$intel['recommendations'][] = array(
					'level' => 'warning',
					'text'  => __( 'No content URLs appear in the top crawler paths for this range. Check whether sitemaps expose your important pages and whether robots, cache, firewall or canonical rules are limiting discovery.', 'ai-o-optimiser' ),
				);
			}

			if ( $intel['issue_hits'] > 0 ) {
				$intel['recommendations'][] = array(
					'level' => 'warning',
					'text'  => __( 'Malformed or suspicious paths are present. Look for double-slash links, relative robots.txt references, bad redirects, tracking templates, or JavaScript injecting about:blank into URLs.', 'ai-o-optimiser' ),
				);
			}

			if ( $intel['duplicate_groups'] > 0 ) {
				$intel['recommendations'][] = array(
					'level' => 'warning',
					'text'  => __( 'Multiple raw paths collapse to the same normalised URL. Add redirects or fix internal links so crawlers do not waste crawl budget on duplicate path variants.', 'ai-o-optimiser' ),
				);
			}

			if ( $intel['slug_groups'] > 0 ) {
				$intel['recommendations'][] = array(
					'level' => 'warning',
					'text'  => __( 'The same final page slug appears under more than one path. Confirm your preferred canonical URL, update internal links, and make sure the sitemap exposes only the preferred version.', 'ai-o-optimiser' ),
				);
			}
		}

		return $intel;
	}

	/**
	 * Classify a request path into a practical crawler-intelligence bucket.
	 *
	 * @param string $raw_path Raw stored request path.
	 * @return array
	 */
	private function analyse_crawler_page_path( $raw_path ) {
		$raw        = trim( (string) $raw_path );
		$normalised = $this->normalise_crawler_page_path( $raw );
		$lower_raw  = strtolower( $raw );
		$lower_norm = strtolower( $normalised );
		$issues     = array();

		if ( '' === $raw ) {
			$issues[] = __( 'empty path', 'ai-o-optimiser' );
		}

		if ( false !== strpos( $raw, '//' ) ) {
			$issues[] = __( 'double slash', 'ai-o-optimiser' );
		}

		if ( false !== strpos( $lower_raw, 'about:blank' ) ) {
			$issues[] = __( 'about:blank fragment', 'ai-o-optimiser' );
		}

		if ( preg_match( '#/(robots\.txt|sitemap(?:_index)?\.xml|llms(?:-full)?\.txt)$#', $lower_norm, $matches ) ) {
			$file_name = $matches[1];
			$is_root   = '/' . $file_name === $lower_norm;

			if ( ! $is_root ) {
				return array(
					'bucket'      => 'issue',
					'label'       => __( 'Misplaced utility file', 'ai-o-optimiser' ),
					'badge_class' => 'ai-o-optimiser-badge-warning',
					'normalised'  => $normalised,
					'note'        => __( 'This looks like robots/sitemap/llms.txt requested under a subdirectory. Usually this means a malformed relative link, redirect, or crawler probe.', 'ai-o-optimiser' ),
				);
			}

			if ( ! empty( $issues ) ) {
				return array(
					'bucket'      => 'issue',
					'label'       => __( 'Duplicate utility path', 'ai-o-optimiser' ),
					'badge_class' => 'ai-o-optimiser-badge-warning',
					'normalised'  => $normalised,
					'note'        => sprintf(
						/* translators: %s: comma-separated issue labels. */
						__( 'Crawler reached a utility file through a messy path: %s. Redirect or fix the source link.', 'ai-o-optimiser' ),
						implode( ', ', $issues )
					),
				);
			}

			return array(
				'bucket'      => 'utility',
				'label'       => __( 'Discovery file', 'ai-o-optimiser' ),
				'badge_class' => 'ai-o-optimiser-badge-neutral',
				'normalised'  => $normalised,
				'note'        => __( 'Normal crawler discovery of robots.txt, sitemap or AI guidance files. Useful signal, but not a content citation signal.', 'ai-o-optimiser' ),
			);
		}

		if ( ! empty( $issues ) ) {
			return array(
				'bucket'      => 'issue',
				'label'       => __( 'Malformed content path', 'ai-o-optimiser' ),
				'badge_class' => 'ai-o-optimiser-badge-warning',
				'normalised'  => $normalised,
				'note'        => sprintf(
					/* translators: %s: comma-separated issue labels. */
					__( 'This content URL contains a path-quality issue: %s. Check source links, redirects, canonical tags and JS-generated links.', 'ai-o-optimiser' ),
					implode( ', ', $issues )
				),
			);
		}

		return array(
			'bucket'      => 'content',
			'label'       => __( 'Content page', 'ai-o-optimiser' ),
			'badge_class' => 'ai-o-optimiser-badge-pass',
			'normalised'  => $normalised,
			'note'        => __( 'A real page or archive is being crawled. Prioritise this URL for answer quality, schema, internal links and conversion paths.', 'ai-o-optimiser' ),
		);
	}

	/**
	 * Normalise messy crawler paths for dashboard interpretation only.
	 *
	 * @param string $path Raw stored path.
	 * @return string
	 */
	private function normalise_crawler_page_path( $path ) {
		$path = trim( (string) $path );

		if ( '' === $path ) {
			return '/';
		}

		$parsed_path = wp_parse_url( $path, PHP_URL_PATH );
		if ( is_string( $parsed_path ) && '' !== $parsed_path ) {
			$path = $parsed_path;
		}

		$path = strtok( $path, '?' );
		$path = false === $path ? '/' : $path;
		$path = preg_replace( '#/+#', '/', $path );
		$path = '/' . ltrim( (string) $path, '/' );
		$path = preg_replace( '#/about:blank/?$#i', '/', $path );
		$path = preg_replace( '#/+#', '/', $path );

		if ( strlen( $path ) > 1 ) {
			$path = untrailingslashit( $path );
			if ( preg_match( '#\.(txt|xml)$#i', $path ) ) {
				return strtolower( $path );
			}
			return trailingslashit( $path );
		}

		return '/';
	}

	/**
	 * Extract the final path segment for duplicate-slug checks.
	 *
	 * @param string $path Normalised path.
	 * @return string
	 */
	private function final_path_slug( $path ) {
		$path = trim( (string) $path, '/' );
		if ( '' === $path ) {
			return '';
		}

		$parts = explode( '/', $path );
		$slug  = end( $parts );

		return sanitize_title( (string) $slug );
	}

	/**
	 * Render summary cards and recommendations for the top crawler page table.
	 *
	 * @param array $intel Page intelligence data.
	 */
	private function render_page_intelligence_panel( $intel ) {
		if ( empty( $intel['total_hits'] ) ) {
			return;
		}
		?>
		<div class="ai-o-optimiser-panel ai-o-optimiser-page-intelligence-panel">
			<h3><?php esc_html_e( 'Crawler page intelligence', 'ai-o-optimiser' ); ?></h3>
			<div class="ai-o-optimiser-intel-grid">
				<div>
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Discovery files', 'ai-o-optimiser' ); ?></span>
					<strong><?php echo esc_html( number_format_i18n( $intel['utility_hits'] ) ); ?></strong>
				</div>
				<div>
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Content pages', 'ai-o-optimiser' ); ?></span>
					<strong><?php echo esc_html( number_format_i18n( $intel['content_hits'] ) ); ?></strong>
				</div>
				<div>
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'URL issues', 'ai-o-optimiser' ); ?></span>
					<strong><?php echo esc_html( number_format_i18n( $intel['issue_hits'] ) ); ?></strong>
				</div>
				<div>
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Normalised URLs', 'ai-o-optimiser' ); ?></span>
					<strong><?php echo esc_html( number_format_i18n( $intel['normalised_count'] ) ); ?></strong>
				</div>
				<div>
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Slug conflicts', 'ai-o-optimiser' ); ?></span>
					<strong><?php echo esc_html( number_format_i18n( $intel['slug_groups'] ) ); ?></strong>
				</div>
			</div>
			<?php if ( ! empty( $intel['recommendations'] ) ) : ?>
				<ul class="ai-o-optimiser-intel-recommendations">
					<?php foreach ( $intel['recommendations'] as $recommendation ) : ?>
						<li>
							<span class="ai-o-optimiser-badge <?php echo esc_attr( $this->recommendation_badge_class( $recommendation['level'] ) ); ?>"><?php echo esc_html( $this->recommendation_label( $recommendation['level'] ) ); ?></span>
							<span><?php echo esc_html( $recommendation['text'] ); ?></span>
						</li>
					<?php endforeach; ?>
				</ul>
			<?php endif; ?>
		</div>
		<?php
	}

	/**
	 * Badge class for an intelligence recommendation.
	 *
	 * @param string $level Recommendation level.
	 * @return string
	 */
	private function recommendation_badge_class( $level ) {
		if ( 'pass' === $level ) {
			return 'ai-o-optimiser-badge-pass';
		}
		if ( 'warning' === $level ) {
			return 'ai-o-optimiser-badge-warning';
		}
		return 'ai-o-optimiser-badge-neutral';
	}

	/**
	 * Human label for an intelligence recommendation.
	 *
	 * @param string $level Recommendation level.
	 * @return string
	 */
	private function recommendation_label( $level ) {
		if ( 'pass' === $level ) {
			return __( 'Opportunity', 'ai-o-optimiser' );
		}
		if ( 'warning' === $level ) {
			return __( 'Fix', 'ai-o-optimiser' );
		}
		return __( 'Read', 'ai-o-optimiser' );
	}


	/**
	 * Load the Visibility Dash stylesheets, after the others.
	 *
	 * This guards the premium dashboard layout against stale admin.css, plugin CSS concatenation,
	 * and third-party admin styles that can force dashboard cards back to full-width blocks.
	 *
	 * Runs at enqueue time rather than from inside the dashboard markup, and
	 * depends on the two ordinary stylesheets so it is always printed after
	 * them. It was captured with ob_start() and attached inline until 1.27.0;
	 * a file of its own is what the enqueue API is for.
	 *
	 * The feature-card row below the charts is styled from here too, for the
	 * same reason it is enqueued rather than inlined: it is the Dash's, and
	 * only the Dash's.
	 */
	private function enqueue_visibility_layout_guard() {
		$guard_path = AI_O_Optimiser_PLUGIN_DIR . 'assets/admin-visibility-layout-guard.css';
		$guard_ver  = file_exists( $guard_path ) ? AI_O_Optimiser_VERSION . '.' . filemtime( $guard_path ) : AI_O_Optimiser_VERSION;
		wp_enqueue_style( 'ai-o-optimiser-admin-visibility-layout-guard', AI_O_Optimiser_PLUGIN_URL . 'assets/admin-visibility-layout-guard.css', array( 'ai-o-optimiser-admin', 'ai-o-optimiser-admin-modules' ), $guard_ver );

		$cards_path = AI_O_Optimiser_PLUGIN_DIR . 'assets/admin-feature-cards.css';
		$cards_ver  = file_exists( $cards_path ) ? AI_O_Optimiser_VERSION . '.' . filemtime( $cards_path ) : AI_O_Optimiser_VERSION;
		wp_enqueue_style( 'ai-o-optimiser-admin-feature-cards', AI_O_Optimiser_PLUGIN_URL . 'assets/admin-feature-cards.css', array( 'ai-o-optimiser-admin', 'ai-o-optimiser-admin-modules' ), $cards_ver );
	}

	/* ----------------------------------------------------------------
	 * Dashboard
	 * ---------------------------------------------------------------- */

	public function render_dashboard() {
		if ( ! current_user_can( self::dashboard_capability() ) ) {
			return;
		}

		$range            = $this->resolve_range();
		$all_filters      = $this->filters_for_range( $range );
		$crawler_filters  = $this->filters_for_range( $range, 'crawler' );
		$referral_filters = $this->filters_for_range( $range, 'referral' );
		$guidance_filters = $this->filters_for_range( $range, 'guidance' );

		$total_hits     = AI_O_Optimiser_DB::count( $all_filters );
		$crawler_hits   = AI_O_Optimiser_DB::count( $crawler_filters );
		// How many of those requests were actually answered with a page. A
		// crawler walking a list of URLs that no longer exist looks identical to
		// one reading the site until these two numbers are set side by side.
		$crawler_ok     = AI_O_Optimiser_DB::count_successful( $crawler_filters );
		ai_o_optimiser_visibility_load_client_ip();
		$verify_on        = AI_O_Optimiser_Bot_Verification::enabled();
		$crawler_verified = $verify_on ? AI_O_Optimiser_DB::count_verified( $crawler_filters ) : 0;
		$referral_hits  = AI_O_Optimiser_DB::count( $referral_filters );
		$guidance_hits  = AI_O_Optimiser_DB::count( $guidance_filters );
		$by_bot         = AI_O_Optimiser_DB::totals_by_bot( $crawler_filters );
		$by_group       = $this->group_totals_from_bot_rows( $by_bot );
		$by_referrer    = AI_O_Optimiser_DB::totals_by_referrer_source( $referral_filters );
		$by_guidance    = AI_O_Optimiser_DB::totals_by_guidance_file( $guidance_filters );
		$brand_rows     = $this->build_brand_intelligence( $by_bot, $by_referrer );
		$top_brands     = array_slice( $brand_rows, 0, 3 );
		$top_bot_pages  = AI_O_Optimiser_DB::top_pages( array_merge( $crawler_filters, array( 'limit' => 20 ) ) );
		$top_ref_pages  = AI_O_Optimiser_DB::top_pages( array_merge( $referral_filters, array( 'limit' => 10 ) ) );
		$page_intel     = $this->build_page_intelligence( $top_bot_pages );
		$daily          = AI_O_Optimiser_DB::daily_counts_for_range( $range['since'], $range['until'], $range['local_start'], $range['local_end'], $all_filters );
		$max_day        = $daily ? max( $daily ) : 0;

		$top_bot_label      = $by_bot ? $by_bot[0]->bot_label : __( '—', 'ai-o-optimiser' );
		$top_page           = $top_bot_pages ? $top_bot_pages[0]->request_uri : __( '—', 'ai-o-optimiser' );
		$top_group_label    = __( '—', 'ai-o-optimiser' );
		$top_group_hits     = 0;
		foreach ( $by_group as $group_row ) {
			if ( $group_row['total'] > $top_group_hits ) {
				$top_group_hits  = (int) $group_row['total'];
				$top_group_label = $group_row['label'];
			}
		}
		$top_referrer_label = $by_referrer ? $by_referrer[0]->source_label : __( '—', 'ai-o-optimiser' );
		$top_referrer_hits  = $by_referrer ? (int) $by_referrer[0]->total : 0;
		$comparison         = isset( $range['comparison']['label'] ) ? $range['comparison']['label'] : '';

		$prev_total_hits    = $this->comparison_count( $range );
		$prev_crawler_hits  = $this->comparison_count( $range, 'crawler' );
		$prev_referral_hits = $this->comparison_count( $range, 'referral' );
		$prev_guidance_hits = $this->comparison_count( $range, 'guidance' );
		$prev_training_hits = $this->comparison_count( $range, 'crawler', array( 'bot_slugs' => AI_O_Optimiser_Bots::slugs_for_group( 'training' ) ) );
		$prev_user_hits     = $this->comparison_count( $range, 'crawler', array( 'bot_slugs' => AI_O_Optimiser_Bots::slugs_for_group( 'user' ) ) );
		$traffic_evidence   = $this->traffic_evidence_for_range( $range );
		$can_administer     = current_user_can( self::CAPABILITY );
		$connector_settings = AI_O_Optimiser_Connector_Client::settings();
		$ga4_properties     = array();
		$ga4_properties_error = null;
		if ( $can_administer && ! empty( $connector_settings['connector_id'] ) ) {
			$ga4_property_result = $this->ga4_properties();
			if ( is_wp_error( $ga4_property_result ) ) {
				$ga4_properties_error = $ga4_property_result;
			} else {
				$ga4_properties = $ga4_property_result;
			}
		}
		$traffic_impact     = $this->build_traffic_impact( $crawler_hits, $prev_crawler_hits, $referral_hits, $prev_referral_hits, $traffic_evidence );
		?>
		<div class="wrap ai-o-optimiser-wrap">
			<h1><?php esc_html_e( 'Dashboard', 'ai-o-optimiser' ); ?></h1>
			<p class="description">
				<?php esc_html_e( 'Shows what AI systems can access, what AI-O Optimiser can measure directly, and whether those visibility signals align with website traffic and conversion trends. Unattributable platform activity is shown as context, never invented as traffic.', 'ai-o-optimiser' ); ?>
			</p>

			<?php $this->render_range_picker( 'ai-o-optimiser-dashboard' ); ?>

			<?php self::render_dashboard_tab_nav(); ?>

			<?php
			require_once AI_O_Optimiser_PLUGIN_DIR . 'includes/class-ai-o-optimiser-cache-layers.php';
			?>
			<p class="description ai-o-optimiser-measurement-caveat">
				<?php echo esc_html( AI_O_Optimiser_Cache_Layers::dashboard_note() ); ?>
			</p>

			<section id="ai-o-optimiser-ai-brands" class="ai-o-optimiser-brand-section ai-o-optimiser-brand-section-top">
				<div class="ai-o-optimiser-section-heading-row">
					<div>
						<h2><?php esc_html_e( 'Top AI brands', 'ai-o-optimiser' ); ?></h2>
						<p class="description"><?php esc_html_e( 'Ranked by measured server-side AI activity for the selected range. This is activity volume, not a count of people or audience size.', 'ai-o-optimiser' ); ?></p>
					</div>
				</div>

				<div class="ai-o-optimiser-signal-explainer" role="note">
					<strong><?php esc_html_e( 'Signal guide:', 'ai-o-optimiser' ); ?></strong>
					<span><?php esc_html_e( 'Every signal name below carries a ? that says what it means. Counts are observed requests and referrals, not unique people or prompts.', 'ai-o-optimiser' ); ?></span>
				</div>

				<?php if ( empty( $top_brands ) ) : ?>
					<div class="ai-o-optimiser-panel">
						<p><?php esc_html_e( 'No AI brand activity has been recorded for this range yet.', 'ai-o-optimiser' ); ?></p>
					</div>
				<?php else : ?>
					<div class="ai-o-optimiser-brand-top-grid">
						<?php foreach ( $top_brands as $index => $brand ) : ?>
							<?php $this->render_brand_card( $brand, $index + 1, true ); ?>
						<?php endforeach; ?>
					</div>
				<?php endif; ?>

				<div class="ai-o-optimiser-impact-summary ai-o-optimiser-brand-meaning-summary">
					<strong><?php esc_html_e( 'What this means', 'ai-o-optimiser' ); ?></strong>
					<p><?php echo esc_html( $this->brand_signal_summary( $brand_rows ) ); ?></p>
				</div>

				<?php $this->render_provider_coverage_panel( $brand_rows ); ?>
			</section>

			<div id="ai-o-optimiser-visibility-overview" class="ai-o-optimiser-visibility-summary-grid ai-o-optimiser-brand-section-top">
				<div class="ai-o-optimiser-card ai-o-optimiser-card-highlight">
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Measured AI activity', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-card-value"><?php echo esc_html( number_format_i18n( $total_hits ) ); ?></span>
					<span class="ai-o-optimiser-card-sub"><?php echo esc_html( $range['label'] ); ?></span>
					<?php $this->render_comparison_line( $total_hits, $prev_total_hits, $comparison ); ?>
				</div>
				<div class="ai-o-optimiser-card">
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Brands seen', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-card-value"><?php echo esc_html( number_format_i18n( count( $brand_rows ) ) ); ?></span>
					<span class="ai-o-optimiser-card-sub"><?php esc_html_e( 'AI platforms with crawler or referral signals', 'ai-o-optimiser' ); ?></span>
				</div>
				<div class="ai-o-optimiser-card">
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'AI bot / fetch requests', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-card-value"><?php echo esc_html( number_format_i18n( $crawler_hits ) ); ?></span>
					<?php if ( $crawler_ok < $crawler_hits ) : ?>
						<span class="ai-o-optimiser-card-sub">
							<?php
							printf(
								/* translators: %s: number of requests that were answered with a page. */
								esc_html__( '%s were served a page; the rest were redirects, missing URLs or errors', 'ai-o-optimiser' ),
								esc_html( number_format_i18n( $crawler_ok ) )
							);
							?>
						</span>
					<?php endif; ?>
					<?php if ( $verify_on && $crawler_hits > 0 ) : ?>
						<span class="ai-o-optimiser-card-sub">
							<?php
							printf(
								/* translators: %s: number of requests whose crawler identity was proved. */
								esc_html__( '%s proved they came from the company they named', 'ai-o-optimiser' ),
								esc_html( number_format_i18n( $crawler_verified ) )
							);
							?>
						</span>
					<?php endif; ?>
					<?php $this->render_comparison_line( $crawler_hits, $prev_crawler_hits, $comparison ); ?>
				</div>
				<div class="ai-o-optimiser-card">
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'AI referral visits', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-card-value"><?php echo esc_html( number_format_i18n( $referral_hits ) ); ?></span>
					<?php $this->render_comparison_line( $referral_hits, $prev_referral_hits, $comparison ); ?>
				</div>
				<div class="ai-o-optimiser-card">
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Guidance requests', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-card-value"><?php echo esc_html( number_format_i18n( $guidance_hits ) ); ?></span>
					<?php $this->render_comparison_line( $guidance_hits, $prev_guidance_hits, $comparison ); ?>
				</div>
				<div class="ai-o-optimiser-card">
					<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Most-visited crawler page', 'ai-o-optimiser' ); ?></span>
					<span class="ai-o-optimiser-card-value ai-o-optimiser-card-value-small"><?php echo esc_html( $top_page ); ?></span>
				</div>
			</div>




			<section id="ai-o-optimiser-ai-league" class="ai-o-optimiser-brand-section">
				<h2><?php esc_html_e( 'AI brand league table', 'ai-o-optimiser' ); ?></h2>
				<p class="description"><?php esc_html_e( 'Ranks directly measurable crawler, fetcher and referral signals only. Googlebot is intentionally excluded from AI totals because the same crawler serves standard Search and Google AI Search features.', 'ai-o-optimiser' ); ?></p>
				<table class="widefat striped ai-o-optimiser-brand-league-table">
					<thead>
						<tr>
							<th><?php esc_html_e( 'Rank', 'ai-o-optimiser' ); ?></th>
							<th><?php esc_html_e( 'AI brand', 'ai-o-optimiser' ); ?></th>
							<th><?php esc_html_e( 'Total', 'ai-o-optimiser' ); ?></th>
							<th><?php esc_html_e( 'Discovery / index', 'ai-o-optimiser' ); ?><?php $this->render_signal_hint( 'discovery' ); ?></th>
							<th><?php esc_html_e( 'Live AI fetch', 'ai-o-optimiser' ); ?><?php $this->render_signal_hint( 'live' ); ?></th>
							<th><?php esc_html_e( 'Other / validation', 'ai-o-optimiser' ); ?><?php $this->render_signal_hint( 'other' ); ?></th>
							<th><?php esc_html_e( 'Referrals', 'ai-o-optimiser' ); ?><?php $this->render_signal_hint( 'referral' ); ?></th>
							<th><?php esc_html_e( 'Top source', 'ai-o-optimiser' ); ?></th>
							<th><?php esc_html_e( 'Last seen', 'ai-o-optimiser' ); ?></th>
						</tr>
					</thead>
					<tbody>
						<?php if ( empty( $brand_rows ) ) : ?>
							<tr><td colspan="9"><?php esc_html_e( 'No brand-level AI data has been recorded for this range yet.', 'ai-o-optimiser' ); ?></td></tr>
						<?php else : ?>
							<?php foreach ( $brand_rows as $index => $brand ) : ?>
								<?php
								$top_source = $brand['top_referrer_hits'] >= $brand['top_bot_hits'] && ! empty( $brand['top_referrer'] ) ? $brand['top_referrer'] : $brand['top_bot'];
								if ( empty( $top_source ) ) {
									$top_source = __( '—', 'ai-o-optimiser' );
								}
								?>
								<tr>
									<td><?php echo esc_html( '#' . ( $index + 1 ) ); ?></td>
									<td><strong><?php echo esc_html( $brand['label'] ); ?></strong></td>
									<td><?php echo esc_html( number_format_i18n( $brand['total'] ) ); ?></td>
									<td><?php echo esc_html( number_format_i18n( $brand['training_hits'] ) ); ?></td>
									<td><?php echo esc_html( number_format_i18n( $brand['user_hits'] ) ); ?></td>
									<td><?php echo esc_html( number_format_i18n( $brand['other_hits'] ) ); ?></td>
									<td><?php echo esc_html( number_format_i18n( $brand['referral_hits'] ) ); ?></td>
									<td><?php echo esc_html( $top_source ); ?></td>
									<td><?php echo $brand['last_seen'] ? esc_html( $this->format_site_time( $brand['last_seen'] ) ) : esc_html__( '—', 'ai-o-optimiser' ); ?></td>
								</tr>
							<?php endforeach; ?>
						<?php endif; ?>
					</tbody>
				</table>
			</section>

			<div class="ai-o-optimiser-columns ai-o-optimiser-top-insight-columns">
				<div class="ai-o-optimiser-column ai-o-optimiser-priority-panel">
					<h2><?php esc_html_e( 'Hits by bot type', 'ai-o-optimiser' ); ?></h2>
					<table class="widefat striped ai-o-optimiser-group-table">
						<thead>
							<tr>
								<th><?php esc_html_e( 'Bot type', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Hits', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Distinct bots', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Last seen', 'ai-o-optimiser' ); ?></th>
							</tr>
						</thead>
						<tbody>
							<?php foreach ( $by_group as $group => $group_row ) : ?>
								<tr>
									<td><?php echo esc_html( $group_row['label'] ); ?></td>
									<td><?php echo esc_html( number_format_i18n( $group_row['total'] ) ); ?></td>
									<td><?php echo esc_html( number_format_i18n( $group_row['bot_count'] ) ); ?></td>
									<td><?php echo $group_row['last_seen'] ? esc_html( $this->format_site_time( $group_row['last_seen'] ) ) : esc_html__( '—', 'ai-o-optimiser' ); ?></td>
								</tr>
							<?php endforeach; ?>
						</tbody>
					</table>
				</div>

				<div class="ai-o-optimiser-column ai-o-optimiser-priority-panel">
					<h2><?php esc_html_e( 'AI referral sources', 'ai-o-optimiser' ); ?></h2>
					<table class="widefat striped">
						<thead>
							<tr>
								<th><?php esc_html_e( 'Source', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Visits', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Last seen', 'ai-o-optimiser' ); ?></th>
							</tr>
						</thead>
						<tbody>
							<?php if ( empty( $by_referrer ) ) : ?>
								<tr><td colspan="3"><?php esc_html_e( 'No AI referral visits recorded yet for this range.', 'ai-o-optimiser' ); ?></td></tr>
							<?php else : ?>
								<?php foreach ( $by_referrer as $row ) : ?>
									<tr>
										<td><?php echo esc_html( $row->source_label ); ?></td>
										<td><?php echo esc_html( number_format_i18n( $row->total ) ); ?></td>
										<td><?php echo esc_html( $this->format_site_time( $row->last_seen ) ); ?></td>
									</tr>
								<?php endforeach; ?>
							<?php endif; ?>
						</tbody>
					</table>
				</div>
			</div>

			<h2><?php esc_html_e( 'Daily AI activity', 'ai-o-optimiser' ); ?></h2>
			<div class="ai-o-optimiser-chart">
				<?php foreach ( $daily as $day => $count ) : ?>
					<?php $height = $max_day > 0 ? max( 2, round( ( $count / $max_day ) * 100 ) ) : 2; ?>
					<div class="ai-o-optimiser-chart-col" title="<?php echo esc_attr( $day . ': ' . $count ); ?>">
						<div class="ai-o-optimiser-chart-bar" style="height: <?php echo esc_attr( $height ); ?>%;"></div>
					</div>
				<?php endforeach; ?>
			</div>
			<p class="ai-o-optimiser-chart-caption">
				<?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
					__( '%1$s — %2$s', 'ai-o-optimiser' ), array_key_first( $daily ), array_key_last( $daily ) ) ); ?>
			</p>


			<section id="ai-o-optimiser-traffic-impact" class="ai-o-optimiser-brand-section ai-o-optimiser-brand-section-top ai-o-optimiser-traffic-impact-section">
				<div class="ai-o-optimiser-section-heading-row">
					<div>
						<h2><?php esc_html_e( 'AI Visibility & Traffic Impact', 'ai-o-optimiser' ); ?></h2>
						<p class="description"><?php esc_html_e( 'Connects directly measured AI website signals with GA4 Direct-channel sessions, session duration and key events for the same period. When GA4 read access is connected, AI-O Optimiser retrieves these figures automatically through the Google Analytics Data API. Direct traffic remains supporting evidence only: it also contains bookmarks, untagged links and other unattributed visits.', 'ai-o-optimiser' ); ?></p>
					</div>
					<span class="ai-o-optimiser-badge <?php echo esc_attr( 'ai-o-optimiser-impact-badge ai-o-optimiser-impact-' . str_replace( '_', '-', $traffic_impact['level'] ) ); ?>">
						<?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
							__( 'AI-assisted traffic indication: %s', 'ai-o-optimiser' ), $traffic_impact['label'] ) ); ?>
					</span>
				</div>

				<div class="ai-o-optimiser-impact-summary">
					<strong><?php esc_html_e( 'What this means', 'ai-o-optimiser' ); ?></strong>
					<p><?php echo esc_html( $traffic_impact['summary'] ); ?></p>
					<small><?php echo esc_html( $traffic_impact['evidence_line'] ); ?></small>
				</div>

				<div class="ai-o-optimiser-visibility-summary-grid ai-o-optimiser-impact-metrics">
					<div class="ai-o-optimiser-card">
						<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'AI bot / fetch activity', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-value"><?php echo esc_html( number_format_i18n( $crawler_hits ) ); ?></span>
						<span class="ai-o-optimiser-card-sub"><?php echo esc_html( null === $traffic_impact['crawler_change'] ? __( 'No comparable prior period', 'ai-o-optimiser' ) : sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
							__( '%+.1f%% vs comparison', 'ai-o-optimiser' ), $traffic_impact['crawler_change'] ) ); ?></span>
					</div>
					<div class="ai-o-optimiser-card">
						<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Measured AI referrals', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-value"><?php echo esc_html( number_format_i18n( $referral_hits ) ); ?></span>
						<span class="ai-o-optimiser-card-sub"><?php echo esc_html( null === $traffic_impact['referral_change'] ? __( 'No comparable prior period', 'ai-o-optimiser' ) : sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
							__( '%+.1f%% vs comparison', 'ai-o-optimiser' ), $traffic_impact['referral_change'] ) ); ?></span>
					</div>
					<div class="ai-o-optimiser-card">
						<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'GA4 Direct sessions', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-value"><?php echo null !== $traffic_impact['metrics']['sessions']['current'] ? esc_html( number_format_i18n( $traffic_impact['metrics']['sessions']['current'], 0 ) ) : esc_html__( '—', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-sub"><?php echo esc_html( $this->evidence_change_text( $traffic_impact['metrics']['sessions']['current'], $traffic_impact['metrics']['sessions']['previous'] ) ); ?></span>
					</div>
					<div class="ai-o-optimiser-card">
						<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'GA4 avg session duration', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-value"><?php echo null !== $traffic_impact['metrics']['engagement']['current'] ? esc_html( number_format_i18n( $traffic_impact['metrics']['engagement']['current'], 1 ) . 's' ) : esc_html__( '—', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-sub"><?php echo esc_html( $this->evidence_change_text( $traffic_impact['metrics']['engagement']['current'], $traffic_impact['metrics']['engagement']['previous'] ) ); ?></span>
					</div>
					<div class="ai-o-optimiser-card">
						<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'GA4 Direct conversions / key events', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-value"><?php echo null !== $traffic_impact['metrics']['conversions']['current'] ? esc_html( number_format_i18n( $traffic_impact['metrics']['conversions']['current'], 1 ) ) : esc_html__( '—', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-sub"><?php echo esc_html( $this->evidence_change_text( $traffic_impact['metrics']['conversions']['current'], $traffic_impact['metrics']['conversions']['previous'] ) ); ?></span>
					</div>
					<div class="ai-o-optimiser-card">
						<span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Attribution confidence', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-value ai-o-optimiser-card-value-small"><?php esc_html_e( 'Supporting indication', 'ai-o-optimiser' ); ?></span>
						<span class="ai-o-optimiser-card-sub"><?php esc_html_e( 'Never treated as proof that Direct traffic came from AI.', 'ai-o-optimiser' ); ?></span>
					</div>
				</div>


				<?php if ( $can_administer ) : ?>
				<?php
				$selected_ga4_label = ! empty( $connector_settings['ga4_property'] ) ? $connector_settings['ga4_property'] : '';
				foreach ( $ga4_properties as $property ) {
					if ( isset( $property['property'] ) && $property['property'] === $connector_settings['ga4_property'] ) {
						$selected_ga4_label = isset( $property['display_name'] ) ? $property['display_name'] : $property['property'];
						if ( ! empty( $property['account_name'] ) ) {
							$selected_ga4_label .= ' — ' . $property['account_name'];
						}
						break;
					}
				}
				?>
				<div class="ai-o-optimiser-ga4-data-connection">
					<div class="ai-o-optimiser-section-heading-row">
						<div>
							<strong><?php esc_html_e( 'GA4 reporting source', 'ai-o-optimiser' ); ?></strong>
							<p class="description"><?php esc_html_e( 'Read-only reporting uses the Google Analytics Data API through AI-O Connector Hub. Google refresh tokens remain on the Hub; this WordPress site receives only the constrained report results.', 'ai-o-optimiser' ); ?></p>
						</div>
						<span class="ai-o-optimiser-badge <?php echo ! empty( $traffic_evidence['source'] ) && 'ga4_data_api' === $traffic_evidence['source'] ? 'ai-o-optimiser-badge-allowed' : 'ai-o-optimiser-badge-context'; ?>">
							<?php echo ! empty( $traffic_evidence['source'] ) && 'ga4_data_api' === $traffic_evidence['source'] ? esc_html__( 'GA4 Data API active', 'ai-o-optimiser' ) : esc_html__( 'GA4 Data API not active', 'ai-o-optimiser' ); ?>
						</span>
					</div>

					<?php if ( ! empty( $connector_settings['ga4_last_error'] ) ) : ?>
						<div class="notice notice-warning inline"><p><?php echo esc_html( $connector_settings['ga4_last_error'] ); ?></p></div>
					<?php elseif ( $ga4_properties_error ) : ?>
						<div class="notice notice-info inline"><p><?php echo esc_html( $ga4_properties_error->get_error_message() ); ?></p></div>
					<?php endif; ?>

					<details class="ai-o-optimiser-ga4-connection-details" <?php echo empty( $connector_settings['ga4_property'] ) ? 'open' : ''; ?>>
						<summary><strong><?php echo $selected_ga4_label ? esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
							__( 'GA4: %s', 'ai-o-optimiser' ), $selected_ga4_label ) ) : esc_html__( 'GA4: choose reporting property', 'ai-o-optimiser' ); ?></strong><span><?php echo $selected_ga4_label ? esc_html__( 'Change property or refresh permission', 'ai-o-optimiser' ) : esc_html__( 'Connect read-only reporting', 'ai-o-optimiser' ); ?></span></summary>
					<div class="ai-o-optimiser-ga4-data-actions">
						<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>">
							<input type="hidden" name="action" value="ai_o_optimiser_ga4_data_connect" />
							<?php wp_nonce_field( 'ai_o_optimiser_ga4_data_connect' ); ?>
							<button type="submit" class="button <?php echo empty( $connector_settings['ga4_property'] ) ? 'button-primary' : ''; ?>"><?php echo empty( $connector_settings['ga4_property'] ) ? esc_html__( 'Connect GA4 reporting', 'ai-o-optimiser' ) : esc_html__( 'Refresh GA4 permission', 'ai-o-optimiser' ); ?></button>
						</form>

						<?php if ( ! empty( $ga4_properties ) ) : ?>
							<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="ai-o-optimiser-ga4-property-form">
								<input type="hidden" name="action" value="ai_o_optimiser_ga4_data_save_property" />
								<?php wp_nonce_field( 'ai_o_optimiser_ga4_data_save_property' ); ?>
								<label for="ai-o-optimiser-ga4-property"><strong><?php esc_html_e( 'GA4 property', 'ai-o-optimiser' ); ?></strong></label>
								<select id="ai-o-optimiser-ga4-property" name="ga4_property">
									<option value=""><?php esc_html_e( 'Select a GA4 property', 'ai-o-optimiser' ); ?></option>
									<?php foreach ( $ga4_properties as $property ) :
										$property_resource = isset( $property['property'] ) ? $property['property'] : '';
										$property_label    = isset( $property['display_name'] ) ? $property['display_name'] : $property_resource;
										if ( ! empty( $property['account_name'] ) ) {
											$property_label .= ' — ' . $property['account_name'];
										}
									?>
										<option value="<?php echo esc_attr( $property_resource ); ?>" <?php selected( $connector_settings['ga4_property'], $property_resource ); ?>><?php echo esc_html( $property_label ); ?></option>
									<?php endforeach; ?>
								</select>
								<button type="submit" class="button"><?php esc_html_e( 'Use property', 'ai-o-optimiser' ); ?></button>
							</form>
						<?php endif; ?>
					</div>

					<?php if ( ! empty( $connector_settings['ga4_property'] ) ) : ?>
						<p class="description">
							<?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
								__( 'Selected property: %s.', 'ai-o-optimiser' ), $selected_ga4_label ? $selected_ga4_label : $connector_settings['ga4_property'] ) ); ?>
							<?php if ( ! empty( $connector_settings['ga4_last_sync'] ) ) : ?> <?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
								__( 'Last API read: %s.', 'ai-o-optimiser' ), $this->format_site_time( $connector_settings['ga4_last_sync'] ) ) ); ?><?php endif; ?>
						</p>
					<?php endif; ?>
					</details>
				</div>

				<details class="ai-o-optimiser-impact-evidence-form">
					<summary><?php esc_html_e( 'Manual GA4 evidence fallback', 'ai-o-optimiser' ); ?></summary>
					<p class="description">
						<?php esc_html_e( 'Use this only when GA4 Data API access is unavailable. Automatic API evidence takes precedence whenever a GA4 property is connected.', 'ai-o-optimiser' ); ?>
					</p>
					<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="ai-o-optimiser-impact-form">
						<?php wp_nonce_field( 'ai_o_optimiser_save_traffic_evidence' ); ?>
						<input type="hidden" name="action" value="ai_o_optimiser_save_traffic_evidence" />
						<input type="hidden" name="range" value="<?php echo esc_attr( $range['key'] ); ?>" />
						<input type="hidden" name="compare" value="<?php echo esc_attr( $range['compare'] ); ?>" />
						<?php if ( 'custom' === $range['key'] ) : ?>
							<input type="hidden" name="custom_from" value="<?php echo esc_attr( $range['custom_from'] ); ?>" />
							<input type="hidden" name="custom_to" value="<?php echo esc_attr( $range['custom_to'] ); ?>" />
						<?php endif; ?>
						<div class="ai-o-optimiser-impact-form-grid">
							<label><span><?php esc_html_e( 'Direct sessions — current', 'ai-o-optimiser' ); ?></span><input type="number" min="0" step="1" name="direct_sessions_current" value="<?php echo esc_attr( isset( $traffic_evidence['direct_sessions_current'] ) && null !== $traffic_evidence['direct_sessions_current'] ? $traffic_evidence['direct_sessions_current'] : '' ); ?>" /></label>
							<label><span><?php esc_html_e( 'Direct sessions — previous', 'ai-o-optimiser' ); ?></span><input type="number" min="0" step="1" name="direct_sessions_previous" value="<?php echo esc_attr( isset( $traffic_evidence['direct_sessions_previous'] ) && null !== $traffic_evidence['direct_sessions_previous'] ? $traffic_evidence['direct_sessions_previous'] : '' ); ?>" /></label>
							<label><span><?php esc_html_e( 'Avg session duration seconds — current', 'ai-o-optimiser' ); ?></span><input type="number" min="0" step="0.1" name="engagement_seconds_current" value="<?php echo esc_attr( isset( $traffic_evidence['engagement_seconds_current'] ) && null !== $traffic_evidence['engagement_seconds_current'] ? $traffic_evidence['engagement_seconds_current'] : '' ); ?>" /></label>
							<label><span><?php esc_html_e( 'Avg session duration seconds — previous', 'ai-o-optimiser' ); ?></span><input type="number" min="0" step="0.1" name="engagement_seconds_previous" value="<?php echo esc_attr( isset( $traffic_evidence['engagement_seconds_previous'] ) && null !== $traffic_evidence['engagement_seconds_previous'] ? $traffic_evidence['engagement_seconds_previous'] : '' ); ?>" /></label>
							<label><span><?php esc_html_e( 'Direct key events — current', 'ai-o-optimiser' ); ?></span><input type="number" min="0" step="0.1" name="conversions_current" value="<?php echo esc_attr( isset( $traffic_evidence['conversions_current'] ) && null !== $traffic_evidence['conversions_current'] ? $traffic_evidence['conversions_current'] : '' ); ?>" /></label>
							<label><span><?php esc_html_e( 'Direct key events — previous', 'ai-o-optimiser' ); ?></span><input type="number" min="0" step="0.1" name="conversions_previous" value="<?php echo esc_attr( isset( $traffic_evidence['conversions_previous'] ) && null !== $traffic_evidence['conversions_previous'] ? $traffic_evidence['conversions_previous'] : '' ); ?>" /></label>
						</div>
						<label class="ai-o-optimiser-impact-note-field"><span><?php esc_html_e( 'Optional note / GA4 report reference', 'ai-o-optimiser' ); ?></span><textarea name="traffic_evidence_note" rows="2"><?php echo esc_textarea( isset( $traffic_evidence['note'] ) ? $traffic_evidence['note'] : '' ); ?></textarea></label>
						<p><button type="submit" class="button"><?php esc_html_e( 'Save manual fallback', 'ai-o-optimiser' ); ?></button></p>
					</form>
				</details>
				<?php else : ?>
					<div class="ai-o-optimiser-ga4-data-connection ai-o-optimiser-ga4-readonly-state">
						<div class="ai-o-optimiser-section-heading-row"><div><strong><?php esc_html_e( 'GA4 reporting source', 'ai-o-optimiser' ); ?></strong><p class="description"><?php esc_html_e( 'Read-only GA4 evidence is connected and managed by an administrator. Dashboard viewers can see the reporting outcome but cannot change the Analytics connection or property.', 'ai-o-optimiser' ); ?></p></div><span class="ai-o-optimiser-badge <?php echo ! empty( $connector_settings['ga4_property'] ) ? 'ai-o-optimiser-badge-allowed' : 'ai-o-optimiser-badge-context'; ?>"><?php echo ! empty( $connector_settings['ga4_property'] ) ? esc_html__( 'GA4 connected', 'ai-o-optimiser' ) : esc_html__( 'GA4 not connected', 'ai-o-optimiser' ); ?></span></div>
						<?php if ( ! empty( $connector_settings['ga4_last_sync'] ) ) : ?><p class="description"><?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
							__( 'Last API read: %s.', 'ai-o-optimiser' ), $this->format_site_time( $connector_settings['ga4_last_sync'] ) ) ); ?></p><?php endif; ?>
					</div>
				<?php endif; ?>
			</section>




			<div class="ai-o-optimiser-columns">
				<div class="ai-o-optimiser-column">
					<h2><?php esc_html_e( 'AI guidance file requests', 'ai-o-optimiser' ); ?></h2>
					<table class="widefat striped">
						<thead>
							<tr>
								<th><?php esc_html_e( 'File', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Requests', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Last seen', 'ai-o-optimiser' ); ?></th>
							</tr>
						</thead>
						<tbody>
							<?php if ( empty( $by_guidance ) ) : ?>
								<tr><td colspan="3"><?php esc_html_e( 'No llms.txt or llms-full.txt requests recorded yet for this range.', 'ai-o-optimiser' ); ?></td></tr>
							<?php else : ?>
								<?php foreach ( $by_guidance as $row ) : ?>
									<tr>
										<td><?php echo esc_html( $row->source_label ); ?></td>
										<td><?php echo esc_html( number_format_i18n( $row->total ) ); ?></td>
										<td><?php echo esc_html( $this->format_site_time( $row->last_seen ) ); ?></td>
									</tr>
								<?php endforeach; ?>
							<?php endif; ?>
						</tbody>
					</table>
				</div>
			</div>

			<details class="ai-o-optimiser-panel ai-o-optimiser-advanced-crawler-detail">
				<summary><strong><?php esc_html_e( 'Advanced crawler detail', 'ai-o-optimiser' ); ?></strong> <span class="description"><?php esc_html_e( 'Individual bot signatures and crawler page detail for diagnostics.', 'ai-o-optimiser' ); ?></span></summary>
				<div class="ai-o-optimiser-columns">
				<div class="ai-o-optimiser-column">
					<h2><?php esc_html_e( 'Hits by bot', 'ai-o-optimiser' ); ?></h2>
					<table class="widefat striped">
						<thead>
							<tr>
								<th><?php esc_html_e( 'Bot', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Type', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Hits', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Last seen', 'ai-o-optimiser' ); ?></th>
							</tr>
						</thead>
						<tbody>
							<?php if ( empty( $by_bot ) ) : ?>
								<tr><td colspan="4"><?php esc_html_e( 'No AI bot visits recorded yet for this range.', 'ai-o-optimiser' ); ?></td></tr>
							<?php else : ?>
								<?php foreach ( $by_bot as $row ) : ?>
									<tr>
										<td><?php echo esc_html( $row->bot_label ); ?></td>
										<td><?php echo esc_html( AI_O_Optimiser_Bots::group_label( AI_O_Optimiser_Bots::group_for_slug( $row->bot_slug ) ) ); ?></td>
										<td><?php echo esc_html( number_format_i18n( $row->total ) ); ?></td>
										<td><?php echo esc_html( $this->format_site_time( $row->last_seen ) ); ?></td>
									</tr>
								<?php endforeach; ?>
							<?php endif; ?>
						</tbody>
					</table>
				</div>
				</div>
			</details>

			<div id="ai-o-optimiser-page-detail" class="ai-o-optimiser-columns">
				<div class="ai-o-optimiser-column">
					<h2><?php esc_html_e( 'Top pages visited by AI bots', 'ai-o-optimiser' ); ?></h2>
					<?php $this->render_page_intelligence_panel( $page_intel ); ?>
					<table class="widefat striped ai-o-optimiser-smart-pages-table ai-o-optimiser-smart-pages-accordion-table">
						<thead>
							<tr>
								<th><?php esc_html_e( 'Page', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Hits', 'ai-o-optimiser' ); ?></th>
							</tr>
						</thead>
						<tbody>
							<?php if ( empty( $top_bot_pages ) ) : ?>
								<tr><td colspan="2"><?php esc_html_e( 'No crawler data yet for this range.', 'ai-o-optimiser' ); ?></td></tr>
							<?php else : ?>
								<?php foreach ( $page_intel['rows'] as $row ) : ?>
									<tr>
										<td>
											<details class="ai-o-optimiser-page-accordion">
												<summary>
													<span class="ai-o-optimiser-page-summary-main">
														<code class="ai-o-optimiser-table-url"><?php echo esc_html( $row['raw'] ); ?></code>
														<span class="ai-o-optimiser-badge <?php echo esc_attr( $row['badge_class'] ); ?>"><?php echo esc_html( $row['label'] ); ?></span>
													</span>
													<span class="ai-o-optimiser-page-summary-hint"><?php esc_html_e( 'Details', 'ai-o-optimiser' ); ?></span>
												</summary>
												<div class="ai-o-optimiser-page-accordion-body">
													<div>
														<strong><?php esc_html_e( 'Smart read:', 'ai-o-optimiser' ); ?></strong>
														<span><?php echo esc_html( $row['note'] ); ?></span>
													</div>
													<?php if ( $row['normalised'] !== $row['raw'] ) : ?>
														<div>
															<strong><?php esc_html_e( 'Normalised:', 'ai-o-optimiser' ); ?></strong>
															<code><?php echo esc_html( $row['normalised'] ); ?></code>
														</div>
													<?php endif; ?>
												</div>
											</details>
										</td>
										<td class="ai-o-optimiser-page-hits-cell"><?php echo esc_html( number_format_i18n( $row['hits'] ) ); ?></td>
									</tr>
								<?php endforeach; ?>
							<?php endif; ?>
						</tbody>
					</table>
				</div>
			</div>

			<div class="ai-o-optimiser-columns">
				<div class="ai-o-optimiser-column">
					<h2><?php esc_html_e( 'Top pages from AI referrals', 'ai-o-optimiser' ); ?></h2>
					<table class="widefat striped">
						<thead>
							<tr>
								<th><?php esc_html_e( 'Page', 'ai-o-optimiser' ); ?></th>
								<th><?php esc_html_e( 'Visits', 'ai-o-optimiser' ); ?></th>
							</tr>
						</thead>
						<tbody>
							<?php if ( empty( $top_ref_pages ) ) : ?>
								<tr><td colspan="2"><?php esc_html_e( 'No AI referral page data yet for this range.', 'ai-o-optimiser' ); ?></td></tr>
							<?php else : ?>
								<?php foreach ( $top_ref_pages as $row ) : ?>
									<tr>
										<td><?php echo esc_html( $row->request_uri ); ?></td>
										<td><?php echo esc_html( number_format_i18n( $row->total ) ); ?></td>
									</tr>
								<?php endforeach; ?>
							<?php endif; ?>
						</tbody>
					</table>
				</div>
			</div>

			<?php $this->render_monthly_report_panel(); ?>
			<?php AI_O_Optimiser_Feature_Cards::render(); ?>
		</div>
		<?php
	}

	/* ----------------------------------------------------------------
	 * Logs
	 * ---------------------------------------------------------------- */

	public function render_logs() {
		// phpcs:disable WordPress.Security.NonceVerification.Recommended -- Read-only screen state (filters, tab selection, pagination, redirect result notices). Nothing is written here, so there is no form submission to carry a nonce.
		if ( ! current_user_can( self::CAPABILITY ) ) {
			return;
		}

		$range       = $this->resolve_range();
		$source_type = isset( $_GET['source_type'] ) ? $this->sanitize_source_type( sanitize_text_field( wp_unslash( $_GET['source_type'] ) ) ) : '';
		$bot_slug    = isset( $_GET['bot'] ) ? sanitize_key( wp_unslash( $_GET['bot'] ) ) : '';
		$bot_group   = isset( $_GET['group'] ) ? $this->sanitize_group_filter( sanitize_text_field( wp_unslash( $_GET['group'] ) ) ) : '';
		$page        = isset( $_GET['paged'] ) ? max( 1, (int) $_GET['paged'] ) : 1;
		$per_page    = 50;

		$filters = $this->filters_for_range( $range, $source_type );
		if ( 'referral' !== $source_type ) {
			if ( $bot_slug ) {
				$filters['bot_slug'] = $bot_slug;
			}
			if ( $bot_group && empty( $bot_slug ) ) {
				$filters['bot_slugs'] = AI_O_Optimiser_Bots::slugs_for_group( $bot_group );
			}
		}

		$rows  = AI_O_Optimiser_DB::get_rows( array_merge( $filters, array( 'page' => $page, 'per_page' => $per_page ) ) );
		$total = AI_O_Optimiser_DB::count( array_merge( $filters, array( 'raw' => true ) ) );
		$pages = max( 1, ceil( $total / $per_page ) );

		$export_args = array(
			'action'      => 'ai_o_optimiser_export_csv',
			'range'       => $range['key'],
			'custom_from' => $range['custom_from'],
			'custom_to'   => $range['custom_to'],
			'source_type' => $source_type,
			'group'       => $bot_group,
			'bot'         => $bot_slug,
		);
		$export_url = wp_nonce_url( add_query_arg( $export_args, admin_url( 'admin-post.php' ) ), 'ai_o_optimiser_export_csv' );
		?>
		<div class="wrap ai-o-optimiser-wrap">
			<h1><?php esc_html_e( 'AI-O Optimiser Logs', 'ai-o-optimiser' ); ?></h1>
			<?php self::render_settings_tabs( 'logs' ); ?>

			<div class="ai-o-optimiser-logs-toolbar">
				<?php $this->render_range_picker( 'ai-o-optimiser-logs', array( 'source_type' => $source_type, 'group' => $bot_group, 'bot' => $bot_slug ) ); ?>

				<form method="get" class="ai-o-optimiser-source-filter-form">
					<input type="hidden" name="page" value="ai-o-optimiser-logs" />
					<input type="hidden" name="range" value="<?php echo esc_attr( $range['key'] ); ?>" />
					<?php if ( $range['custom_from'] ) : ?><input type="hidden" name="custom_from" value="<?php echo esc_attr( $range['custom_from'] ); ?>" /><?php endif; ?>
					<?php if ( $range['custom_to'] ) : ?><input type="hidden" name="custom_to" value="<?php echo esc_attr( $range['custom_to'] ); ?>" /><?php endif; ?>
					<label for="ai-o-optimiser-source-type"><?php esc_html_e( 'Source:', 'ai-o-optimiser' ); ?></label>
					<select name="source_type" id="ai-o-optimiser-source-type" onchange="this.form.submit()">
						<option value=""><?php esc_html_e( 'All activity', 'ai-o-optimiser' ); ?></option>
						<option value="crawler" <?php selected( $source_type, 'crawler' ); ?>><?php esc_html_e( 'AI crawlers', 'ai-o-optimiser' ); ?></option>
						<option value="referral" <?php selected( $source_type, 'referral' ); ?>><?php esc_html_e( 'AI referrals', 'ai-o-optimiser' ); ?></option>
						<option value="guidance" <?php selected( $source_type, 'guidance' ); ?>><?php esc_html_e( 'AI guidance files', 'ai-o-optimiser' ); ?></option>
					</select>
				</form>

				<form method="get" class="ai-o-optimiser-group-filter-form">
					<input type="hidden" name="page" value="ai-o-optimiser-logs" />
					<input type="hidden" name="range" value="<?php echo esc_attr( $range['key'] ); ?>" />
					<?php if ( $range['custom_from'] ) : ?><input type="hidden" name="custom_from" value="<?php echo esc_attr( $range['custom_from'] ); ?>" /><?php endif; ?>
					<?php if ( $range['custom_to'] ) : ?><input type="hidden" name="custom_to" value="<?php echo esc_attr( $range['custom_to'] ); ?>" /><?php endif; ?>
					<?php if ( $source_type ) : ?><input type="hidden" name="source_type" value="<?php echo esc_attr( $source_type ); ?>" /><?php endif; ?>
					<label for="ai-o-optimiser-group"><?php esc_html_e( 'Bot type:', 'ai-o-optimiser' ); ?></label>
					<select name="group" id="ai-o-optimiser-group" onchange="this.form.submit()">
						<option value=""><?php esc_html_e( 'All bot types', 'ai-o-optimiser' ); ?></option>
						<?php foreach ( AI_O_Optimiser_Bots::group_definitions() as $group => $label ) : ?>
							<option value="<?php echo esc_attr( $group ); ?>" <?php selected( $bot_group, $group ); ?>><?php echo esc_html( $label ); ?></option>
						<?php endforeach; ?>
					</select>
				</form>

				<form method="get" class="ai-o-optimiser-bot-filter-form">
					<input type="hidden" name="page" value="ai-o-optimiser-logs" />
					<input type="hidden" name="range" value="<?php echo esc_attr( $range['key'] ); ?>" />
					<?php if ( $range['custom_from'] ) : ?><input type="hidden" name="custom_from" value="<?php echo esc_attr( $range['custom_from'] ); ?>" /><?php endif; ?>
					<?php if ( $range['custom_to'] ) : ?><input type="hidden" name="custom_to" value="<?php echo esc_attr( $range['custom_to'] ); ?>" /><?php endif; ?>
					<?php if ( $source_type ) : ?><input type="hidden" name="source_type" value="<?php echo esc_attr( $source_type ); ?>" /><?php endif; ?>
					<?php if ( $bot_group ) : ?><input type="hidden" name="group" value="<?php echo esc_attr( $bot_group ); ?>" /><?php endif; ?>
					<label for="ai-o-optimiser-bot"><?php esc_html_e( 'Bot:', 'ai-o-optimiser' ); ?></label>
					<select name="bot" id="ai-o-optimiser-bot" onchange="this.form.submit()">
						<option value=""><?php esc_html_e( 'All bots', 'ai-o-optimiser' ); ?></option>
						<?php foreach ( AI_O_Optimiser_Bots::group_definitions() as $group => $label ) : ?>
							<?php if ( $bot_group && $bot_group !== $group ) : ?>
								<?php continue; ?>
							<?php endif; ?>
							<optgroup label="<?php echo esc_attr( $label ); ?>">
								<?php foreach ( AI_O_Optimiser_Bots::all() as $slug => $bot ) : ?>
									<?php if ( $group !== AI_O_Optimiser_Bots::group_for_slug( $slug ) ) : ?>
										<?php continue; ?>
									<?php endif; ?>
									<option value="<?php echo esc_attr( $slug ); ?>" <?php selected( $bot_slug, $slug ); ?>>
										<?php echo esc_html( $bot['label'] ); ?>
									</option>
								<?php endforeach; ?>
							</optgroup>
						<?php endforeach; ?>
					</select>
				</form>

				<a class="button" href="<?php echo esc_url( $export_url ); ?>">
					<?php esc_html_e( 'Export CSV', 'ai-o-optimiser' ); ?>
				</a>
			</div>

			<table class="widefat striped">
				<thead>
					<tr>
						<th><?php esc_html_e( 'Time', 'ai-o-optimiser' ); ?></th>
						<th><?php esc_html_e( 'Source', 'ai-o-optimiser' ); ?></th>
						<th><?php esc_html_e( 'Type', 'ai-o-optimiser' ); ?></th>
						<th><?php esc_html_e( 'Name', 'ai-o-optimiser' ); ?></th>
						<th><?php esc_html_e( 'Page', 'ai-o-optimiser' ); ?></th>
						<th><?php esc_html_e( 'Referrer', 'ai-o-optimiser' ); ?></th>
						<th><?php esc_html_e( 'User agent', 'ai-o-optimiser' ); ?></th>
					</tr>
				</thead>
				<tbody>
					<?php if ( empty( $rows ) ) : ?>
						<tr><td colspan="7"><?php esc_html_e( 'No matching log entries.', 'ai-o-optimiser' ); ?></td></tr>
					<?php else : ?>
						<?php foreach ( $rows as $row ) : ?>
							<?php
							$row_source_type = ! empty( $row->source_type ) ? $row->source_type : 'crawler';
							$is_referral     = 'referral' === $row_source_type;
							$is_guidance     = 'guidance' === $row_source_type;
							$name            = $is_referral || $is_guidance ? $row->source_label : $row->bot_label;
							$type            = $is_referral ? __( 'AI referral', 'ai-o-optimiser' ) : ( $is_guidance ? __( 'AI guidance file', 'ai-o-optimiser' ) : AI_O_Optimiser_Bots::group_label( AI_O_Optimiser_Bots::group_for_slug( $row->bot_slug ) ) );
							$source_label    = $is_referral ? __( 'AI referral', 'ai-o-optimiser' ) : ( $is_guidance ? __( 'AI guidance', 'ai-o-optimiser' ) : __( 'AI crawler', 'ai-o-optimiser' ) );
							$source_class    = $is_referral ? 'ai-o-optimiser-badge-referral' : ( $is_guidance ? 'ai-o-optimiser-badge-guidance' : 'ai-o-optimiser-badge-crawler' );
							$type_class      = $is_referral ? 'ai-o-optimiser-badge-referral' : ( $is_guidance ? 'ai-o-optimiser-badge-guidance' : 'ai-o-optimiser-badge-other' );
							?>
							<tr>
								<td><?php echo esc_html( $this->format_site_time( $row->hit_time ) ); ?></td>
								<td><span class="ai-o-optimiser-badge <?php echo esc_attr( $source_class ); ?>"><?php echo esc_html( $source_label ); ?></span></td>
								<td><span class="ai-o-optimiser-badge <?php echo esc_attr( $type_class ); ?>"><?php echo esc_html( $type ); ?></span></td>
								<td><?php echo esc_html( $name ); ?></td>
								<td><span class="ai-o-optimiser-table-url" title="<?php echo esc_attr( $row->request_uri ); ?>"><?php echo esc_html( $row->request_uri ); ?></span></td>
								<td><span class="ai-o-optimiser-table-url" title="<?php echo esc_attr( $row->referrer ); ?>"><?php echo esc_html( $row->referrer ); ?></span></td>
								<td class="ai-o-optimiser-ua-cell" title="<?php echo esc_attr( $row->user_agent ); ?>">
									<?php echo esc_html( $this->truncate_text( $row->user_agent, 60 ) ); ?>
								</td>
							</tr>
						<?php endforeach; ?>
					<?php endif; ?>
				</tbody>
			</table>

			<?php if ( $pages > 1 ) : ?>
				<div class="ai-o-optimiser-pagination">
					<?php
					echo wp_kses_post( paginate_links(
						array(
							'base'      => add_query_arg( 'paged', '%#%' ),
							'format'    => '',
							'current'   => $page,
							'total'     => $pages,
							'prev_text' => __( '&laquo; Previous', 'ai-o-optimiser' ),
							'next_text' => __( 'Next &raquo;', 'ai-o-optimiser' ),
						)
					) );
					?>
				</div>
			<?php endif; ?>
		</div>
		<?php
		// phpcs:enable WordPress.Security.NonceVerification.Recommended
	}

	/**
	 * Stream a CSV of the filtered logs and exit.
	 */
	public function handle_csv_export() {
		if ( ! current_user_can( self::CAPABILITY ) || ! check_admin_referer( 'ai_o_optimiser_export_csv' ) ) {
			wp_die( esc_html__( 'You are not allowed to do that.', 'ai-o-optimiser' ) );
		}

		$range       = $this->resolve_range();
		$source_type = isset( $_GET['source_type'] ) ? $this->sanitize_source_type( sanitize_text_field( wp_unslash( $_GET['source_type'] ) ) ) : '';
		$bot_slug    = isset( $_GET['bot'] ) ? sanitize_key( wp_unslash( $_GET['bot'] ) ) : '';
		$bot_group   = isset( $_GET['group'] ) ? $this->sanitize_group_filter( sanitize_text_field( wp_unslash( $_GET['group'] ) ) ) : '';

		$filters = $this->filters_for_range( $range, $source_type );
		if ( 'referral' !== $source_type ) {
			if ( $bot_slug ) {
				$filters['bot_slug'] = $bot_slug;
			}
			if ( $bot_group && empty( $bot_slug ) ) {
				$filters['bot_slugs'] = AI_O_Optimiser_Bots::slugs_for_group( $bot_group );
			}
		}

		$rows = AI_O_Optimiser_DB::get_all_rows( $filters );

		nocache_headers();
		header( 'Content-Type: text/csv; charset=utf-8' );
		header( 'Content-Disposition: attachment; filename=ai-visibility-log-' . sanitize_file_name( $range['key'] ) . '-' . current_time( 'Y-m-d' ) . '.csv' );

		$output = fopen( 'php://output', 'w' );
		fputcsv( $output, $this->csv_safe_row( array( 'Time (UTC)', 'Time (Site Time)', 'Source Type', 'Activity Type', 'Name', 'Page', 'Referrer', 'User Agent' ) ) );
		foreach ( $rows as $row ) {
			$row_source_type = ! empty( $row->source_type ) ? $row->source_type : 'crawler';
			$is_referral     = 'referral' === $row_source_type;
			$is_guidance     = 'guidance' === $row_source_type;
			$name            = $is_referral || $is_guidance ? $row->source_label : $row->bot_label;
			$type            = $is_referral ? 'AI referral' : ( $is_guidance ? 'AI guidance file' : AI_O_Optimiser_Bots::group_label( AI_O_Optimiser_Bots::group_for_slug( $row->bot_slug ) ) );
			$source_label    = $is_referral ? 'AI referral' : ( $is_guidance ? 'AI guidance' : 'AI crawler' );
			fputcsv( $output, $this->csv_safe_row( array( $row->hit_time, $this->format_site_time( $row->hit_time ), $source_label, $type, $name, $row->request_uri, $row->referrer, $row->user_agent ) ) );
		}
		// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- Closes the php://output response stream for a CSV download, not a file. WP_Filesystem cannot write to the response body, and WPCS exempts the matching fopen( 'php://output' ) for the same reason.
		fclose( $output );
		exit;
	}


	/* ----------------------------------------------------------------
	 * AI Deep Review Prompt
	 * ---------------------------------------------------------------- */

	/**
	 * Make every exported CSV cell safe for spreadsheet apps that evaluate formulas.
	 *
	 * @param array $row CSV row.
	 * @return array
	 */
	private function csv_safe_row( $row ) {
		return array_map( array( $this, 'csv_safe_cell' ), $row );
	}

	/**
	 * Escape spreadsheet formula triggers in CSV cells.
	 *
	 * @param mixed $value Cell value.
	 * @return string
	 */
	private function csv_safe_cell( $value ) {
		$value = (string) $value;
		if ( preg_match( '/^[=+\-@]/', $value ) ) {
			return "'" . $value;
		}
		return $value;
	}

	/**
	 * Truncate text without requiring the mbstring extension.
	 *
	 * @param string $text Text.
	 * @param int    $length Maximum characters.
	 * @return string
	 */
	private function truncate_text( $text, $length ) {
		$text   = (string) $text;
		$length = max( 1, (int) $length );
		if ( function_exists( 'mb_strimwidth' ) ) {
			return mb_strimwidth( $text, 0, $length, '…' );
		}
		return strlen( $text ) > $length ? substr( $text, 0, max( 1, $length - 3 ) ) . '...' : $text;
	}

	/**
	 * Render a site-specific prompt for a manual AI accessibility and citation-readiness review.
	 */
	public function render_deep_review_prompt() {
		if ( ! current_user_can( self::CAPABILITY ) ) {
			wp_die( esc_html__( 'You do not have permission to access this page.', 'ai-o-optimiser' ) );
		}

		$site_url     = trailingslashit( home_url() );
		$site_name    = get_bloginfo( 'name' );
		$header_urls  = $this->get_header_menu_urls();
		$recent_posts = $this->get_recent_post_urls( 3 );
		$utility_urls = array(
			'robots.txt'        => home_url( '/robots.txt' ),
			'llms.txt'          => home_url( '/llms.txt' ),
			'sitemap_index.xml' => home_url( '/sitemap_index.xml' ),
			'sitemap.xml'       => home_url( '/sitemap.xml' ),
		);

		$prompt = $this->build_deep_review_prompt( $site_url, $site_name, $header_urls, $recent_posts, $utility_urls );
		?>
		<div class="wrap ai-o-optimiser-wrap">
			<h1><?php esc_html_e( 'AI Deep Review Prompt', 'ai-o-optimiser' ); ?></h1>
			<?php self::render_settings_tabs( 'review-prompt' ); ?>
			<p class="description">
				<?php esc_html_e( 'Use this when you are actively working on the site and want a fresh AI accessibility, crawlability and citation-readiness review from an external AI model.', 'ai-o-optimiser' ); ?>
			</p>

			<div class="ai-o-optimiser-card">
				<h2><?php esc_html_e( 'Dynamic site context', 'ai-o-optimiser' ); ?></h2>
				<table class="widefat striped">
					<tbody>
						<tr>
							<th scope="row"><?php esc_html_e( 'Site URL', 'ai-o-optimiser' ); ?></th>
							<td><code><?php echo esc_html( $site_url ); ?></code></td>
						</tr>
						<tr>
							<th scope="row"><?php esc_html_e( 'Header/menu URLs found', 'ai-o-optimiser' ); ?></th>
							<td><?php echo esc_html( count( $header_urls ) ); ?></td>
						</tr>
						<tr>
							<th scope="row"><?php esc_html_e( 'Recent posts included', 'ai-o-optimiser' ); ?></th>
							<td><?php echo esc_html( count( $recent_posts ) ); ?></td>
						</tr>
					</tbody>
				</table>
			</div>

			<div class="ai-o-optimiser-card ai-o-optimiser-deep-review-scope-card">
				<h2><?php esc_html_e( 'Audit scope guide', 'ai-o-optimiser' ); ?></h2>
				<p><?php esc_html_e( 'This screen creates a live-review prompt for an external AI model. It does not crawl the site itself. For small sites, the model should review every important public page it can discover. For larger sites, it should review the exact listed URLs plus representative page templates and clearly state what was not reviewed.', 'ai-o-optimiser' ); ?></p>
				<ul class="ul-disc">
					<li><?php esc_html_e( 'Use Schema Dash for the internal rendered JSON-LD scan.', 'ai-o-optimiser' ); ?></li>
					<li><?php esc_html_e( 'Use System Check for robots.txt, CDN/cache, DNS and llms.txt access diagnostics.', 'ai-o-optimiser' ); ?></li>
					<li><?php esc_html_e( 'Use this prompt for the broader qualitative site audit: content clarity, citation readiness, thin pages, page-source checks and practical recommendations.', 'ai-o-optimiser' ); ?></li>
				</ul>
			</div>

			<div class="ai-o-optimiser-card">
				<h2><?php esc_html_e( 'Copy prompt', 'ai-o-optimiser' ); ?></h2>
				<p><?php esc_html_e( 'Paste this into ChatGPT, Claude, Gemini, Perplexity or another AI model. The URL is generated dynamically from this WordPress installation.', 'ai-o-optimiser' ); ?></p>
				<p>
					<button type="button" class="button button-primary" id="ai-o-optimiser-copy-deep-review-prompt"><?php esc_html_e( 'Copy Prompt', 'ai-o-optimiser' ); ?></button>
					<span id="ai-o-optimiser-copy-deep-review-status" style="margin-left:8px;"></span>
				</p>
				<textarea id="ai-o-optimiser-deep-review-prompt" class="large-text code" rows="32" readonly><?php echo esc_textarea( $prompt ); ?></textarea>
			</div>
		</div>
		<?php
	}

	/**
	 * Return likely header/navigation URLs from registered WordPress menus.
	 *
	 * @return array<int,string>
	 */
	private function get_header_menu_urls() {
		$locations = get_nav_menu_locations();
		$menus     = array();
		$urls      = array();

		if ( ! empty( $locations ) ) {
			foreach ( $locations as $location => $menu_id ) {
				if ( preg_match( '/(primary|main|header|top|navigation|menu)/i', (string) $location ) ) {
					$menus[] = (int) $menu_id;
				}
			}
		}

		if ( empty( $menus ) && ! empty( $locations ) ) {
			$menus = array_map( 'intval', array_values( $locations ) );
		}

		if ( empty( $menus ) ) {
			foreach ( wp_get_nav_menus() as $menu ) {
				$menus[] = (int) $menu->term_id;
			}
		}

		foreach ( array_unique( $menus ) as $menu_id ) {
			$items = wp_get_nav_menu_items( $menu_id );
			if ( empty( $items ) || ! is_array( $items ) ) {
				continue;
			}

			foreach ( $items as $item ) {
				if ( empty( $item->url ) || '#' === $item->url ) {
					continue;
				}

				$url = esc_url_raw( $item->url );
				if ( $this->is_internal_url( $url ) ) {
					$urls[] = $url;
				}
			}
		}

		$urls = array_values( array_unique( array_map( array( $this, 'normalise_prompt_url' ), $urls ) ) );
		return array_slice( $urls, 0, 40 );
	}

	/**
	 * Return recent public post URLs for the prompt.
	 *
	 * @param int $limit Number of posts.
	 * @return array<int,string>
	 */
	private function get_recent_post_urls( $limit = 3 ) {
		$posts = get_posts(
			array(
				'post_type'      => 'post',
				'post_status'    => 'publish',
				'posts_per_page' => max( 1, (int) $limit ),
				'orderby'        => 'date',
				'order'          => 'DESC',
				'fields'         => 'ids',
			)
		);

		$urls = array();
		foreach ( $posts as $post_id ) {
			$permalink = get_permalink( $post_id );
			if ( $permalink ) {
				$urls[] = $this->normalise_prompt_url( $permalink );
			}
		}

		return array_values( array_unique( $urls ) );
	}

	/**
	 * Build the final reusable prompt text.
	 *
	 * @param string $site_url Site URL.
	 * @param string $site_name Site name.
	 * @param array  $header_urls Header/menu URLs.
	 * @param array  $recent_posts Recent post URLs.
	 * @param array  $utility_urls Utility URLs.
	 * @return string
	 */
	private function build_deep_review_prompt( $site_url, $site_name, $header_urls, $recent_posts, $utility_urls ) {
		$header_list  = $this->format_prompt_url_list( $header_urls, '- No WordPress header menu URLs were detected. Start from the homepage and discover the main header navigation manually.' );
		$post_list    = $this->format_prompt_url_list( $recent_posts, '- No recent published blog/news posts were detected. If a blog/news section exists, discover and review at least 3 recent posts manually.' );
		$utility_list = '';
		foreach ( $utility_urls as $label => $url ) {
			$utility_list .= '- ' . $label . ': ' . $url . "\n";
		}

		$current_year = gmdate( 'Y' );
		$site_host    = wp_parse_url( $site_url, PHP_URL_HOST );
		$site_host    = $site_host ? strtolower( (string) $site_host ) : $site_url;
		$rank_math_filter = "add_action( 'rank_math/llms_txt/before_output', function() {\n" .
			"    header_remove( 'X-Robots-Tag' );\n" .
			"    header( 'X-Robots-Tag: noindex', true );\n" .
			"} );";

		$prompt = array(
			'You are an expert AI Accessibility, Technical SEO, and Answer Engine Optimization (AEO) Systems Auditor.',
			'Your task is to perform an uncompromising, live, data-grounded review of this specific website only:',
			'',
			'Site name: ' . $site_name,
			'Website URL: ' . $site_url,
			'Primary domain constraint: ' . $site_host,
			'',
			'================================================================================',
			'CRITICAL OPERATIONAL DIRECTIVES — HONESTY FILTER',
			'================================================================================',
			'- ZERO INFERENCE: Do not rely on past memory, cached knowledge, brand assumptions, old crawls, generic WordPress/SEO plugin behaviour, or third-party claims.',
			'- LIVE FETCH ONLY: Every finding must be tied to a fresh live fetch of this domain during this prompt execution.',
			'- VERIFY OUTPUT, NOT SETTINGS: If a plugin, sitemap, schema element, header, robots rule, llms.txt file, or CMS feature is expected to exist, do not state that it works until you have read the actual live response headers and response body.',
			'- DOMAIN-SPECIFIC ONLY: Keep findings scoped to the listed website/domain. Do not use examples, facts, schema expectations, or competitor assumptions from other domains except when explaining why a specific observed issue matters.',
			'- NO UNLABELED ASSUMPTIONS: If you infer anything from a fetched page, label it as an inference. If you cannot directly verify something, write: "UNVERIFIED: [Element] could not be checked because [Reason]."',
			'- EVIDENCE REQUIRED: For each issue, include the exact URL/file checked, the observed HTTP status where relevant, the observed header/body/schema evidence, and why that evidence supports the finding.',
			'- CURRENT YEAR TEMPORAL ANCHOR: You are operating in calendar year ' . $current_year . '. Evaluate freshness, date signals, modified dates, reports, authorship, and stale claims using ' . $current_year . ' as the active base year.',
			'- AUDIT LABEL ACCURACY: Do not call this a full-site audit unless every important public URL was actually fetched. If you sample by template, call it a representative audit and list the sample basis.',
			'',
			'================================================================================',
			'AUDIT SCOPE AND PATHS TO REVIEW',
			'================================================================================',
			'Homepage:',
			'- ' . $site_url,
			'',
			'Main navigation URLs detected from this WordPress installation:',
			$header_list,
			'Recent blog/news URLs detected from this WordPress installation:',
			$post_list,
			'Core discovery and guidance files to fetch:',
			$utility_list,
			'If the detected lists are incomplete, discover additional public URLs from the fetched homepage, header/footer navigation, robots.txt, sitemap files, and on-page links. Keep the crawl domain-specific and list exactly what you reviewed.',
			'',
			'================================================================================',
			'WORDPRESS / RANK MATH LLMS.TXT CHECK — VERIFY LIVE OUTPUT',
			'================================================================================',
			'This prompt was generated inside WordPress, but you must not assume the live frontend is using any specific SEO plugin output. Validate the live /llms.txt response directly.',
			'',
			'For /llms.txt and /llms-full.txt where present, fetch and report:',
			'- HTTP status code after redirects.',
			'- Final URL after redirects.',
			'- Content-Type.',
			'- X-Robots-Tag header value, especially whether it contains noindex, nofollow, follow, none, or noarchive.',
			'- Whether the body is plain text/Markdown rather than an HTML page, redirect page, login page, WAF challenge, or empty response.',
			'- Whether internal links in the file point to live, indexable, useful public URLs on this same domain.',
			'',
			'Rank Math llms.txt recommendation to test against:',
			'- It is acceptable and often preferable for llms.txt to send X-Robots-Tag: noindex so the file itself is not indexed in SERPs.',
			'- It is not acceptable for llms.txt to send nofollow when the purpose of the file is to expose useful internal links to AI crawlers and answer engines.',
			'- If the live X-Robots-Tag contains nofollow, flag it as a warning and recommend removing nofollow while keeping noindex.',
			'- Recommended Rank Math filter when Rank Math is serving /llms.txt and the live response includes nofollow:',
			'```php',
			$rank_math_filter,
			'```',
			'- Do not claim this filter is installed or working unless the live /llms.txt headers confirm that X-Robots-Tag is noindex without nofollow.',
			'',
			'================================================================================',
			'AI SYSTEMS AND CRAWLERS TO CONSIDER',
			'================================================================================',
			'Assess accessibility and citation readiness from the perspective of search engines, answer engines, and AI retrieval systems including:',
			'- Google Search / Googlebot.',
			'- Google AI fetchers, including Google-Agent, Google-GeminiNotebook, legacy Google-NotebookLM and Google-CloudVertexBot where visible in logs, headers or robots context.',
			'- Google-Extended as a robots.txt policy token, not as proof of a runtime visit.',
			'- Bingbot and Microsoft Copilot/Bing answer experiences.',
			'- OpenAI systems including OAI-SearchBot, GPTBot, ChatGPT-User, and ChatGPT retrieval/search.',
			'- Anthropic systems including ClaudeBot, Claude-SearchBot, and Claude-User.',
			'- PerplexityBot and Perplexity-User.',
			'- Common Crawl and other AI discovery crawlers where live evidence makes them relevant.',
			'',
			'================================================================================',
			'WHAT TO INSPECT ON EACH REVIEWED URL',
			'================================================================================',
			'- HTTP status, redirect chain, final URL, canonical tag, meta robots, X-Robots-Tag, content type, title tag, meta description, heading structure, and indexability.',
			'- Visible page content and whether the primary entity, service/product/topic, audience, location/service area, and conversion path are explicit without relying on brand knowledge.',
			'- Rendered content where available, but also inspect source/HTML for JSON-LD, metadata, canonical tags, hreflang if present, and important content hidden behind JavaScript.',
			'- Internal links, breadcrumbs, footer/header navigation, sitemap inclusion, stale or broken links, and orphan-risk pages.',
			'- Schema markup including Organization, LocalBusiness, WebSite/SearchAction, WebPage, BreadcrumbList, Article/BlogPosting/NewsArticle, Service, Product, Offer, FAQPage, HowTo, Person, ProfilePage, AboutPage, ContactPage, Review, AggregateRating, Event, Restaurant/FoodEstablishment/Menu/MenuItem where contextually relevant.',
			'- For schema findings, separate factual errors, missing required/recommended fields, and suggestions. Do not mark a schema type as missing unless the page context genuinely warrants it.',
			'',
			'================================================================================',
			'REQUIRED REPORT FORMAT',
			'================================================================================',
			'## 1. Pages reviewed and audit coverage',
			'',
			'List the exact URLs reviewed, grouped by homepage, main navigation pages, service/product pages, blog/news posts, and utility files. State whether this is a full-site audit or representative audit and explain the coverage basis.',
			'',
			'## 2. Live fetch evidence table',
			'',
			'Create a table with: URL/file, HTTP status, final URL, content type, index/follow directive, schema types found, and notes. Include robots.txt, llms.txt, llms-full.txt if present, and sitemap files.',
			'',
			'## 3. AI crawler accessibility',
			'',
			'Check whether the website appears accessible to AI crawlers. Include robots.txt rules, Google/Gemini access signals, OpenAI access signals, Anthropic access signals, Perplexity access signals, llms.txt availability, llms.txt content usefulness, sitemap discovery, and obvious firewall/CDN/login/JavaScript/rendering barriers. Flag each issue as ✅ Pass, ⚠️ Warning, or ❌ Fail.',
			'',
			'## 4. Rank Math / llms.txt header verdict',
			'',
			'Provide the exact live X-Robots-Tag value for /llms.txt. State one of: ✅ noindex without nofollow observed; ⚠️ nofollow observed and should be removed; ⚠️ no X-Robots-Tag observed; ❌ file could not be fetched; or UNVERIFIED with reason. If nofollow is observed, include the Rank Math filter recommendation from this prompt.',
			'',
			'## 5. SEO and crawlability issues',
			'',
			'Review indexability, HTTP status, redirects, canonicals, meta robots, title tags, meta descriptions, heading structure, internal linking, sitemap availability, broken navigation paths, thin content, duplicate content, and stale pages. Prioritise issues affecting organic search, AI search, or answer engine discovery.',
			'',
			'## 6. AI citation readiness',
			'',
			'Evaluate whether an AI system could confidently cite this organisation/business. Check for clear entity name, offering descriptions, locations/service areas, contact details, physical address if relevant, founding year/history, named experts, credentials, trust signals, case studies, client/customer examples, testimonials, quantified claims, FAQs, sourceable reports, and author information. Provide an AI citation readiness score out of 10 and justify it using observed evidence only.',
			'',
			'## 7. Content gaps for AI search',
			'',
			'Identify missing or weak content that would help AI systems understand and cite the site, including FAQ content, service explanations, comparison content, pricing/process information, case studies, author bios, geographic relevance, unique proof points, topical depth, fresh research/news, answer-based content, and clear definitions of important terms.',
			'',
			'## 8. Schema and structured data',
			'',
			'List schema types observed by URL. State whether each appears useful, incomplete, missing, duplicated, conflicting, or potentially inaccurate. Include Organization, LocalBusiness, WebSite/SearchAction, WebPage, BreadcrumbList, Article/BlogPosting/NewsArticle, Service, Product/Offer, FAQPage, Person/ProfilePage, AboutPage, ContactPage, Review/AggregateRating, Event, and food/restaurant/menu schema only where the page context warrants it.',
			'',
			'## 9. Blog/news AI visibility',
			'',
			'For reviewed posts, assess whether each post has a clear title, answers a specific user question, has a clear author, visible publication or modified date, Article/BlogPosting/NewsArticle schema, relevant internal links, and citation potential.',
			'',
			'## 10. Technical risks for AI discovery',
			'',
			'Identify anything that may prevent accurate AI crawling, extraction, or citation, such as heavy JavaScript rendering, cookie banners blocking content, bot protection, Cloudflare/WAF challenges, noindex/nofollow headers, incorrect content types, missing plain-text guidance files, poor mobile rendering, hidden text, broken schema, duplicate titles, canonical conflicts, blocked assets, or important content embedded in images/PDFs only.',
			'',
			'## 11. Priority issue table',
			'',
			'Create a table with these columns: Priority, Issue, Evidence, Affected URL/file, Why it matters, Recommended fix. Use priority levels: 🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low. Every row must be tied to observed live evidence or explicitly labelled UNVERIFIED.',
			'',
			'## 12. Recommended next actions',
			'',
			'Split the action plan into: Fix immediately, Improve this month, and Content opportunities. Keep every recommendation specific to this domain and tied to a reviewed URL/file.',
			'',
			'## 13. Final summary',
			'',
			'Provide a concise executive summary covering whether the site is accessible to AI crawlers, whether Google/Gemini and other AI systems are likely to understand it correctly, whether it is citation-ready, the top 3 fixes, and the top 3 content opportunities.',
			'',
			'Do not provide generic advice. Every recommendation must be tied to a specific observed issue, missing signal, or unverified live-check limitation from this exact site.',
		);

		return implode( "\n", $prompt );
	}

	/**
	 * Convert URL array into a prompt list.
	 *
	 * @param array  $urls URLs.
	 * @param string $empty Empty-state line.
	 * @return string
	 */
	private function format_prompt_url_list( $urls, $empty ) {
		if ( empty( $urls ) ) {
			return $empty . "\n";
		}

		$output = '';
		foreach ( $urls as $url ) {
			$output .= '- ' . $url . "\n";
		}
		return $output;
	}

	/**
	 * Check if a URL belongs to this site.
	 *
	 * @param string $url URL.
	 * @return bool
	 */
	private function is_internal_url( $url ) {
		$site_host = wp_parse_url( home_url(), PHP_URL_HOST );
		$url_host  = wp_parse_url( $url, PHP_URL_HOST );

		return empty( $url_host ) || strtolower( (string) $site_host ) === strtolower( (string) $url_host );
	}

	/**
	 * Normalise a URL for display in the prompt.
	 *
	 * @param string $url URL.
	 * @return string
	 */
	private function normalise_prompt_url( $url ) {
		$url = trim( (string) $url );
		if ( 0 === strpos( $url, '/' ) ) {
			$url = home_url( $url );
		}
		return esc_url_raw( $url );
	}

	/* ----------------------------------------------------------------
	 * Settings
	 * ---------------------------------------------------------------- */

	/**
	 * Central operational notifications workspace.
	 *
	 * Keeps unresolved cross-module notices available to administrators without
	 * consuming prime space on Dashboard or Metadata during normal work.
	 */
	public function render_notifications() {
		if ( ! current_user_can( self::SENSITIVE_CAPABILITY ) ) {
			wp_die( esc_html__( 'Administrator access is required for AI-O Optimiser notifications.', 'ai-o-optimiser' ) );
		}
		?>
		<div class="wrap ai-o-optimiser-wrap">
			<h1><?php esc_html_e( 'Notifications', 'ai-o-optimiser' ); ?></h1>
			<?php self::render_settings_tabs( 'notifications' ); ?>
			<p class="description"><?php esc_html_e( 'Operational notices that may need administrator attention. Routine Dashboard and Metadata work stays uncluttered when everything is healthy.', 'ai-o-optimiser' ); ?></p>
			<?php $this->render_needs_attention(); ?>
		</div>
		<?php
	}

	public function render_settings() {
		// phpcs:disable WordPress.Security.NonceVerification.Recommended -- Read-only screen state (filters, tab selection, pagination, redirect result notices). Nothing is written here, so there is no form submission to carry a nonce.
		if ( ! current_user_can( self::SENSITIVE_CAPABILITY ) ) {
			wp_die( esc_html__( 'Administrator access is required for AI-O Optimiser settings.', 'ai-o-optimiser' ) );
		}

		$settings     = wp_parse_args( get_option( 'ai_o_optimiser_settings', array() ), self::default_settings() );
		$custom_lines = array();
		foreach ( $settings['custom_bots'] as $slug => $bot ) {
			$custom_lines[] = $bot['needle'] . '|' . $bot['label'];
		}
		?>
		<div class="wrap ai-o-optimiser-wrap">
			<h1><?php esc_html_e( 'AI-O Optimiser Settings', 'ai-o-optimiser' ); ?></h1>
			<?php self::render_settings_tabs( 'settings' ); ?>

				<?php if ( isset( $_GET['updated'] ) ) : ?>
				<div class="notice notice-success is-dismissible"><p><?php esc_html_e( 'Settings saved.', 'ai-o-optimiser' ); ?></p></div>
			<?php endif; ?>

			<?php
			$ga4_test_result = get_transient( AI_O_Optimiser_GA4::TEST_RESULT_OPTION );
			if ( false !== $ga4_test_result ) :
				delete_transient( AI_O_Optimiser_GA4::TEST_RESULT_OPTION );
				$notice_class = ! empty( $ga4_test_result['success'] ) ? 'notice-success' : 'notice-error';
				?>
				<div class="notice <?php echo esc_attr( $notice_class ); ?> is-dismissible"><p><?php echo esc_html( $ga4_test_result['message'] ); ?></p></div>
			<?php endif; ?>

			<?php AI_O_Optimiser_Settings_Navigation::open_panel( 'setup' ); ?>
			<?php AI_O_Optimiser_Settings_Navigation::print_stashed( 'setup' ); ?>
			<div class="ai-o-optimiser-card ai-o-optimiser-setup-connections">
				<div class="ai-o-optimiser-panel-heading-row">
					<div>
						<h2><?php esc_html_e( 'Setup & connections', 'ai-o-optimiser' ); ?></h2>
						<p class="description"><?php esc_html_e( 'The main setup actions in one place. Use these before running Metadata, Schema or NAP work on a new site.', 'ai-o-optimiser' ); ?></p>
					</div>
				</div>
				<div class="ai-o-optimiser-setup-connections-grid">
					<div class="ai-o-optimiser-setup-connection-card">
						<strong><?php esc_html_e( 'System Check', 'ai-o-optimiser' ); ?></strong>
						<p><?php esc_html_e( 'Check robots.txt, crawler access, DNS, cache/CDN signals and runtime health.', 'ai-o-optimiser' ); ?></p>
						<a class="button" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-system-check' ) ); ?>"><?php esc_html_e( 'Open System Check', 'ai-o-optimiser' ); ?></a>
					</div>
					<div class="ai-o-optimiser-setup-connection-card is-primary">
						<strong><?php esc_html_e( 'AI API keys', 'ai-o-optimiser' ); ?></strong>
						<p><?php esc_html_e( 'Add or replace OpenAI and Gemini API keys used when a compatible WordPress AI connector is unavailable.', 'ai-o-optimiser' ); ?></p>
						<a class="button button-primary" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=settings#ai-o-optimiser-metadata-api-keys' ) ); ?>"><?php esc_html_e( 'Manage AI API keys', 'ai-o-optimiser' ); ?></a>
					</div>
					<div class="ai-o-optimiser-setup-connection-card">
						<strong><?php esc_html_e( 'Search data', 'ai-o-optimiser' ); ?></strong>
						<p><?php esc_html_e( 'Connect Google Search Console and optionally add a Bing Webmaster API key for opportunity evidence.', 'ai-o-optimiser' ); ?></p>
						<a class="button" href="<?php echo esc_url( admin_url( 'admin.php?page=ai-o-optimiser-metadata-workflow&tab=opportunities#ai-o-optimiser-metadata-subtab-settings' ) ); ?>"><?php esc_html_e( 'Manage search connections', 'ai-o-optimiser' ); ?></a>
					</div>
				</div>
			</div>
			<?php AI_O_Optimiser_Settings_Navigation::close_panel(); ?>

			<form method="post" class="ai-o-optimiser-panel" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>"<?php echo in_array( AI_O_Optimiser_Settings_Navigation::current_section(), AI_O_Optimiser_Settings_Navigation::form_sections(), true ) ? '' : ' hidden'; ?>>
				<?php wp_nonce_field( 'ai_o_optimiser_save_settings' ); ?>
				<input type="hidden" name="ai_o_optimiser_section" value="<?php echo esc_attr( AI_O_Optimiser_Settings_Navigation::current_section() ); ?>" />
				<input type="hidden" name="action" value="ai_o_optimiser_save_settings" />

				<?php AI_O_Optimiser_Settings_Navigation::open_panel( 'tracking' ); ?>
				<?php AI_O_Optimiser_Settings_Navigation::heading( 'tracking', __( 'Crawler &amp; referral tracking', 'ai-o-optimiser' ) ); ?>
			<?php $this->render_near_miss_card( $settings ); ?>
				<p class="description"><?php esc_html_e( 'What gets logged, and which known AI bots and answer platforms to track.', 'ai-o-optimiser' ); ?></p>
				<table class="form-table" role="presentation">
					<tr id="ai-o-optimiser-crawler-tracking-setting">
						<th scope="row"><?php esc_html_e( 'Crawler tracking', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="enabled" value="1" <?php checked( ! empty( $settings['enabled'] ) ); ?> />
								<?php esc_html_e( 'Log visits from known AI crawlers and assistants', 'ai-o-optimiser' ); ?>
							</label>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'AI referral tracking', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="enable_referrals" value="1" <?php checked( ! empty( $settings['enable_referrals'] ) ); ?> />
								<?php esc_html_e( 'Log visits referred by known AI answer platforms such as ChatGPT, Perplexity, Claude, Gemini and Copilot', 'ai-o-optimiser' ); ?>
							</label>
							<p class="description"><?php esc_html_e( 'Three signals are read, in this order: the referring site, the assistant app that opened the link, and a campaign parameter such as utm_source=chatgpt.com on the link itself. The third matters because many assistant visits now arrive with no referrer at all. The parameter is read from the live request only; whether it is stored follows the query-string setting under Privacy below.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'Bots to track', 'ai-o-optimiser' ); ?></th>
						<td>
							<p class="description"><?php esc_html_e( 'Runtime matches are based on User-Agent strings, which any client can set to anything. Turn on identity verification below to record, per request, whether the claim was checked and whether it held.', 'ai-o-optimiser' ); ?></p>
							<?php foreach ( AI_O_Optimiser_Bots::group_definitions() as $group => $label ) : ?>
								<h3 class="ai-o-optimiser-settings-group-heading"><?php echo esc_html( $label ); ?></h3>
								<?php foreach ( AI_O_Optimiser_Bots::defaults() as $slug => $bot ) : ?>
									<?php if ( $group !== AI_O_Optimiser_Bots::group_for_slug( $slug ) ) : ?>
										<?php continue; ?>
									<?php endif; ?>
									<label class="ai-o-optimiser-bot-checkbox">
										<input
											type="checkbox"
											name="tracked_bots[<?php echo esc_attr( $slug ); ?>]"
											value="1"
											<?php checked( ! empty( $settings['tracked_bots'][ $slug ] ) ); ?>
										/>
										<?php echo esc_html( $bot['label'] ); ?>
									</label><br />
								<?php endforeach; ?>
							<?php endforeach; ?>
							<h3 class="ai-o-optimiser-settings-group-heading"><?php esc_html_e( 'Robots.txt policy tokens', 'ai-o-optimiser' ); ?></h3>
							<p class="description"><?php esc_html_e( 'Googlebot is shown as a Google AI Search crawl-eligibility signal but is not counted as AI activity because it also serves ordinary Google Search. Google-Extended is checked as a Gemini / Vertex robots.txt policy token and is not loggable as a separate HTTP User-Agent.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row">
							<label for="ai-o-optimiser-custom-bots"><?php esc_html_e( 'Custom signatures', 'ai-o-optimiser' ); ?></label>
						</th>
						<td>
							<textarea
								id="ai-o-optimiser-custom-bots"
								name="custom_bots_raw"
								rows="4"
								class="large-text code"
								placeholder="SomeNewBot|My Label For This Bot"
							><?php echo esc_textarea( implode( "\n", $custom_lines ) ); ?></textarea>
							<p class="description">
								<?php esc_html_e( 'One per line, format: UserAgentSubstring|Label. Use this to add a new bot before it appears in a plugin update.', 'ai-o-optimiser' ); ?>
							</p>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'Verify crawler identity', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="verify_bot_identity" value="1" <?php checked( ! empty( $settings['verify_bot_identity'] ) ); ?> />
								<?php esc_html_e( 'Check that a request claiming to be an AI crawler really came from that company', 'ai-o-optimiser' ); ?>
							</label>
							<p class="description">
								<?php esc_html_e( 'Off by default. A User-Agent header is just text, so anything can call itself GPTBot and be counted as one. Where a company publishes the addresses its crawlers use — OpenAI, Anthropic and Perplexity do — each request is checked against that list. Where a company documents reverse-DNS instead — Google and Apple — the address is resolved to a name and the name resolved back, and both have to agree.', 'ai-o-optimiser' ); ?>
							</p>
							<p class="description">
								<?php esc_html_e( 'Requests are marked verified, failed, or no published proof. The last of those is not a failure: it means the company offers nothing to check against, so nothing can be concluded either way. Turning this on lets the site fetch those published lists once a day, and make a reverse-DNS lookup for crawlers checked that way — after the page has already been sent, so visitors never wait for it.', 'ai-o-optimiser' ); ?>
							</p>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'Near-miss capture', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="near_miss_capture_enabled" value="1" <?php checked( ! empty( $settings['near_miss_capture_enabled'] ) ); ?> />
								<?php esc_html_e( 'Capture requests that loosely resemble an AI platform but do not match a known signature', 'ai-o-optimiser' ); ?>
							</label>
							<p class="description"><?php esc_html_e( 'Off by default. Every request already gets checked against the signature list above; a request that fails that check normally leaves no trace at all. This stores just the raw User-Agent string of anything that mentions a known AI-brand name anyway, so you can see exactly what a platform sent and add it as a custom signature above. No IP address is stored.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
				</table>

				<?php AI_O_Optimiser_Settings_Navigation::close_panel(); ?>
				<?php AI_O_Optimiser_Settings_Navigation::open_panel( 'privacy' ); ?>
				<?php AI_O_Optimiser_Settings_Navigation::heading( 'privacy', __( 'Privacy &amp; data retention', 'ai-o-optimiser' ) ); ?>
				<p class="description"><?php esc_html_e( 'What gets stored from each request, for how long, and what happens to it if the plugin is removed.', 'ai-o-optimiser' ); ?></p>
				<table class="form-table" role="presentation">
					<tr>
						<th scope="row"><?php esc_html_e( 'Stored page paths', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="strip_query_strings" value="1" <?php checked( ! empty( $settings['strip_query_strings'] ) ); ?> />
								<?php esc_html_e( 'Strip query strings before storing page paths', 'ai-o-optimiser' ); ?>
							</label>
							<p class="description"><?php esc_html_e( 'Recommended. Query strings can contain emails, tokens, click IDs or other identifiers.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'Stored referrers', 'ai-o-optimiser' ); ?></th>
						<td>
							<select name="referrer_storage">
								<option value="domain" <?php selected( $settings['referrer_storage'], 'domain' ); ?>><?php esc_html_e( 'Domain only, recommended', 'ai-o-optimiser' ); ?></option>
								<option value="full" <?php selected( $settings['referrer_storage'], 'full' ); ?>><?php esc_html_e( 'Full referrer URL', 'ai-o-optimiser' ); ?></option>
							</select>
							<p class="description"><?php esc_html_e( 'The plugin can match AI sources using the live request referrer without permanently storing the full URL.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-trusted-proxies"><?php esc_html_e( 'Reverse proxies in front of this site', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<textarea
								id="ai-o-optimiser-trusted-proxies"
								name="trusted_proxies"
								rows="3"
								class="large-text code"
								placeholder="10.0.0.1&#10;192.168.0.0/16"
							><?php echo esc_textarea( (string) $settings['trusted_proxies'] ); ?></textarea>
							<p class="description">
								<?php esc_html_e( 'Leave empty unless this site sits behind a load balancer or proxy you run. One address or CIDR block per line. Only these are allowed to tell the plugin who a visitor is; a forwarded address from anywhere else is ignored, because any visitor can send that header. Cloudflare is recognised from its published ranges and does not need to be listed.', 'ai-o-optimiser' ); ?>
							</p>
							<p class="description">
								<?php esc_html_e( 'Without this, every visitor behind the proxy is counted as the proxy itself, which merges their visits together and makes crawler identity impossible to verify.', 'ai-o-optimiser' ); ?>
							</p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-raw-retention"><?php esc_html_e( 'Detailed request history', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<input type="number" id="ai-o-optimiser-raw-retention" name="raw_retention_days" min="1" max="30" step="1" value="<?php echo esc_attr( $settings['raw_retention_days'] ); ?>" class="small-text" />
							<?php esc_html_e( 'days', 'ai-o-optimiser' ); ?>
							<p class="description"><?php esc_html_e( 'Short-lived row-level diagnostics only. The newest 50,000 detailed requests are kept at most; long-term reporting uses compact daily aggregates instead.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-aggregate-retention"><?php esc_html_e( 'Visibility trend history', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<input type="number" id="ai-o-optimiser-aggregate-retention" name="aggregate_retention_days" min="90" max="1095" step="1" value="<?php echo esc_attr( $settings['aggregate_retention_days'] ); ?>" class="small-text" />
							<?php esc_html_e( 'days', 'ai-o-optimiser' ); ?>
							<p class="description"><?php esc_html_e( 'Compact daily counts retain crawler, referral and page trends without keeping one database row for every hit. Default: 730 days.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'When this plugin is deleted', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="delete_data_on_uninstall" value="1" <?php checked( ! empty( $settings['delete_data_on_uninstall'] ) ); ?> />
								<?php esc_html_e( 'Remove all AI-O Optimiser data (logs, settings, saved schema) when the plugin is deleted', 'ai-o-optimiser' ); ?>
							</label>
							<p class="description">
								<?php esc_html_e( 'Off by default. Deactivating the plugin never deletes data — this only applies if you delete it entirely from the Plugins screen.', 'ai-o-optimiser' ); ?>
							</p>
						</td>
					</tr>
				</table>

				<?php AI_O_Optimiser_Settings_Navigation::close_panel(); ?>
				<?php AI_O_Optimiser_Settings_Navigation::open_panel( 'integrations' ); ?>
				<?php AI_O_Optimiser_Settings_Navigation::heading( 'integrations', __( 'Integrations', 'ai-o-optimiser' ) ); ?>
				<p class="description"><?php esc_html_e( 'Send AI visibility events to Google Analytics 4 alongside the plugin\'s own reports.', 'ai-o-optimiser' ); ?></p>
				<table class="form-table" role="presentation">
					<tr>
						<th scope="row"><?php esc_html_e( 'GA4 event export', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="ga4_enabled" value="1" <?php checked( ! empty( $settings['ga4_enabled'] ) ); ?> />
								<?php esc_html_e( 'Export AI traffic visibility events to Google Analytics 4', 'ai-o-optimiser' ); ?>
							</label>
							<p class="description">
								<?php esc_html_e( 'Uses GA4 Measurement Protocol custom events. Local plugin reports remain the source of truth.', 'ai-o-optimiser' ); ?>
							</p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-ga4-measurement-id"><?php esc_html_e( 'GA4 Measurement ID', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<input type="text" id="ai-o-optimiser-ga4-measurement-id" name="ga4_measurement_id" value="<?php echo esc_attr( $settings['ga4_measurement_id'] ); ?>" class="regular-text" placeholder="G-XXXXXXXXXX" />
							<p class="description"><?php esc_html_e( 'Use the Measurement ID from your GA4 web data stream.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-ga4-api-secret"><?php esc_html_e( 'GA4 API secret', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<input type="password" id="ai-o-optimiser-ga4-api-secret" name="ga4_api_secret" value="" class="regular-text" autocomplete="new-password" placeholder="<?php echo ! empty( $settings['ga4_api_secret'] ) ? esc_attr__( 'Saved - leave blank to keep', 'ai-o-optimiser' ) : esc_attr__( 'Paste API secret', 'ai-o-optimiser' ); ?>" />
							<?php if ( ! empty( $settings['ga4_api_secret'] ) ) : ?>
								<label class="ai-o-optimiser-inline-option"><input type="checkbox" name="ga4_clear_api_secret" value="1" /> <?php esc_html_e( 'Clear saved secret', 'ai-o-optimiser' ); ?></label>
							<?php endif; ?>
							<p class="description"><?php esc_html_e( 'Create this under GA4 Admin → Data streams → your web stream → Measurement Protocol API secrets.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'GA4 collection region', 'ai-o-optimiser' ); ?></th>
						<td>
							<select name="ga4_region">
								<option value="global" <?php selected( $settings['ga4_region'], 'global' ); ?>><?php esc_html_e( 'Global endpoint', 'ai-o-optimiser' ); ?></option>
								<option value="eu" <?php selected( $settings['ga4_region'], 'eu' ); ?>><?php esc_html_e( 'EU endpoint', 'ai-o-optimiser' ); ?></option>
							</select>
						</td>
					</tr>
					<tr>
						<th scope="row"><?php esc_html_e( 'GA4 events to export', 'ai-o-optimiser' ); ?></th>
						<td>
							<label class="ai-o-optimiser-bot-checkbox"><input type="checkbox" name="ga4_export_crawlers" value="1" <?php checked( ! empty( $settings['ga4_export_crawlers'] ) ); ?> /> <?php esc_html_e( 'AI crawler hits: ai_crawler_hit', 'ai-o-optimiser' ); ?></label><br />
							<label class="ai-o-optimiser-bot-checkbox"><input type="checkbox" name="ga4_export_referrals" value="1" <?php checked( ! empty( $settings['ga4_export_referrals'] ) ); ?> /> <?php esc_html_e( 'AI referral visits: ai_referral_visit', 'ai-o-optimiser' ); ?></label><br />
							<label class="ai-o-optimiser-bot-checkbox"><input type="checkbox" name="ga4_export_guidance" value="1" <?php checked( ! empty( $settings['ga4_export_guidance'] ) ); ?> /> <?php esc_html_e( 'Guidance-file requests: ai_guidance_file_request', 'ai-o-optimiser' ); ?></label>
							<p class="description"><?php esc_html_e( 'Exported parameters include source type, source label, bot label, safe request path and referrer domain only.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<?php
					if ( class_exists( 'AI_O_Optimiser_Site_Report' ) ) {
						AI_O_Optimiser_Site_Report::render_setting_row( $settings );
					}
					?>
				</table>

				<?php AI_O_Optimiser_Settings_Navigation::close_panel(); ?>
				<?php AI_O_Optimiser_Settings_Navigation::open_panel( 'health' ); ?>
				<?php AI_O_Optimiser_Settings_Navigation::heading( 'health', __( 'Nightly health monitor', 'ai-o-optimiser' ) ); ?>
				<p class="description"><?php esc_html_e( 'An automated background check for AI crawlability and SEO sanity issues, with email alerts on failure.', 'ai-o-optimiser' ); ?></p>
				<table class="form-table" role="presentation">
					<tr id="ai-o-optimiser-nightly-health-monitor-setting">
						<th scope="row"><?php esc_html_e( 'Nightly health monitor', 'ai-o-optimiser' ); ?></th>
						<td>
							<label>
								<input type="checkbox" name="health_check_enabled" value="1" <?php checked( ! empty( $settings['health_check_enabled'] ) ); ?> />
								<?php esc_html_e( 'Run an automated AI crawlability and SEO sanity check on this schedule', 'ai-o-optimiser' ); ?>
							</label>
							<p class="description"><?php esc_html_e( 'Uses WordPress cron. The check runs after the first site visit after the scheduled hour.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-health-email"><?php esc_html_e( 'Tech alert email', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<input type="email" id="ai-o-optimiser-health-email" name="health_check_email" value="<?php echo esc_attr( $settings['health_check_email'] ); ?>" class="regular-text" />
							<p class="description"><?php esc_html_e( 'Failure reports are sent here. Defaults to the WordPress admin email.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-health-frequency"><?php esc_html_e( 'Frequency', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<select id="ai-o-optimiser-health-frequency" name="health_check_frequency">
								<option value="daily" <?php selected( 'weekly' !== ( $settings['health_check_frequency'] ?? 'daily' ) ); ?>><?php esc_html_e( 'Daily', 'ai-o-optimiser' ); ?></option>
								<option value="weekly" <?php selected( 'weekly' === ( $settings['health_check_frequency'] ?? 'daily' ) ); ?>><?php esc_html_e( 'Weekly', 'ai-o-optimiser' ); ?></option>
							</select>
							<p class="description"><?php esc_html_e( 'Daily catches a crawler-access break the same day it happens. Weekly runs the same checks with less background load, at the cost of up to a week before a break is caught — a reasonable trade on a low-change site.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
					<tr>
						<th scope="row"><label for="ai-o-optimiser-health-hour"><?php esc_html_e( 'Run hour', 'ai-o-optimiser' ); ?></label></th>
						<td>
							<input type="number" id="ai-o-optimiser-health-hour" name="health_check_hour" min="17" max="23" step="1" value="<?php echo esc_attr( $settings['health_check_hour'] ); ?>" class="small-text" />
							<?php esc_html_e( ':00 site time', 'ai-o-optimiser' ); ?>
							<p class="description"><?php esc_html_e( 'On weekly, the first run after saving sets the weekday; it repeats on that same weekday and hour.', 'ai-o-optimiser' ); ?></p>
						</td>
					</tr>
				</table>

				<?php
				$storage = AI_O_Optimiser_DB::storage_report();
				$aggregate_state = isset( $storage['aggregate_state'] ) && is_array( $storage['aggregate_state'] ) ? $storage['aggregate_state'] : array();
				$aggregate_total = max( 0, (int) ( $aggregate_state['max_id'] ?? 0 ) );
				$aggregate_done = min( $aggregate_total, max( 0, (int) ( $aggregate_state['last_id'] ?? 0 ) ) );
				$aggregate_pct = $aggregate_total > 0 ? min( 100, (int) round( ( $aggregate_done / $aggregate_total ) * 100 ) ) : ( ! empty( $aggregate_state['complete'] ) ? 100 : 0 );
				?>
				<div id="ai-o-optimiser-storage-guardrails" class="ai-o-optimiser-panel ai-o-optimiser-storage-guardrails">
					<h2><?php esc_html_e( 'Database guardrails', 'ai-o-optimiser' ); ?></h2>
					<p><?php esc_html_e( 'AI-O Optimiser keeps high-volume data bounded: detailed request rows are short-lived and capped at 50,000, while long-term Visibility Dash reporting uses compact daily aggregates. Completed/error Metadata Queue history is capped at 5,000 rows; Search Insights imports replace prior source rows; Schema Dash keeps the current audit, one temporary baseline and eight compact history summaries.', 'ai-o-optimiser' ); ?></p>
					<div class="ai-o-optimiser-status-grid ai-o-optimiser-status-grid-3">
						<div class="ai-o-optimiser-card"><span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Plugin table storage', 'ai-o-optimiser' ); ?></span><strong><?php echo esc_html( size_format( isset( $storage['table_bytes'] ) ? (int) $storage['table_bytes'] : 0, 2 ) ); ?></strong></div>
						<div class="ai-o-optimiser-card"><span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Schema option storage', 'ai-o-optimiser' ); ?></span><strong><?php echo esc_html( size_format( isset( $storage['schema_option_bytes'] ) ? (int) $storage['schema_option_bytes'] : 0, 2 ) ); ?></strong></div>
						<div class="ai-o-optimiser-card"><span class="ai-o-optimiser-card-label"><?php esc_html_e( 'Estimated AI-O Optimiser storage', 'ai-o-optimiser' ); ?></span><strong><?php echo esc_html( size_format( isset( $storage['total_bytes'] ) ? (int) $storage['total_bytes'] : 0, 2 ) ); ?></strong></div>
					</div>
					<?php if ( isset( $_GET['ai_o_optimiser_storage_backfill'] ) && in_array( sanitize_key( wp_unslash( $_GET['ai_o_optimiser_storage_backfill'] ) ), array( 'progress', 'complete' ), true ) ) : ?>
						<div class="notice notice-success inline"><p><?php echo ! empty( $aggregate_state['complete'] ) ? esc_html__( 'Visibility storage backfill is complete. Retention cleanup has been allowed to run.', 'ai-o-optimiser' ) : esc_html__( 'One bounded visibility-storage backfill batch was processed. Background migration remains scheduled.', 'ai-o-optimiser' ); ?></p></div>
					<?php endif; ?>
					<div class="ai-o-optimiser-storage-migration-status">
						<p><strong><?php esc_html_e( 'Visibility storage migration', 'ai-o-optimiser' ); ?></strong> — <?php echo esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
							__( '%1$s / %2$s historic rows aggregated (%3$s%%)', 'ai-o-optimiser' ), number_format_i18n( $aggregate_done ), number_format_i18n( $aggregate_total ), number_format_i18n( $aggregate_pct ) ) ); ?></p>
						<?php if ( empty( $aggregate_state['complete'] ) ) : ?>
							<p class="description"><?php esc_html_e( 'Background migration continues through WP-Cron. Use the button to safely process one 5,000-row batch now; it will not try to finish the whole migration in this request.', 'ai-o-optimiser' ); ?></p>
							<form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" class="ai-o-optimiser-inline-form">
								<?php wp_nonce_field( 'ai_o_optimiser_process_visibility_backfill' ); ?>
								<input type="hidden" name="action" value="ai_o_optimiser_process_visibility_backfill" />
								<?php submit_button( __( 'Process next backfill batch', 'ai-o-optimiser' ), 'secondary', 'submit', false ); ?>
							</form>
						<?php else : ?>
							<p class="description"><?php esc_html_e( 'Backfill complete. Long-term visibility reporting uses compact daily aggregates and normal retention cleanup can remove expired raw detail.', 'ai-o-optimiser' ); ?></p>
						<?php endif; ?>
					</div>
					<p class="description"><?php esc_html_e( 'Storage is checked again by Environmental Safety Check → Database / storage guardrails. Daily cleanup never removes queued or suggested metadata work. If the 5,000 terminal-item ceiling is ever exceeded, the oldest applied queue records can lose one-click rollback history; the metadata already written to posts is not removed.', 'ai-o-optimiser' ); ?></p>
				</div>

				<p class="ai-o-optimiser-privacy-note">
					<?php esc_html_e( 'Privacy note: IP addresses are stored as a salted one-way hash rather than plain text. Logs may still be personal data depending on jurisdiction and site traffic, especially if full referrer URLs or query strings are stored.', 'ai-o-optimiser' ); ?>
				</p>

			<?php $this->render_background_jobs(); ?>
				<?php AI_O_Optimiser_Settings_Navigation::print_stashed( 'health' ); ?>
				<?php AI_O_Optimiser_Settings_Navigation::render_checks_panel(); ?>
				<?php AI_O_Optimiser_Settings_Navigation::close_panel(); ?>
				<?php submit_button( __( 'Save Settings', 'ai-o-optimiser' ) ); ?>
			</form>

			<div class="ai-o-optimiser-settings-section-panel"<?php echo AI_O_Optimiser_Settings_Navigation::is_active( 'health' ) ? '' : ' hidden'; ?>>
				<?php if ( class_exists( 'AI_O_Optimiser_Email_Report' ) ) { AI_O_Optimiser_Email_Report::render_settings_panel(); } ?>
			</div>

			<div class="ai-o-optimiser-settings-section-panel"<?php echo AI_O_Optimiser_Settings_Navigation::is_active( 'integrations' ) ? '' : ' hidden'; ?>>
			<form method="post" class="ai-o-optimiser-panel" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>">
				<h2><?php esc_html_e( 'GA4 test event', 'ai-o-optimiser' ); ?></h2>
				<p><?php esc_html_e( 'After saving your Measurement ID and API secret, send a validation event to confirm the payload is accepted by GA4.', 'ai-o-optimiser' ); ?></p>
				<?php wp_nonce_field( 'ai_o_optimiser_test_ga4' ); ?>
				<input type="hidden" name="action" value="ai_o_optimiser_test_ga4" />
				<?php submit_button( __( 'Send GA4 Test Event', 'ai-o-optimiser' ), 'secondary', 'submit', false ); ?>
			</form>
			<?php
			if ( class_exists( 'AI_O_Optimiser_Site_Report' ) ) {
				AI_O_Optimiser_Site_Report::render_send_panel();
			}
			?>
			</div>

			<?php AI_O_Optimiser_Settings_Navigation::open_panel( AI_O_Optimiser_Settings_Navigation::edition_section_key() ); ?>
			<?php $this->render_edition_section(); ?>
			<?php AI_O_Optimiser_Settings_Navigation::close_panel(); ?>
		</div>
		<?php
		// phpcs:enable WordPress.Security.NonceVerification.Recommended
	}

	/**
	 * Render the Settings -> Edition panel.
	 *
	 * Free's counterpart to the paid edition's key panel: which edition is
	 * running, where it is installed, and what the other one adds. Nothing
	 * here is an upsell interstitial -- one static panel on a screen an
	 * administrator opened deliberately, no dismissible nag, no repetition
	 * elsewhere in the admin, and nothing reported back.
	 *
	 * @return void
	 */
	private function render_edition_section() {
		/*
		 * A compatible paid add-on, if active, renders its own key-entry
		 * panel here instead of this static text -- registered by the
		 * commercial subsystem this build removes, so Free itself never
		 * registers anything for this key; it only ever asks. See
		 * RELEASES/1.37.28-core-pro-addon-key-entry-ui-fix.md (this
		 * comment's own wording is deliberate: see the note above this
		 * method on the word this build is scrubbed of).
		 */
		if ( class_exists( 'AI_O_Optimiser_Extensions' ) && AI_O_Optimiser_Extensions::render( 'entitlement' ) ) {
			return;
		}
		?>
		<div class="ai-o-optimiser-panel">
			<h2 class="ai-o-optimiser-settings-section-heading"><?php esc_html_e( 'Edition', 'ai-o-optimiser' ); ?></h2>
			<p class="description"><?php esc_html_e( 'Which edition of AI-O Optimiser this site is running, and what the other one adds.', 'ai-o-optimiser' ); ?></p>

			<div class="notice notice-info inline">
				<p><?php esc_html_e( 'This is the free edition, published on WordPress.org. There is no key to enter here, and nothing it does is capped, metered or time-limited — no page limits, no trial period, no counter that runs out. Three workspaces are not in this build at all: Metadata, Schema and Business details (NAP). Their screens explain what each one does.', 'ai-o-optimiser' ); ?></p>
			</div>

			<table class="form-table" role="presentation">
				<tr>
					<th scope="row"><?php esc_html_e( 'Edition', 'ai-o-optimiser' ); ?></th>
					<td><?php esc_html_e( 'Free', 'ai-o-optimiser' ); ?></td>
				</tr>
				<tr>
					<th scope="row"><?php esc_html_e( 'Version', 'ai-o-optimiser' ); ?></th>
					<td><code><?php echo esc_html( AI_O_Optimiser_VERSION ); ?></code></td>
				</tr>
				<tr>
					<th scope="row"><?php esc_html_e( 'Plugin folder', 'ai-o-optimiser' ); ?></th>
					<td><code><?php echo esc_html( basename( dirname( AI_O_Optimiser_PLUGIN_FILE ) ) ); ?></code></td>
				</tr>
			</table>

			<p>
				<?php
				echo wp_kses(
					sprintf(
						/* translators: %s: link to the AI-O Optimiser product page. */
						__( 'The paid edition adds those three workspaces, along with product updates delivered from AI-O and standard product support. It installs into its own folder beside this one and reads the same tables, so everything this site has already collected carries over with no export and no re-setup, and only one of the two ever runs at a time. %s', 'ai-o-optimiser' ),
						'<a href="https://ai-o.com.au/ai-o-optimiser/" target="_blank" rel="noopener noreferrer">' . esc_html__( 'Compare the editions at ai-o.com.au', 'ai-o-optimiser' ) . '</a>'
					),
					array( 'a' => array( 'href' => array(), 'target' => array(), 'rel' => array() ) )
				);
				?>
			</p>
			<?php AI_O_Optimiser_Pro_Features::render_settings_section(); ?>
			<p class="description"><?php esc_html_e( 'Already bought the paid edition? Download it from your AI-O account and install it as a new plugin. The copy published on WordPress.org is this free one on every site, so a key bought for the paid edition has nothing to activate here.', 'ai-o-optimiser' ); ?></p>
		</div>
		<?php
	}

	/**
	 * Persist the Settings form.
	 */
	public function handle_save_settings() {
		if ( ! current_user_can( self::SENSITIVE_CAPABILITY ) || ! check_admin_referer( 'ai_o_optimiser_save_settings' ) ) {
			wp_die( esc_html__( 'You are not allowed to do that.', 'ai-o-optimiser' ) );
		}

		$posted_tracked_bots = isset( $_POST['tracked_bots'] ) && is_array( $_POST['tracked_bots'] ) ? array_map( 'sanitize_text_field', wp_unslash( $_POST['tracked_bots'] ) ) : array();
		$tracked_bots        = array();
		foreach ( array_keys( AI_O_Optimiser_Bots::defaults() ) as $slug ) {
			$tracked_bots[ $slug ] = isset( $posted_tracked_bots[ $slug ] );
		}

		$custom_bots = array();
		if ( isset( $_POST['custom_bots_raw'] ) ) {
			$raw   = sanitize_textarea_field( wp_unslash( $_POST['custom_bots_raw'] ) );
			$lines = preg_split( '/\r\n|\r|\n/', $raw );
			foreach ( $lines as $line ) {
				$line = trim( $line );
				if ( '' === $line || false === strpos( $line, '|' ) ) {
					continue;
				}
				list( $needle, $label ) = array_map( 'trim', explode( '|', $line, 2 ) );
				if ( '' === $needle ) {
					continue;
				}
				$slug                 = 'custom_' . sanitize_title( $needle );
				$custom_bots[ $slug ] = array(
					'label'  => $label ? $label : $needle,
					'needle' => $needle,
					'group'  => 'other',
				);
				$tracked_bots[ $slug ] = true;
			}
		}

		$settings = wp_parse_args( get_option( 'ai_o_optimiser_settings', array() ), self::default_settings() );
		$settings['enabled']          = isset( $_POST['enabled'] );
		$settings['enable_referrals'] = isset( $_POST['enable_referrals'] );
		$settings['tracked_bots']     = $tracked_bots;
		$settings['custom_bots']      = $custom_bots;
		$settings['near_miss_capture_enabled'] = isset( $_POST['near_miss_capture_enabled'] );
		// Stored as the administrator typed it, minus anything that is not a valid
		// address or block: a typo here would otherwise widen who is believed.
		$settings['verify_bot_identity'] = isset( $_POST['verify_bot_identity'] );
		ai_o_optimiser_visibility_load_client_ip();
		$settings['trusted_proxies'] = isset( $_POST['trusted_proxies'] )
			? implode( "\n", AI_O_Optimiser_Client_IP::parse_proxy_list( sanitize_textarea_field( wp_unslash( $_POST['trusted_proxies'] ) ) ) )
			: '';
		$settings['raw_retention_days']       = isset( $_POST['raw_retention_days'] ) ? max( 1, min( 30, (int) $_POST['raw_retention_days'] ) ) : 14;
		$settings['aggregate_retention_days'] = isset( $_POST['aggregate_retention_days'] ) ? max( 90, min( 1095, (int) $_POST['aggregate_retention_days'] ) ) : 730;
		$settings['strip_query_strings'] = isset( $_POST['strip_query_strings'] );
		$referrer_storage = isset( $_POST['referrer_storage'] ) ? sanitize_key( wp_unslash( $_POST['referrer_storage'] ) ) : 'domain';
		$settings['referrer_storage'] = in_array( $referrer_storage, array( 'domain', 'full' ), true ) ? $referrer_storage : 'domain';
		$settings['health_check_enabled'] = isset( $_POST['health_check_enabled'] );
		$settings['health_check_email']   = isset( $_POST['health_check_email'] ) && is_email( wp_unslash( $_POST['health_check_email'] ) ) ? sanitize_email( wp_unslash( $_POST['health_check_email'] ) ) : get_option( 'admin_email' );
		$settings['health_check_hour']    = isset( $_POST['health_check_hour'] ) ? min( 23, max( 17, (int) $_POST['health_check_hour'] ) ) : 20;
		$settings['health_check_frequency'] = isset( $_POST['health_check_frequency'] ) && 'weekly' === $_POST['health_check_frequency'] ? 'weekly' : 'daily';
		$settings['delete_data_on_uninstall'] = isset( $_POST['delete_data_on_uninstall'] );
		$settings = AI_O_Optimiser_GA4::sanitize_submitted_settings( $settings );
		if ( class_exists( 'AI_O_Optimiser_Site_Report' ) ) {
			$settings = AI_O_Optimiser_Site_Report::apply_submitted( $settings, wp_unslash( $_POST ) );
		}

		update_option( 'ai_o_optimiser_settings', $settings );
		AI_O_Optimiser_System_Check::reschedule_nightly_health_check();
		if ( class_exists( 'AI_O_Optimiser_Site_Report' ) ) {
			AI_O_Optimiser_Site_Report::sync_schedule();
		}

		// Back to the section the administrator was on, not the first one.
		$section = isset( $_POST['ai_o_optimiser_section'] ) ? sanitize_key( wp_unslash( $_POST['ai_o_optimiser_section'] ) ) : 'tracking';
		wp_safe_redirect( add_query_arg( array( 'updated' => '1', 'section' => $section ), admin_url( 'admin.php?page=ai-o-optimiser-settings' ) ) );
		exit;
	}

	/**
	 * Add one captured near-miss User-Agent as a permanent custom signature,
	 * then remove it from the near-miss list — it will now match directly.
	 */
	public function handle_add_near_miss_signature() {
		if ( ! current_user_can( self::CAPABILITY ) || ! check_admin_referer( 'ai_o_optimiser_add_near_miss_signature' ) ) {
			wp_die( esc_html__( 'You are not allowed to do that.', 'ai-o-optimiser' ) );
		}

		$key   = isset( $_POST['near_miss_key'] ) ? sanitize_text_field( wp_unslash( $_POST['near_miss_key'] ) ) : '';
		$label = isset( $_POST['near_miss_label'] ) ? sanitize_text_field( wp_unslash( $_POST['near_miss_label'] ) ) : '';
		$near_misses = AI_O_Optimiser_Bots::get_near_misses();

		if ( '' === $key || '' === $label || empty( $near_misses[ $key ] ) ) {
			wp_safe_redirect( add_query_arg( 'near_miss_error', '1', admin_url( 'admin.php?page=ai-o-optimiser-settings' ) ) );
			exit;
		}

		$needle = trim( (string) $near_misses[ $key ]['user_agent'] );
		// Use the raw captured string as the matching substring. It is longer than
		// a typical hand-written signature, but that is safer here than guessing
		// which fragment of an unfamiliar string is the meaningful part — an
		// admin can always shorten it afterwards in the Custom signatures field.
		$slug = 'custom_' . substr( md5( $needle ), 0, 10 );

		$settings = wp_parse_args( get_option( 'ai_o_optimiser_settings', array() ), self::default_settings() );
		$settings['custom_bots'] = is_array( $settings['custom_bots'] ) ? $settings['custom_bots'] : array();
		$settings['custom_bots'][ $slug ] = array(
			'label'  => $label,
			'needle' => $needle,
			'group'  => 'other',
		);
		$settings['tracked_bots'] = is_array( $settings['tracked_bots'] ) ? $settings['tracked_bots'] : array();
		$settings['tracked_bots'][ $slug ] = true;
		update_option( 'ai_o_optimiser_settings', $settings );
		AI_O_Optimiser_Bots::dismiss_near_miss( $key );

		wp_safe_redirect( add_query_arg( 'near_miss_added', '1', admin_url( 'admin.php?page=ai-o-optimiser-settings' ) ) );
		exit;
	}

	/**
	 * Dismiss one captured near-miss entry without adding it as a signature.
	 */
	public function handle_dismiss_near_miss() {
		if ( ! current_user_can( self::CAPABILITY ) || ! check_admin_referer( 'ai_o_optimiser_dismiss_near_miss' ) ) {
			wp_die( esc_html__( 'You are not allowed to do that.', 'ai-o-optimiser' ) );
		}
		$key = isset( $_POST['near_miss_key'] ) ? sanitize_text_field( wp_unslash( $_POST['near_miss_key'] ) ) : '';
		if ( '' !== $key ) {
			AI_O_Optimiser_Bots::dismiss_near_miss( $key );
		}
		wp_safe_redirect( admin_url( 'admin.php?page=ai-o-optimiser-settings' ) );
		exit;
	}

	/**
	 * Clear every captured near-miss entry.
	 */
	public function handle_clear_near_misses() {
		if ( ! current_user_can( self::CAPABILITY ) || ! check_admin_referer( 'ai_o_optimiser_clear_near_misses' ) ) {
			wp_die( esc_html__( 'You are not allowed to do that.', 'ai-o-optimiser' ) );
		}
		AI_O_Optimiser_Bots::clear_near_misses();
		wp_safe_redirect( admin_url( 'admin.php?page=ai-o-optimiser-settings' ) );
		exit;
	}

	/**
	 * Render the captured near-miss traffic card, if there is anything to show.
	 *
	 * @param array $settings Current plugin settings.
	 */
	private function render_near_miss_card( array $settings ) {
		// phpcs:disable WordPress.Security.NonceVerification.Recommended -- Read-only screen state (filters, tab selection, pagination, redirect result notices). Nothing is written here, so there is no form submission to carry a nonce.
		if ( isset( $_GET['near_miss_added'] ) ) {
			echo '<div class="notice notice-success is-dismissible"><p>' . esc_html__( 'Added as a custom signature. It will now be logged as a match on its next visit.', 'ai-o-optimiser' ) . '</p></div>';
		} elseif ( isset( $_GET['near_miss_error'] ) ) {
			echo '<div class="notice notice-error is-dismissible"><p>' . esc_html__( 'That entry could not be added — it may already have been handled.', 'ai-o-optimiser' ) . '</p></div>';
		}

		$near_misses = AI_O_Optimiser_Bots::get_near_misses();
		if ( empty( $near_misses ) ) {
			if ( ! empty( $settings['near_miss_capture_enabled'] ) ) {
				echo '<div class="notice notice-info inline ai-o-optimiser-near-miss-card"><p>' . esc_html__( 'Near-miss capture is on. Nothing has been caught yet — nothing to do here until a request comes in that mentions a known AI-brand name without matching a signature.', 'ai-o-optimiser' ) . '</p></div>';
			}
			return;
		}

		echo '<div class="ai-o-optimiser-panel ai-o-optimiser-near-miss-card">';
		echo '<h2>' . esc_html__( 'Near-miss traffic', 'ai-o-optimiser' ) . '</h2>';
		echo '<p class="description">' . esc_html__( 'Requests that mentioned a known AI-brand name but did not match any signature above. Review the raw string, then add it as a signature (it will start being logged on its next visit) or dismiss it if it is not relevant.', 'ai-o-optimiser' ) . '</p>';
		echo '<table class="widefat striped"><thead><tr>';
		echo '<th>' . esc_html__( 'User-Agent', 'ai-o-optimiser' ) . '</th>';
		echo '<th>' . esc_html__( 'Seen', 'ai-o-optimiser' ) . '</th>';
		echo '<th>' . esc_html__( 'Last request path', 'ai-o-optimiser' ) . '</th>';
		echo '<th>' . esc_html__( 'Last seen', 'ai-o-optimiser' ) . '</th>';
		echo '<th>' . esc_html__( 'Action', 'ai-o-optimiser' ) . '</th>';
		echo '</tr></thead><tbody>';
		foreach ( $near_misses as $key => $entry ) {
			echo '<tr>';
			echo '<td><code>' . esc_html( $entry['user_agent'] ) . '</code></td>';
			echo '<td>' . esc_html( sprintf( /* translators: Placeholder values are replaced with contextual values shown in this message. */
				_n( '%d time', '%d times', (int) $entry['count'], 'ai-o-optimiser' ), (int) $entry['count'] ) ) . '</td>';
			echo '<td>' . esc_html( $entry['request_uri'] ) . '</td>';
			echo '<td>' . esc_html( human_time_diff( (int) $entry['last_seen'] ) . ' ' . __( 'ago', 'ai-o-optimiser' ) ) . '</td>';
			echo '<td class="ai-o-optimiser-near-miss-actions">';
			echo '<form method="post" action="' . esc_url( admin_url( 'admin-post.php' ) ) . '" class="ai-o-optimiser-near-miss-add-form">';
			wp_nonce_field( 'ai_o_optimiser_add_near_miss_signature' );
			echo '<input type="hidden" name="action" value="ai_o_optimiser_add_near_miss_signature">';
			echo '<input type="hidden" name="near_miss_key" value="' . esc_attr( $key ) . '">';
			echo '<input type="text" name="near_miss_label" class="regular-text" placeholder="' . esc_attr__( 'Label, e.g. Gemini live fetch', 'ai-o-optimiser' ) . '" required>';
			echo '<button type="submit" class="button button-small">' . esc_html__( 'Add as signature', 'ai-o-optimiser' ) . '</button>';
			echo '</form>';
			echo '<form method="post" action="' . esc_url( admin_url( 'admin-post.php' ) ) . '">';
			wp_nonce_field( 'ai_o_optimiser_dismiss_near_miss' );
			echo '<input type="hidden" name="action" value="ai_o_optimiser_dismiss_near_miss">';
			echo '<input type="hidden" name="near_miss_key" value="' . esc_attr( $key ) . '">';
			echo '<button type="submit" class="button button-small button-link-delete">' . esc_html__( 'Dismiss', 'ai-o-optimiser' ) . '</button>';
			echo '</form>';
			echo '</td>';
			echo '</tr>';
		}
		echo '</tbody></table>';
		echo '<form method="post" action="' . esc_url( admin_url( 'admin-post.php' ) ) . '">';
		wp_nonce_field( 'ai_o_optimiser_clear_near_misses' );
		echo '<input type="hidden" name="action" value="ai_o_optimiser_clear_near_misses">';
		echo '<button type="submit" class="button">' . esc_html__( 'Clear all', 'ai-o-optimiser' ) . '</button>';
		echo '</form>';
		echo '</div>';
		// phpcs:enable WordPress.Security.NonceVerification.Recommended
	}

	/**
	 * Validate saved GA4 settings with a debug Measurement Protocol event.
	 */
	public function handle_test_ga4() {
		if ( ! current_user_can( self::CAPABILITY ) || ! check_admin_referer( 'ai_o_optimiser_test_ga4' ) ) {
			wp_die( esc_html__( 'You are not allowed to do that.', 'ai-o-optimiser' ) );
		}

		$result = AI_O_Optimiser_GA4::send_test_event();
		set_transient( AI_O_Optimiser_GA4::TEST_RESULT_OPTION, $result, MINUTE_IN_SECONDS );

		wp_safe_redirect( admin_url( 'admin.php?page=ai-o-optimiser-settings' ) );
		exit;
	}
}