<?php
namespace Actirise\Includes\FastCmp;

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly
}

use Actirise\Includes\Helpers;
use Actirise\Includes\Options;

/**
 * Builds the flat payload the plugin exchanges with the Actirise API, and reads
 * one back into the option store.
 *
 * Deliberately knows **no FastCMP configuration path**: no `options.`, no
 * `bootstrap.`, no `theme.colors`. The plugin speaks its own vocabulary and
 * Krull owns the whole translation, so correcting a path never again requires a
 * WordPress.org release.
 *
 * @link       https://actirise.com
 * @since      4.3.0
 * @package    actirise
 * @subpackage actirise/includes/fastcmp
 * @author     actirise <wordpress@actirise.com>
 */
final class ConfigPayload {
	/**
	 * Posted form key => the option suffix that key is stored under.
	 *
	 * Every key the settings form submits and the contract carries. A key missing
	 * here is silently unsyncable: {@see self::delta()} skips what it cannot map,
	 * so the save publishes nothing, WordPress keeps an edit Actirise never heard
	 * of, and the next inbound push overwrites it. `fastcmp-name` is the one
	 * deliberate absence — the form never posts it, so `publisherName` reaches
	 * Actirise through the seed alone.
	 *
	 * The admin form posts `privacyPolicy` and `headOffice` in camelCase while the
	 * canonical options are `fastcmp-privacypolicy` and `fastcmp-headoffice`; both
	 * spellings resolve to the same row only because MySQL compares `option_name`
	 * case-insensitively. This map is what keeps the projection independent of
	 * that accident. `customStyle` keeps its camelCase on both sides — the option
	 * really is `fastcmp-customStyle`.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const POSTED_SUFFIXES = array(
		'privacyPolicy'         => 'privacypolicy',
		'headOffice'            => 'headoffice',
		'targetedaudience'      => 'targetedaudience',
		'logo'                  => 'logo',
		'customStyle'           => 'customStyle',
		'excludediabvendors'    => 'excludediabvendors',
		'excludedgooglevendors' => 'excludedgooglevendors',
		'customsVendor'         => 'customsvendor',
	);

	/**
	 * Option suffix => the DTO field it travels as, for the values that need no
	 * reshaping.
	 *
	 * The delta's half of {@see self::EFFECTIVE_SCALARS}, which the seed uses; the
	 * two are keyed differently — option suffixes here, effective-view keys there —
	 * so they are spelled out separately rather than derived from one another. They
	 * must cover the same DTO fields all the same: a field the seed can publish and
	 * a save cannot is a value that diverges the moment the publisher edits it.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const SCALAR_FIELDS = array(
		'privacypolicy'    => 'policyUrl',
		'headoffice'       => 'countryCode',
		'targetedaudience' => 'jurisdiction',
		'logo'             => 'publisherLogo',
		'customStyle'      => 'customCss',
	);

	/**
	 * Option suffix => the DTO field it travels as, for the two vendor-exclusion
	 * lists. The DTO types both `list<int>`, so every entry is cast: a digit
	 * string is storable today and would fail validation.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const INT_LIST_FIELDS = array(
		'excludediabvendors'    => 'excludedIabVendors',
		'excludedgooglevendors' => 'excludedGoogleVendors',
	);

	/**
	 * Option suffix => the DTO field it travels as, for the publisher's own vendor
	 * list.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const VENDOR_LIST_FIELDS = array( 'customsvendor' => 'customVendors' );

	/**
	 * Posted key (also the option suffix) => the signal it sets in the DTO.
	 *
	 * The seven travel together under `googleConsentMode.defaults`, so they form
	 * one unit as far as the delta is concerned.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const CONSENT_SIGNALS = array(
		'googleAdStorage'              => 'adStorage',
		'googleAnalyticsStorage'       => 'analyticsStorage',
		'googlePersonalizationStorage' => 'personalizationStorage',
		'googleFunctionalityStorage'   => 'functionalityStorage',
		'googleSecurityStorage'        => 'securityStorage',
		'googleAdPersonalization'      => 'adPersonalization',
		'googleAdUserData'             => 'adUserData',
	);

	/**
	 * Stored signal key => the signal it sets in the DTO.
	 *
	 * The region-override code the publisher pastes spells the signals the way
	 * Google does; the DTO spells them the way the rest of the payload does.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const CONSENT_STORED_SIGNALS = array(
		'ad_storage'              => 'adStorage',
		'analytics_storage'       => 'analyticsStorage',
		'personalization_storage' => 'personalizationStorage',
		'functionality_storage'   => 'functionalityStorage',
		'security_storage'        => 'securityStorage',
		'ad_personalization'      => 'adPersonalization',
		'ad_user_data'            => 'adUserData',
	);

	/**
	 * DTO fields validated as a URL.
	 *
	 * A value that is not an absolute URL is left out of the payload rather than
	 * sent and refused: the WordPress form accepts a relative path, the DTO does
	 * not, and a rejected payload now costs the publisher their whole save. An
	 * empty value is left out for the same reason it is ignored server-side —
	 * clearing the policy link or the logo of a live consent banner is not
	 * something a blank field should be able to do.
	 *
	 * @since 4.3.0
	 * @var   string[]
	 */
	const URL_FIELDS = array( 'policyUrl', 'publisherLogo' );

	/**
	 * DTO fields an empty value is never sent for.
	 *
	 * Both are posted by a `<select>` carrying an empty option, so the form can
	 * submit a blank on a field the publisher never opened — and both are validated
	 * against a referential no blank belongs to (`ValidCountryCode`,
	 * `ValidJurisdiction`). Sending one costs the publisher their whole save on a
	 * `422`, where leaving it out simply keeps what Actirise already holds.
	 *
	 * `customCss` is deliberately absent: it carries no validation and an empty
	 * value there is an instruction — the publisher clearing their stylesheet.
	 *
	 * @since 4.3.0
	 * @var   string[]
	 */
	const NON_EMPTY_FIELDS = array( 'countryCode', 'jurisdiction' );

	/**
	 * The longest `publisherName` the DTO accepts. A longer value is left out
	 * rather than truncated: a silently shortened publisher name on a consent
	 * banner is worse than an unsynced one.
	 *
	 * @since 4.3.0
	 * @var   int
	 */
	const PUBLISHER_NAME_MAX = 255;

	/**
	 * Posted key (also the option suffix) => the button it describes in the DTO.
	 *
	 * The three travel together under a single `colors` field, so they form one
	 * top-level unit as far as the delta is concerned.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const COLOR_BUTTONS = array(
		'acceptButtonStyle'     => 'accept',
		'declineButtonStyle'    => 'decline',
		'parametersButtonStyle' => 'parameters',
	);

	/**
	 * A colour the DTO takes verbatim: 3, 4, 6 or 8 hexadecimal digits.
	 *
	 * @since 4.3.0
	 * @var   string
	 */
	const COLOR_HEX = '/^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i';

	/**
	 * `rgb()` / `rgba()`, in the legacy comma syntax or the space one, each
	 * channel an integer or a percentage, with an optional alpha.
	 *
	 * @since 4.3.0
	 * @var   string
	 */
	const COLOR_RGB = '/^rgba?\(\s*([0-9.]+%?)\s*[,\s]\s*([0-9.]+%?)\s*[,\s]\s*([0-9.]+%?)(?:\s*[,\/]\s*([0-9.]+%?))?\s*\)$/i';

	/**
	 * The effective view key => the DTO field it travels as, for the values that
	 * need no reshaping.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const EFFECTIVE_SCALARS = array(
		'name'             => 'publisherName',
		'privacyPolicy'    => 'policyUrl',
		'headOffice'       => 'countryCode',
		'targetedAudience' => 'jurisdiction',
		'logo'             => 'publisherLogo',
		'customStyle'      => 'customCss',
	);

	/**
	 * The posted keys that belong to the contract.
	 *
	 * What it leaves out is the point: `enabled` decides whether the consent
	 * banner is injected at all, so it is written whatever the API answers. An
	 * Actirise outage must never stop a publisher from switching their CMP
	 * **off** — a site in breach would stay live until the API came back.
	 *
	 * @since 4.3.0
	 * @return string[]
	 */
	public static function contract_keys() {
		return array_merge(
			array_keys( self::POSTED_SUFFIXES ),
			array_keys( self::COLOR_BUTTONS ),
			array( 'consentV2', 'googleTagsStatus', 'googleSpecificEnabled', 'googleSpecificData' ),
			array_keys( self::CONSENT_SIGNALS )
		);
	}

	/**
	 * The complete payload describing the banner as it is actually served.
	 *
	 * Built from {@see \Actirise\Includes\Helpers::get_fastcmp_options()}, which is
	 * the same projection the emission uses — WordPress fallbacks included, so a
	 * publisher who never filled a field still seeds Actirise with the value their
	 * visitors see. Seeding the stored blank instead would leave Actirise
	 * describing a banner nobody is served, with nothing to reveal it.
	 *
	 * Used for the first publication only; every later save sends a delta.
	 *
	 * @since 4.3.0
	 * @return array<string, mixed>
	 */
	public static function effective() {
		$options   = Helpers::get_fastcmp_options( true );
		$effective = array();

		foreach ( self::EFFECTIVE_SCALARS as $key => $field ) {
			$value = self::as_string( isset( $options[ $key ] ) ? $options[ $key ] : '' );

			if ( ! self::is_sendable_field( $field, $value ) ) {
				continue;
			}

			$effective[ $field ] = $value;
		}

		$effective['excludedIabVendors']    = self::vendor_ids( isset( $options['excludedIabVendors'] ) ? $options['excludedIabVendors'] : array() );
		$effective['excludedGoogleVendors'] = self::vendor_ids( isset( $options['excludedGoogleVendors'] ) ? $options['excludedGoogleVendors'] : array() );
		$effective['customVendors']         = self::custom_vendors( isset( $options['customsVendor'] ) ? $options['customsVendor'] : array() );

		$resolved = array(
			'consentV2'        => ! empty( $options['consentV2'] ),
			'googleTagsStatus' => ! empty( $options['googleTagsStatus'] ),
		);

		foreach ( self::CONSENT_SIGNALS as $key => $signal ) {
			$resolved[ $key ] = ! empty( $options[ $key ] );
		}

		$effective['googleConsentMode'] = self::consent_block(
			$resolved,
			! empty( $options['googleSpecificEnabled'] ),
			self::as_string( isset( $options['googleSpecificData'] ) ? $options['googleSpecificData'] : '' )
		);

		$styles = array();

		foreach ( self::COLOR_BUTTONS as $key => $button ) {
			$styles[ $button ] = self::button_colors(
				$button,
				self::button_style( isset( $options[ $key ] ) ? $options[ $key ] : array() )
			);
		}

		$effective['colors'] = $styles;

		return $effective;
	}

	/**
	 * DTO field => the option suffix it is written back to.
	 *
	 * The inverse of {@see self::EFFECTIVE_SCALARS}, spelled out rather than
	 * flipped at runtime so the write side is readable on its own.
	 *
	 * @since 4.3.0
	 * @var   array<string, string>
	 */
	const FIELD_SUFFIXES = array(
		'publisherName' => 'name',
		'policyUrl'     => 'privacypolicy',
		'countryCode'   => 'headoffice',
		'jurisdiction'  => 'targetedaudience',
		'publisherLogo' => 'logo',
		'customCss'     => 'customStyle',
	);

	/**
	 * Write an incoming configuration into the option store.
	 *
	 * The single writer the push handler, the reconciliation GET and the seed all
	 * converge on, so whichever channel delivered a change the resulting options
	 * are identical.
	 *
	 * Only the eleven contract fields are written. `fastcmp-enabled` above all is
	 * never touched: it decides whether the consent banner is injected at all, and
	 * Actirise must not be able to switch a live banner off. `fastcmp-uuid` is the
	 * domain uid the tag identifies itself to FastCMP with, `fastcmp-stub-light`
	 * and `fastcmp-vendors` are runtime assets,
	 * and `fastcmp-lastupdate` belongs to the stub-light cron.
	 *
	 * A field absent from the payload is left alone — absent means "not supplied
	 * by this payload", which is not the same as an explicit `null`.
	 *
	 * The two URL fields are held to the same rule on the way in as on the way
	 * out. Both reach the page — `policyUrl` as the banner's privacy link,
	 * `publisherLogo` as an `img` src in the inline configuration script — so a
	 * `javascript:` or `data:` scheme stored here would be a click away from
	 * running, and an empty one would blank a live banner. Neither is stored;
	 * the value the site already serves is kept instead, which costs the
	 * publisher nothing, since a payload carrying a broken URL carries no usable
	 * one either.
	 *
	 * This is a guard on what is *stored*, not the escaping of what is emitted:
	 * `FILTER_VALIDATE_URL` accepts a quote inside an otherwise well-formed URL,
	 * so the inline script escapes every value it writes regardless. Two
	 * independent controls, neither standing in for the other.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $config The configuration as the API projects it.
	 * @return void
	 */
	public static function apply( array $config ) {
		foreach ( self::FIELD_SUFFIXES as $field => $suffix ) {
			if ( ! array_key_exists( $field, $config ) || null === $config[ $field ] ) {
				continue;
			}

			$value = self::as_string( $config[ $field ] );

			// Reuses the constraint the outbound payload declares, so the two
			// directions cannot drift into disagreeing about what a URL is.
			if ( in_array( $field, self::URL_FIELDS, true ) && ! self::is_sendable_field( $field, $value ) ) {
				continue;
			}

			Options::update( 'fastcmp-' . $suffix, $value );
		}

		foreach ( self::INT_LIST_FIELDS as $suffix => $field ) {
			if ( array_key_exists( $field, $config ) && null !== $config[ $field ] ) {
				Options::update( 'fastcmp-' . $suffix, self::vendor_ids( $config[ $field ] ) );
			}
		}

		if ( array_key_exists( 'customVendors', $config ) && null !== $config['customVendors'] ) {
			Options::update( 'fastcmp-customsvendor', self::stored_vendors( $config['customVendors'] ) );
		}

		if ( isset( $config['googleConsentMode'] ) && is_array( $config['googleConsentMode'] ) ) {
			self::apply_consent( $config['googleConsentMode'] );
		}

		if ( isset( $config['colors'] ) && is_array( $config['colors'] ) ) {
			self::apply_colors( $config['colors'] );
		}
	}

	/**
	 * Write the Google Consent Mode block back into its eleven options.
	 *
	 * Region overrides are re-serialised from the typed entries rather than stored
	 * as any string the API happened to send: the code is injected **raw** into the
	 * inline script that emits `FAST_CMP_OPTIONS`, and the validator it passes
	 * through ignores keys it does not know. Rebuilding it from the decoded values
	 * is what keeps that injection point closed.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $consent The `googleConsentMode` block.
	 * @return void
	 */
	private static function apply_consent( array $consent ) {
		if ( array_key_exists( 'enabled', $consent ) && null !== $consent['enabled'] ) {
			Options::update( 'fastcmp-consentV2', (bool) $consent['enabled'] );
		}

		$defaults = isset( $consent['defaults'] ) && is_array( $consent['defaults'] ) ? $consent['defaults'] : null;

		Options::update( 'fastcmp-googleTagsStatus', null !== $defaults );

		if ( null !== $defaults ) {
			foreach ( self::CONSENT_SIGNALS as $key => $signal ) {
				Options::update( 'fastcmp-' . $key, ! empty( $defaults[ $signal ] ) );
			}
		}

		$regions = isset( $consent['regions'] ) && is_array( $consent['regions'] ) ? $consent['regions'] : array();
		$code    = self::stored_consent_code( $regions );

		Options::update( 'fastcmp-googleSpecificEnabled', '' !== $code );
		Options::update( 'fastcmp-googleSpecificData', $code );
	}

	/**
	 * Re-serialise region overrides into the code the emission injects.
	 *
	 * Strict JSON, which is valid JavaScript and which the existing validator
	 * accepts unchanged — it only quotes keys that are not quoted already.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $regions Region overrides as the API projects them.
	 * @return string
	 */
	private static function stored_consent_code( array $regions ) {
		$entries = array();

		foreach ( $regions as $region ) {
			$region = (array) $region;
			$codes  = array();

			foreach ( (array) ( isset( $region['regions'] ) ? $region['regions'] : array() ) as $code ) {
				if ( is_string( $code ) && '' !== $code ) {
					$codes[] = $code;
				}
			}

			if ( array() === $codes ) {
				continue;
			}

			$entry = array( 'region' => $codes );

			foreach ( self::CONSENT_STORED_SIGNALS as $key => $signal ) {
				$entry[ $key ] = ! empty( $region[ $signal ] ) ? 'granted' : 'denied';
			}

			$encoded = wp_json_encode( $entry );

			if ( is_string( $encoded ) ) {
				$entries[] = $encoded;
			}
		}

		return implode( ',', $entries );
	}

	/**
	 * Write the three button styles back into their options.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $colors The `colors` block.
	 * @return void
	 */
	private static function apply_colors( array $colors ) {
		foreach ( self::COLOR_BUTTONS as $suffix => $button ) {
			if ( ! isset( $colors[ $button ] ) ) {
				continue;
			}

			$incoming = (array) $colors[ $button ];
			$stored   = self::button_style( Options::get( 'fastcmp-' . $suffix, array() ) );

			$style = array(
				'bg'   => self::as_string( isset( $incoming['background'] ) ? $incoming['background'] : $stored['bg'] ),
				'font' => self::as_string( isset( $incoming['font'] ) ? $incoming['font'] : $stored['font'] ),
			);

			// Accept has no border of its own — Krull derives it from the background —
			// and the Decline border the plugin stores has never been emitted, so
			// neither is ever rewritten from a payload.
			if ( 'parameters' === $button ) {
				$style['border'] = self::as_string( isset( $incoming['border'] ) ? $incoming['border'] : $stored['border'] );
			} elseif ( '' !== $stored['border'] ) {
				$style['border'] = $stored['border'];
			}

			Options::update( 'fastcmp-' . $suffix, $style );
		}
	}

	/**
	 * Rebuild the publisher's vendor list as the objects the option store holds.
	 *
	 * `Script.php` dereferences them with `->name` and `->id`, so an associative
	 * array here would break the emission on the next render.
	 *
	 * @since 4.3.0
	 * @param mixed $vendors Vendors as the API projects them.
	 * @return array<int, object>
	 */
	private static function stored_vendors( $vendors ) {
		$stored = array();

		foreach ( self::custom_vendors( $vendors ) as $vendor ) {
			$stored[] = (object) $vendor;
		}

		return $stored;
	}

	/**
	 * Build the payload for a save: only the submitted fields whose value differs
	 * from what the option store holds right now.
	 *
	 * Called before the local write, so the store still carries the pre-submission
	 * values — the basis that makes an untouched field never travel.
	 *
	 * @since 4.3.0
	 * @param array<mixed>|object $submitted The keys the admin form posted.
	 * @return array<string, mixed> The DTO subset to send, empty when nothing changed.
	 */
	public static function delta( $submitted ) {
		$delta = array();

		foreach ( (array) $submitted as $posted_key => $value ) {
			if ( ! isset( self::POSTED_SUFFIXES[ $posted_key ] ) ) {
				continue;
			}

			$suffix = self::POSTED_SUFFIXES[ $posted_key ];
			$field  = self::field_for( $suffix );

			if ( null === $field ) {
				continue;
			}

			$submitted_value = self::coerce( $suffix, $value );

			if ( ! self::is_sendable_field( $field, $submitted_value ) ) {
				continue;
			}

			// Compared after coercion, so a stored digit-string vendor id and the
			// integer the form posts are not mistaken for an edit.
			if ( $submitted_value === self::coerce( $suffix, Options::get( 'fastcmp-' . $suffix, '' ) ) ) {
				continue;
			}

			$delta[ $field ] = $submitted_value;
		}

		$colors = self::colors_delta( (array) $submitted );

		if ( null !== $colors ) {
			$delta['colors'] = $colors;
		}

		$consent = self::consent_delta( (array) $submitted );

		if ( null !== $consent ) {
			$delta['googleConsentMode'] = $consent;
		}

		return $delta;
	}

	/**
	 * The `googleConsentMode` block when at least one of its inputs changed, null
	 * otherwise.
	 *
	 * `enabled` carries the plugin's consent-mode switch; the seven defaults are
	 * emitted together, and only while the Google-tags switch is on — that is
	 * exactly when the plugin emits a `default` block of its own.
	 *
	 * Known contract gap: turning the Google-tags switch **off** cannot ask Krull
	 * to drop the block it already stores, because only `enabled: false` does
	 * that. WordPress has two switches where the DTO has one.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $submitted The keys the admin form posted.
	 * @return array<string, mixed>|null
	 */
	private static function consent_delta( array $submitted ) {
		$keys = array_merge(
			array( 'consentV2', 'googleTagsStatus' ),
			array_keys( self::CONSENT_SIGNALS )
		);

		$changed  = false;
		$resolved = array();

		foreach ( $keys as $key ) {
			$stored = (bool) Options::get( 'fastcmp-' . $key, false );

			if ( ! array_key_exists( $key, $submitted ) ) {
				$resolved[ $key ] = $stored;

				continue;
			}

			$resolved[ $key ] = (bool) $submitted[ $key ];

			if ( $resolved[ $key ] !== $stored ) {
				$changed = true;
			}
		}

		$specific_enabled = self::resolved_bool( $submitted, 'googleSpecificEnabled' );
		$specific_code    = self::resolved_string( $submitted, 'googleSpecificData' );

		if ( $specific_enabled['changed'] || $specific_code['changed'] ) {
			$changed = true;
		}

		if ( ! $changed ) {
			return null;
		}

		return self::consent_block( $resolved, $specific_enabled['value'], $specific_code['value'] );
	}

	/**
	 * Assemble the `googleConsentMode` block from already-resolved inputs, shared
	 * by the seed and the delta so the two cannot describe consent differently.
	 *
	 * @since 4.3.0
	 * @param array<string, bool> $resolved         consentV2, googleTagsStatus and the seven signals.
	 * @param bool                $specific_enabled Whether region overrides are on.
	 * @param string              $specific_code    The region-override code.
	 * @return array<string, mixed>
	 */
	private static function consent_block( array $resolved, $specific_enabled, $specific_code ) {
		$block = array( 'enabled' => $resolved['consentV2'] );

		if ( $resolved['googleTagsStatus'] ) {
			$defaults = array();

			foreach ( self::CONSENT_SIGNALS as $key => $signal ) {
				$defaults[ $signal ] = $resolved[ $key ];
			}

			$block['defaults'] = $defaults;
		}

		if ( $specific_enabled ) {
			$regions = self::consent_regions( $specific_code );

			// An unparseable code yields nothing rather than an empty list: the DTO
			// would take `[]` as "no overrides" and drop the ones Actirise holds,
			// where the emission simply ignores a code it cannot read.
			if ( array() !== $regions ) {
				$block['regions'] = $regions;
			}
		}

		return $block;
	}

	/**
	 * The region overrides in the DTO's vocabulary, decoded through the very
	 * normaliser the emission validates with.
	 *
	 * @since 4.3.0
	 * @param string $code The code the publisher pasted.
	 * @return array<int, array<string, mixed>>
	 */
	private static function consent_regions( $code ) {
		$regions = array();

		foreach ( Helpers::cmp_consent_decode( $code ) as $entry ) {
			$codes = array();

			foreach ( (array) ( isset( $entry['region'] ) ? $entry['region'] : array() ) as $region ) {
				if ( is_string( $region ) && '' !== $region ) {
					$codes[] = $region;
				}
			}

			// The DTO requires at least one region code on every entry.
			if ( array() === $codes ) {
				continue;
			}

			$override = array( 'regions' => $codes );

			foreach ( self::CONSENT_STORED_SIGNALS as $key => $signal ) {
				$override[ $signal ] = isset( $entry[ $key ] ) && 'granted' === $entry[ $key ];
			}

			$regions[] = $override;
		}

		return $regions;
	}

	/**
	 * Resolve a boolean input to the submitted value or the stored one, reporting
	 * whether the submission changed it.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $submitted The keys the admin form posted.
	 * @param string       $key       Posted key, also the option suffix.
	 * @return array{value: bool, changed: bool}
	 */
	private static function resolved_bool( array $submitted, $key ) {
		$stored = (bool) Options::get( 'fastcmp-' . $key, false );

		if ( ! array_key_exists( $key, $submitted ) ) {
			return array(
				'value'   => $stored,
				'changed' => false,
			);
		}

		$value = (bool) $submitted[ $key ];

		return array(
			'value'   => $value,
			'changed' => $value !== $stored,
		);
	}

	/**
	 * Resolve a string input to the submitted value or the stored one, reporting
	 * whether the submission changed it.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $submitted The keys the admin form posted.
	 * @param string       $key       Posted key, also the option suffix.
	 * @return array{value: string, changed: bool}
	 */
	private static function resolved_string( array $submitted, $key ) {
		$stored = self::as_string( Options::get( 'fastcmp-' . $key, '' ) );

		if ( ! array_key_exists( $key, $submitted ) ) {
			return array(
				'value'   => $stored,
				'changed' => false,
			);
		}

		$value = self::as_string( $submitted[ $key ] );

		return array(
			'value'   => $value,
			'changed' => $value !== $stored,
		);
	}

	/**
	 * The `colors` block when at least one button changed, null otherwise.
	 *
	 * All three buttons are always emitted together, the untouched ones read back
	 * from the option store: Krull restricts validation to the submitted
	 * *top-level* fields and no deeper, so the leaves of a partially-sent block
	 * are seeded from its own storage and validated regardless — and a stored
	 * value it refuses would then reject a save that never touched it.
	 *
	 * @since 4.3.0
	 * @param array<mixed> $submitted The keys the admin form posted.
	 * @return array<string, array<string, string>>|null
	 */
	private static function colors_delta( array $submitted ) {
		$changed = false;
		$block   = array();

		foreach ( self::COLOR_BUTTONS as $posted_key => $button ) {
			$stored = self::button_style( Options::get( 'fastcmp-' . $posted_key, array() ) );

			if ( ! array_key_exists( $posted_key, $submitted ) ) {
				$block[ $button ] = self::button_colors( $button, $stored );

				continue;
			}

			$posted = self::button_style( $submitted[ $posted_key ] );

			if ( $posted !== $stored ) {
				$changed = true;
			}

			$block[ $button ] = self::button_colors( $button, $posted );
		}

		return $changed ? $block : null;
	}

	/**
	 * Normalise a stored or posted button style to the three keys the plugin
	 * edits, so a comparison never trips on a missing key or on the object the
	 * admin form posts.
	 *
	 * @since 4.3.0
	 * @param mixed $style Raw button style.
	 * @return array<string, string>
	 */
	private static function button_style( $style ) {
		$style = (array) $style;

		return array(
			'bg'     => self::as_string( isset( $style['bg'] ) ? $style['bg'] : '' ),
			'font'   => self::as_string( isset( $style['font'] ) ? $style['font'] : '' ),
			'border' => self::as_string( isset( $style['border'] ) ? $style['border'] : '' ),
		);
	}

	/**
	 * Project one normalised button style into the DTO's vocabulary.
	 *
	 * `border` is carried for the Parameters button only. Accept derives its
	 * border from its background, and the Decline border the plugin stores has
	 * never been emitted — syncing it would give it an effect it never had.
	 *
	 * @since 4.3.0
	 * @param string                $button One of accept, decline, parameters.
	 * @param array<string, string> $style  Normalised button style.
	 * @return array<string, string>
	 */
	private static function button_colors( $button, array $style ) {
		$colors = array(
			'background' => self::css_color( $style['bg'] ),
			'font'       => self::css_color( $style['font'] ),
		);

		if ( 'parameters' === $button ) {
			$colors['border'] = self::css_color( $style['border'] );
		}

		return $colors;
	}

	/**
	 * Express a stored colour in the narrow grammar the DTO accepts.
	 *
	 * The plugin's colour fields are free text — the admin form pairs a picker
	 * with a plain input — and everything they hold is emitted into the banner's
	 * stylesheet, where the whole CSS colour grammar is legal. The DTO takes a
	 * hexadecimal colour or exactly `transparent`, and nothing else, so a value
	 * as ordinary as `rgb(219, 44, 52)` refuses the publisher's save with a `422`
	 * on a field they may not even have touched — the block travels whole.
	 *
	 * Converting is safe where it is exact: the same colour, spelled the way the
	 * contract spells it. Padding is dropped for the same reason — a stored
	 * `" #929292 "` is the measured cause of a `422` in Krull's own logs.
	 *
	 * Anything else is returned untouched, and the API refuses it. That is the
	 * deliberate half: a value this cannot represent — `hsl()`, a colour keyword,
	 * a CSS variable — would have to be replaced by a *different* colour to pass,
	 * and the API's answer is adopted locally, so the banner would silently
	 * change appearance. A refused save the publisher can see beats a banner
	 * repainted behind their back.
	 *
	 * @since 4.3.0
	 * @param string $value The stored or posted colour.
	 * @return string
	 */
	private static function css_color( $value ) {
		$value = trim( self::as_string( $value ) );

		if ( 'transparent' === strtolower( $value ) ) {
			return 'transparent';
		}

		if ( 1 === preg_match( self::COLOR_HEX, $value ) ) {
			return $value;
		}

		$channels = array();

		if ( 1 !== preg_match( self::COLOR_RGB, $value, $channels ) ) {
			return $value;
		}

		$hex = sprintf(
			'#%02x%02x%02x',
			self::color_byte( $channels[1] ),
			self::color_byte( $channels[2] ),
			self::color_byte( $channels[3] )
		);

		// An alpha the value did not carry leaves the trailing group out of the
		// match entirely, rather than present and empty.
		if ( ! isset( $channels[4] ) ) {
			return $hex;
		}

		$alpha = self::alpha_byte( $channels[4] );

		return ( 255 === $alpha ) ? $hex : $hex . sprintf( '%02x', $alpha );
	}

	/**
	 * One `rgb()` channel as a byte — an integer, or a percentage of 255.
	 *
	 * @since 4.3.0
	 * @param string $channel The channel as written.
	 * @return int
	 */
	private static function color_byte( $channel ) {
		$percent = ( '%' === substr( $channel, -1 ) );
		$number  = (float) ( $percent ? substr( $channel, 0, -1 ) : $channel );

		return self::clamp_byte( $percent ? ( $number * 255 / 100 ) : $number );
	}

	/**
	 * An `rgba()` alpha as a byte — a fraction of 1, or a percentage.
	 *
	 * @since 4.3.0
	 * @param string $alpha The alpha as written.
	 * @return int
	 */
	private static function alpha_byte( $alpha ) {
		$percent = ( '%' === substr( $alpha, -1 ) );
		$number  = (float) ( $percent ? substr( $alpha, 0, -1 ) : $alpha );

		return self::clamp_byte( ( $percent ? ( $number / 100 ) : $number ) * 255 );
	}

	/**
	 * Round a computed colour component into `0..255`.
	 *
	 * @since 4.3.0
	 * @param float $number The component.
	 * @return int
	 */
	private static function clamp_byte( $number ) {
		return (int) max( 0, min( 255, round( $number ) ) );
	}

	/**
	 * The DTO field an option suffix travels as, or null when the suffix is not
	 * part of the contract.
	 *
	 * @since 4.3.0
	 * @param string $suffix Option suffix, without the `fastcmp-` prefix.
	 * @return string|null
	 */
	private static function field_for( $suffix ) {
		if ( isset( self::SCALAR_FIELDS[ $suffix ] ) ) {
			return self::SCALAR_FIELDS[ $suffix ];
		}

		if ( isset( self::INT_LIST_FIELDS[ $suffix ] ) ) {
			return self::INT_LIST_FIELDS[ $suffix ];
		}

		if ( isset( self::VENDOR_LIST_FIELDS[ $suffix ] ) ) {
			return self::VENDOR_LIST_FIELDS[ $suffix ];
		}

		return null;
	}

	/**
	 * Whether a coerced value may travel at all, by the constraint the DTO
	 * declares on that field.
	 *
	 * @since 4.3.0
	 * @param string $field The DTO field.
	 * @param mixed  $value The coerced value.
	 * @return bool
	 */
	private static function is_sendable_field( $field, $value ) {
		if ( in_array( $field, self::URL_FIELDS, true ) ) {
			return is_string( $value ) && false !== filter_var( $value, FILTER_VALIDATE_URL );
		}

		if ( 'publisherName' === $field ) {
			return is_string( $value ) && '' !== $value && strlen( $value ) <= self::PUBLISHER_NAME_MAX;
		}

		if ( in_array( $field, self::NON_EMPTY_FIELDS, true ) ) {
			return is_string( $value ) && '' !== $value;
		}

		return true;
	}

	/**
	 * Bring a stored or submitted value to the shape and type the DTO declares.
	 *
	 * @since 4.3.0
	 * @param string $suffix Option suffix, without the `fastcmp-` prefix.
	 * @param mixed  $value  The raw value.
	 * @return mixed
	 */
	private static function coerce( $suffix, $value ) {
		if ( isset( self::INT_LIST_FIELDS[ $suffix ] ) ) {
			return self::vendor_ids( $value );
		}

		if ( isset( self::VENDOR_LIST_FIELDS[ $suffix ] ) ) {
			return self::custom_vendors( $value );
		}

		return $value;
	}

	/**
	 * The vendor-exclusion list as the DTO types it: `list<int>`.
	 *
	 * A non-numeric entry is dropped rather than cast, which would send a vendor
	 * id of `0` — a value that exists in no referential and that the publisher
	 * never chose.
	 *
	 * @since 4.3.0
	 * @param mixed $value Raw stored or submitted list.
	 * @return int[]
	 */
	private static function vendor_ids( $value ) {
		$ids = array();

		foreach ( (array) $value as $id ) {
			if ( is_numeric( $id ) ) {
				$ids[] = (int) $id;
			}
		}

		return $ids;
	}

	/**
	 * A mixed value as the string the DTO expects, or an empty string when it is
	 * not representable as one.
	 *
	 * @since 4.3.0
	 * @param mixed $value Raw value.
	 * @return string
	 */
	private static function as_string( $value ) {
		return is_scalar( $value ) ? (string) $value : '';
	}

	/**
	 * Project the publisher's own vendor list onto exactly `id` and `name`.
	 *
	 * The DTO refuses extra fields, so the admin form's `checked` flag cannot
	 * travel, and it types `id` as a string where the form may post a number. An
	 * entry missing either value is dropped rather than sent blank, which the DTO
	 * would refuse just the same. Entries arrive as stdClass — that is how the
	 * option store holds them, and how `Script.php` dereferences them.
	 *
	 * Name and ID are free text the save never refuses, so both are cleaned here
	 * (see {@see self::vendor_text()}), on every path to and from Actirise. An ID
	 * that collides once cleaned keeps its first vendor.
	 *
	 * @since 4.3.0
	 * @param mixed $vendors Raw vendor list.
	 * @return array<int, array<string, string>>
	 */
	private static function custom_vendors( $vendors ) {
		$projected = array();
		$seen_ids  = array();

		foreach ( (array) $vendors as $vendor ) {
			$vendor = (array) $vendor;

			$id   = self::vendor_text( isset( $vendor['id'] ) ? $vendor['id'] : '' );
			$name = self::vendor_text( isset( $vendor['name'] ) ? $vendor['name'] : '' );

			if ( '' === $id || '' === $name || isset( $seen_ids[ $id ] ) ) {
				continue;
			}

			$seen_ids[ $id ] = true;

			$projected[] = array(
				'id'   => $id,
				'name' => $name,
			);
		}

		return $projected;
	}

	/**
	 * A custom vendor's name or ID as plain text, safe for any consumer of the
	 * Actirise configuration: tags are stripped (script and style content
	 * included), then control characters and the characters that open markup or
	 * break out of a quoted string (`<`, `>`, `"`, `\`, backtick). Ordinary
	 * names keep `&`, `'` and accents.
	 *
	 * Not `sanitize_text_field()`, which HTML-encodes a lone `<` into an entity
	 * that would then travel as text.
	 *
	 * @since 4.3.2
	 * @param mixed $value Raw name or ID.
	 * @return string The cleaned text, or an empty string when nothing is left.
	 */
	private static function vendor_text( $value ) {
		$text = preg_replace( '/[\x00-\x1F\x7F<>"`\\\\]/u', '', wp_strip_all_tags( self::as_string( $value ) ) );

		// `null` on invalid UTF-8: dropped, as the JSON encoding would fail anyway
		if ( ! is_string( $text ) ) {
			return '';
		}

		return trim( $text );
	}
}