UNIVERSAL WP SPEED OPTIMIZER
User Guide / Usage Instructions
Version 1.0.1

============================================================
1. WHAT THIS PLUGIN DOES
============================================================

Universal WP Speed Optimizer is a compatibility-first WordPress performance
plugin designed to help improve PageSpeed Insights and Core Web Vitals without
blindly applying risky optimizations to every website.

It includes:

SAFE DEFAULT OPTIMIZATIONS
- Disable legacy WordPress emoji assets
- Remove wp-embed.js
- Remove Dashicons for logged-out visitors
- Lazy-load iframe embeds
- Disable frontend WordPress Heartbeat
- Remove small legacy head tags
- Optimize logged-out visitors only by default

ADVANCED OPTIONAL OPTIMIZATIONS
- Preload the actual LCP image
- Preconnect important third-party origins
- Preload critical fonts
- Conditionally unload Contact Form 7
- Conditionally unload WooCommerce assets
- Conditionally unload Gutenberg block CSS
- Defer selected JavaScript files by WordPress handle
- Delay selected third-party scripts until interaction
- Async-load selected CSS files by WordPress handle
- Add small custom Critical CSS

============================================================
2. INSTALLATION
============================================================

1. Log in to your WordPress Dashboard.
2. Go to:
   Plugins > Add New Plugin > Upload Plugin
3. Select the plugin ZIP file.
4. Click Install Now.
5. Click Activate Plugin.
6. Go to:
   Settings > WP Speed Optimizer

IMPORTANT:
After activation or after changing settings, always clear your page cache
and CDN cache before testing performance.

============================================================
3. RECOMMENDED FIRST-TIME SETUP
============================================================

For a new website, DO NOT enable every option immediately.

Start with only the default Safe Core Optimizations.

Recommended initial settings:

ON:
- Optimize logged-out visitors only
- Disable legacy WordPress emoji assets
- Remove wp-embed.js
- Remove Dashicons for logged-out visitors
- Lazy-load content iframes
- Disable WordPress Heartbeat on frontend visitors
- Remove small legacy head tags

OFF:
- Contact Form 7 unloading
- WooCommerce unloading
- Gutenberg CSS unloading
- Script defer
- Third-party script delay
- Async CSS
- Critical CSS
- LCP preload, unless you know the exact LCP image

After saving:
1. Purge WordPress cache
2. Purge CDN cache
3. Open the website in Incognito/Private mode
4. Test desktop and mobile
5. Run PageSpeed Insights

============================================================
4. HOW TO USE THE LCP IMAGE OPTION
============================================================

LCP means Largest Contentful Paint.

Usually the LCP element is:
- a hero image
- a banner image
- a large heading
- a featured image

Do NOT guess the LCP image.

To identify it:
1. Open PageSpeed Insights
2. Test your page
3. Open the LCP / Largest Contentful Paint diagnostic
4. Find the exact image URL used as the LCP
5. Copy that URL
6. Go to:
   Settings > WP Speed Optimizer
7. Paste it into:
   "LCP image URL"

Only use this if your theme or caching plugin is NOT already preloading that
same image.

Do not preload multiple large images unnecessarily.

============================================================
5. PRECONNECT DOMAINS
============================================================

Use this only for domains needed very early in page loading.

Examples:
https://fonts.gstatic.com
https://fonts.googleapis.com

Add one origin per line.

Do not add dozens of domains.
Too many preconnects can hurt performance.

============================================================
6. PRELOAD CRITICAL FONTS
============================================================

Use this only for fonts that are:
- used above the fold
- required immediately
- served as .woff or .woff2

Add one full font URL per line.

Example:
https://example.com/wp-content/uploads/fonts/myfont.woff2

Do not preload every font on the website.

============================================================
7. CONTACT FORM 7 UNLOADING
============================================================

Enable:
"Unload Contact Form 7 when its shortcode is not present"

Use this if Contact Form 7 loads its CSS/JS on pages where no contact form exists.

The plugin checks the current singular page content for the Contact Form 7 shortcode.

CAUTION:
If your theme injects a Contact Form 7 form from:
- header
- footer
- popup
- widget
- template builder
then this option may remove required assets.

Test carefully.

============================================================
8. WOOCOMMERCE ASSET UNLOADING
============================================================

Enable only if your site has WooCommerce but many pages do not need
WooCommerce functionality.

The plugin avoids unloading on:
- Shop pages
- Product pages
- Cart
- Checkout
- My Account
- pages containing common WooCommerce shortcodes

CAUTION:
Do NOT enable this if your header/footer uses:
- mini cart
- AJAX cart
- product widgets
- WooCommerce blocks
- dynamic cart count

============================================================
9. GUTENBERG BLOCK CSS UNLOADING
============================================================

This option can remove WordPress block CSS on singular pages that do not contain
blocks.

Enable only after testing.

Do NOT use blindly if your:
- theme uses block styles globally
- header/footer uses blocks
- widgets use blocks
- template parts are block-based

============================================================
10. DEFER JAVASCRIPT
============================================================

This is an Advanced option.

First enable:
"Defer scripts by handle"

Then enter one WordPress script HANDLE per line.

Important:
This is NOT the script URL.
It is the WordPress registered handle.

Examples may look like:
my-slider
custom-frontend
analytics-script

Do NOT blindly defer:
- jQuery
- checkout scripts
- navigation/menu dependencies
- login scripts
- payment scripts

If a feature breaks, remove that handle and clear cache.

============================================================
11. DELAY THIRD-PARTY SCRIPTS
============================================================

Useful for non-critical scripts such as:
- chat widgets
- social widgets
- some marketing widgets

The plugin delays matching script URLs until:
- the visitor interacts with the page
OR
- the configured timeout is reached

Default example patterns:
chaty
chatway
facebook.net
connect.facebook.net
platform.twitter.com

CAUTION:
Do not delay scripts that must run immediately, including:
- payment scripts
- consent tools
- essential accessibility scripts
- login/security scripts
- mission-critical analytics if your business requires immediate collection

============================================================
12. ASYNC CSS
============================================================

This is an Expert option.

Do NOT async-load your entire theme stylesheet.

Only add stylesheet handles that you have tested as non-critical.

Wrong CSS deferral can cause:
- Flash of Unstyled Content
- CLS
- broken header/menu
- temporary blank sections
- layout shifting

If any visual issue appears:
1. disable the option
2. remove the handle
3. purge caches

============================================================
13. CRITICAL CSS
============================================================

Critical CSS should contain only the small amount of CSS required for the
initial above-the-fold viewport.

Good candidates:
- header shell
- logo dimensions
- hero dimensions
- first heading
- first visible buttons

Do NOT paste your whole theme stylesheet into this field.

Poor Critical CSS can cause:
- duplicate CSS
- layout shifts
- maintenance problems
- worse PageSpeed results

============================================================
14. HEARTBEAT
============================================================

The plugin disables frontend Heartbeat for visitors by default.

This does not disable WordPress Heartbeat in wp-admin.

The interval setting can be adjusted between 15 and 120 seconds.

For most websites, the default is fine.

============================================================
15. CACHE PLUGINS
============================================================

Universal WP Speed Optimizer does NOT replace a page caching plugin.

You can use it with products such as:
- WP Rocket
- LiteSpeed Cache
- server cache
- Cloudflare

Recommended division of responsibility:

THIS PLUGIN:
- conditional asset cleanup
- LCP hints
- iframe lazy loading
- selected JS/CSS controls
- small WordPress frontend cleanup

CACHE/CDN:
- full-page cache
- browser caching
- CDN delivery
- Brotli/Gzip
- cache warmup
- server-level performance

Avoid enabling the exact same optimization aggressively in two plugins.

============================================================
16. PAGE SPEED TESTING WORKFLOW
============================================================

Use this workflow every time:

STEP 1
Make only one or two optimization changes.

STEP 2
Clear:
- WordPress page cache
- used/critical CSS cache if applicable
- CDN cache

STEP 3
Test the site while logged out.

Check:
- header
- mobile menu
- forms
- login
- cart/checkout if applicable
- sliders
- popups
- course/LMS features
- search
- footer

STEP 4
Run PageSpeed Insights.

STEP 5
Look at the real bottleneck:
- LCP
- FCP
- CLS
- TBT
- Speed Index
- render-blocking resources
- unused JavaScript
- unused CSS
- image delivery
- server response time

STEP 6
Enable only the option that addresses the measured problem.

============================================================
17. IMPORTANT CORE WEB VITALS NOTES
============================================================

LCP
Improve:
- hero/LCP image size
- preload only the true LCP image
- fetch priority
- server response time
- render-blocking CSS

CLS
Avoid:
- images without dimensions
- ads/widgets injecting space unexpectedly
- async main theme CSS
- unstable banners
- late-loading fonts that change geometry

TBT / MAIN THREAD
Improve:
- reduce unnecessary JavaScript
- delay non-critical third-party scripts
- avoid heavy sliders
- avoid excessive widgets

IMAGES
Use:
- WebP or AVIF where supported
- correctly sized images
- lazy loading below the fold
- eager/high priority only for true above-the-fold critical images

============================================================
18. WHAT THIS PLUGIN DOES NOT PROMISE
============================================================

No WordPress plugin can honestly guarantee 90, 95, or 100 PageSpeed score on
every website.

Performance depends on:
- hosting/server response time
- theme quality
- page builder
- number of plugins
- third-party scripts
- image sizes
- database performance
- CDN
- fonts
- page complexity
- mobile CPU simulation used by Lighthouse

This plugin is designed to provide a safe toolbox for improving those areas
without applying the same dangerous optimization to every site.

============================================================
19. TROUBLESHOOTING
============================================================

If the site breaks after enabling an advanced option:

1. Disable the most recently enabled advanced option.
2. Save settings.
3. Clear WordPress cache.
4. Clear CDN cache.
5. Hard refresh / use Incognito mode.
6. Test again.

If necessary:
Deactivate Universal WP Speed Optimizer and clear all caches.

The plugin does not modify:
- WordPress core
- theme files
- uploaded media
- database schema

============================================================
20. RECOMMENDED PRODUCTION RULE
============================================================

SAFE SETTINGS:
Can normally stay enabled.

ADVANCED SETTINGS:
Treat them as diagnostic tools.

Measure first.
Change one thing.
Clear cache.
Test functionality.
Then test PageSpeed.

Do not optimize only for a Lighthouse number if the real website becomes
unstable or unusable.

LICENSE REQUIREMENT (v1.1.0)
----------------------------
The commercial build requires a valid license before performance optimizations run.
Open Settings > WP Speed Optimizer, enter the license key supplied by the seller, and
click Activate License. One key can activate only the number of sites allowed by its plan.
