<?php
/**
 * TitanCart Category Landing — Default Core Template.
 *
 * Routed to by StorefrontModule::maybe_load_template() for the tc_category
 * query var. Out-of-the-box this renders the same filtered grid as the shop
 * archive — TitanCart sees no behavior change vs. the pre-S163.5 routing,
 * which collapsed tc_category into shop/archive.php directly.
 *
 * The architectural value is the SEAM. Extensions and themes can now override
 * `category/single.php` independently of `shop/archive.php` to render a
 * dedicated category landing UX (featured/popular/recent sections, category
 * heroes, subcategory grids) without forking the shop archive.
 *
 * The default below routes through TemplateLoader::locate() rather than
 * including shop/archive.php directly, so any existing override of
 * shop/archive.php (theme-level OR extension-level) continues to apply to
 * category pages until / unless that extension also ships its own
 * category/single.php override. Preserves backward compat for marketplace
 * installs, themed installs, and vanilla installs identically.
 *
 * Override paths (priority order via TemplateLoader::locate()):
 *   1. titancart_template_override filter (extensions, e.g. Marketplace)
 *   2. {child-theme}/titancart/category/single.php
 *   3. {parent-theme}/titancart/category/single.php
 *   4. This file (core default)
 *
 * Variables in scope (extracted by template-wrapper.php from
 * StorefrontModule::build_template_data() — same set the shop archive sees):
 *
 *   @var array       $products         Product rows from ProductRepository
 *   @var array       $params           { page, per_page, total_items, total_pages }
 *   @var object|null $category         Category row with name + description
 *   @var object|null $tag              Always null for tc_category requests
 *   @var int         $category_id      Resolved category ID
 *   @var array       $active_filters   Resolved filter state (search/price/sort/rating/updated)
 *   @var string      $filter_mode      "" / "hidden-treasures" / "biggest-deals"
 *   @var string      $lang             Active language code
 *
 * @package TitanCart\Storefront
 * @since   S163.5
 */

defined( 'ABSPATH' ) || exit;

use TitanCart\Storefront\TemplateLoader;

// Defer to whatever currently overrides (or defines) shop/archive.php. Goes
// through the full override chain — preserves marketplace, theme, and vanilla
// behavior identically. Self-reference guard prevents pathological recursion
// if a deploy ever symlinks shop/archive.php → this file.
$archive_template = TemplateLoader::locate( 'shop/archive.php' );

if ( $archive_template && realpath( $archive_template ) !== realpath( __FILE__ ) ) {
	include $archive_template;
}
