=== LazyBlur Placeholder Addon for WP Rocket ===
Contributors: alihs123
Tags: lazy loading, images, performance, lqip, wp-rocket
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Replaces empty WP-Rocket lazy-load placeholders with lightweight, blurred previews generated from your WordPress media library.

== Description ==

You satisfied Google's performance guidance by lazy-loading offscreen images, but visitors may still see empty image areas while those files load. LazyBlur Placeholder Addon for WP Rocket fills those spaces with a tiny preview of the final image.

The plugin uses the Low Quality Image Placeholder (LQIP) technique. It generates a small image when media is uploaded, stores it as a base64 data URI, and displays it through WP-Rocket's LazyLoad markup until the full image is ready. The preview then sharpens into the final image with a one-second transition.

This improves perceived loading and gives visitors visual context immediately. It complements image lazy loading and Core Web Vitals work; it does not guarantee search rankings or performance scores.

= Features =

* Generates LQIP data automatically for new Media Library images.
* Backfills placeholders for images uploaded before activation.
* Works with WP-Rocket JavaScript and native image lazy loading.
* Supports JPEG, PNG, GIF, and WebP attachments.
* Resolves responsive sizes, scaled originals, and CDN-hosted uploads.
* Optionally adds a placeholder to the first above-the-fold image.
* Preserves responsive `srcset` data and provides no-JavaScript fallbacks.
* Applies an accessible reduced-motion-safe fade from preview to full image.
* Caches local LQIP previews for WP-Rocket YouTube placeholders.
* Provides coverage statistics, integration checks, and a live preview.
* Includes filters for custom attachment resolution and final image markup.

= SEO and user experience =

Lazy loading helps reduce initial page weight, but an empty placeholder can make a page feel unfinished. LQIP keeps the layout visually populated while deferred images load, helping users understand the page sooner.

The plugin preserves image dimensions and responsive sources. The optional first-image setting is disabled by default because replacing an above-the-fold image can affect Largest Contentful Paint. Test that option against your own Core Web Vitals data before enabling it in production.

= Requirements =

* WordPress 5.6 or later.
* PHP 7.4 or later.
* WP-Rocket with LazyLoad for images enabled to display image placeholders.
* WP-Rocket LazyLoad for iframes and videos, plus YouTube preview replacement, for YouTube LQIP support.

== Installation ==

1. Upload the `lazyblur-for-wp-rocket` folder to `/wp-content/plugins/`, or install the plugin ZIP through **Plugins > Add New > Upload Plugin**.
2. Activate **LazyBlur Placeholder Addon for WP Rocket**.
3. In WP-Rocket, enable **LazyLoad for images** under **Settings > WP-Rocket > Media**.
4. Open **Settings > LazyBlur**.
5. Configure placeholder width and compression quality.
6. Run the backfill tool if the Media Library contains images uploaded before activation.
7. Clear the WP-Rocket cache and test the front end while logged out.

== Frequently Asked Questions ==

= Does this replace WP-Rocket? =

No. This plugin extends WP-Rocket's LazyLoad output. WP-Rocket remains responsible for deciding which images are lazy-loaded and when the full files are loaded.

= What problem does LQIP solve? =

Standard lazy loading can leave an empty or generic placeholder before an image enters the viewport. LQIP displays a recognizable, lightweight preview during that interval.

= Are placeholders generated for existing images? =

Use the backfill tool under **Settings > LazyBlur**. It processes the Media Library in small batches to reduce timeout risk.

= Does it work with CDN or resized image URLs? =

Yes. The plugin resolves WordPress intermediate sizes, `-scaled` originals, and upload paths served from a different CDN hostname.

= Can it add a placeholder to the first image? =

Yes. Enable **Include the first image** in the settings. This option can affect Largest Contentful Paint, so measure the result before using it on a production site.

= Does it support native lazy loading? =

Yes. The real `src` and `srcset` are restored near the viewport using a small IntersectionObserver script. A no-JavaScript fallback retains access to the original image.

= What happens when JavaScript is disabled? =

Images converted by the native or first-image modes include their original markup in a `noscript` fallback.

= Can developers customize the output? =

Use `wrlqip_final_image_html` to filter completed image markup. Use `wrlqip_pre_attachment_id_from_url` to provide an attachment ID for custom CDN or offload URLs.

== Screenshots ==

1. Image placeholder settings, including width, quality, and first-image controls.
2. Media Library coverage statistics and the backfill tool.
3. Side-by-side placeholder and full-image preview.
4. WP-Rocket integration requirements and YouTube preview settings.

== External services ==

The optional YouTube preview feature requests thumbnail images from `i.ytimg.com` using the video ID already present in the page content. The thumbnail is downloaded when a post is saved or through a scheduled background task, then stored locally in the WordPress Media Library.

This service is provided by YouTube/Google and is subject to the [YouTube Terms of Service](https://www.youtube.com/t/terms) and [Google Privacy Policy](https://policies.google.com/privacy). No request is made when YouTube preview support is disabled or no YouTube video is present.

== Changelog ==

= 1.0.0 =

* Initial release.
* Added image LQIP generation, backfill, native lazy-load support, optional first-image handling, fade transitions, and YouTube previews.
