=== Space Lightplay ===
Contributors: wpspacenerd
Donate link: https://www.spacenerd.space/
Tags: youtube, video, embed, lazy load, performance, gutenberg
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A single Gutenberg block that lazy-loads YouTube video embeds. Shows a static preview, loads the iframe only on click. Fast, lightweight, no bloat.

== Description ==

Every embedded YouTube video adds weight to your page — external scripts, iframes, tracking pixels — even if the visitor never presses Play. Space Lightplay fixes that.

Drop the block into any post or page, paste a YouTube video URL, and Space Lightplay renders a static preview image with a customizable Play button. The actual iframe is injected only when the visitor clicks. No JavaScript frameworks, no third-party requests until interaction.

**Why it matters:**

* Pages with 3–5 embedded videos can save 2–4 MB of initial page weight and dozens of network requests.
* Largest Contentful Paint (LCP) and Time to Interactive (TTI) improve because heavy iframes no longer block rendering.
* Privacy improves too — no cookies or tracking scripts load until the visitor explicitly chooses to play.

**What you get:**

* One block, one job — lazy-load YouTube video embeds with zero configuration required.
* Custom poster image — upload any image from the Media Library or use the automatic YouTube thumbnail.
* Aspect ratio control — 16:9, 4:3, 1:1, 9:16 (vertical/Shorts), or 21:9 cinematic.
* Start time — set a starting timecode, or paste a YouTube URL with ?t=… and it fills automatically.
* Above-the-fold mode — disables lazy-load on the preview image for hero videos, improving LCP.
* Hover prefetch — opens connections to YouTube the instant the cursor lands on the block, so the iframe loads noticeably faster on click. No extra config.
* Play button styling — control size, button shape (circle, rounded, square), triangle corner roundness, background color, icon color, and hover states using the native WordPress color picker with full theme palette support.
* Block style variations — Minimal, Bold, and Glass presets in one click.
* Pulse animation — optional hover effect to draw attention to the Play button.
* Thumbnail quality — choose between standard and maximum resolution thumbnails.
* Accessible by default — full keyboard navigation, ARIA attributes, optional descriptive title for screen readers, visible focus indicators, RTL support, and prefers-reduced-motion support.
* Noscript fallback — visitors without JavaScript get a direct link to the YouTube video (with timecode preserved).
* Responsive — chosen aspect ratio adapts to any container width.
* Clean uninstall — removing the plugin leaves no options, transients, or database entries behind.

**For developers:**

Space Lightplay uses register_block_type_from_metadata() with a standard block.json manifest. All assets are declared in block.json and enqueued automatically by WordPress. The plugin adds zero global hooks, filters, admin pages, or database entries. Output is a server-rendered block via render.php.

== Installation ==

1. Upload the space-lightplay folder to /wp-content/plugins/.
2. Activate the plugin through the "Plugins" menu in WordPress.
3. In the block editor, search for "Space Lightplay" and add it to your post or page.
4. Paste a YouTube video URL or ID — done. Optionally tweak the Play button in the sidebar.

== Frequently Asked Questions ==

= Does Space Lightplay load any scripts before the visitor clicks Play? =

No. Before the click, only a static preview image and a small CSS file are loaded. The iframe, along with all associated scripts from YouTube, is injected only after the visitor presses Play.

= Can I use my own preview image instead of the automatic thumbnail? =

Yes. In the block sidebar under "Video", click "Upload preview image" and select any image from your Media Library. To revert to the automatic thumbnail, click "Remove".

= Does the block work with the Full Site Editor? =

Yes. Space Lightplay is a standard Gutenberg block and works in the post editor, the site editor, and any context that supports WordPress blocks.

= Will removing Space Lightplay leave anything in my database? =

No. Space Lightplay does not create any options, custom tables, or transients. Deactivating and deleting the plugin leaves your database clean.

= Why does the Play button look oval on my theme? =

This was a known issue in earlier development. The current version uses aspect-ratio: 1 and flex-shrink: 0 to guarantee a perfect circle regardless of your theme's CSS.

= I'm upgrading from 1.0.0 — will my existing blocks break? =

No. All new attributes default to safe values, all old attributes are preserved, and CSS class names have not changed. Two visual notes: the play triangle is now properly optically centred (previously slightly off in some shapes), and colours chosen via the WordPress color picker now apply correctly on the frontend (in 1.0.0 some values silently fell back to defaults). Both are bug fixes — your blocks should look as you originally intended.

== Upgrade Notice ==

= 1.1.0 =
Bug fixes (colours now apply on the frontend, wide/full alignment, triangle centring) plus new features: aspect ratio, start time, block style variations, hover prefetch, and one-click transform from core/embed YouTube blocks. Fully backward compatible with 1.0.0 blocks.

== Changelog ==

= 1.1.0 =
* Fixed: frontend colours not applying when chosen via the native WordPress colour picker (alpha values, CSS variables, and rgba with spaces are now accepted).
* Fixed: wide and full alignment now respect the active theme's container width instead of stretching to the page viewport. Block themes and classic themes both work correctly.
* Fixed: play triangle is now optically centred regardless of button shape and stays the same visible size when corner roundness is adjusted.
* New: aspect ratio control — 16:9, 4:3, 1:1, 9:16 (vertical/Shorts), 21:9 cinematic.
* New: start time (timecode) — set in seconds, or paste a URL with ?t=… and it auto-fills.
* New: above-the-fold mode — disables lazy-load on the preview image for hero videos to improve LCP.
* New: hover-prefetch — preconnect to YouTube on hover/focus/touch, so the iframe loads faster on click. Always on, zero config.
* New: block style variations — Minimal, Bold, Glass.
* New: triangle corner roundness control — round the tips of the play icon.
* New: optional accessible title for the video iframe — describes the video to screen readers.
* New: alpha-channel support on background colour pickers.
* New: block transforms — convert from a core/embed YouTube block to Space Lightplay and back in one click.
* New: spacing (margin) and HTML anchor block supports.
* New: RTL support for the play triangle.
* New: translations directory and `.pot` file for the WordPress.org translation community.
* Improved: block wrapper now uses semantic `&lt;figure&gt;` element instead of `&lt;div&gt;` — better for accessibility, screen readers, and content parsers. Existing CSS targeting the `.space-lightplay` class is unaffected; spacing controls in the editor continue to work.

= 1.0.0 =
* Initial release.