=== MisticEase ===
Contributors: misticuantum
Tags: lightbox, popup, modal, video, youtube
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.2
Stable tag: 1.0.0
License: GPLv2
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn YouTube, Vimeo, and Dailymotion URLs into popup-ready thumbnails or title links, with optional Media Library image popups.

== Description ==

MisticEase is designed around the idea that every added feature should reduce user effort and simplify the workflow. It is built so editors can focus on what they want to say and how they want to express it.

Paste a YouTube, Vimeo, or Dailymotion URL, save the page, and let MisticEase handle the rest.
Supported video URLs are converted into clickable thumbnails that open in a popup only when selected.

If you prefer a title link instead of a thumbnail, add `n/` before the URL.

No custom HTML, extra classes, or special attributes are required.

Fetched thumbnail images are stored locally in the uploads directory and reused on later page views.
This reduces repeated remote thumbnail requests.

Media Library images can also open in a popup viewer.
When enabled, images on the same page are grouped automatically for sequential viewing.

MisticEase also includes a full settings panel with inline guidance, floating popup controls, cache management, and network-wide settings for Multisite environments.
In practice, most settings only need to be configured once.

== Features ==

* Paste a YouTube, Vimeo, or Dailymotion URL and save
* Automatic thumbnail generation for supported video URLs
* Popup playback without leaving the page
* Optional title links with the `n/` format
* Local thumbnail caching in the uploads directory
* Configurable cache size with automatic cleanup
* Draggable floating popup on supported screen sizes
* Optional popup viewer for Media Library images
* Automatic grouping for images on the same page
* Responsive thumbnail and popup sizing
* Network-wide settings for Multisite environments
* Inline guidance throughout the settings panel

== Quick Start ==

Activate MisticEase first, then try a simple test page to see how it works.

The example below is written for the Block Editor with Paragraph blocks.
Because MisticEase detects the text content itself, the same idea also works in the Classic Editor.

Create a test page with content like this, then save and view the page:

    https://www.youtube.com/watch?v=PASTE_A_REAL_VIDEO_ID_HERE

    This Video is n/https://www.youtube.com/watch?v=PASTE_A_REAL_VIDEO_ID_HERE///.

    Image  ← link this to an image from the Media Library

Once you try this, you will already understand the basic MisticEase workflow.

* The first URL appears as a clickable thumbnail
* The `n/` version appears as a title link instead of a thumbnail
* If the image is linked to its media file, it opens in the popup viewer

After seeing the result once, the workflow usually feels natural right away.

== Floating Popup ==

Floating behavior depends on screen size.

On desktop, a drag indicator appears when the pointer moves over the playing media.
On tablets, the move button is always visible and can be pressed to drag the popup.
On smaller screens such as smartphones, floating mode is disabled.

This allows visitors to keep reading the page while a video continues playing where floating is available.

== JavaScript Requirement ==

MisticEase requires JavaScript for popup viewing.
Popup viewing, floating windows, and gallery navigation do not work when JavaScript is disabled.
MisticEase is not designed as a no-JavaScript thumbnail viewer.

== n-link (Title Link) Syntax ==

If you want to show a title link instead of a thumbnail, add `n/` before the URL.

Example:

    This Video is n/https://www.youtube.com/watch?v=PASTE_A_REAL_VIDEO_ID_HERE///.

The optional `///` marker can be added at the end as an explicit end marker.
This helps MisticEase detect the URL boundary correctly when punctuation appears immediately after the link.

The `///` marker is not displayed on the page.

This is also helpful in East Asian languages, where spaces are often not used inside sentences.
In such cases, adding a space before `n/` and `///` at the end helps MisticEase recognize the title link correctly.

== Media Library Images ==

Media Library images can also open in a popup when they are linked to their media file in the usual way.

In the image popup:

* the left and right halves of the image act as previous and next controls
* dedicated navigation buttons are also available
* those buttons fade out after 2.5 seconds so they do not get in the way of viewing the image

If you already use another gallery plugin, this image popup feature can be turned off in the settings so your preferred gallery experience remains unchanged.

== Layout Tips ==

Both thumbnails and popups are responsive.

If the available space is smaller than the size set in the settings panel, they automatically scale down to fit the layout.
For many sites, setting the thumbnail width close to the main content column is a good starting point.

If you want a clean tile-style layout, using the WordPress Table block is recommended.
Paste one video URL into each cell, and MisticEase can turn them into a neatly arranged grid of thumbnails.
For a cleaner look, hide the table borders or set them to 0.

The same idea also works in the Classic Editor using table markup such as:

    <td>https://www.youtube.com/watch?v=PASTE_A_REAL_VIDEO_ID_HERE</td>

If you place videos in a three-column table, the thumbnails will shrink to fit and line up evenly.

== How It Works ==

When a supported video URL is first displayed, MisticEase fetches the thumbnail image and stores it locally in the WordPress uploads directory.

On later page views, the cached local thumbnail is reused.
This reduces repeated remote thumbnail requests.

== Thumbnail Cache Management ==

Thumbnail images are stored locally in the WordPress uploads directory.

The maximum cache size can be configured in the settings panel.
When the cache limit is reached, older cached thumbnails are removed automatically.
A scheduled cleanup also runs once every 30 days to remove older cached thumbnails.

== External Services ==

MisticEase connects to external services when a supported video thumbnail has not yet been cached locally.
These requests are used only to retrieve thumbnail images or thumbnail-related metadata for supported video URLs.
After the thumbnail is fetched, it is stored locally in the WordPress uploads directory and reused on later page views.

For Vimeo videos, a temporary placeholder thumbnail may appear on the first page load or when no local thumbnail cache is available.
This is expected behavior. Once MisticEase retrieves and stores the thumbnail locally, the actual Vimeo thumbnail is used on later page views.

When a visitor plays a video, the browser also connects to the original video service for playback.

Depending on the video service, MisticEase uses the following external services:

* YouTube – thumbnail images and video playback
  Service: https://www.youtube.com/
  YouTube Terms of Service: https://www.youtube.com/t/terms
  YouTube API Services Terms: https://developers.google.com/youtube/terms/api-services-terms-of-service
  YouTube API Services Developer Policies: https://developers.google.com/youtube/terms/developer-policies
  Privacy Policy: https://policies.google.com/privacy

* Vimeo – oEmbed data, thumbnail images, and video playback
  Service: https://vimeo.com/
  Vimeo Terms of Service: https://vimeo.com/legal
  Vimeo Developer Addendum: https://vimeo.com/legal/service-terms/api
  Privacy Policy: https://vimeo.com/privacy

* Dailymotion – video thumbnail API, thumbnail images, and video playback
  Service: https://www.dailymotion.com/
  Dailymotion Terms of Use: https://legal.dailymotion.com/en/terms-of-use/
  Privacy Policy: https://legal.dailymotion.com/en/privacy-policy

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/` directory, or install the plugin through the WordPress Plugins screen.
2. Activate the plugin through the "Plugins" screen in WordPress.
3. Paste a YouTube, Vimeo, or Dailymotion URL into your content and save.

== Frequently Asked Questions ==

= What video services are supported? =

Currently supported services are:

* YouTube
* Vimeo
* Dailymotion

= Where are thumbnails stored? =

Thumbnail images are stored in the WordPress uploads directory.

Typical locations are:

* Single site: `/wp-content/uploads/misticease/`
* Multisite main site: `/wp-content/uploads/misticease/`
* Multisite subsite: `/wp-content/uploads/sites/2/misticease/`

In Multisite, sites other than the main site use separate site-specific folders under `uploads/sites/`.

= Does this plugin make external requests? =

Yes.
If a local thumbnail cache file does not yet exist, MisticEase makes external requests to retrieve thumbnail images or thumbnail-related metadata for supported video content.
When a visitor plays a video, the browser also connects to the original video service for playback.

= Does this plugin collect personal data? =

MisticEase itself does not collect, store, or analyze personal information.

If you voluntarily opt in to the optional Freemius connection, Freemius may receive the information shown in its consent screen. See the Freemius SDK and Optional Opt-in section below.

= How does floating behave on different devices? =

On desktop, dragging becomes available when the pointer moves over the playing media.
On tablets, the move button is always visible.
On smartphone-sized screens, floating mode is disabled.

= Why does a raw video URL sometimes appear in post lists or archives? =

On post list pages such as blog archives, thumbnail conversion is not applied in the same way.
If a post begins with a video URL, the raw URL may appear at the beginning of the excerpt instead.

For a cleaner archive layout, it is often better to begin the post with normal text or use a featured image.

= Does this work with Multisite? =

Yes.
MisticEase includes network-wide settings for Multisite environments.

== Freemius SDK and Optional Opt-in ==

MisticEase itself does not include any functionality intended to collect, store, or analyze personal information.

MisticEase includes the Freemius SDK to support optional Freemius connection, important product notices, future MisticEase Arc upgrade flows, licensing, and support-related features.

Use of Freemius is entirely optional.
All MisticEase features can be used without opting in to Freemius.
MisticEase works the same way whether you opt in or skip the Freemius connection.

If you do not opt in, no user data is registered with or transmitted to Freemius by MisticEase.

If you choose to opt in, Freemius may receive the information shown in the Freemius opt-in screen, such as the WordPress user display name, email address, site URL, product version, plugin status, WordPress version, PHP version, site language, and other basic WordPress environment information used for compatibility, update, and support-related purposes.

This information may allow the developer to better understand compatibility issues and send important notices when necessary, such as critical issue notifications, security-related information, compatibility notices, or update announcements.

The developer does not use Freemius email communication for frequent promotional emails.
User information is not used by the MisticEase developer for unrelated purposes.

Management and storage of Freemius opt-in information are handled by Freemius, not by the MisticEase developer.

Freemius states that it manages personal information in accordance with applicable privacy laws, including GDPR.
For details, please refer to the Freemius Privacy Policy, Data Practices, and Terms of Service pages.

Service:
https://freemius.com/

API:
https://api.freemius.com/

Freemius Privacy Policy:
https://freemius.com/privacy/

Freemius Data Practices:
https://freemius.com/privacy/data-practices/

Freemius Terms of Service:
https://freemius.com/terms/

== Screenshots ==

1. Paste a supported video URL into the editor and save the page.
2. The published page automatically displays the pasted video URL as a clickable thumbnail.
3. Click a thumbnail to open and play the video in a popup without leaving the page.
4. A full settings panel is included, with inline guidance for each option.

== Upgrade Notice ==

= 1.0.0 =
Initial release.

== Changelog ==

= 1.0.0 =
* Initial release