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. Search Performance (M3)

• Debounce: 250ms in assets/js/search.js:debounce (200–300ms target). Prevents request on every keystroke.
• Min length: 2 chars (handler returns empty without query). Input data-min-length.
• Bounded: limit default 6, max 20, validated; handler over-fetches limit*2 for dedup then slices to limit; max 40 IDs scanned.
• Stale protection: AbortController cancels previous fetch + monotonic seq counter ignores stale JSON; rapid iph → iphone cannot overwrite newer.
• Dedupe: identical query (lastQuery) reopens dropdown without fetch.
• Query: WP_Query s + _sku LIKE, post_status publish, no_found_rows, fields ids, no N+1, wc_get_product only for returned IDs (≤6).
• Asset: search.js enqueued only on front-end where data-xshop-search exists (header on all front-end pages, guarded via initAll); woo.css global intentional.
• Caching: server Cache-Control: public, max-age=60; no client cache beyond in-memory lastQuery (no stale invalidation issues).
• Payload: minimal 6 items × 6 fields (~2KB JSON).

9. 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.