mataba/shop/docs/PERFORMANCE.md

XShop – Performance

1. Budgets

• LCP < 2.5s on mid-tier mobile (4G, Moto G4 class).
• Total blocking JS < 150ms.
• No render-blocking webfont swap beyond FOIT 100ms (use font-display: swap).
• DB queries: shop archive < 12 queries, product < 15 (WC baseline excluded).

2. Assets

• Conditional enqueue: each module (search, filter, gallery, wishlist) enqueued only where needed (is_shop, is_product, is_search, or presence of shortcode/block).
• No global JS: single xshop.js is ~5KB bootstrap; feature modules lazy-imported via import().
• CSS: tokens + base always; component CSS split but concatenated in release (critical inline optional, not required v1).
• No jQuery for new code; WC jQuery remains for its own handlers.
• Images: loading="lazy" + decoding="async" + srcset, hero eager. Thumbnails via wp_get_attachment_image.
• Fonts: system stack default; optional Vazirmatn self-hosted, subset, no external request by default.

3. Queries

• Avoid N+1: prime post caches (update_post_meta_cache, update_post_term_cache), use wc_get_products with return => ids where only IDs needed, then wc_get_product in loop.
• Cache expensive counts: filter counts via transient (5 min), search suggestions via transient (5 min).
• No queries on init for frontend; defer to template.

4. Caching

• Transients for search/filter counts; wp_cache for in-request repeated lookups (e.g., xshop_get_setting).
• Compatibility with WP Rocket / LiteSpeed – no DONOTCACHEPAGE abuse.

5. Minification

• Release build minifies CSS/JS (tools/build-release.ps1 runs cssnano/terser or PHP minify). Source maps for dev.

6. DOM

• Minimal wrappers, no deep nesting. No layout thrash (batch DOM reads/writes).
• Carousel: CSS scroll-snap, no heavy JS.

7. Monitoring

• System Status reports: PHP/WP/WC versions, active plugins, asset sizes, transient hit rate.
• Lighthouse CI optional (not required for v1).

8. Anti-Patterns Forbidden

• Global wp_enqueue_script without condition.
• Querying all products to compute filters.
• Unbounded WP_Query without posts_per_page / no_found_rows.
• External fonts/CDNs by default.