<?php
// phpcs:disable WordPress.Files.FileName.InvalidClassFileName
/**
 * Plugin Name:       AeroSpin CSS Loading Spinners
 * Plugin URI:        https://wpclearpath.com/aerospin-css-loading-spinners
 * Description:       AeroSpin CSS Loading Spinners is a lightweight loading utility for WordPress that displays customizable, accessible frontend loaders during page navigation transitions and form submissions. Choose from 100 modern CSS spinner animations, control colors and sizing, and manage display behavior from a focused admin interface.
 * Version:           1.1.6
 * Requires at least: 5.8
 * Requires PHP:      7.4
 * Author:            WPClearPath.com
 * Author URI:        https://wpclearpath.com
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       aerospin-css-loading-spinners
 * Domain Path:       /languages
 *
 * @package AeroSpin_CSS_Loading_Spinners
 */

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

/*
|--------------------------------------------------------------------------
| SECTION 1: Core Plugin Constants
|--------------------------------------------------------------------------
|
| These constants provide one trusted reference point for paths, URLs,
| options, versions, capabilities, support links, and plugin action links
| throughout AeroSpin CSS Loading Spinners.
|
| Important:
| - This file must be saved as UTF-8 without BOM.
| - This file must not have a PHP closing tag.
| - Nothing should be printed, echoed, dumped, or sent during plugin load.
|
*/

if ( ! defined( 'ACLS_VERSION' ) ) {
	define( 'ACLS_VERSION', '1.1.6' );
}

if ( ! defined( 'ACLS_MINIMUM_WP_VERSION' ) ) {
	define( 'ACLS_MINIMUM_WP_VERSION', '5.8' );
}

if ( ! defined( 'ACLS_MINIMUM_PHP_VERSION' ) ) {
	define( 'ACLS_MINIMUM_PHP_VERSION', '7.4' );
}

if ( ! defined( 'ACLS_PLUGIN_FILE' ) ) {
	define( 'ACLS_PLUGIN_FILE', __FILE__ );
}

if ( ! defined( 'ACLS_PLUGIN_BASENAME' ) ) {
	define( 'ACLS_PLUGIN_BASENAME', plugin_basename( ACLS_PLUGIN_FILE ) );
}

if ( ! defined( 'ACLS_PLUGIN_DIR' ) ) {
	define( 'ACLS_PLUGIN_DIR', plugin_dir_path( ACLS_PLUGIN_FILE ) );
}

if ( ! defined( 'ACLS_PLUGIN_URL' ) ) {
	define( 'ACLS_PLUGIN_URL', plugin_dir_url( ACLS_PLUGIN_FILE ) );
}

if ( ! defined( 'ACLS_PLUGIN_SLUG' ) ) {
	define( 'ACLS_PLUGIN_SLUG', 'aerospin-css-loading-spinners' );
}

if ( ! defined( 'ACLS_TEXT_DOMAIN' ) ) {
	define( 'ACLS_TEXT_DOMAIN', 'aerospin-css-loading-spinners' );
}

if ( ! defined( 'ACLS_OPTIONS_KEY' ) ) {
	define( 'ACLS_OPTIONS_KEY', 'acls_settings' );
}

if ( ! defined( 'ACLS_SETTINGS_PAGE_SLUG' ) ) {
	define( 'ACLS_SETTINGS_PAGE_SLUG', 'acls-settings' );
}

if ( ! defined( 'ACLS_REQUIRED_CAPABILITY' ) ) {
	define( 'ACLS_REQUIRED_CAPABILITY', 'manage_options' );
}

if ( ! defined( 'ACLS_BRAND_URL' ) ) {
	define( 'ACLS_BRAND_URL', 'https://wpclearpath.com' );
}

if ( ! defined( 'ACLS_DOCS_URL' ) ) {
	define( 'ACLS_DOCS_URL', 'https://wpclearpath.com/aerospin-css-loading-spinners' );
}

if ( ! defined( 'ACLS_SUPPORT_URL' ) ) {
	define( 'ACLS_SUPPORT_URL', 'https://wpclearpath.com' );
}

if ( ! defined( 'ACLS_DEBUG_LOG_OPTION' ) ) {
	define( 'ACLS_DEBUG_LOG_OPTION', 'acls_bootstrap_debug_log' );
}

// Backward-compatibility aliases for AEROSPIN_CSS_LOADING_SPINNERS_*
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_VERSION' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_VERSION', ACLS_VERSION );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_MINIMUM_WP_VERSION' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_MINIMUM_WP_VERSION', ACLS_MINIMUM_WP_VERSION );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_MINIMUM_PHP_VERSION' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_MINIMUM_PHP_VERSION', ACLS_MINIMUM_PHP_VERSION );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_FILE' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_FILE', ACLS_PLUGIN_FILE );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_BASENAME' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_BASENAME', ACLS_PLUGIN_BASENAME );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_DIR' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_DIR', ACLS_PLUGIN_DIR );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_URL' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_URL', ACLS_PLUGIN_URL );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_SLUG' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_SLUG', ACLS_PLUGIN_SLUG );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_TEXT_DOMAIN' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_TEXT_DOMAIN', ACLS_TEXT_DOMAIN );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_OPTIONS_KEY' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_OPTIONS_KEY', ACLS_OPTIONS_KEY );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_SETTINGS_PAGE_SLUG' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_SETTINGS_PAGE_SLUG', ACLS_SETTINGS_PAGE_SLUG );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_REQUIRED_CAPABILITY' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_REQUIRED_CAPABILITY', ACLS_REQUIRED_CAPABILITY );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_BRAND_URL' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_BRAND_URL', ACLS_BRAND_URL );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_DOCS_URL' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_DOCS_URL', ACLS_DOCS_URL );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_SUPPORT_URL' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_SUPPORT_URL', ACLS_SUPPORT_URL );
}
if ( ! defined( 'AEROSPIN_CSS_LOADING_SPINNERS_DEBUG_LOG_OPTION' ) ) {
	define( 'AEROSPIN_CSS_LOADING_SPINNERS_DEBUG_LOG_OPTION', ACLS_DEBUG_LOG_OPTION );
}

// Backward-compatibility aliases for legacy Pure_CSS_Spinners constant references.
if ( ! defined( 'PURE_CSS_SPINNERS_VERSION' ) ) {
	define( 'PURE_CSS_SPINNERS_VERSION', AEROSPIN_CSS_LOADING_SPINNERS_VERSION );
}
if ( ! defined( 'PURE_CSS_SPINNERS_MINIMUM_WP_VERSION' ) ) {
	define( 'PURE_CSS_SPINNERS_MINIMUM_WP_VERSION', AEROSPIN_CSS_LOADING_SPINNERS_MINIMUM_WP_VERSION );
}
if ( ! defined( 'PURE_CSS_SPINNERS_MINIMUM_PHP_VERSION' ) ) {
	define( 'PURE_CSS_SPINNERS_MINIMUM_PHP_VERSION', AEROSPIN_CSS_LOADING_SPINNERS_MINIMUM_PHP_VERSION );
}
if ( ! defined( 'PURE_CSS_SPINNERS_PLUGIN_FILE' ) ) {
	define( 'PURE_CSS_SPINNERS_PLUGIN_FILE', AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_FILE );
}
if ( ! defined( 'PURE_CSS_SPINNERS_PLUGIN_BASENAME' ) ) {
	define( 'PURE_CSS_SPINNERS_PLUGIN_BASENAME', AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_BASENAME );
}
if ( ! defined( 'PURE_CSS_SPINNERS_PLUGIN_DIR' ) ) {
	define( 'PURE_CSS_SPINNERS_PLUGIN_DIR', AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_DIR );
}
if ( ! defined( 'PURE_CSS_SPINNERS_PLUGIN_URL' ) ) {
	define( 'PURE_CSS_SPINNERS_PLUGIN_URL', AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_URL );
}
if ( ! defined( 'PURE_CSS_SPINNERS_PLUGIN_SLUG' ) ) {
	define( 'PURE_CSS_SPINNERS_PLUGIN_SLUG', AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_SLUG );
}
if ( ! defined( 'PURE_CSS_SPINNERS_TEXT_DOMAIN' ) ) {
	define( 'PURE_CSS_SPINNERS_TEXT_DOMAIN', AEROSPIN_CSS_LOADING_SPINNERS_TEXT_DOMAIN );
}
if ( ! defined( 'PURE_CSS_SPINNERS_OPTIONS_KEY' ) ) {
	define( 'PURE_CSS_SPINNERS_OPTIONS_KEY', AEROSPIN_CSS_LOADING_SPINNERS_OPTIONS_KEY );
}
if ( ! defined( 'PURE_CSS_SPINNERS_SETTINGS_PAGE_SLUG' ) ) {
	define( 'PURE_CSS_SPINNERS_SETTINGS_PAGE_SLUG', AEROSPIN_CSS_LOADING_SPINNERS_SETTINGS_PAGE_SLUG );
}
if ( ! defined( 'PURE_CSS_SPINNERS_REQUIRED_CAPABILITY' ) ) {
	define( 'PURE_CSS_SPINNERS_REQUIRED_CAPABILITY', AEROSPIN_CSS_LOADING_SPINNERS_REQUIRED_CAPABILITY );
}
if ( ! defined( 'PURE_CSS_SPINNERS_BRAND_URL' ) ) {
	define( 'PURE_CSS_SPINNERS_BRAND_URL', AEROSPIN_CSS_LOADING_SPINNERS_BRAND_URL );
}
if ( ! defined( 'PURE_CSS_SPINNERS_DOCS_URL' ) ) {
	define( 'PURE_CSS_SPINNERS_DOCS_URL', AEROSPIN_CSS_LOADING_SPINNERS_DOCS_URL );
}
if ( ! defined( 'PURE_CSS_SPINNERS_SUPPORT_URL' ) ) {
	define( 'PURE_CSS_SPINNERS_SUPPORT_URL', AEROSPIN_CSS_LOADING_SPINNERS_SUPPORT_URL );
}
if ( ! defined( 'PURE_CSS_SPINNERS_DEBUG_LOG_OPTION' ) ) {
	define( 'PURE_CSS_SPINNERS_DEBUG_LOG_OPTION', AEROSPIN_CSS_LOADING_SPINNERS_DEBUG_LOG_OPTION );
}
if ( ! defined( 'Pure_CSS_Spinners_VERSION' ) ) {
	define( 'Pure_CSS_Spinners_VERSION', AEROSPIN_CSS_LOADING_SPINNERS_VERSION );
}
if ( ! defined( 'Pure_CSS_Spinners_PLUGIN_URL' ) ) {
	define( 'Pure_CSS_Spinners_PLUGIN_URL', AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_URL );
}
if ( ! defined( 'Pure_CSS_Spinners_PLUGIN_DIR' ) ) {
	define( 'Pure_CSS_Spinners_PLUGIN_DIR', AEROSPIN_CSS_LOADING_SPINNERS_PLUGIN_DIR );
}
if ( ! defined( 'Pure_CSS_Spinners_OPTIONS_KEY' ) ) {
	define( 'Pure_CSS_Spinners_OPTIONS_KEY', AEROSPIN_CSS_LOADING_SPINNERS_OPTIONS_KEY );
}
if ( ! defined( 'Pure_CSS_Spinners_SETTINGS_PAGE_SLUG' ) ) {
	define( 'Pure_CSS_Spinners_SETTINGS_PAGE_SLUG', AEROSPIN_CSS_LOADING_SPINNERS_SETTINGS_PAGE_SLUG );
}
if ( ! defined( 'Pure_CSS_Spinners_REQUIRED_CAPABILITY' ) ) {
	define( 'Pure_CSS_Spinners_REQUIRED_CAPABILITY', AEROSPIN_CSS_LOADING_SPINNERS_REQUIRED_CAPABILITY );
}

/*
|--------------------------------------------------------------------------
| SECTION 2: Plugin Bootstrap Class
|--------------------------------------------------------------------------
|
| This class isolates the plugin's loading logic, ensuring files are only
| included if requirements are met, and tracking any accidental output via
| output buffering.
|
*/

if ( ! class_exists( 'AeroSpin_CSS_Loading_Spinners_Bootstrap' ) ) {

	/**
	 * Handles the initial environment checks and file inclusions.
	 *
	 * @since 1.1.4
	 */
	final class ACLS_Bootstrap {

		/**
		 * Initialize the bootstrap sequence.
		 *
		 * @since 1.1.4
		 *
		 * @return void
		 */
		public static function init() {
			if ( self::meets_minimum_requirements() ) {
				self::load_includes();
			} else {
				add_action( 'admin_notices', array( __CLASS__, 'minimum_requirements_notice' ) );
			}
		}

		/**
		 * Check whether the site meets AeroSpin CSS Loading Spinners minimum requirements.
		 *
		 * @since 1.1.4
		 *
		 * @return bool
		 */
		public static function meets_minimum_requirements() {
			global $wp_version;

			// Verify PHP compatibility.
			if ( version_compare( PHP_VERSION, ACLS_MINIMUM_PHP_VERSION, '<' ) ) {
				return false;
			}

			// Verify WordPress compatibility.
			if ( isset( $wp_version ) && version_compare( $wp_version, ACLS_MINIMUM_WP_VERSION, '<' ) ) {
				return false;
			}

			return true;
		}

		/**
		 * Display an admin notice when minimum requirements are not met.
		 *
		 * @since 1.1.4
		 *
		 * @return void
		 */
		public static function minimum_requirements_notice() {
			if ( self::meets_minimum_requirements() ) {
				return;
			}

			global $wp_version;

			$current_wp_version = isset( $wp_version ) ? $wp_version : '';

			printf(
				'<div class="notice notice-error"><p><strong>%1$s</strong> %2$s</p></div>',
				esc_html__( 'AeroSpin CSS Loading Spinners:', 'aerospin-css-loading-spinners' ),
				sprintf(
					/* translators: 1: Minimum WordPress version. 2: Current WordPress version. 3: Minimum PHP version. 4: Current PHP version. */
					esc_html__( 'This plugin requires WordPress %1$s or higher and PHP %3$s or higher. Current versions: WordPress %2$s, PHP %4$s.', 'aerospin-css-loading-spinners' ),
					esc_html( ACLS_MINIMUM_WP_VERSION ),
					esc_html( $current_wp_version ),
					esc_html( ACLS_MINIMUM_PHP_VERSION ),
					esc_html( PHP_VERSION )
				)
			);
		}

		/**
		 * Load core files cleanly.
		 *
		 * @since 1.1.4
		 *
		 * @return void
		 */
		private static function load_includes() {
			// Require the helper schema before everything else to establish defaults.
			self::require_plugin_file( 'includes/acls-helpers.php' );
			self::require_plugin_file( 'includes/acls-spinners-list.php' );
			self::require_plugin_file( 'includes/acls-settings.php' );
			self::require_plugin_file( 'admin/acls-admin.php' );
			self::require_plugin_file( 'public/acls-public.php' );
		}

		/**
		 * Load a plugin file while capturing accidental output.
		 *
		 * This prevents accidental output from included files from reaching the
		 * browser and records the output length/hex value when WP_DEBUG is enabled.
		 *
		 * @since 1.1.4
		 *
		 * @param string $relative_path Relative plugin path.
		 * @return bool
		 */
		private static function require_plugin_file( $relative_path ) {
			$relative_path = ltrim( (string) $relative_path, '/\\' );
			$file_path     = ACLS_PLUGIN_DIR . $relative_path;

			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_file_exists -- WP_Filesystem is not available during early bootstrap without massive overhead.
			if ( ! file_exists( $file_path ) || ! is_readable( $file_path ) ) {
				self::bootstrap_debug_log( 'Missing or unreadable include: ' . $relative_path );
				return false;
			}

			// Capture output buffer to prevent headers already sent errors.
			ob_start();

			require_once $file_path;

			$unexpected_output = ob_get_clean();

			if ( '' !== $unexpected_output ) {
				self::bootstrap_debug_log( 'Unexpected output while loading ' . $relative_path . '. Length: ' . strlen( $unexpected_output ) . '. Hex: ' . bin2hex( $unexpected_output ) );
			}

			return true;
		}

		/**
		 * Determine whether AeroSpin CSS Loading Spinners should log bootstrap debug details.
		 *
		 * @since 1.1.4
		 *
		 * @return bool
		 */
		private static function should_log_bootstrap_debug() {
			return defined( 'WP_DEBUG' ) && WP_DEBUG;
		}

		/**
		 * Write a safe bootstrap debug message.
		 *
		 * Stores recent bootstrap/debug messages in a WordPress option instead of
		 * writing directly to a log file.
		 *
		 * @since 1.1.4
		 *
		 * @param string $message Message to log.
		 * @return void
		 */
		private static function bootstrap_debug_log( $message ) {
			if ( ! self::should_log_bootstrap_debug() ) {
				return;
			}

			if ( ! is_string( $message ) || '' === $message ) {
				return;
			}

			$entries = get_option( ACLS_DEBUG_LOG_OPTION, array() );

			if ( ! is_array( $entries ) ) {
				$entries = array();
			}

			// Enhancement: Replaced deprecated current_time() with wp_date() and gmdate() for accurate, modern time tracking.
			$entries[] = array(
				'time'    => function_exists( 'wp_date' ) ? wp_date( 'Y-m-d H:i:s' ) : gmdate( 'Y-m-d H:i:s' ),
				'message' => sanitize_text_field( $message ),
			);

			// Keep only the most recent 20 logs.
			$entries = array_slice( $entries, -20 );

			update_option( ACLS_DEBUG_LOG_OPTION, $entries, false );
		}
	}
}

if ( ! class_exists( 'AeroSpin_CSS_Loading_Spinners_Bootstrap' ) ) {
	class_alias( 'ACLS_Bootstrap', 'AeroSpin_CSS_Loading_Spinners_Bootstrap' );
}
if ( ! class_exists( 'Pure_CSS_Spinners_Bootstrap' ) ) {
	class_alias( 'ACLS_Bootstrap', 'Pure_CSS_Spinners_Bootstrap' );
}
if ( ! class_exists( 'AreoSpin_Css_Loading_Spinners_Bootstrap' ) ) {
	class_alias( 'ACLS_Bootstrap', 'AreoSpin_Css_Loading_Spinners_Bootstrap' );
}

/*
|--------------------------------------------------------------------------
| SECTION 3: Main Plugin Class
|--------------------------------------------------------------------------
|
| The main AeroSpin CSS Loading Spinners class registers lifecycle hooks and plugin row action
| links. Feature-specific behavior remains in the dedicated admin, public,
| settings, helper, and spinner registry files.
|
*/

if ( ! class_exists( 'AeroSpin_CSS_Loading_Spinners' ) ) {

	/**
	 * Main plugin bootstrap class.
	 *
	 * @since 1.0.0
	 */
	// phpcs:ignore Generic.Files.OneObjectStructurePerFile.MultipleFound -- Main plugin file houses both early bootstrap and lifecycle hooks.
	final class ACLS_Plugin {

		/**
		 * Single plugin instance.
		 *
		 * @since 1.0.0
		 *
		 * @var AeroSpin_CSS_Loading_Spinners|null
		 */
		private static $instance = null;

		/**
		 * Get the single plugin instance.
		 *
		 * @since 1.0.0
		 *
		 * @return AeroSpin_CSS_Loading_Spinners
		 */
		public static function get_instance() {
			if ( null === self::$instance ) {
				self::$instance = new self();
			}

			return self::$instance;
		}

		/**
		 * Set up lifecycle hooks and plugin integrations.
		 *
		 * @since 1.0.0
		 */
		private function __construct() {
			// Register activation/deactivation hooks.
			register_activation_hook( ACLS_PLUGIN_FILE, array( $this, 'activate' ) );
			register_deactivation_hook( ACLS_PLUGIN_FILE, array( $this, 'deactivate' ) );

			// Add custom action links.
			add_filter( 'plugin_action_links_' . ACLS_PLUGIN_BASENAME, array( $this, 'add_action_links' ) );
			if ( defined( 'PURE_CSS_SPINNERS_PLUGIN_BASENAME' ) && PURE_CSS_SPINNERS_PLUGIN_BASENAME !== ACLS_PLUGIN_BASENAME ) {
				add_filter( 'plugin_action_links_' . PURE_CSS_SPINNERS_PLUGIN_BASENAME, array( $this, 'add_action_links' ) );
			}
			add_filter( 'plugin_row_meta', array( $this, 'add_plugin_row_meta' ), 10, 2 );

			// Ensure admin controller is registered.
			if ( class_exists( 'ACLS_Admin' ) ) {
				ACLS_Admin::get_instance();
			} elseif ( class_exists( 'AeroSpin_CSS_Loading_Spinners_Admin' ) ) {
				AeroSpin_CSS_Loading_Spinners_Admin::get_instance();
			}
		}

		/**
		 * Prevent cloning the singleton.
		 *
		 * @since 1.0.0
		 *
		 * @return void
		 */
		private function __clone() {
			_doing_it_wrong(
				__FUNCTION__,
				esc_html__( 'Cloning instances of the main plugin class is forbidden.', 'aerospin-css-loading-spinners' ),
				'1.0.0'
			);
		}

		/**
		 * Prevent unserializing the singleton.
		 *
		 * @since 1.0.0
		 *
		 * @return void
		 */
		public function __wakeup() {
			_doing_it_wrong(
				__FUNCTION__,
				esc_html__( 'Unserializing instances of the main plugin class is forbidden.', 'aerospin-css-loading-spinners' ),
				'1.0.0'
			);
		}

		/*
		|--------------------------------------------------------------------------
		| SECTION 4: Plugin Action Links and Meta Links
		|--------------------------------------------------------------------------
		*/

		/**
		 * Add plugin action links on the Plugins screen.
		 *
		 * @since 1.0.0
		 *
		 * @param array $links Existing plugin action links.
		 * @return array Modified plugin action links.
		 */
		public function add_action_links( $links ) {
			$slug         = defined( 'ACLS_SETTINGS_PAGE_SLUG' ) ? ACLS_SETTINGS_PAGE_SLUG : ( defined( 'AEROSPIN_CSS_LOADING_SPINNERS_SETTINGS_PAGE_SLUG' ) ? AEROSPIN_CSS_LOADING_SPINNERS_SETTINGS_PAGE_SLUG : 'acls-settings' );
			$settings_url = admin_url( 'admin.php?page=' . $slug );

			$plugin_links = array(
				'settings' => sprintf(
					'<a href="%1$s">%2$s</a>',
					esc_url( $settings_url ),
					esc_html__( 'Settings', 'aerospin-css-loading-spinners' )
				),
			);

			return array_merge( $plugin_links, $links );
		}

		/**
		 * Add plugin row meta links.
		 *
		 * @since 1.1.4
		 *
		 * @param array  $links Plugin row meta links.
		 * @param string $file  Current plugin file basename.
		 * @return array Modified plugin row meta links.
		 */
		public function add_plugin_row_meta( $links, $file ) {
			if ( ACLS_PLUGIN_BASENAME !== $file && PURE_CSS_SPINNERS_PLUGIN_BASENAME !== $file ) {
				return $links;
			}

			$brand_url = defined( 'ACLS_BRAND_URL' ) ? ACLS_BRAND_URL : 'https://wpclearpath.com';
			$doc_url   = defined( 'ACLS_DOCS_URL' ) ? ACLS_DOCS_URL : 'https://wpclearpath.com/aerospin-css-loading-spinners';

			$row_meta = array(
				sprintf(
					'<a href="%1$s" target="_blank" rel="noopener noreferrer">%2$s</a>',
					esc_url( $doc_url ),
					esc_html__( 'Docs', 'aerospin-css-loading-spinners' )
				),
				sprintf(
					'<a href="%1$s" target="_blank" rel="noopener noreferrer">%2$s</a>',
					esc_url( $brand_url ),
					esc_html__( 'Visit Site', 'aerospin-css-loading-spinners' )
				),
			);

			return array_merge( $links, $row_meta );
		}

		/*
		|--------------------------------------------------------------------------
		| SECTION 5: Activation and Deactivation
		|--------------------------------------------------------------------------
		*/

		/**
		 * Run plugin activation tasks.
		 *
		 * Creates the settings option only when it does not already exist.
		 * Existing user settings are never overwritten during activation.
		 *
		 * @since 1.0.0
		 *
		 * @return void
		 */
		public function activate() {
			ob_start();

			if ( ! ACLS_Bootstrap::meets_minimum_requirements() ) {
				$this->log_activation_output();
				deactivate_plugins( ACLS_PLUGIN_BASENAME );

				wp_die(
					sprintf(
						/* translators: 1: Minimum WordPress version. 2: Current WordPress version. */
						esc_html__( 'AeroSpin CSS Loading Spinners requires WordPress %1$s or higher and PHP %2$s or higher.', 'aerospin-css-loading-spinners' ),
						esc_html( ACLS_MINIMUM_WP_VERSION ),
						esc_html( ACLS_MINIMUM_PHP_VERSION )
					),
					esc_html__( 'AeroSpin CSS Loading Spinners Activation Error', 'aerospin-css-loading-spinners' ),
					array(
						'back_link' => true,
						'response'  => 200,
					)
				);
			}

			if ( false === get_option( ACLS_OPTIONS_KEY, false ) ) {
				add_option( ACLS_OPTIONS_KEY, $this->get_activation_defaults() );
			}

			$this->log_activation_output();
		}

		/**
		 * Run plugin deactivation tasks.
		 *
		 * User settings are intentionally preserved. Data removal belongs in
		 * uninstall.php, not in the deactivation routine.
		 *
		 * @since 1.0.0
		 *
		 * @return void
		 */
		public function deactivate() {
			// Intentionally left blank. Data removal is handled in uninstall.php.
		}

		/**
		 * Capture and log unexpected activation output.
		 * Logs to the database via options instead of directly calling
		 * error_log() to comply strictly with WordPress PHPCS standards.
		 *
		 * @since 1.1.4
		 *
		 * @return void
		 */
		private function log_activation_output() {
			$unexpected_output = ob_get_clean();

			if ( '' === $unexpected_output ) {
				return;
			}

			// Store early-activation anomalies safely via settings logic to ensure PHPCS compliance.
			if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
				$entries = get_option( ACLS_DEBUG_LOG_OPTION, array() );

				if ( ! is_array( $entries ) ) {
					$entries = array();
				}

				// Enhancement: Replaced deprecated current_time() with wp_date() and gmdate() for absolute PHPCS compliance.
				$entries[] = array(
					'time'    => function_exists( 'wp_date' ) ? wp_date( 'Y-m-d H:i:s' ) : gmdate( 'Y-m-d H:i:s' ),
					'message' => 'AeroSpin CSS Loading Spinners Activation Output: ' . strlen( $unexpected_output ) . ' bytes detected.',
				);

				// Keep only the most recent 20 logs.
				$entries = array_slice( $entries, -20 );

				update_option( ACLS_DEBUG_LOG_OPTION, $entries, false );
			}
		}

		/**
		 * Get safe default settings for activation.
		 *
		 * By the time this runs, the OOP bootstrap guarantees the helper class is available.
		 *
		 * @since 1.1.4
		 *
		 * @return array
		 */
		private function get_activation_defaults() {
			if ( class_exists( 'ACLS_Helpers' ) || class_exists( 'AeroSpin_CSS_Loading_Spinners_Helpers' ) ) {
				return class_exists( 'ACLS_Helpers' ) ? ACLS_Helpers::normalize_settings( ACLS_Helpers::get_defaults() ) : AeroSpin_CSS_Loading_Spinners_Helpers::normalize_settings( AeroSpin_CSS_Loading_Spinners_Helpers::get_defaults() );
			}

			return array();
		}
	}
}

if ( ! class_exists( 'AeroSpin_CSS_Loading_Spinners' ) ) {
	class_alias( 'ACLS_Plugin', 'AeroSpin_CSS_Loading_Spinners' );
}
if ( ! class_exists( 'Pure_CSS_Spinners' ) ) {
	class_alias( 'ACLS_Plugin', 'Pure_CSS_Spinners' );
}
if ( ! class_exists( 'AreoSpin_Css_Loading_Spinners' ) ) {
	class_alias( 'ACLS_Plugin', 'AreoSpin_Css_Loading_Spinners' );
}

/*
|--------------------------------------------------------------------------
| SECTION 6: Plugin Initialization
|--------------------------------------------------------------------------
*/

// Initialize the secure bootstrap sequence.
ACLS_Bootstrap::init();

// Spin up the core hooks if the environment qualifies.
if ( ACLS_Bootstrap::meets_minimum_requirements() ) {
	ACLS_Plugin::get_instance();
}