=== ProgMaze Media Scanner ===
Contributors:      progmaze,wpvirtuoso,ranaumar7899
Donate link:       https://progmaze.com/
Tags:              media, media library, images, gutenberg, optimization
Requires at least: 5.8
Tested up to:      6.9
Requires PHP:      7.4
Stable tag:        1.0.0
License:           GPLv2 or later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Deep scan of where media is used site-wide; find unused library files and delete or detach them safely.

== Description ==

Need to know which posts, builders, or meta fields still reference an image—or which uploads are safe to remove?

**ProgMaze Media Scanner** runs a **deep scan** of your site: it walks public post types (including templates), reads `post_content` and `post_meta`, parses Gutenberg-style block data, URLs, featured images, and nested serialized or JSON values so you get a clear picture of **where each file is used** and what is **unused**.

= Key Features =

* **Full site scan** — Scans all post types, pages, custom post types, templates, and reusable blocks.
* **Gutenberg aware** — Parses block JSON attributes (core/image, core/gallery, core/cover, core/video, core/file, core/media-text, and more) to find media IDs.
* **Page builder support** — Scans media used in Gutenberg, Avada, Elementor, and similar setups that store IDs or URLs in content or meta.
* **Featured image tracking** — Detects when a media item is used as a featured image on any post or custom post type.
* **Post meta scanning** — Finds media in ACF fields, WooCommerce product galleries, and other plugins that store attachment IDs or URLs in meta.
* **Usage detail view** — Open any item to see every post that uses it, with Edit and View links and usage type (content, featured image, meta, gallery, setting).
* **Safe deletion** — Only unused media can be deleted directly; used items can be detached first or removed with **Detach & Delete**.
* **Bulk delete** — Remove multiple unused items in one action.
* **Incremental updates** — Saving a post re-scans that post only, keeping the cache fresh without a full rescan.
* **Filters** — All / Used / Unused, mime type filters, and search by filename.
* **Library overview** — On the main screen: total storage, image vs non-image space, space by file type (bars), largest uploads, and most-referenced media (cached for performance).

= Supported for =

* WordPress Gutenberg (core blocks)
* Elementor
* Avada
* ACF (Advanced Custom Fields)
* WooCommerce (featured image + gallery)
* Builders that store media URLs or IDs in `post_content` or `post_meta`

== Installation ==

1. Upload the `progmaze-media-scanner` folder to `/wp-content/plugins/` (or upload the ZIP in WP Admin).
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Go to **Media → ProgMaze Media Scanner** in your admin menu.
4. Click **Scan All Media** to run the first full scan.

== Frequently Asked Questions ==

= Does this slow down my site? =
No. The scan runs when you click **Scan All Media** or when a post is saved—not on normal front-end views.

= How accurate is the detection? =
Very accurate for typical WordPress setups and the integrations listed above. Custom storage patterns may need manual judgment.

= What happens when I click "Detach & Delete"? =
Featured image references are cleared, `post_parent` is detached, usage rows are removed, then the attachment is permanently deleted.

= Can I undo a deletion? =
No. Back up before bulk deletes.

= Is it compatible with multisite? =
Single-site tested; multisite is planned for a future release.

== How it works ==

When you run **Scan All Media**, the plugin rebuilds its usage cache: it inspects content and meta for attachment IDs, upload URLs, `_thumbnail_id`, WooCommerce galleries, and nested structures. Each link is stored with a usage type. Saving a post triggers a targeted re-scan for that post only.

On **Media → ProgMaze Media Scanner**, filter by used or unused, narrow by type, search by filename, use **View Usage** for details, and delete or **Detach & Delete** as needed. Deletions are permanent—back up first.

== Screenshots ==

1. Main media grid showing used/unused status badges and action buttons.
2. Usage detail modal showing every post/page using a media file with type badges and direct links.
3. Scan progress bar during a full site scan.

== Changelog ==

= 1.0.0 =
* Initial release as **ProgMaze Media Scanner** (distinct from other “media tracker” plugins; internal code prefixes unchanged).

== Upgrade Notice ==

= 1.0.0 =
Initial release.
