=== KineticHub Page Loader ===
Contributors: kinetichub
Tags: preloader, page loader, loading screen, site intro, brand preloader
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A lightweight brand preloader and site intro for WordPress. Display a polished loading screen with your logo before your site appears.

== Description ==

KineticHub Page Loader lets you display a branded loading screen as your WordPress site is being rendered. It covers the page with your logo, site name, or a tagline - then cleanly fades out and removes itself from the DOM once the page is ready.

It is designed to improve the **perceived first impression** of your site by showing polished, intentional branding instead of a blank white page during the initial load. It does not improve server response time or actual page speed.

The loader is built with CSS-first animations, vanilla JavaScript, and no external dependencies. It respects user accessibility preferences, cleans up after itself, and is safe to use alongside caching plugins.

**Key highlights:**

* No jQuery dependency
* No external fonts, CDN assets, or remote requests
* CSS-first animations - five polished presets included
* Respects `prefers-reduced-motion` - animations are collapsed for users who prefer reduced motion
* Loader is removed from the DOM after hiding, so it has no lasting impact on the page
* No focus trap - keyboard and screen reader users are not locked into the loader
* Once-per-session display option using `sessionStorage`
* Maximum timeout safety - the loader always disappears, even if a resource never loads
* Works alongside common caching plugins
* Compatible with classic themes, block themes, and WooCommerce pages

== Features ==

* **Enable / disable** the loader from the settings screen
* **Display on:** entire site or homepage only
* **Show frequency:** every page load or once per session
* **Logo:** upload via the WordPress media library
* **Text fallback:** shown when no logo is set; falls back to the site name if empty
* **Tagline:** optional short line displayed beneath the logo or text
* **Five animation presets:** each is a CSS-only animation with no JavaScript dependency
* **Colors:** background, accent, and text colors with optional gradient background
* **Timing controls:** minimum display time, maximum timeout, and fade-out duration
* **Visibility:** independently enable or disable the loader on desktop and mobile

== Included Loader Styles ==

1. **Minimal Pulse** - A small pulsing dot using the accent color
2. **Logo Fade** - Content fades and rises in gently
3. **Gradient Sweep** - An animated gradient that flows across the background
4. **Soft Orb** - A radial glow that breathes behind the content
5. **Progress Bar Minimal** - A thin bar that advances across the top of the loader

All presets automatically collapse to an instant transition when `prefers-reduced-motion: reduce` is detected.

== Installation ==

1. Upload the `kinetichub-page-loader` folder to `/wp-content/plugins/`, or install directly through the WordPress plugin directory.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **Settings -> Page Loader** to configure your loader.
4. Upload your logo, choose a preset, set your colors, and save.

== Frequently Asked Questions ==

= Does this make my website faster? =

No. KineticHub Page Loader does not improve server response time or optimize assets. It creates a branded loading layer that can improve the **perceived first impression** of your site while the page finishes rendering in the background.

= Does it work with caching plugins? =

Yes. The loader HTML is output server-side and cached normally. Session tracking is handled entirely client-side using `sessionStorage`, so no server-side session state is needed and full-page-cache compatibility is maintained.

= Does it use jQuery? =

No. The frontend script is plain vanilla JavaScript with no library dependencies.

= What happens if JavaScript is disabled? =

A `<noscript>` style block is output in `<head>` that hides the loader immediately. Visitors with JavaScript disabled see the page normally without any blocked overlay.

= Does it respect reduced motion settings? =

Yes. When the visitor's operating system or browser reports `prefers-reduced-motion: reduce`, all animations are collapsed to an instant transition and the minimum display time is effectively bypassed, so the loader disappears as quickly as possible.

= What is the "maximum timeout" setting? =

It is a safety net. If a third-party resource (script, font, image) never finishes loading and the browser `load` event never fires, the maximum timeout ensures the loader is removed anyway, preventing it from blocking the page indefinitely.

= Is the loader accessible? =

The loader uses `aria-hidden="true"` so screen readers skip it. There is no focus trap - keyboard focus stays on the page below. The loader is fully removed from the DOM after hiding, leaving no residual impact on the accessibility tree.

= Does it work with block themes? =

Yes. The loader uses the `wp_body_open` action that all modern themes call. A `wp_footer` fallback is included for themes that do not call `wp_body_open`.

= Does it support WooCommerce? =

The loader will display on WooCommerce pages unless you set **Display On** to **Homepage only**. WooCommerce-specific display rules are not available in this release.

== Screenshots ==

1. Settings page with loader controls, color options, and animation presets.
2. Admin preview panel showing live color and content updates.
3. Minimal Pulse loader preset - centered pulsing dot with logo.
4. Gradient Sweep loader preset - animated flowing gradient background.
5. Progress Bar Minimal preset - thin bar advancing across the top.

== Changelog ==

= 1.0.0 =
* Initial release.
* Added lightweight page loader with five CSS-first animation presets.
* Added logo upload, text fallback, and optional tagline.
* Added background, accent, and text color controls with optional gradient.
* Added minimum display time, maximum timeout, and fade-out duration controls.
* Added once-per-session display option.
* Added desktop and mobile visibility controls.
* Added maximum timeout safety net to prevent indefinite blocking.
* Added `prefers-reduced-motion` support.
* Added noscript fallback to hide loader for JavaScript-disabled visitors.
* Added `wp_footer` fallback output for themes without `wp_body_open` support.

== Upgrade Notice ==

= 1.0.0 =
Initial WordPress.org release.

