<?php
/**
 * Storefront integration.
 *
 * - Enqueues an un-delayable vanilla bootstrap that binds the trigger and
 *   lazy-loads the heavy React widget on first intent.
 * - Injects window.AISTHETIX_CONFIG with the PUBLISHABLE key only (never the secret).
 * - Exposes the per-variation image map for variable products.
 * - Renders the trigger button (auto-hook / shortcode / block / Elementor all
 *   funnel through {@see render_button()}).
 * - Registers optimizer exclusions so the bootstrap is never delayed/stripped.
 *
 * @package Aisthetix\TryOn
 */

namespace Aisthetix\TryOn;

defined( 'ABSPATH' ) || exit;

/**
 * Storefront controller.
 */
class Storefront {

	/**
	 * Script handle for the bootstrap loader.
	 *
	 * @var string
	 */
	const BOOTSTRAP_HANDLE = 'aisthetix-tryon-bootstrap';

	/**
	 * First-party durable visitor cookie name (the WooCommerce analog of Shopify's
	 * clientId). Set server-side on product pages; sent to the brain as visitorKey,
	 * the PRIMARY attribution key (survives Safari ITP far better than localStorage).
	 *
	 * @var string
	 */
	const VISITOR_COOKIE = 'aisthetix_vid';

	/**
	 * Visitor cookie lifetime: ~13 months (matches GA4 default; long enough for the
	 * 30-day attribution window with margin, short enough to be reasonable).
	 *
	 * @var int
	 */
	const VISITOR_COOKIE_TTL = 34214400; // 396 days in seconds.

	/**
	 * Status component.
	 *
	 * @var Status
	 */
	private $status;

	/**
	 * Whether the config object + assets have already been printed on this request.
	 *
	 * @var bool
	 */
	private $printed = false;

	/** @var int Number of placement surfaces rendered in this response. */
	private $render_index = 0;

	/**
	 * The visitor key resolved for this request (from the cookie, or freshly minted).
	 * Cached so build_config() and the Set-Cookie agree within one request.
	 *
	 * @var string|null
	 */
	private $visitor_key = null;

	/**
	 * Whether the durable visitor cookie was actually persisted (Set-Cookie emitted,
	 * or already present in $_COOKIE) for this request. When false, a freshly minted
	 * key is ephemeral — it will NOT survive to the later server-side order event — so
	 * build_config() must not advertise it as the visitorKey (see config_visitor_key()).
	 *
	 * @var bool
	 */
	private $cookie_persisted = false;

	/**
	 * Constructor.
	 *
	 * @param Status $status Status component.
	 */
	public function __construct( Status $status ) {
		$this->status = $status;
	}

	/**
	 * Register hooks.
	 *
	 * @return void
	 */
	public function init() {
		add_action( 'wp_enqueue_scripts', array( $this, 'register_assets' ) );

		// HARDENING (DESIGN decision #19/#20): enqueue the un-delayable bootstrap +
		// inline config UNCONDITIONALLY on eligible product pages in
		// wp_enqueue_scripts, independent of when (or whether) the trigger markup is
		// rendered. Page builders like Elementor (the 3sides.it stack) render the
		// product template from their own hooks/templates, so relying on the
		// render-path to enqueue (the old behaviour) could miss the loader entirely.
		// We register at the default priority and enqueue late so is_product() and
		// the global $product are resolved. The render path only prints trigger markup.
		add_action( 'wp_enqueue_scripts', array( $this, 'maybe_enqueue_on_product' ), 20 );

		// Set the durable first-party visitor cookie as early as possible (before any
		// output) on product pages, so attribution events carry a stable visitorKey.
		// We hook several increasingly-late points and let the method no-op once the
		// cookie is persisted: 'send_headers' / 'init' fire before most theme output
		// (shrinking the headers_sent() race window where the cookie can't be set),
		// and 'template_redirect' is the backstop once the main query is resolved and
		// is_product() is reliable. The earliest hook at which is_product() is true and
		// headers are still open wins; the rest no-op.
		add_action( 'send_headers', array( $this, 'maybe_set_visitor_cookie' ) );
		add_action( 'init', array( $this, 'maybe_set_visitor_cookie' ) );
		add_action( 'template_redirect', array( $this, 'maybe_set_visitor_cookie' ) );

		// Auto placement: render after the Add to cart button on simple/variable products.
		add_action( 'woocommerce_after_add_to_cart_button', array( $this, 'maybe_auto_render' ) );

		// Shortcode (universal fallback).
		add_shortcode( 'aisthetix_tryon', array( $this, 'shortcode' ) );

		// Optimizer compatibility exclusions.
		$this->register_optimizer_exclusions();
	}

	/**
	 * Read the well-formed first-party `aisthetix_vid` cookie value, or '' if absent
	 * or malformed.
	 *
	 * The value is a random 32-hex token. We deliberately do not trust an arbitrary
	 * cookie value verbatim — only accept the expected shape — so a hostile cookie
	 * can't inject markup or oversized keys downstream.
	 *
	 * @return string The validated cookie value, or '' when none.
	 */
	private function read_visitor_cookie() {
		if ( ! isset( $_COOKIE[ self::VISITOR_COOKIE ] ) ) {
			return '';
		}
		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- validated by the strict regex below.
		$candidate = wp_unslash( $_COOKIE[ self::VISITOR_COOKIE ] );
		if ( is_string( $candidate ) && preg_match( '/^[a-f0-9]{32}$/', $candidate ) ) {
			return $candidate;
		}
		return '';
	}

	/**
	 * Resolve the durable visitor key for this request: read the first-party
	 * `aisthetix_vid` cookie if present and well-formed, otherwise mint a fresh one.
	 *
	 * Used by the cookie-setting path (the minted value WILL be persisted there). For
	 * the client config use {@see config_visitor_key()} instead, which never advertises
	 * an ephemeral (un-persistable) key.
	 *
	 * @return string
	 */
	public function get_visitor_key() {
		if ( null !== $this->visitor_key ) {
			return $this->visitor_key;
		}

		$existing = $this->read_visitor_cookie();

		if ( '' === $existing ) {
			$existing = md5( wp_generate_password( 32, false, false ) . microtime() . wp_rand() );
		}

		$this->visitor_key = $existing;
		return $this->visitor_key;
	}

	/**
	 * Resolve the visitorKey to advertise in window.AISTHETIX_CONFIG.
	 *
	 * CONSISTENCY GUARANTEE: the value placed in the client config must equal the value
	 * the later server-side order event will read from $_COOKIE — otherwise the client
	 * try-on/view events and the server checkout event are filed under two different
	 * visitor keys and never correlate.
	 *
	 * - If the cookie was (or could be) persisted this request, the resolved key is
	 *   durable → use it.
	 * - If the cookie could NOT be set (headers already sent and no prior cookie),
	 *   minting a brand-new key here would be ephemeral: it would live only in this
	 *   page's JS and never reach the order-event cookie read. So instead we fall back
	 *   to the existing (validated) cookie value, or null. null is honest — the brain
	 *   then attributes via customerId for logged-in shoppers and simply can't tie
	 *   anonymous events from this single un-cookied page view.
	 *
	 * @return string|null
	 */
	public function config_visitor_key() {
		// A real (persistable) cookie value already exists on the request.
		$existing = $this->read_visitor_cookie();
		if ( '' !== $existing ) {
			return $existing;
		}

		// No cookie yet. Only advertise a freshly minted key if it was actually
		// persisted (Set-Cookie emitted this request); otherwise it can't survive to
		// the order event, so report null rather than a value that won't agree.
		if ( $this->cookie_persisted ) {
			return $this->get_visitor_key();
		}

		return null;
	}

	/**
	 * Set (or refresh) the first-party visitor cookie on product pages, server-side.
	 *
	 * SameSite=Lax, ~13-month expiry, Secure when the site is HTTPS, HttpOnly=false
	 * because the widget's browser JS must read it to attach visitorKey to client
	 * events (it is a non-secret analytics id, not a credential). Runs on
	 * template_redirect (before output) so the Set-Cookie header is valid.
	 *
	 * @return void
	 */
	public function maybe_set_visitor_cookie() {
		// Idempotent: this runs on send_headers + init + template_redirect; the first
		// eligible invocation persists the cookie and the rest no-op.
		if ( $this->cookie_persisted ) {
			return;
		}
		if ( headers_sent() ) {
			return;
		}
		if ( ! Plugin::is_connected() ) {
			return;
		}
		if ( ! function_exists( 'is_product' ) || ! is_product() ) {
			return;
		}

		// Opt-in analytics: do NOT set the durable visitor cookie unless the merchant
		// has enabled anonymous analytics (default OFF). See Plugin::analytics_enabled().
		if ( ! Plugin::analytics_enabled() ) {
			return;
		}

		$value = $this->get_visitor_key();

		// Refresh the cookie each product-page view to keep the 13-month window
		// rolling for active shoppers.
		$args = array(
			'expires'  => time() + self::VISITOR_COOKIE_TTL,
			'path'     => defined( 'COOKIEPATH' ) && COOKIEPATH ? COOKIEPATH : '/',
			'domain'   => defined( 'COOKIE_DOMAIN' ) ? COOKIE_DOMAIN : '',
			'secure'   => is_ssl(),
			'httponly' => false,
			'samesite' => 'Lax',
		);

		if ( PHP_VERSION_ID >= 70300 ) {
			setcookie( self::VISITOR_COOKIE, $value, $args );
		} else {
			// Older PHP: smuggle SameSite via the path argument (a well-known shim).
			setcookie(
				self::VISITOR_COOKIE,
				$value,
				$args['expires'],
				$args['path'] . '; samesite=Lax',
				$args['domain'],
				$args['secure'],
				$args['httponly']
			);
		}

		// Make the just-set value readable within this same request (so the order
		// event and config_visitor_key() see the same value the browser will return).
		$_COOKIE[ self::VISITOR_COOKIE ] = $value;
		$this->cookie_persisted          = true;
	}

	/**
	 * Enqueue the bootstrap + inline config on eligible product pages, regardless of
	 * whether/when the trigger button is rendered. See init() for the rationale.
	 *
	 * @return void
	 */
	public function maybe_enqueue_on_product() {
		if ( ! $this->can_render_any() ) {
			return;
		}
		$this->ensure_assets( $this->resolve_product() );
	}

	/**
	 * Resolve the current product context.
	 *
	 * The global $product is frequently NOT set yet at wp_enqueue_scripts time (the
	 * loop has not run), and on block themes the enqueue pass can run before the
	 * product block renders. Fall back to the queried product so the injected config
	 * is always complete (publishableKey + productId + productImage), never empty.
	 *
	 * @return \WC_Product|null
	 */
	private function resolve_product() {
		global $product;
		if ( $product instanceof \WC_Product ) {
			return $product;
		}
		if ( function_exists( 'wc_get_product' ) ) {
			$queried = wc_get_product( get_queried_object_id() );
			if ( $queried instanceof \WC_Product ) {
				return $queried;
			}
		}
		return null;
	}

	/**
	 * Whether the try-on entry point is allowed to render on the current request.
	 *
	 * @return bool
	 */
	public function can_render() {
		if ( ! Plugin::is_connected() ) {
			return false;
		}
		// Only on single product pages where we have a product image to try on.
		if ( ! function_exists( 'is_product' ) || ! is_product() ) {
			return false;
		}
		// Cached status gate: active && withinQuota.
		$product = $this->resolve_product();
		return $product instanceof \WC_Product && $this->status->should_render( $this->product_context( $product ) );
	}

	/**
	 * Whether either independent PDP entry point can render.
	 *
	 * @return bool
	 */
	public function can_render_any() {
		if ( ! Plugin::is_connected() || ! function_exists( 'is_product' ) || ! is_product() ) {
			return false;
		}
		$product = $this->resolve_product();
		if ( ! $product instanceof \WC_Product || $product->is_type( 'grouped' ) ) {
			return false;
		}
		return $this->status->should_render( $this->product_context( $product ) ) || $this->can_render_size( $product );
	}

	/**
	 * Whether this product has a real, purchasable size recommendation path.
	 *
	 * @param \WC_Product|null $product Product context.
	 * @return bool
	 */
	public function can_render_size( $product = null ) {
		if ( ! Plugin::is_connected() ) {
			return false;
		}
		if ( null === $product ) {
			if ( ! function_exists( 'is_product' ) || ! is_product() ) {
				return false;
			}
			$product = $this->resolve_product();
		}
		if ( ! $product instanceof \WC_Product || $product->is_type( 'grouped' ) ) {
			return false;
		}
		return self::size_is_eligible(
			$this->status->get(),
			$this->product_context( $product ),
			$this->get_size_variants( $product )
		);
	}

	/**
	 * Pure size-entry gate shared by rendering and its regression test.
	 *
	 * @param array $status   Normalised storefront status.
	 * @param array $context  Product id and category slugs.
	 * @param array $variants Real WooCommerce size variations.
	 * @return bool
	 */
	public static function size_is_eligible( $status, $context, $variants ) {
		if ( empty( $status['active'] ) ) {
			return false;
		}
		$size = isset( $status['size'] ) && is_array( $status['size'] ) ? $status['size'] : array();
		if ( empty( $size['hasSizeGuide'] ) || ! is_array( $variants ) || empty( $variants ) ) {
			return false;
		}
		if ( ! Status::feature_enabled( isset( $size['targeting'] ) ? $size['targeting'] : null, $context ) ) {
			return false;
		}
		$guide = self::resolve_size_guide( $size, $context );
		if ( ! is_array( $guide ) || ! isset( $guide['labels'] ) || ! is_array( $guide['labels'] ) ) {
			return false;
		}
		$guide_labels = array();
		foreach ( $guide['labels'] as $label ) {
			$normalised = self::normalize_size_label( $label );
			if ( '' !== $normalised ) {
				$guide_labels[ $normalised ] = true;
			}
		}
		$one_size = array_fill_keys(
			array( 'onesize', 'os', 'tagliaunica', 'tallaunica', 'tailleunique', 'einheitsgrosse', 'tamanhounico', 'maatuniek', 'uniwersalny', 'unisize', 'freesize', 'unica', 'unico' ),
			true
		);
		$matched = array();
		foreach ( $variants as $variant ) {
			if ( empty( $variant['available'] ) || ! isset( $variant['size_label'] ) ) {
				continue;
			}
			$normalised = self::normalize_size_label( $variant['size_label'] );
			if ( '' !== $normalised && ! isset( $one_size[ $normalised ] ) && isset( $guide_labels[ $normalised ] ) ) {
				$matched[ $normalised ] = true;
			}
		}
		return count( $matched ) >= 2;
	}

	/**
	 * Canonical comparison key used only by the storefront eligibility gate.
	 *
	 * @param mixed $label Merchant-provided size label.
	 * @return string
	 */
	private static function normalize_size_label( $label ) {
		if ( ! is_string( $label ) ) {
			return '';
		}
		$label = strtr(
			trim( $label ),
			array(
				'À' => 'a', 'Á' => 'a', 'Â' => 'a', 'Ã' => 'a', 'Ä' => 'a', 'Å' => 'a',
				'à' => 'a', 'á' => 'a', 'â' => 'a', 'ã' => 'a', 'ä' => 'a', 'å' => 'a',
				'È' => 'e', 'É' => 'e', 'Ê' => 'e', 'Ë' => 'e', 'è' => 'e', 'é' => 'e', 'ê' => 'e', 'ë' => 'e',
				'Ì' => 'i', 'Í' => 'i', 'Î' => 'i', 'Ï' => 'i', 'ì' => 'i', 'í' => 'i', 'î' => 'i', 'ï' => 'i',
				'Ò' => 'o', 'Ó' => 'o', 'Ô' => 'o', 'Õ' => 'o', 'Ö' => 'o', 'ò' => 'o', 'ó' => 'o', 'ô' => 'o', 'õ' => 'o', 'ö' => 'o',
				'Ù' => 'u', 'Ú' => 'u', 'Û' => 'u', 'Ü' => 'u', 'ù' => 'u', 'ú' => 'u', 'û' => 'u', 'ü' => 'u',
				'ß' => 'ss', 'Ç' => 'c', 'ç' => 'c', 'Ñ' => 'n', 'ñ' => 'n',
			)
		);
		return preg_replace( '/[^a-z0-9]+/', '', strtolower( $label ) );
	}

	/**
	 * Describe which merchant guide route serves the product for analytics.
	 *
	 * @param array $status  Normalised storefront status.
	 * @param array $context Product id and category slugs.
	 * @return string collection, shop_default, or none.
	 */
	public static function size_guide_resolution( $status, $context ) {
		$size = isset( $status['size'] ) && is_array( $status['size'] ) ? $status['size'] : array();
		$guide = self::resolve_size_guide( $size, $context );
		if ( ! $guide ) { return 'none'; }
		$id = isset( $context['productId'] ) ? (string) $context['productId'] : '';
		if ( in_array( $id, isset( $guide['categories']['productIds'] ) ? $guide['categories']['productIds'] : array(), true ) ) { return 'product_id'; }
		return empty( $guide['categories']['categories'] ) ? 'shop_default' : 'collection';
	}

	/** Product > category > fallback; first guide in server order wins ties. */
	private static function resolve_size_guide( $size, $context ) {
		$guides = isset( $size['guides'] ) && is_array( $size['guides'] ) ? $size['guides'] : array();
		$id = isset( $context['productId'] ) ? (string) $context['productId'] : '';
		$categories = isset( $context['categories'] ) && is_array( $context['categories'] ) ? $context['categories'] : array();
		$fallback = null;
		$category = null;
		foreach ( $guides as $guide ) {
			if ( ! is_array( $guide ) ) { continue; }
			$c = isset( $guide['categories'] ) ? $guide['categories'] : array();
			if ( ! is_array( $c ) ) { continue; }
			$ids = isset( $c['productIds'] ) ? $c['productIds'] : array();
			$cats = isset( $c['categories'] ) ? $c['categories'] : array();
			if ( ! is_array( $ids ) || ! is_array( $cats ) ) { continue; }
			if ( '' !== $id && in_array( $id, $ids, true ) ) { return $guide; }
			if ( null === $category && ! empty( array_intersect( $cats, $categories ) ) ) { $category = $guide; }
			if ( null === $fallback && empty( $ids ) && empty( $cats ) ) { $fallback = $guide; }
		}
		return null !== $category ? $category : $fallback;
	}

	/**
	 * Register (do not yet enqueue) the bootstrap loader.
	 *
	 * The bootstrap is deliberately tiny and synchronous-friendly so JS-delay
	 * optimizers cannot break it. The heavy widget bundle is lazy-loaded by the
	 * bootstrap itself on first intent (click/hover).
	 *
	 * @return void
	 */
	public function register_assets() {
		wp_register_script(
			self::BOOTSTRAP_HANDLE,
			AISTHETIX_TRYON_URL . 'assets/bootstrap.js',
			array(),
			AISTHETIX_TRYON_VERSION,
			true
		);

		// Tell optimizers (and the browser) to leave this script alone. WordPress
		// core does not render arbitrary data-* keys from wp_script_add_data into
		// the <script> tag, so we inject them via script_loader_tag below.
		add_filter( 'script_loader_tag', array( $this, 'add_bootstrap_attributes' ), 10, 2 );
	}

	/**
	 * Inject optimizer-resilience attributes onto the bootstrap <script> tag.
	 *
	 * WordPress core only renders a fixed allowlist of extra script keys into the
	 * tag, so arbitrary data-* attributes registered via wp_script_add_data() are
	 * never emitted. This filter writes the attributes directly onto our tag so
	 * client-side optimizers (e.g. Cloudflare Rocket Loader keying off
	 * data-cfasync, or any optimizer respecting data-no-optimize / data-no-defer
	 * on the tag itself) leave the un-delayable bootstrap alone. See DESIGN.md
	 * decision #20.
	 *
	 * @param string $tag    The full <script> tag HTML.
	 * @param string $handle The script handle being rendered.
	 * @return string The (possibly modified) tag.
	 */
	public function add_bootstrap_attributes( $tag, $handle ) {
		if ( self::BOOTSTRAP_HANDLE !== $handle ) {
			return $tag;
		}
		// Don't double-inject if the filter somehow runs twice on the same tag.
		if ( false !== strpos( $tag, 'data-cfasync' ) ) {
			return $tag;
		}
		return str_replace(
			'<script ',
			'<script data-no-optimize="1" data-no-defer="1" data-cfasync="false" ',
			$tag
		);
	}

	/**
	 * Build the configuration object injected into the page.
	 *
	 * IMPORTANT: only the PUBLISHABLE key is exposed here. The secret key is
	 * server-only and must never appear in this array.
	 *
	 * @param \WC_Product|null $product Product context (defaults to global product).
	 * @return array
	 */
	public function build_config( $product = null ) {
		if ( null === $product ) {
			global $product;
		}

		$product_id    = $product instanceof \WC_Product ? $product->get_id() : 0;
		$product_title = $product instanceof \WC_Product ? $product->get_name() : '';
		$image_url     = $product instanceof \WC_Product ? $this->get_product_image_url( $product ) : '';
		$customer_id   = get_current_user_id();

		$config = array(
			// API base the widget posts try-ons to (brain storefront gateway).
			'brainUrl'       => Plugin::brain_url(),
			'apiBaseUrl'     => Plugin::brain_url() . '/api/storefront/tryon',
			'sizeApiUrl'     => Plugin::brain_url() . '/api/storefront/size',
			'sizePhotoQcUrl' => Plugin::brain_url() . '/api/storefront/photo-qc',
			// Attribution event ingestion endpoint (client events; publishable key).
			'eventsUrl'      => Plugin::brain_url() . '/api/events',
			'publishableKey' => Plugin::publishable_key(),
			'productId'      => (string) $product_id,
			'productCategories' => $this->get_product_category_slugs( $product ),
			'productCategoryIds' => $this->get_product_category_ids( $product ),
			'productTitle'   => html_entity_decode( $product_title, ENT_QUOTES | ENT_HTML5, 'UTF-8' ),
			'siteName'       => html_entity_decode( get_bloginfo( 'name' ), ENT_QUOTES | ENT_HTML5, 'UTF-8' ),
			'productImage'   => $image_url,
			'productUrl'     => $product instanceof \WC_Product
				? (string) preg_replace( '/^http:/i', 'https:', $product->get_permalink() )
				: '',
			'variantId'      => null,
			'siteUrl'        => home_url(),
			'locale'         => get_locale(),
			// Shopper-safe fallback shown only during the short status-cache race after
			// quota exhaustion. Empty copy fields let the localized widget defaults win.
			'unavailableMessage' => array(
				'title'       => Plugin::get_setting( 'unavailable_title', '' ),
				'message'     => Plugin::get_setting( 'unavailable_message', '' ),
				'buttonLabel' => Plugin::get_setting( 'unavailable_button_text', '' ),
				'buttonUrl'   => Plugin::get_setting( 'unavailable_button_url', '' ),
			),
			// Opt-in analytics flag read by assets/bootstrap.js to gate ATTRIBUTION
			// events. Product analytics and replay answer to a stricter gate — the
			// shopper's own CMP — which this flag deliberately cannot open.
			'analyticsEnabled' => Plugin::analytics_enabled(),
			// Stamped on every product-analytics event, so a regression can be tied
			// to the plugin release that introduced it.
			'pluginVersion'    => AISTHETIX_TRYON_VERSION,
			'customerId'     => $customer_id ? (string) $customer_id : null,
			// Durable first-party visitor key (PRIMARY attribution key). The widget
			// uses this for events and keeps localStorage only as a fallback. Resolved
			// via config_visitor_key() so the client never gets an ephemeral key that
			// the later server-side order event couldn't agree with (headers_sent race).
			'visitorKey'     => $this->config_visitor_key(),
			// Per-variation image map (empty for simple products).
			'variationImages' => $product instanceof \WC_Product ? $this->get_variation_image_map( $product ) : array(),
			'productVariants' => $product instanceof \WC_Product ? $this->get_size_variants( $product ) : array(),
			'variationSelections' => $product instanceof \WC_Product ? $this->get_variation_selections( $product ) : array(),
		);

		// Session replay, when it is switched on at all. Merged rather than always
		// present, so a store with replay off ships a config with no analytics
		// block — and the widget then never fetches the recorder.
		//
		// The operator's half of the switch comes from Core, with the status this
		// site already caches: that is what makes "stop recording everywhere" a
		// thing Aisthetix can actually do, within the cache TTL, without a plugin
		// release. A status call that failed carries a disabled replay block, so
		// an outage records less rather than more.
		$status = $this->status->get();
		$config['size'] = isset( $status['size'] ) ? $status['size'] : array();
		$remote_replay = isset( $status['replay'] ) && is_array( $status['replay'] )
			? $status['replay']
			: array();
		$config = array_merge( $config, Plugin::replay_settings( $remote_replay ) );

		/**
		 * Filter the storefront config before it is injected.
		 *
		 * @param array            $config  Config array.
		 * @param \WC_Product|null $product Product context.
		 */
		return apply_filters( 'aisthetix_tryon_config', $config, $product );
	}

	/**
	 * Resolve the best featured image URL for a product.
	 *
	 * @param \WC_Product $product Product.
	 * @return string Image URL (empty string if none).
	 */
	private function get_product_image_url( $product ) {
		$image_id = $product->get_image_id();
		if ( $image_id ) {
			$src = wp_get_attachment_image_url( $image_id, 'large' );
			if ( $src ) {
				return $src;
			}
		}
		return wc_placeholder_img_src( 'large' );
	}

	/**
	 * Product category slugs for provider routing (spec 2026-07-02).
	 *
	 * @param \WC_Product|null $product Product.
	 * @return array<int,string> Category slugs (empty if none / not a product).
	 */
	private function get_product_category_slugs( $product ) {
		if ( ! ( $product instanceof \WC_Product ) ) {
			return array();
		}
		$terms = get_the_terms( $product->get_id(), 'product_cat' );
		if ( ! is_array( $terms ) ) {
			return array();
		}
		return array_values( array_map( static function ( $t ) { return $t->slug; }, $terms ) );
	}

	/**
	 * Stable WooCommerce product category identifiers. Names/slugs may change;
	 * term IDs do not, so fit overrides remain attached across renames.
	 *
	 * @param \WC_Product|null $product Product.
	 * @return array<int,string>
	 */
	private function get_product_category_ids( $product ) {
		if ( ! ( $product instanceof \WC_Product ) ) {
			return array();
		}
		$terms = get_the_terms( $product->get_id(), 'product_cat' );
		if ( ! is_array( $terms ) ) {
			return array();
		}
		return self::stable_category_ids( $terms );
	}

	/**
	 * Convert WooCommerce terms into rename-safe category identifiers.
	 *
	 * @param array $terms Product category terms.
	 * @return array<int,string>
	 */
	public static function stable_category_ids( $terms ) {
		$out = array();
		foreach ( is_array( $terms ) ? $terms : array() as $term ) {
			if ( isset( $term->term_id ) && (int) $term->term_id > 0 ) {
				$out[] = 'wc:product_cat:' . (int) $term->term_id;
			}
		}
		return array_values( array_unique( $out ) );
	}

	private function product_context( $product ) {
		return array(
			'categories' => $this->get_product_category_slugs( $product ),
			'productId'  => (string) $product->get_id(),
		);
	}

	/**
	 * Variant ids and their actual size labels. Unknown attribute layouts yield
	 * an empty list, which hides the size offer instead of guessing a variant.
	 *
	 * @param \WC_Product $product Product.
	 * @return array
	 */
	private function get_size_variants( $product ) {
		if ( ! $product->is_type( 'variable' ) ) {
			return array();
		}
		$size_names = array( 'size', 'sizes', 'taglia', 'taglie', 'talla', 'tallas', 'taille', 'tailles', 'groesse', 'grosse', 'tamanho', 'maat' );
		$out = array();
		foreach ( $product->get_children() as $variation_id ) {
			$variation = wc_get_product( $variation_id );
			if ( ! $variation instanceof \WC_Product_Variation ) {
				continue;
			}
			$label = '';
			foreach ( $variation->get_attributes() as $attribute => $value ) {
				$normalised = sanitize_title( str_replace( array( 'attribute_', 'pa_' ), '', (string) $attribute ) );
				if ( in_array( $normalised, $size_names, true ) ) {
					$label = (string) $value;
					break;
				}
			}
			if ( '' === $label ) {
				continue;
			}
			$out[] = array(
				'variant_id' => (string) $variation_id,
				'size_label' => $label,
				'available'  => $variation->is_in_stock() && $variation->is_purchasable(),
			);
		}
		return $out;
	}

	private function get_variation_selections( $product ) {
		$out = array();
		if ( ! $product->is_type( 'variable' ) ) {
			return $out;
		}
		foreach ( $product->get_children() as $variation_id ) {
			$variation = wc_get_product( $variation_id );
			if ( ! $variation instanceof \WC_Product_Variation ) {
				continue;
			}
			$attributes = array();
			foreach ( $variation->get_attributes() as $name => $value ) {
				$attributes[ 'attribute_' . $name ] = (string) $value;
			}
			$out[ (string) $variation_id ] = $attributes;
		}
		return $out;
	}

	/**
	 * Build a variation-id => image-url map for variable products.
	 *
	 * The bootstrap listens to WooCommerce's `found_variation` event and swaps
	 * the garment image to the selected variation's image using this map.
	 *
	 * @param \WC_Product $product Product (may be variable).
	 * @return array<int,string>
	 */
	private function get_variation_image_map( $product ) {
		$map = array();

		if ( ! $product->is_type( 'variable' ) ) {
			return $map;
		}

		foreach ( $product->get_children() as $variation_id ) {
			$variation = wc_get_product( $variation_id );
			if ( ! $variation instanceof \WC_Product_Variation ) {
				continue;
			}
			$image_id = $variation->get_image_id();
			if ( ! $image_id ) {
				// Fall back to the parent image when a variation has no image.
				$image_id = $product->get_image_id();
			}
			if ( $image_id ) {
				$url = wp_get_attachment_image_url( $image_id, 'large' );
				if ( $url ) {
					$map[ (int) $variation_id ] = $url;
				}
			}
		}

		return $map;
	}

	/**
	 * Enqueue the bootstrap and print the config object exactly once per request.
	 *
	 * @param \WC_Product|null $product Product context.
	 * @return void
	 */
	private function ensure_assets( $product = null ) {
		if ( $this->printed ) {
			return;
		}
		// The bootstrap handle is registered by register_assets() on
		// wp_enqueue_scripts priority 10. On BLOCK THEMES the add-to-cart block
		// (hence woocommerce_after_add_to_cart_button -> render_button) can render
		// BEFORE wp_enqueue_scripts runs; enqueuing + inlining the config then would
		// be silently dropped before the footer print. If the handle isn't
		// registered yet, defer WITHOUT consuming the $printed guard so the
		// priority-20 maybe_enqueue_on_product() pass attaches the config reliably.
		if ( ! wp_script_is( self::BOOTSTRAP_HANDLE, 'registered' ) ) {
			return;
		}
		$this->printed = true;

		wp_enqueue_script( self::BOOTSTRAP_HANDLE );

		$config = $this->build_config( $product );

		// Inline config printed BEFORE the bootstrap runs. We mark it via the
		// global name so optimizers that match inline content can exclude it.
		// Version the lazily-loaded bundle URLs so a plugin update busts the
		// browser cache (the bootstrap loads these by URL, outside wp_enqueue's
		// own ?ver handling).
		$asset_ver = '?ver=' . rawurlencode( AISTHETIX_TRYON_VERSION );
		$inline = 'window.AISTHETIX_CONFIG = ' . wp_json_encode( $config ) . ';'
			. 'window.AISTHETIX_WIDGET_URL = ' . wp_json_encode( AISTHETIX_TRYON_URL . 'assets/widget.js' . $asset_ver ) . ';'
			. 'window.AISTHETIX_WIDGET_CSS = ' . wp_json_encode( AISTHETIX_TRYON_URL . 'assets/widget.css' . $asset_ver ) . ';';

		wp_add_inline_script( self::BOOTSTRAP_HANDLE, $inline, 'before' );
	}

	/**
	 * Auto placement callback (woocommerce_after_add_to_cart_button).
	 *
	 * @return void
	 */
	public function maybe_auto_render() {
		if ( 'after_add_to_cart' !== Plugin::get_setting( 'placement', 'after_add_to_cart' ) ) {
			return;
		}
		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- render_button() escapes internally and returns safe HTML.
		echo $this->render_button( array( 'surface' => 'auto' ) );
	}

	/**
	 * Shortcode handler: [aisthetix_tryon label="Try it on"].
	 *
	 * @param array $atts Shortcode attributes.
	 * @return string HTML.
	 */
	public function shortcode( $atts ) {
		$atts = shortcode_atts(
			array(
				'label' => '',
			),
			$atts,
			'aisthetix_tryon'
		);

		return $this->render_button( array( 'label' => $atts['label'], 'surface' => 'shortcode' ) );
	}

	/**
	 * Render the trigger button + the widget mount point.
	 *
	 * All placement surfaces (auto-hook, shortcode, block, Elementor) call this.
	 * Returns an empty string when the entry point must be absent (per DESIGN.md
	 * decision #14: no inert button, no nag, no layout shift).
	 *
	 * @param array $args Optional. 'label' => string, 'product' => WC_Product.
	 * @return string HTML (escaped) or empty string.
	 */
	public function render_button( $args = array() ) {
		$product = isset( $args['product'] ) && $args['product'] instanceof \WC_Product
			? $args['product']
			: null;

		// Resolve product first; try-on and size have independent targeting gates.
		if ( null === $product ) {
			if ( ! Plugin::is_connected() || ! function_exists( 'is_product' ) || ! is_product() ) {
				return '';
			}
			$product = $this->resolve_product();
		} elseif ( ! Plugin::is_connected() ) {
			return '';
		}

		if ( ! $product instanceof \WC_Product ) {
			return '';
		}

		// A grouped product is a catalogue of different child garments, not one
		// try-on target. Its featured image may be a logo/collage and WooCommerce
		// exposes no selected child to this button, so sending it to the model would
		// produce a misleading result. The button remains available on each child
		// product page where the garment image and product id are unambiguous.
		if ( $product->is_type( 'grouped' ) ) {
			return '';
		}

		$tryon_allowed = $this->status->should_render( $this->product_context( $product ) );
		$size_allowed = $this->can_render_size( $product );
		$size_guide_resolution = self::size_guide_resolution( $this->status->get(), $this->product_context( $product ) );
		if ( ! $tryon_allowed && ! $size_allowed ) {
			return '';
		}

		$this->ensure_assets( $product );

		$label = '';
		if ( ! empty( $args['label'] ) ) {
			$label = $args['label'];
		}
		if ( '' === $label ) {
			$label = Plugin::get_setting( 'button_text', '' );
		}
		if ( '' === $label ) {
			$label = __( 'Try it on', 'aisthetix-virtual-try-on' );
		}
		++$this->render_index;
		$size_note_id = 'aisthetix-size-entry-note-' . (int) $product->get_id() . '-' . $this->render_index;

		ob_start();
		?>
		<div class="aisthetix-tryon-wrap" data-no-optimize="1">
			<?php if ( $tryon_allowed ) : ?>
			<button
				type="button"
				id="aisthetix-tryon-trigger"
				class="aisthetix-tryon-trigger button"
				data-aisthetix-trigger="1"
			>
				<?php echo esc_html( $label ); ?>
			</button>
			<?php endif; ?>
			<?php if ( $size_allowed ) : ?>
			<div class="aisthetix-size-entry">
				<button
					type="button"
					class="aisthetix-size-trigger button"
					data-aisthetix-trigger="1"
					data-aisthetix-size-trigger="1"
					data-aisthetix-size-guide-resolution="<?php echo esc_attr( $size_guide_resolution ); ?>"
					aria-describedby="<?php echo esc_attr( $size_note_id ); ?>"
				>
					<?php esc_html_e( 'Find my size', 'aisthetix-virtual-try-on' ); ?>
				</button>
				<p id="<?php echo esc_attr( $size_note_id ); ?>" class="aisthetix-size-entry-note">
					<?php esc_html_e( 'Recommendation from this store’s size guide, separate from virtual try-on.', 'aisthetix-virtual-try-on' ); ?>
				</p>
			</div>
			<?php endif; ?>
			<div id="aisthetix-widget-root"></div>
		</div>
		<?php
		$html = trim( ob_get_clean() );

		// The markup is REALLY going out on a product page: report the placement
		// receipt the brain uses as its activation truth source. After the markup
		// is built, so a receipt can never fire for a render that returned ''.
		$this->maybe_report_placement(
			isset( $args['surface'] ) ? (string) $args['surface'] : 'shortcode',
			(int) $product->get_id()
		);

		return $html;
	}

	/**
	 * Send the placement receipt for a genuine storefront render. Editor and
	 * preview contexts are excluded — a block placed in the editor preview is
	 * not a live storefront placement, and a false "active" would be worse
	 * than a late one. Throttling and connectivity live in Connector.
	 *
	 * @param string $surface    Placement surface.
	 * @param int    $product_id Product rendered on.
	 * @return void
	 */
	private function maybe_report_placement( $surface, $product_id ) {
		if ( ! self::placement_context_allows_reporting( self::current_placement_context() ) ) {
			return;
		}
		$connector = Plugin::instance()->connector;
		if ( $connector instanceof Connector ) {
			$connector->report_placement( self::normalize_placement_surface( $surface ), $product_id );
		}
	}

	/**
	 * The current request's placement-reporting context flags.
	 *
	 * @return array{admin:bool,rest:bool,preview:bool,elementor_preview:bool}
	 */
	public static function current_placement_context() {
		return array(
			'admin'             => is_admin(),
			'rest'              => defined( 'REST_REQUEST' ) && REST_REQUEST,
			'preview'           => function_exists( 'is_preview' ) && is_preview(),
			// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only context check.
			'elementor_preview' => isset( $_GET['elementor-preview'] ),
		);
	}

	/**
	 * Whether a render in this context is a GENUINE storefront placement.
	 *
	 * Editor and preview contexts are excluded on purpose: a block sitting in
	 * the editor preview is not a live placement, and a false "active" claim
	 * would be worse than a late one. Pure so the exclusion table is testable
	 * without WordPress.
	 *
	 * @param array $context Flags from {@see current_placement_context()}.
	 * @return bool
	 */
	public static function placement_context_allows_reporting( $context ) {
		if ( ! empty( $context['admin'] ) ) {
			return false; // wp-admin and Elementor editor ajax.
		}
		if ( ! empty( $context['rest'] ) ) {
			return false; // block editor ServerSideRender preview.
		}
		if ( ! empty( $context['preview'] ) ) {
			return false; // post preview.
		}
		if ( ! empty( $context['elementor_preview'] ) ) {
			return false; // Elementor editor iframe.
		}
		return true;
	}

	/**
	 * Clamp a surface value to the brain's contract enum.
	 *
	 * @param string $surface Raw surface.
	 * @return string
	 */
	public static function normalize_placement_surface( $surface ) {
		$allowed = array( 'auto', 'shortcode', 'gutenberg_block', 'elementor' );
		return in_array( $surface, $allowed, true ) ? $surface : 'shortcode';
	}

	/**
	 * Register exclusions with common JS-delay / optimizer plugins so the
	 * bootstrap loader and its inline config are never deferred or removed.
	 *
	 * @return void
	 */
	private function register_optimizer_exclusions() {
		$handles_and_paths = array(
			'aisthetix',           // matches our handle, file, and inline marker.
			'AISTHETIX_CONFIG',
			'bootstrap.js',
		);

		// WP Rocket: delay-JS exclusions.
		add_filter(
			'rocket_delay_js_exclusions',
			function ( $excluded ) use ( $handles_and_paths ) {
				return array_merge( (array) $excluded, $handles_and_paths );
			}
		);

		// WP Rocket: do not lazy/delay our inline config.
		add_filter(
			'rocket_excluded_inline_js_content',
			function ( $excluded ) {
				$excluded   = (array) $excluded;
				$excluded[] = 'AISTHETIX_CONFIG';
				$excluded[] = 'AISTHETIX_WIDGET_URL';
				return $excluded;
			}
		);

		// WP Rocket: exclude from minify/concat as well.
		add_filter(
			'rocket_exclude_js',
			function ( $excluded ) {
				$excluded   = (array) $excluded;
				$excluded[] = 'aisthetix-tryon/assets/bootstrap.js';
				$excluded[] = 'aisthetix-tryon/assets/widget.js';
				return $excluded;
			}
		);

		// LiteSpeed Cache: exclude from JS defer.
		add_filter(
			'litespeed_optm_js_defer_exc',
			function ( $excluded ) use ( $handles_and_paths ) {
				return array_merge( (array) $excluded, $handles_and_paths );
			}
		);
		// LiteSpeed Cache: exclude from optimization entirely.
		add_filter(
			'litespeed_optimize_js_excludes',
			function ( $excluded ) use ( $handles_and_paths ) {
				return array_merge( (array) $excluded, $handles_and_paths );
			}
		);

		// Perfmatters: delay-JS exclusions.
		add_filter(
			'perfmatters_delay_js_exclusions',
			function ( $excluded ) use ( $handles_and_paths ) {
				return array_merge( (array) $excluded, $handles_and_paths );
			}
		);
		// Perfmatters: script-manager / JS exclusions.
		add_filter(
			'perfmatters_js_exclusions',
			function ( $excluded ) use ( $handles_and_paths ) {
				return array_merge( (array) $excluded, $handles_and_paths );
			}
		);
	}
}