<?php
/**
 * Cache module — Theme Compat Base
 *
 * Abstract adapter for theme/page-builder compatibility. Each concrete adapter
 * targets one premium theme or builder (Avada, Elementor, Divi, ...) and is
 * responsible for:
 *   1. Detecting when its target is active.
 *   2. Defusing the cache-incompatible behaviour of the target (constants,
 *      filter overrides, dynamic-CSS toggles).
 *   3. Synchronising purges in both directions.
 *   4. Surfacing exclusions for Defer JS / Delay JS / RUCSS via the shared
 *      filters defined below.
 *
 * @package BlaminhorEssentials
 */

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

abstract class Blaminhor_Essentials_Cache_Theme_Compat_Base {

	/** @var Blaminhor_Essentials_Module_Cache */
	protected $parent;

	public function __construct( Blaminhor_Essentials_Module_Cache $parent ) {
		$this->parent = $parent;
	}

	/**
	 * Stable slug used for settings keys, log lines, UI labels.
	 * Lowercase, no spaces. Examples: 'avada', 'elementor', 'divi'.
	 *
	 * @return string
	 */
	abstract public function id();

	/**
	 * Human-readable name for the admin UI.
	 *
	 * @return string
	 */
	abstract public function label();

	/**
	 * Whether this adapter's target is currently active on the site. Cheap and
	 * deterministic — must not query the DB or hit the network.
	 *
	 * @return bool
	 */
	abstract public function is_active();

	/**
	 * Wire the adapter's hooks. Called only after is_active() returned true
	 * AND the user has not disabled this adapter in settings.
	 *
	 * @return void
	 */
	abstract public function register_hooks();

	/**
	 * Default Defer JS exclusions contributed by this adapter. Plain strings
	 * matched by str_contains(), or regex if surrounded by '#...#'.
	 *
	 * @return string[]
	 */
	public function defer_js_exclusions() {
		return array();
	}

	/**
	 * Default Delay JS exclusions contributed by this adapter.
	 *
	 * @return string[]
	 */
	public function delay_js_exclusions() {
		return array();
	}

	/**
	 * Default RUCSS safelist contributed by this adapter (CSS selectors).
	 *
	 * @return string[]
	 */
	public function rucss_safelist() {
		return array();
	}

	/**
	 * Stylesheet handles or handle prefixes that MUST stay in the synchronous
	 * cascade. The Critical CSS async loader skips any handle that exact-matches
	 * an entry, or that starts with an entry ending in '-'. Used to preserve the
	 * cascade order for theme/builder bundles whose rules override each other in
	 * a strict sequence (Avada's fusion-dynamic-css overriding fusion-styles is
	 * the canonical example: rewriting both as preload swaps the cascade order
	 * to network-arrival order and breaks layout containers).
	 *
	 * @return string[]
	 */
	public function async_css_excluded_handles() {
		return array();
	}
}
