=== AssetPilot - Granular control over frontend assets ===
Contributors: amrelarabi
Tags: performance, scripts, defer, dequeue, page-speed
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Conditionally disable, defer, and preload scripts and styles — with page scans, safety checks, and Safe Mode.

== Description ==

**AssetPilot** helps you speed up WordPress by controlling **which scripts and styles load on which pages** — without guessing handle names in `functions.php`.

Scan a real page URL, see every enqueued asset (and many from the HTML), then create rules to **disable**, **defer**, **async**, **preload**, or set **fetch priority** — only where your conditions match (homepage, shop, mobile, logged-in users, specific URLs, and more).

Built for site owners who want measurable wins and for developers who want **conditional dequeue with guardrails**: validation warnings, dependency insight, scan history, and **Safe Mode** if something breaks.

= Why AssetPilot instead of a simple “unload” plugin? =

* **See before you change** — scan a URL and browse assets with origin, size, and usage hints.
* **Rules, not one-off hacks** — reusable conditions (page type, archive, WooCommerce views, device, auth, URL).
* **Bulk actions** — one rule for many handles (e.g. a plugin’s scripts everywhere except checkout).
* **Safer changes** — conflict checks, impact preview, optional verification, automatic runtime pause after repeated errors.
* **Stay in control** — dependency graph, recommendations, debug logs, and Safe Mode.

= What you can do =

* Disable scripts and styles you do not need on specific views
* Defer or async JavaScript to reduce render-blocking work
* Preload critical scripts, styles, fonts, and images
* Set `fetchpriority` on images and preloads
* Target by singular page, post type, archive, URL fragment, query string, device, login state, user role, WooCommerce page type, and scan URL
* Create **bulk rules** from the asset list
* Review **optimization recommendations** from scan data
* Explore **asset dependencies** in a visual graph
* Keep **scan history** and compare what changed over time

= Typical use cases =

* Stop a plugin’s CSS/JS on pages where it is not used (blog posts, landing pages, archives)
* Defer non-critical scripts on catalog pages while keeping checkout intact
* Preload hero fonts or LCP images on key templates only
* Audit what Elementor, WooCommerce, or form plugins actually enqueue before tightening rules

= How it works =

1. Open **AssetPilot → Assets** and scan a page (your homepage, a product page, a form page, etc.).
2. Pick an asset (or select several for a bulk rule).
3. Choose an action and **conditions** (where the rule applies).
4. Review validation and impact, then save.
5. Visit the front end — use **Safe Mode** anytime you need to disable all runtime rules instantly.

The block editor includes an **AssetPilot** sidebar on supported setups so you can jump from a post to asset management with context.

= Requirements =

* WordPress 6.2+
* PHP 8.1+
* Administrator access to configure rules

Frontend runtime changes apply to **public site views**, not the WordPress admin dashboard.

== Installation ==

1. Install and activate **AssetPilot** from the Plugins screen (or upload the `assetpilot` folder to `/wp-content/plugins/`).
2. In the admin menu, open **AssetPilot**.
3. Go to **Assets**, enter a page URL, and run a scan.
4. Create your first rule from any row in the results table.

No command-line build is required for normal use on WordPress.org installs.

== Getting started ==

**First rule in a few minutes**

1. **Assets** → enter your site homepage URL → scan.
2. Find a script or style from a plugin you suspect is unnecessary on the homepage.
3. Click to create a rule → choose **Disable** (or **Defer** for scripts).
4. Set a condition such as “this scan URL only” or “non-WooCommerce pages” if you are testing carefully.
5. Save, open the homepage in a private window, and confirm the site still works.

Use **Recommendations** after a few scans for ideas (duplicate libraries, large files, low usage patterns).

**Create Rule** is opened from assets or recommendations — it is the guided wizard for actions, conditions, validation, and review.

== Safe Mode ==

If the site looks wrong after applying rules, enable Safe Mode while logged in as an administrator:

`/wp-admin/?assetpilot-safe-mode=1`

Safe Mode turns off **all frontend runtime rule changes** for the whole site. The admin UI, REST API, scanning, and rule editing still work. Clear any page cache after enabling if changes seem to stick.

If repeated frontend fatals occur, AssetPilot **pauses runtime rules for 30 minutes** automatically. Resume early from **Settings** or:

`/wp-admin/admin.php?page=assetpilot-settings&assetpilot-resume-runtime=1`

== Screenshots ==

1. Dashboard — scan progress and quick entry to asset tools
2. Assets Explorer — scripts and styles found on a scanned URL
3. Create Rule — choose action, asset, and conditions in steps
4. Conditions — page, URL, device, WooCommerce, and more
5. Bulk rule — apply one action to multiple handles
6. Dependency graph — see what depends on what before disabling
7. Recommendations — suggested optimizations from your scans
8. Settings — Safe Mode, logging, and runtime status

== Frequently Asked Questions ==

= Will this break my site? =

Any plugin that changes how assets load can break layouts or checkout if rules are too aggressive. AssetPilot reduces risk with validation messages, dependency information, Safe Mode, and automatic runtime pause after errors. Start with narrow conditions (one URL or one page type), test, then expand.

= Will AssetPilot improve my PageSpeed or Core Web Vitals score? =

It can help by removing or deferring assets that should not run on a given view. Results depend on your theme, hosting, caching, and which plugins enqueue heavy scripts. AssetPilot shows what is loaded so you can make informed cuts — it is not a full-page cache or image optimizer.

= How is this different from “Asset CleanUp” or “unload” plugins? =

Those tools focus on unloading assets per page. AssetPilot emphasizes **conditional rules**, bulk targeting, scan history, dependency graph, recommendations, validation, and verification workflows in one admin app — aimed at repeatable, auditable performance work.

= Does it work with WooCommerce? =

Yes. Conditions can target shop, product, cart, checkout, and account views so you can keep payment scripts where they are needed.

= Does it work with Elementor and page builders? =

Yes. Scan Elementor-built pages to see builder assets, then create rules with page-level conditions. Test carefully on editor and preview URLs; use Safe Mode if a template looks wrong.

= Does it work with Contact Form 7 and other plugins? =

Scan pages with and without the form (or feature). Disable or defer that plugin’s handles only on views where the shortcode or block is not present.

= Does AssetPilot change the WordPress admin? =

No. Rules target **frontend** delivery for visitors (subject to your conditions). Admin and block editor tooling are for configuration only.

= Do I need to edit code? =

No. Everything is configured in the AssetPilot admin UI. Developers can extend behavior via documented PHP hooks (see Development).

= Where is the source code? =

https://github.com/amrelarabi/assetpilot

== Development ==

**Source repository:** https://github.com/amrelarabi/assetpilot

Human-readable UI source is in `assets/src/`. Production bundles in `assets/build/` are built with [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts).

**Build (contributors only):**

1. `npm install`
2. `npm run build`

PHP lives under `includes/` (Composer PSR-4, `AssetControl\` namespace).

**Third-party frontend libraries:** `@xyflow/react` (dependency graph), `react-select` (rule builder fields).

**Extension hooks:** `assetpilot_rest_register`, `assetpilot_admin_localize`, `assetpilot_admin_menu_pages`, `assetpilot_scan_saved`, `assetpilot_condition_handlers`, `assetpilot_site_key_scan_urls`, `assetpilot_site_key_scan_max_urls`, `assetpilot_key_pages_scan_complete`

== Changelog ==

= 1.0.0 =
* Initial release on WordPress.org
* Page asset scanning and Assets Explorer
* Rules: disable, defer, async, preload, fetch priority
* Advanced conditions (URL, device, auth, roles, WooCommerce, singular, archives, scan URL)
* Bulk rules, validation pipeline, impact preview
* Dependency graph and optimization recommendations
* Scan history, debug logs, Safe Mode, and automatic runtime pause on errors
* Block editor sidebar entry point

== Upgrade Notice ==

= 1.0.0 =
First public release. Scan a page, create a narrow rule, and test before applying site-wide conditions.
