with a Copy button.',
	 * ]
	 *
	 * @return array[]
	 */
	public function ui_notices(): array {
		return array();
	}

	/**
	 * Is this module actually doing something right now?
	 *
	 * "On" is not one shape across the plugin. Most modules carry an
	 * `enabled` setting, but page caching lives in the GLOBAL option
	 * (`xspeed_options.cache_enabled`), Minify and Lazy are on when any of
	 * their individual flags is set, and MCP is on when it is connected.
	 * The sidebar's "N on" badge counted only the literal `enabled` key, so
	 * it under-reported: on a site with page caching, minification, lazy
	 * loading and MCP all running it read "Cache 2 / Optimization 1" and
	 * left the plugin's headline feature out of its own count. (#363)
	 *
	 * The default below keeps the historic behaviour for the modules that
	 * genuinely do store `enabled`. A module whose "on" means something
	 * else overrides this and answers for itself, which is what stops the
	 * count drifting again the next time a module changes shape.
	 *
	 * Three-state on purpose:
	 *   true  — on and doing work
	 *   false — off
	 *   null  — no meaningful on/off (a status panel like Health). Callers
	 *           must exclude these rather than counting them as off.
	 */
	public function is_active(): ?bool {
		$settings = $this->get_settings();
		return array_key_exists( 'enabled', $settings )
			? (bool) $settings['enabled']
			: null;
	}

	/**
	 * "On if any of my boolean flags is on" — the shape used by modules
	 * that have no master switch, only a set of independent toggles
	 * (Minify, Lazy, Bloat, Gzip).
	 *
	 * Derived from the module's OWN schema rather than a hardcoded key
	 * list, so adding a flag to a module cannot silently fall out of its
	 * active state the way a literal list would. Only `bool` fields count:
	 * an int like `eager_first_n` or a list like `excluded_images` is
	 * configuration for a feature, not evidence the feature is on.
	 *
	 * Returns null when the module declares no boolean flags at all, so a
	 * caller can exclude it rather than record a misleading false.
	 */
	final protected function any_bool_flag_on(): ?bool {
		$schema   = $this->settings_schema();
		$settings = $this->get_settings();

		$found = false;
		foreach ( $schema as $key => $spec ) {
			if ( 'bool' !== ( $spec['type'] ?? '' ) ) {
				continue;
			}
			$found = true;
			if ( ! empty( $settings[ $key ] ) ) {
				return true;
			}
		}

		return $found ? false : null;
	}

	/**
	 * Why is this module reported on or off? One short sentence for the (i)
	 * beside the status pill.
	 *
	 * "On" is not one shape (see is_active()), so without this the pill is a
	 * bare assertion the user cannot check. It is most opaque exactly where
	 * the rule is least obvious: Media Optimization reads "On" while its two
	 * most prominent switches, Lazy-load Images and Iframes, are both off --
	 * because three other flags are on. The reason names them.
	 *
	 * Computed server-side alongside is_active() so the explanation cannot
	 * drift from the verdict it explains. Returning null means "no reason to
	 * add" and the (i) is not rendered.
	 */
	public function active_reason(): ?string {
		// A module with its own `enabled` switch needs no explaining: the
		// pill and the switch say the same thing, and an (i) that only
		// restates the pill is noise on every one of those pages. Silence
		// here is what keeps the (i) meaningful where it does appear.
		if ( array_key_exists( 'enabled', $this->get_settings() ) ) {
			return null;
		}

		return $this->bool_flag_reason();
	}

	/**
	 * The reason text for a module whose "on" is "any of my flags is on".
	 *
	 * Names the specific settings that are on, using their schema labels, so
	 * the user can go and look at them rather than take the pill on trust.
	 * Shared by every flag-based module for one consistent sentence.
	 */
	final protected function bool_flag_reason(): ?string {
		$schema   = $this->settings_schema();
		$settings = $this->get_settings();

		$on = array();
		foreach ( $schema as $key => $spec ) {
			if ( 'bool' !== ( $spec['type'] ?? '' ) ) {
				continue;
			}
			if ( ! empty( $settings[ $key ] ) ) {
				$on[] = $spec['label'] ?? $key;
			}
		}

		// No boolean flags at all means the module has no on/off to explain
		// (a status panel like Health). Mirrors any_bool_flag_on() returning
		// null: no verdict, so no reason.
		if ( null === $this->any_bool_flag_on() ) {
			return null;
		}

		if ( empty( $on ) ) {
			return __( 'This module has no single on/off switch. It counts as on when any of its settings is on, and none currently is.', 'xspeed' );
		}

		return sprintf(
			/* translators: %s: comma-separated list of setting labels that are switched on. */
			__( 'This module has no single on/off switch. It counts as on because these settings are on: %s.', 'xspeed' ),
			implode( ', ', $on )
		);
	}

	/**
	 * WP-CLI command definitions. Each entry: [
	 *   'name'     => 'xspeed cache purge',
	 *   'callback' => callable,
	 *   'synopsis' => array, // wp-cli synopsis spec
	 * ]
	 *
	 * @return array[]
	 */
	public function cli_commands(): array {
		return array();
	}

	/**
	 * Nginx directives this module contributes to the unified server-block
	 * snippet rendered by Cache::full_nginx_server_block(). Returning a
	 * non-null string opts the module into the consolidated "paste this
	 * once into your nginx vhost" UX on the Cache panel.
	 *
	 * The returned string should be the bare directives only — no `server
	 * { }` wrapper, no comment header (the aggregator adds one). Empty
	 * string and null are both treated as "no contribution this render".
	 *
	 * Return null (default) when the module is disabled, its current
	 * settings make the directives a no-op, or the module doesn't have
	 * nginx-side directives at all.
	 */
	public function nginx_directives(): ?string {
		return null;
	}

	/**
	 * Conflict declarations for this module — which other plugins clash
	 * with which sub-feature. Each entry: [
	 *   'plugin'   => 'wp-rocket/wp-rocket.php',
	 *   'feature'  => 'page_cache',
	 *   'strategy' => 'refuse' | 'warn' | 'allow',
	 *   'reason'   => 'human-readable why',
	 * ]
	 *
	 * @return array[]
	 */
	public function conflicts(): array {
		return array();
	}

	/**
	 * Register WP hooks. Called by Module_Registry::boot_all() after
	 * dependencies are resolved. Modules should NOT register hooks in
	 * their constructors — only in boot() — so the registry can control
	 * load order.
	 */
	public function boot(): void {}

	/**
	 * One-time setup at plugin activation. Idempotent. Examples: create
	 * a custom table, write a silence guard, register a cron schedule.
	 */
	public function activate(): void {}

	/**
	 * Tear down at plugin deactivation. Reversible counterpart to
	 * activate(). MUST leave the site in a clean state — no orphaned
	 * cron jobs, no leftover drop-ins.
	 */
	public function deactivate(): void {}

	/**
	 * Convenience accessors. Modules read/write their own settings
	 * through these so the storage detail (one option per module under
	 * `xspeed_module_`) stays encapsulated.
	 */
	final public function get_setting( string $key, $default = null ) {
		$opts = Settings_Manager::get( static::SLUG );
		return array_key_exists( $key, $opts ) ? $opts[ $key ] : $default;
	}

	final public function get_settings(): array {
		return Settings_Manager::get( static::SLUG );
	}

	final public function update_settings( array $input ): array {
		$refusal = $this->license_write_refusal( $input );
		if ( null !== $refusal ) {
			return $refusal;
		}
		return Settings_Manager::update( static::SLUG, $input );
	}

	/**
	 * Enforce the Pro licence gate on writes, or null to allow the write.
	 *
	 * The dashboard renders a Pro module as `locked` without a valid licence
	 * and refuses to toggle it, but that flag is applied by the
	 * `xspeed_module_descriptor` filter — a decoration on the payload the UI
	 * reads. It never reached the write path, so `POST /xspeed/v1/`
	 * with `{"enabled": true}` returned 200 and persisted, and CLI/MCP hit the
	 * same unguarded callbacks.
	 *
	 * That mattered because module availability is decided by
	 * `Tier_Registry::is_available()`, which asks only whether the Pro plugin
	 * is LOADED — never whether it is licensed. So a Pro module boots and runs
	 * its hooks regardless, and a persisted `enabled: true` genuinely turns the
	 * feature on. This was not cosmetic. (#143)
	 *
	 * Free never references Pro: it asks through `xspeed_pro_licensed`, the
	 * same filter Pro already answers for the descriptor. With no Pro plugin
	 * present nothing hooks it, the default `true` stands, and Free modules
	 * are unaffected either way.
	 *
	 * Reads stay open — the dashboard must still be able to GET settings to
	 * render the locked state at all.
	 *
	 * @param array $input Proposed setting values.
	 * @return array|null Current public settings when refused, else null.
	 */
	private function license_write_refusal( array $input ): ?array {
		if ( ! $this->is_license_locked() ) {
			return null;
		}

		Activity_Log::record(
			'license_write_refused',
			sprintf(
				/* translators: %s: module slug. */
				__( 'Refused a settings write to the Pro module "%s" — no valid license.', 'xspeed' ),
				static::SLUG
			),
			Activity_Log::WARN
		);

		// Return the unchanged public settings rather than throwing: callers
		// expect the module's settings back, and the dashboard already renders
		// this module as locked. REST surfaces the refusal explicitly in
		// rest_update_settings(), which has a WP_Error channel.
		return Settings_Manager::get_public( static::SLUG );
	}

	final public function slug(): string {
		return static::SLUG;
	}

	final public function tier(): string {
		return static::TIER;
	}

	final public function version(): string {
		return static::VERSION;
	}
}