<?php
/**
 * Core module: admin page, asset loading, system status endpoint.
 *
 * @package AiRankSuite
 */

declare(strict_types=1);

namespace AiRankSuite\Modules\Core;

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

use AiRankSuite\Container;
use AiRankSuite\Contracts\ModuleInterface;
use AiRankSuite\Kernel;

final class CoreModule implements ModuleInterface {

	public function id(): string {
		return 'core';
	}

	public function register( Container $container ): void {}

	public function boot( Container $container ): void {
		// Ask every optimiser we know of not to combine or defer this plugin's
		// admin script. Combining it once produced a file the browser refused
		// outright and a blank admin, from a setting the plugin cannot see.
		\AiRankSuite\Support\Cache::protect_admin_assets();

		add_action( 'admin_menu', array( $this, 'add_menu' ) );
		add_action( 'in_admin_header', array( $this, 'silence_foreign_notices' ), 1000 );
		// Late in in_admin_header: after every plugin has registered its notices, before any prints.
		// Priority 11: after add_menu(), because a submenu needs its parent.
		add_action( 'admin_menu', array( $this, 'add_license_page' ), 11 );
		// Runs after every other admin_menu callback, including the Freemius
		// SDK's. See restore_menu_if_removed() for why that is necessary.
		add_action( 'admin_menu', array( $this, 'restore_menu_if_removed' ), PHP_INT_MAX );
		add_action( 'admin_enqueue_scripts', array( $this, 'enqueue' ) );
		// The toolbar's clear-cache link lands here: a plain admin-post handler,
		// because a link in the admin bar cannot carry a REST nonce.
		add_action(
			'admin_post_airanksuite_purge_cache',
			static function () {
				check_admin_referer( 'airanksuite_purge_cache' );
				if ( ! current_user_can( 'manage_options' ) ) {
					wp_die( esc_html__( 'You cannot clear the cache.', 'ai-rank-suite' ), '', array( 'response' => 403 ) );
				}
				$cleared = \AiRankSuite\Support\Cache::purge();
				$back    = wp_get_referer() ?: admin_url();
				wp_safe_redirect( add_query_arg( 'airanksuite-purged', rawurlencode( implode( ',', $cleared ) ), $back ) );
				exit;
			}
		);

		add_action( 'rest_api_init', array( $this, 'routes' ) );
		add_action(
			'rest_api_init',
			function () {
				register_rest_route(
					'airanksuite/v1',
					'/cache/purge',
					array(
						'methods'             => 'POST',
						'permission_callback' => static fn(): bool => current_user_can( 'manage_options' ),
						'callback'            => static function () {
							$cleared = \AiRankSuite\Support\Cache::purge();
							return new \WP_REST_Response(
								array(
									'cleared'  => $cleared,
									'detected' => \AiRankSuite\Support\Cache::detect(),
								)
							);
						},
					)
				);
				register_rest_route(
					'airanksuite/v1',
					'/cache/status',
					array(
						'methods'             => 'GET',
						'permission_callback' => static fn(): bool => current_user_can( 'manage_options' ),
						'callback'            => static fn() => new \WP_REST_Response(
							array( 'detected' => \AiRankSuite\Support\Cache::detect() )
						),
					)
				);

				// Webhooks: the events catalogue, the subscriptions, a test ping
				// and the delivery log. Managing settings is the right bar — a
				// webhook receives the same data the reports show.
				// A webhook sends site data to an address somebody typed in, so
				// the plugin's own, delegable capability is not enough here:
				// WordPress has to agree that this is an administrator.
				$state  = static fn() => new \WP_REST_Response(
					array(
						'events'     => \AiRankSuite\Support\Events::catalogue(),
						'hooks'      => \AiRankSuite\Support\Events::public_hooks(),
						'deliveries' => \AiRankSuite\Support\Events::deliveries(),
					)
				);
				register_rest_route(
					'airanksuite/v1',
					'/webhooks',
					array(
						array(
							'methods'             => 'GET',
							'permission_callback' => static fn() => current_user_can( 'manage_options' ),
							'callback'            => $state,
						),
						array(
							'methods'             => 'POST',
							'permission_callback' => static fn() => current_user_can( 'manage_options' ),
							'callback'            => static function ( \WP_REST_Request $r ) use ( $state ) {
								$saved = \AiRankSuite\Support\Events::save( (array) $r->get_json_params() );
								if ( $saved instanceof \WP_Error ) {
									return $saved;
								}
								$out          = $state()->get_data();
								$out['saved'] = $saved;
								return new \WP_REST_Response( $out );
							},
						),
					)
				);
				register_rest_route(
					'airanksuite/v1',
					'/webhooks/(?P<id>[a-f0-9\-]{36})',
					array(
						array(
							'methods'             => 'DELETE',
							'permission_callback' => static fn() => current_user_can( 'manage_options' ),
							'callback'            => static function ( \WP_REST_Request $r ) use ( $state ) {
								\AiRankSuite\Support\Events::delete( (string) $r['id'] );
								return $state();
							},
						),
					)
				);
				register_rest_route(
					'airanksuite/v1',
					'/webhooks/(?P<id>[a-f0-9\-]{36})/test',
					array(
						'methods'             => 'POST',
						'permission_callback' => static fn() => current_user_can( 'manage_options' ),
						'callback'            => static function ( \WP_REST_Request $r ) use ( $state ) {
							$hook = \AiRankSuite\Support\Events::find( (string) $r['id'] );
							if ( ! $hook ) {
								return new \WP_Error( 'airanksuite_webhook_missing', __( 'No such webhook.', 'ai-rank-suite' ), array( 'status' => 404 ) );
							}
							$result = \AiRankSuite\Support\Events::deliver(
								$hook,
								array(
									'event'   => 'webhook.test',
									'site'    => home_url( '/' ),
									'time'    => time(),
									'version' => AIRANKSUITE_VERSION,
									'data'    => array( 'hello' => 'from AI Rank Suite' ),
								)
							);
							$out           = $state()->get_data();
							$out['result'] = $result;
							return new \WP_REST_Response( $out );
						},
					)
				);
			}
		);

		// The status light. Priority 100 puts it to the right of the site name
		// and the "New" menu rather than in front of them — it is a status, not
		// a navigation item.
		add_action( 'admin_bar_menu', array( Services\Toolbar::class, 'render' ), 100 );
		add_action( 'admin_enqueue_scripts', array( Services\Toolbar::class, 'assets' ) );
		// The front end too: an editor looking at a live page is exactly when
		// "what does this page score" is the question.
		add_action( 'wp_enqueue_scripts', array( Services\Toolbar::class, 'assets' ) );

		// Anything that changes the answer invalidates the cached one.
		foreach ( array( 'save_post', 'deleted_post', 'airanksuite/autopilot/tick', 'airanksuite/audit/done' ) as $hook ) {
			add_action( $hook, array( Services\Pulse::class, 'flush' ) );
		}
	}

	/** The name on the menu and the header — the agency's, when set. */
	public static function brand(): string {
		$core = Kernel::service( \AiRankSuite\Support\Options::class )->get( 'core', \AiRankSuite\Modules\Settings\SettingsModule::defaults() );
		$name = trim( (string) ( $core['brand_name'] ?? '' ) );
		return '' !== $name ? $name : __( 'AI Rank Suite', 'ai-rank-suite' );
	}

	/**
	 * No notice but ours renders on this plugin's own pages.
	 *
	 * This was removed once, on the argument that notices above the heading
	 * are how core screens behave — and put back as an explicit product
	 * decision by the owner: the plugin's screens are the product, and a
	 * stack of other plugins' banners on top of them is not. The scope is
	 * the whole trade-off, so it is enforced first: on any page that is not
	 * one of this plugin's six, this method does nothing at all, and update
	 * and security notices appear everywhere WordPress puts them.
	 *
	 * One exception survives on our pages: the module-quarantine notice.
	 * That one says part of this plugin crashed, and hiding it would make a
	 * genuine failure look like a working product.
	 */
	public function silence_foreign_notices(): void {
		if ( ! function_exists( 'get_current_screen' ) ) {
			return;
		}
		$page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : ''; // phpcs:ignore WordPress.Security.NonceVerification.Recommended
		if ( ! str_starts_with( $page, 'ai-rank-suite' ) ) {
			$screen = get_current_screen();
			if ( ! $screen || ! str_contains( (string) $screen->id, 'ai-rank-suite' ) ) {
				return;
			}
		}
		global $wp_filter;
		foreach ( array( 'admin_notices', 'all_admin_notices', 'user_admin_notices', 'network_admin_notices' ) as $hook ) {
			if ( empty( $wp_filter[ $hook ] ) ) {
				continue;
			}
			foreach ( $wp_filter[ $hook ]->callbacks as $priority => $callbacks ) {
				foreach ( array_keys( $callbacks ) as $id ) {
					if ( str_contains( (string) $id, 'quarantine' ) ) {
						continue;
					}
					unset( $wp_filter[ $hook ]->callbacks[ $priority ][ $id ] );
				}
			}
		}
		remove_action( 'admin_notices', 'update_nag', 3 );
		remove_action( 'network_admin_notices', 'update_nag', 3 );
		remove_action( 'admin_notices', 'maintenance_nag', 10 );
	}

	/**
	 * The areas that get a real WordPress submenu.
	 *
	 * A plugin that replaces the admin menu with its own sidebar is a web app
	 * wearing WordPress as a frame; every SEO plugin people already trust —
	 * Rank Math, Yoast, SEOPress, Jetpack — puts its areas in the menu where
	 * WordPress users look for them, with their own URL, their own browser
	 * history and their own bookmark. Each entry opens the same application at
	 * a different route.
	 *
	 * @return array<string, array{label: string, route: string, cap: string}>
	 */
	/**
	 * The admin menu, and the map the app navigates by.
	 *
	 * One entry per WordPress submenu. Each one owns a *group* of screens —
	 * the submenu opens the group's first screen and the group's other screens
	 * appear as a nav-tab row on the page, which is how every SEO plugin a
	 * WordPress user already owns is built. Six menu items reach all of them;
	 * twenty-six menu items would reach the same screens and bury the rest of
	 * the admin menu doing it.
	 *
	 * `group` matches the group key in the app's screen table (App.jsx), and
	 * the whole map is handed to the browser so a link that crosses a group
	 * lands on the right admin page instead of leaving the menu highlighting
	 * the page the visitor came from.
	 */
	public static function screens(): array {
		$screens = array(
			'ai-rank-suite'          => array( 'label' => __( 'Dashboard', 'ai-rank-suite' ), 'route' => 'dashboard', 'group' => 'Overview', 'cap' => 'manage_options' ),
			'ai-rank-suite-seo'      => array( 'label' => __( 'SEO', 'ai-rank-suite' ), 'route' => 'seo', 'group' => 'Search', 'cap' => 'manage_options' ),
			'ai-rank-suite-optimize' => array( 'label' => __( 'Optimize', 'ai-rank-suite' ), 'route' => 'content', 'group' => 'Optimize', 'cap' => 'manage_options' ),
			'ai-rank-suite-ai'       => array( 'label' => __( 'AI search', 'ai-rank-suite' ), 'route' => 'ai-visibility', 'group' => 'AI search', 'cap' => 'manage_options' ),
			'ai-rank-suite-measure'  => array( 'label' => __( 'Measure', 'ai-rank-suite' ), 'route' => 'measure', 'group' => 'Measure', 'cap' => 'manage_options' ),
			'ai-rank-suite-settings' => array( 'label' => __( 'Settings', 'ai-rank-suite' ), 'route' => 'settings', 'group' => 'System', 'cap' => 'manage_options' ),
		);
		// A shop gets its own menu entry. Everything under it existed as tabs
		// of other screens; a merchant looked for "shop" and found "feeds".
		if ( class_exists( 'WooCommerce' ) ) {
			$shop = array( 'ai-rank-suite-shop' => array( 'label' => __( 'Shop', 'ai-rank-suite' ), 'route' => 'shop', 'group' => 'Shop', 'cap' => 'manage_options' ) );
			$screens = array_slice( $screens, 0, 3, true ) + $shop + array_slice( $screens, 3, null, true );
		}
		return $screens;
	}

	public function add_menu(): void {
		add_menu_page(
			self::brand(),
			self::brand(),
			'manage_options',
			'ai-rank-suite',
			array( $this, 'render_app' ),
			'data:image/svg+xml;base64,' . base64_encode( '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" ><path fill="#a7aaad" fill-rule="evenodd" d="M128 24 37 226h43l19-46h58l19 46h44L129 24h-1Zm0 67 17 49h-34l17-49Z"/><path d="M52 202 102 159 145 168 207 84" fill="none" stroke="#a7aaad" stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/><circle cx="52" cy="202" r="13" fill="#a7aaad" stroke="#a7aaad" stroke-width="6"/><circle cx="207" cy="84" r="13" fill="#a7aaad" stroke="#a7aaad" stroke-width="6"/><path fill="#a7aaad" d="m105 132 7 18 18 7-18 7-7 18-7-18-18-7 18-7 7-18Z"/></svg>' ),
			58
		);

		// The first submenu shares the parent slug on purpose: WordPress would
		// otherwise repeat the menu title there, giving "AI Rank Suite → AI
		// Rank Suite" instead of "→ Dashboard".
		foreach ( self::screens() as $slug => $screen ) {
			add_submenu_page(
				'ai-rank-suite',
				$screen['label'],
				$screen['label'],
				$screen['cap'],
				$slug,
				array( $this, 'render_app' )
			);
		}

		/*
		 * The upgrade entry, free edition only. Amber, last in the menu, the
		 * way every freemium SEO plugin a buyer already owns does it — the
		 * convention is the point, because a convention is recognised without
		 * being read. The Pro edition never shows it: advertising an upgrade
		 * to somebody who paid is how review sections fill up with one star.
		 *
		 * It opens a page of this plugin's own. Every redirect this entry ever
		 * tried landed on the WordPress dashboard instead: Freemius' pricing
		 * and account slugs because the SDK registers neither until a customer
		 * has opted in and registered, and the product's own pricing page
		 * because wp_safe_redirect() refuses a host that is not this site and
		 * substitutes admin_url(). See UpgradeScreen for the whole story.
		 */
		if ( ! ( defined( 'AIRANKSUITE_IS_PRO' ) && AIRANKSUITE_IS_PRO ) ) {
			add_submenu_page(
				'ai-rank-suite',
				__( 'Upgrade to Pro', 'ai-rank-suite' ),
				'<span class="airanksuite-menu-upgrade">' . esc_html__( 'Upgrade to Pro', 'ai-rank-suite' ) . ' &rarr;</span>',
				'manage_options',
				UpgradeScreen::SLUG,
				array( UpgradeScreen::class, 'render' )
			);
			add_action( 'admin_enqueue_scripts', array( $this, 'upgrade_menu_css' ) );
			add_action( 'admin_enqueue_scripts', array( UpgradeScreen::class, 'enqueue' ) );
		}
	}

	/**
	 * A page of our own for Freemius to take over.
	 *
	 * The SDK replaces whichever menu slug it is given with its licence-key
	 * form for as long as the licence is inactive
	 * (Freemius::override_plugin_menu_with_activation). Pointed at the main
	 * menu that means a customer who has just paid cannot see the product they
	 * bought until they find the email with the key in it — and it contradicts
	 * this plugin's own rule that an inactive licence pauses new work rather
	 * than hiding what is already there.
	 *
	 * So Freemius gets this submenu instead. It renders nothing on its own;
	 * the SDK overrides it, and if Freemius is not configured at all the page
	 * simply sends you to the in-app licence screen.
	 */
	public function add_license_page(): void {
		add_submenu_page(
			'ai-rank-suite',
			__( 'License', 'ai-rank-suite' ),
			__( 'License', 'ai-rank-suite' ),
			'manage_options',
			'ai-rank-suite-license',
			static function (): void {
				echo '<div class="wrap"><h1>' . esc_html__( 'License', 'ai-rank-suite' ) . '</h1><p>'
					. wp_kses_post(
						sprintf(
							/* translators: %s: link to the in-app licence screen. */
							__( 'Licensing is managed inside the plugin — <a href="%s">open the License tab</a>.', 'ai-rank-suite' ),
							esc_url( admin_url( 'admin.php?page=ai-rank-suite-settings#/settings/license' ) )
						)
					)
					. '</p></div>';
			}
		);
	}

	/**
	 * Put our admin menu back if the Freemius SDK removed it.
	 *
	 * Freemius::_prepare_admin_menu() calls remove_menu_item() when
	 * `false === has_api_connectivity() && ! is_enable_anonymous()`. A
	 * premium-only product has anonymous mode force-disabled by the SDK
	 * (Freemius::parse_settings()), so that condition reduces to "the site
	 * cannot reach api.freemius.com" — true on any host with outbound HTTP
	 * blocked, a strict firewall, or WP_HTTP_BLOCK_EXTERNAL set.
	 *
	 * The observable result without this guard is not a degraded plugin, it is
	 * a hard failure: admin.php?page=ai-rank-suite returns HTTP 500 and
	 * "Cannot load ai-rank-suite." from wp_die(), with the menu entry gone.
	 * Verified by forcing connectivity_test.is_connected = false.
	 *
	 * Mechanically, FS_Admin_Menu_Manager::remove_menu_item() calls
	 * remove_all_actions() on the page's hook rather than deleting the menu
	 * entry, so WordPress' get_plugin_page_hook() finds no callback and
	 * admin.php bails out. Restoring the render callback is therefore the fix;
	 * the top-level entry is only re-added in the network-activation branch
	 * where Freemius does unset it too.
	 *
	 * This only fires when the page is genuinely unreachable. During normal
	 * activation mode Freemius keeps a callback on the hook to draw its
	 * licence-activation screen, so has_action() is true and this is a no-op —
	 * that intended premium-only flow is left alone.
	 *
	 * Hooked at PHP_INT_MAX, which outranks WP_FS__LOWEST_PRIORITY (999999999).
	 */
	public function restore_menu_if_removed(): void {
		global $admin_page_hooks;

		if ( ! isset( $admin_page_hooks['ai-rank-suite'] ) ) {
			$this->add_menu();
			return;
		}

		$hook = get_plugin_page_hookname( 'ai-rank-suite', '' );

		if ( $hook && ! has_action( $hook ) ) {
			add_action( $hook, array( $this, 'render_app' ) );
		}
	}

	/** Is this admin page one of ours? */
	private function is_our_screen( string $hook ): bool {
		if ( 'toplevel_page_ai-rank-suite' === $hook ) {
			return true;
		}
		foreach ( array_keys( self::screens() ) as $slug ) {
			if ( str_ends_with( $hook, '_page_' . $slug ) ) {
				return true;
			}
		}
		return false;
	}

	/** Which route the current menu page opens on. */
	private function current_route(): string {
		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only screen check.
		$page    = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : 'ai-rank-suite';
		$screens = self::screens();
		return (string) ( $screens[ $page ]['route'] ?? 'dashboard' );
	}

	/** The heading WordPress users expect at the top of an admin page. */
	private function current_title(): string {
		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only screen check.
		$page    = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : 'ai-rank-suite';
		$screens = self::screens();
		return (string) ( $screens[ $page ]['label'] ?? self::brand() );
	}

	/**
	 * A version string that changes whenever the file does.
	 *
	 * Falls back to the release number when the file cannot be stat'd, which
	 * is the old behaviour and never worse than it.
	 */
	private static function asset_version( string $file ): string {
		$stamp = is_readable( $file ) ? (int) filemtime( $file ) : 0;
		return 0 === $stamp ? AIRANKSUITE_VERSION : AIRANKSUITE_VERSION . '.' . $stamp;
	}

	/**
	 * Amber and bold, so the entry reads as an action rather than a screen.
	 *
	 * Attached to a registered handle rather than printed into admin_head: a
	 * printed tag is invisible to the style loader and to anything that
	 * combines or defers stylesheets, which is the reason the directory asks
	 * for enqueues even for a one-line rule.
	 */
	public function upgrade_menu_css(): void {
		\AiRankSuite\Support\Inline::style(
			'airanksuite-menu-upgrade',
			'.airanksuite-menu-upgrade{color:#f0a325;font-weight:600}#adminmenu a:hover .airanksuite-menu-upgrade{color:#ffb84d}'
		);
	}

	public function render_app(): void {
		// The shell paints BEFORE the 289 KB bundle arrives: a sidebar and
		// three card ghosts in pure inline CSS, replaced the moment React
		// mounts. Without it the first visit to this screen is a white void
		// for as long as the network takes — which reads as "broken", not
		// "loading". Self-contained on purpose: no classes from the bundle's
		// stylesheet, so it cannot flash unstyled when that file is slow too.
		// A WordPress admin page starts with .wrap and an <h1>. Printing them
		// from PHP means the page has its title and its frame before a single
		// byte of JavaScript arrives — the same thing every core screen does,
		// and the reason a plugin feels native rather than embedded.
		echo '<div class="wrap airanksuite-wrap">';
		echo '<h1 class="wp-heading-inline">' . esc_html( $this->current_title() ) . '</h1>';
		echo '<hr class="wp-header-end" />';
		echo '<div id="airanksuite-root" data-route="' . esc_attr( $this->current_route() ) . '">'
			. '<div class="airanksuite-boot" aria-hidden="true">'
			. '<div class="airanksuite-boot-nav"><span style="width:60%"></span><span style="width:80%"></span><span style="width:70%"></span><span style="width:75%"></span><span style="width:65%"></span><span style="width:72%"></span></div>'
			. '<div class="airanksuite-boot-main"><span></span><span></span><span></span></div>'
			. '</div>'
			. '</div></div>';
	}

	public function enqueue( string $hook ): void {
		// Every screen of ours, not only the top-level page: each submenu is a
		// real admin page with its own hook suffix.
		if ( ! $this->is_our_screen( $hook ) ) {
			return;
		}
		$build = AIRANKSUITE_DIR . 'assets/admin/build/';
		$url   = AIRANKSUITE_URL . 'assets/admin/build/';

		// Local SEO picks a logo and a photo, and the only picker a WordPress
		// user already knows how to drive is the media library's own.
		wp_enqueue_media();

		/*
		 * The cache buster is the file, not the release number.
		 *
		 * Two builds shipped as 0.0.5 during one day of fixes, so every
		 * browser that had loaded the first one kept serving it from disk:
		 * same URL, same `?ver=`, no reason to re-fetch. The PHP side updated
		 * and the JavaScript did not, which is the worst possible mixture —
		 * on that install `window.airanksuiteData.modules` correctly said the AI
		 * module is absent while the stale bundle still drew the buttons that
		 * call it. Hashing the file means a rebuilt asset is always a new URL.
		 */
		/*
		 * The boot skeleton's rules, enqueued in the head so they are in
		 * force before the markup they style is printed. They used to sit in
		 * a <style> tag inside render_app(), which kept them next to the
		 * markup but out of sight of the style loader; the head is earlier
		 * still, so the ghosts cannot flash unstyled either.
		 */
		\AiRankSuite\Support\Inline::style(
			'airanksuite-boot',
			'@keyframes airanksuiteboot{0%,100%{opacity:.45}50%{opacity:1}}'
			. '.airanksuite-boot{display:grid;grid-template-columns:232px 1fr;min-height:70vh;background:#f4f5f7;border-radius:10px;overflow:hidden}'
			. '.airanksuite-boot-nav{background:#fff;border-right:1px solid #e4e5e9;padding:16px}'
			. '.airanksuite-boot-main{padding:24px;display:grid;gap:16px;align-content:start}'
			. '.airanksuite-boot span{display:block;background:#eeeef1;border-radius:6px;animation:airanksuiteboot 1.2s ease-in-out infinite}'
			. '.airanksuite-boot-nav span{height:12px;margin:14px 0}'
			. '.airanksuite-boot-main span{height:120px;border-radius:10px}'
			. '.airanksuite-boot-main span:first-child{height:180px}'
			. '@media (prefers-color-scheme:dark){.airanksuite-boot{background:#141416}.airanksuite-boot-nav{background:#1c1c1f;border-color:#35353b}.airanksuite-boot span{background:#2b2b30}}'
		);
		wp_enqueue_style( 'airanksuite-admin', $url . 'index.css', array(), self::asset_version( $build . 'index.css' ) );
		wp_enqueue_script( 'airanksuite-admin', $url . 'index.js', array( 'wp-api-fetch', 'wp-i18n', 'underscore' ), self::asset_version( $build . 'index.js' ), true );
		/*
		 * A classic script, not a module.
		 *
		 * The app was briefly an ES module split per screen. On a host running
		 * an optimiser that combines JavaScript, merging those modules broke
		 * their import bindings and the admin died with "Importing binding name
		 * ... is not found" — from a setting this plugin cannot see. It is one
		 * self-contained IIFE again; there is nothing left to merge wrongly.
		 */
		// The admin app is the surface a customer actually reads. Without this
		// its strings are unreachable to a translator no matter how many are
		// wrapped in __() — WordPress needs to be told where the JSON
		// catalogues live before wp.i18n can find one.
		wp_set_script_translations( 'airanksuite-admin', 'ai-rank-suite', AIRANKSUITE_DIR . 'languages' );

		// wp_localize_script casts every value to a string, which would turn
		// booleans into "" / "1". Inline JSON keeps real types.
		wp_add_inline_script(
			'airanksuite-admin',
			'window.airanksuiteData = ' . wp_json_encode(
				array(
					'restUrl'   => esc_url_raw( rest_url( 'airanksuite/v1' ) ),
					// The admin-ajax endpoint, so a stale REST nonce can be
					// replaced without guessing the admin path. A nonce printed
					// into a cached page is the most common reason a save fails
					// on a live site, and it fails as a 403 that looks like a
					// permission problem rather than an expiry.
					'ajaxUrl'   => esc_url_raw( admin_url( 'admin-ajax.php' ) ),
					'nonce'     => wp_create_nonce( 'wp_rest' ),
					'version'   => AIRANKSUITE_VERSION,
					/**
					 * Whether developer surfaces (the REST console) render.
					 * Defaults to WP_DEBUG: the console is a builder's tool,
					 * and a customer install should not present 130 Try
					 * buttons against its own API. A site that wants it in
					 * production opts in through the filter.
					 */
					'debug'     => (bool) apply_filters( 'airanksuite/devtools/api_console', defined( 'WP_DEBUG' ) && WP_DEBUG ),
					// Static images (vendor marks) live outside the JS build.
					'assetsUrl' => esc_url_raw( AIRANKSUITE_URL . 'assets/' ),
					// The menu, as the app sees it: which admin page owns which
					// group of screens. A link that crosses a group has to load
					// that group's page, or WordPress keeps the old submenu
					// highlighted while the content underneath has moved on.
					'screens'   => array_map(
						static function ( $slug, $screen ) {
							return array(
								'slug'  => $slug,
								'route' => $screen['route'],
								'group' => $screen['group'],
								'url'   => admin_url( 'admin.php?page=' . $slug ),
							);
						},
						array_keys( self::screens() ),
						array_values( self::screens() )
					),
					'brand'     => self::brand(),
					'whiteLabel' => (bool) ( Kernel::service( \AiRankSuite\Support\Options::class )->get( 'core', \AiRankSuite\Modules\Settings\SettingsModule::defaults() )['hide_footer'] ?? false ),
					'siteName'  => get_bloginfo( 'name' ),
					// The title-template preview renders %tagline% client-side, so
					// it needs the real value rather than a guess.
					'tagline'   => get_bloginfo( 'description' ),
					// Lets the admin hide the whole commerce section rather than
					// showing a nav item that leads to "install WooCommerce".
					'hasWoo'    => class_exists( 'WooCommerce' ),
					// Language pickers appear only where they mean something:
					// a monolingual site must not pay a filter row for nothing.
					'i18n'      => \AiRankSuite\Support\Multilingual::state(),
					'homeUrl'   => home_url( '/' ),
					'caps'      => array(
						'manage' => current_user_can( 'manage_options' ),
						'audit'  => current_user_can( 'manage_options' ),
					),
					'setupDone' => (bool) ( get_option( 'airanksuite_core_settings', array() )['setup_done'] ?? false ),
					/*
					 * Hooks, webhooks and the REST reference are developer
					 * reference. On a site that never calls them the entry is
					 * a row of chrome on every settings screen, so it shows up
					 * when the site is already in developer mode, when the
					 * setting asks for it, or for a plugin that filters it on.
					 * The screen itself stays reachable by its own address
					 * either way, so an old bookmark still opens.
					 */
					'showDeveloper' => (bool) apply_filters(
						'airanksuite_show_developer_tools',
						( defined( 'WP_DEBUG' ) && WP_DEBUG )
							|| ! empty( get_option( 'airanksuite_core_settings', array() )['developer_tools'] )
					),
					// Which modules are actually running. The free edition ships
					// without the Pro folders, so their screens must not be
					// offered as if they worked: a menu entry whose backend is
					// absent answers "no route was found", which reads as a
					// broken plugin rather than a paid feature.
					'modules'   => array_values( Kernel::instance()->moduleIds() ),
					// Which edition this build IS, as distinct from what the
					// licence allows: an unlicensed Pro install must be asked
					// to activate, never to buy what it already paid for.
					'edition'   => ( defined( 'AIRANKSUITE_IS_PRO' ) && AIRANKSUITE_IS_PRO ) ? 'pro' : 'free',
					// Licence state up front, so every screen can badge itself
					// without waiting on a REST round-trip.
					// Absent in the WordPress.org edition, which carries no
					// licensing code at all; the screens read the empty array
					// as "nothing to badge".
					'license'   => class_exists( \AiRankSuite\Modules\Licensing\Services\LicenseGate::class )
						? \AiRankSuite\Modules\Licensing\Services\LicenseGate::instance()->state()
						: array(),
				)
			) . ';',
			'before'
		);
		// Ensure the file exists so a broken build fails loudly in the UI, not silently.
		if ( ! file_exists( $build . 'index.js' ) ) {
			wp_add_inline_script( 'wp-api-fetch', 'console.error("AI Rank Suite: admin build missing.");' );
		}
	}

	public function routes(): void {
		( new Rest\StatusController() )->register_routes();

		// The toolbar's poll target. Read-only, cheap, and rate limiting it
		// would be theatre — the script already stops asking when there is
		// nothing to watch, and the answer is a cached option read.
		register_rest_route(
			'airanksuite/v1',
			'/pulse',
			array(
				'methods'             => 'GET',
				'permission_callback' => static fn(): bool => current_user_can( 'manage_options' ),
				'callback'            => static fn( \WP_REST_Request $request ) => new \WP_REST_Response(
					Services\Pulse::read( (bool) $request->get_param( 'fresh' ) )
				),
				'args'                => array(
					'fresh' => array( 'type' => 'boolean', 'default' => false ),
				),
			)
		);
	}
}