=== KineticHub Page Loader – Preloader & Branded Loading Screen ===
Contributors: kinetichub
Tags: preloader, page loader, loading screen, loading animation, loader
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Customizable WordPress preloader and page loader with branded loading screens, logo effects, progress styles, transitions, and live preview.

== Description ==

KineticHub Page Loader is a customizable WordPress preloader and page loader for creating branded loading screens while a page finishes rendering. Add your logo, choose a loading animation, configure progress and transitions, and preview the result directly from the WordPress admin.

It is designed for branding and perceived presentation, not for pretending to make a website load faster. The plugin does not improve server response time or actual page speed; it gives visitors a polished visual experience while the page becomes ready.

KineticHub Page Loader is built with CSS-first animations and vanilla JavaScript, with no jQuery, external fonts, CDN assets, or frontend remote requests.

= Smart loading experiences =

* **Smart Anti-Flash** - an optional reveal delay so the loader does not flash on very fast page loads.
* **KineticPower motion profiles** - Ultra Minimal, Calm, Balanced, Dynamic, and Signature Glow, layered over the preset you choose.
* **Seven visual presets** - Minimal Pulse, Logo Fade, Gradient Sweep, Soft Orb, Progress Bar Minimal, Circular Brand Ring, and Logo Color Reveal.
* **Live Preview** - the settings screen renders your loading screen in real time as you change options.

= Branding and logo effects =

Upload a custom logo from the WordPress Media Library, or fall back to short text that defaults to your site name. An optional tagline sits below, with its own spacing control.

* Logo shapes: original, rounded, or circle
* Loading rings around the logo: solid, dashed, dual, or glow, with color, thickness and speed
* Logo reveal effects: Fade, Grayscale to Color, Soft Scale, Soft Shine Sweep, Zoom Bloom, and Mask Reveal
* Background, accent, text, and optional gradient colors

= Progress, transitions and page reveal =

Smart Progress adds a progress indicator in one of six styles: None, Top Bar, Bottom Line, Logo Ring, Center Glow Line, or Minimal Percentage.

**Progress is simulated visual progress** - a timed animation that conveys activity, not a measurement of actual network or download progress.

* Exit transitions: Fade, Slide Up, Blur Lift, Split Curtain, Circle Reveal
* Page Reveal for the handoff into your page: None, Soft Fade, Blur to Sharp, Lift In, Gentle Scale
* Cover modes: Solid, Soft Overlay, Blur Page, Glass
* An optional completion pulse, rotating loading messages, and one-click timing presets

= Display rules and compatibility =

Show the page loader site-wide or on the homepage only, to everyone or to visitors only, on every load, once per session, or once per day. Exclude specific post/page IDs and URL paths, optionally exclude the WooCommerce cart, checkout and account pages, and toggle desktop and mobile visibility independently.

The loader is output through standard WordPress frontend hooks (`wp_body_open`, with a `wp_footer` fallback), so it works with classic themes, block themes, and page builders that render normal frontend pages. Session and daily frequency are tracked in the browser, so pages stay cacheable alongside caching and performance plugins, and the loader includes failsafe handling for setups that delay frontend JavaScript.

= Lightweight and accessible =

* Vanilla JavaScript, no jQuery, no frontend remote requests
* Minified production CSS and JavaScript
* Respects `prefers-reduced-motion` by collapsing animations to an instant transition
* An `aria-hidden` visual overlay with no focus trap, so keyboard focus stays on the page below
* The loader element is removed from the DOM once it has hidden
* A `noscript` fallback hides the loader for visitors with JavaScript disabled
* A bounded maximum timeout ensures the loading screen goes away even if a resource never loads

== Installation ==

1. Install KineticHub Page Loader from the WordPress Plugin Directory, or upload the plugin ZIP.
2. Activate the plugin.
3. Go to Settings -> Page Loader.
4. Enable the loader, add your logo or text, choose the visual options you want, and save.

== Frequently Asked Questions ==

= How do I add a preloader to WordPress? =

Install and activate KineticHub Page Loader, then go to **Settings -> Page Loader**. Enable the loader, add your logo or text, pick a preset and the options you want, and save. The loading screen appears on the next frontend page load.

= Can I use my own logo in the loading screen? =

Yes. Upload any image from the WordPress Media Library. If no logo is set, a text fallback is shown instead, defaulting to your site name. You can add logo reveal effects (fade, grayscale to color, soft scale, shine sweep, zoom bloom, mask reveal), logo shapes (original, rounded, circle), and an animated loading ring.

= Can I add a progress bar or loading percentage? =

Yes. Smart Progress offers Top Bar, Bottom Line, Logo Ring, Center Glow Line, and Minimal Percentage styles, or None. This is simulated visual progress: a timed animation, not a measurement of the actual network loading percentage.

= Can I control where the page loader appears? =

Yes. Show it site-wide or on the homepage only, to everyone or to visitors only, and exclude specific post/page IDs, URL paths, or WooCommerce cart, checkout and account pages. Desktop and mobile visibility are independent.

= Can the preloader show only once per session or once per day? =

Yes. Show frequency can be every page load, once per session, or once per day. On repeat views within that window the loader is suppressed before it can paint, so there is no flash of a loading screen.

= Does KineticHub Page Loader work with WooCommerce, page builders, and caching plugins? =

It is designed to. WooCommerce cart, checkout, and account pages can be excluded with one toggle, and the loader is theme- and builder-agnostic because it renders through normal WordPress frontend hooks. Frequency tracking happens in the browser, so pages stay cacheable, and failsafe handling covers setups that delay frontend JavaScript. Third-party configurations vary, so compatibility with every possible combination cannot be guaranteed.

= Does a preloader make my WordPress site faster? =

No. It changes the visual loading experience and perceived presentation. It does not reduce server response time or optimize your assets.

= Does the loader respect reduced motion and accessibility preferences? =

Yes. When `prefers-reduced-motion: reduce` is set, animations collapse to an instant transition. The overlay is marked `aria-hidden` so screen readers skip it, there is no focus trap, and the loader is removed from the DOM after hiding. With JavaScript disabled, a `noscript` block hides the loader so the page is never blocked.

== Screenshots ==

1. KineticHub Page Loader dashboard with real-time Live Preview and simple site-wide controls.
2. Choose from polished animation presets and customize the visual style with instant preview.
3. Smart Anti-Flash, progress styles, transitions, cover modes, and page reveal controls.
4. KineticPower motion profiles range from Ultra Minimal to the expressive Signature Glow.
5. Flexible display rules control when, where, and for whom the page loader appears.
6. A polished branded loader with logo treatment, simulated progress, and modern visual effects.
7. Another frontend example showing how KineticHub Page Loader can adapt to different brand styles and visual treatments.

== Changelog ==

= 1.4.0 =
* Added: Smart Anti-Flash reveal delay, so the loader does not flash on very fast page loads.
* Added: KineticPower motion profiles - Classic, Ultra Minimal, Calm, Balanced, Dynamic, and Signature Glow.
* Added: logo reveal effects - Soft Shine Sweep, Zoom Bloom, and Mask Reveal, alongside the existing fade, grayscale reveal, and soft scale.
* Added: Smart Progress styles - Top Bar, Bottom Line, Logo Ring, Center Glow Line, and Minimal Percentage. Progress is simulated, not a measurement of actual load progress.
* Added: exit transitions - Slide Up, Blur Lift, Split Curtain, and Circle Reveal - plus optional page reveal effects for a smoother handoff into the page.
* Added: cover modes - Solid, Soft Overlay, Blur Page, and Glass.
* Added: rotating loading messages, an optional completion pulse, and one-click timing presets.
* Improved: redesigned settings screen with a modern KineticHub dashboard layout and an expanded Live Preview.
* Improved: scroll-lock handling on iOS and Safari, and general loader lifecycle robustness.
* Note: all new visual options default to the previous behavior, so existing sites render exactly as before until you opt in.

= 1.3.0 =
* Added: Tagline Spacing setting (0-50 px) in the Content section, controlling the space between the logo/text and the tagline. Default 0 preserves the existing look.
* Added: a one-time, permanently dismissible review request, shown only on the plugin's own settings page at least 10 days after installation.
* Added: a small card on the settings page introducing KineticHub - Animated Blocks, shown only when it is not already installed.
* Fixed: with no logo set, the circle shape and the Circular Brand Ring preset reserved empty space the size of the configured logo width above the tagline.
* Fixed: ring decorations are no longer rendered around the text fallback when no logo is set, where they appeared as stretched ellipses.
* Improved: ring options are visually disabled, with an explanatory note, while the Circular Brand Ring preset is selected, since that preset draws its own rings. Saved ring settings are preserved.
* Improved: the settings sidebar (preview and info card) sticks as one block and scrolls internally on short screens.

== Upgrade Notice ==

= 1.4.0 =
Adds Smart Anti-Flash, KineticPower motion profiles, new progress styles, exit transitions, page reveal and cover modes, plus a redesigned settings experience. Existing settings are preserved and the loader looks unchanged until you opt in.
