<?php
/**
 * Fail-closed screen context helper for SEOvault-owned admin pages.
 *
 * Provides an explicit allowlist of SEOvault screen hook suffixes that own
 * the two-column global canvas and sidebar.  Detection always fails closed
 * for unknown, empty, or malformed screen identifiers.
 *
 * @package SEOvaultSEO\Admin
 */

namespace SEOvaultSEO\Admin;

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

/**
 * Screen context helper.
 *
 * Used by the notice separation layer to determine whether the current
 * request is on an SEOvault-owned page that will render the Action Center.
 */
class ScreenContext {

	/**
	 * SEOvault screen hook suffixes that use the global canvas and sidebar.
	 *
	 * The primary Dashboard (toplevel_page_seovault-ai) is intentionally
	 * excluded because it does not use the two-column canvas.
	 *
	 * The SEO Analyzer (seovault-ai_page_seovault-ai-analyzer) is excluded
	 * because it has its own focused workflow; Analyzer-specific notices
	 * may still be rendered locally inside the Analyzer page.
	 */
	const SCREEN_GENERAL = 'seovault-ai_page_seovault-ai-general';
	const SCREEN_STATUS  = 'seovault-ai_page_seovault-ai-status';

	/**
	 * Complete allowlist of SEOvault screen IDs with the sidebar.
	 *
	 * @var array<string>
	 */
	const ALLOWED_SCREENS = array(
		self::SCREEN_GENERAL,
		self::SCREEN_STATUS,
	);

	/**
	 * Get the current WordPress screen ID.
	 *
	 * @return string Screen ID or empty string when unavailable.
	 */
	public static function get_current_screen_id() {
		$screen = get_current_screen();
		if ( $screen instanceof \WP_Screen ) {
			return (string) $screen->id;
		}
		return '';
	}

	/**
	 * Whether the current request is on an SEOvault-owned screen with the sidebar.
	 *
	 * Fails closed when get_current_screen() is unavailable.
	 *
	 * @return bool
	 */
	public static function is_seovault_screen() {
		$screen_id = self::get_current_screen_id();
		if ( '' === $screen_id ) {
			return false;
		}
		return self::is_allowed_screen( $screen_id );
	}

	/**
	 * Whether a given screen ID is in the SEOvault allowlist.
	 *
	 * Strict string comparison against the allowlist.  Non-string, empty,
	 * and unknown values always return false.
	 *
	 * @param mixed $screen_id Screen ID to check.
	 * @return bool
	 */
	public static function is_allowed_screen( $screen_id ) {
		if ( ! is_string( $screen_id ) || '' === $screen_id ) {
			return false;
		}
		return in_array( $screen_id, self::ALLOWED_SCREENS, true );
	}
}
