=== Capo - Head Optimizer ===
Contributors: rviscomi
Donate link: https://rviscomi.dev/
Tags: performance, speed, head, seo, web-vitals
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.1.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Automatically reorders the HTML head of your WordPress pages for optimal browser rendering performance using the Capo.js methodology.

== Description ==

In standard WordPress sites, WordPress Core, themes, SEO plugins, analytics scripts, and third-party plugins inject elements into `wp_head()` in arbitrary order. This can lead to critical performance pitfalls:

* **Delayed Title Tag Rendering:** SEO metadata and large JSON-LD blocks placed before `<title>`.
* **Delayed Resource Discovery:** Preconnects, preloads, and async scripts pushed below dozens of CSS stylesheets.
* **Render-Blocking Bottlenecks:** External synchronous scripts blocking CSS and parser execution.

**Capo solves this automatically.** By intercepting the page response via output buffering, Capo uses a deterministic, stable sorting algorithm to reorder `<head>` elements strictly according to browser critical rendering path priorities.

### The Capo Head Priority Spectrum

Capo organizes elements into 11 strict priority tiers (Weight 10 down to 0):

1. **Weight 10 (Critical Meta & Viewport):** `<base>`, `<meta charset>`, `<meta name="viewport">`, critical `http-equiv` headers (CSP, origin-trial, accept-ch).
2. **Weight 9 (Title):** `<title>`.
3. **Weight 8 (Preconnect):** `<link rel="preconnect">`.
4. **Weight 7 (Async Script):** `<script src="..." async>`.
5. **Weight 6 (CSS @import Styles):** `<style>` blocks containing `@import` rules.
6. **Weight 5 (Sync / Inline Scripts):** Synchronous/inline JavaScript (`<script>` without defer/async).
7. **Weight 4 (Stylesheets & Style Blocks):** `<link rel="stylesheet">`, `<style>` blocks.
8. **Weight 3 (Preload):** `<link rel="preload">`, `<link rel="modulepreload">`.
9. **Weight 2 (Defer Script):** `<script src="..." defer>`, `<script src="..." type="module">`.
10. **Weight 1 (Prefetch / Prerender):** `<link rel="prefetch">`, `<link rel="dns-prefetch">`, `<link rel="prerender">`, `<script type="speculationrules">`.
11. **Weight 0 (Other Metadata):** OpenGraph, Twitter cards, Schema JSON-LD, RSS feeds, favicons, robots metadata.

### Features

* **Zero Configuration:** Activate the plugin and your `<head>` is immediately optimized.
* **Deterministic Stable Sort:** Equal-weight elements retain their exact relative order, preserving CSS cascade specificity and JavaScript dependencies.
* **Full Cache Compatibility:** Works seamlessly with WP Super Cache, W3 Total Cache, WP Rocket, LiteSpeed Cache, and Cloudflare.
* **Safe HTML Tokenizer:** Respects HTML comments, conditional comments (`<!--[if ...]>`), CDATA blocks, and inline script markup.
* **Site Health & Admin Diagnostics:** Real-time `<head>` hygiene warnings and diagnostic status in Tools > Site Health and Admin Toolbar.
* **Testing & Bypass Mode:** Append `?capo=off` to any frontend URL to inspect the un-reordered head.

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/capo-head-optimizer` directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. If you use a page caching plugin (e.g. WP Super Cache, WP Rocket), clear/flush your cache.

== Frequently Asked Questions ==

= Does Capo break script dependencies or stylesheet cascading? =
No. Capo uses a deterministic stable sort. If you have multiple stylesheets (all Weight 4) or multiple scripts (all Weight 5), they will maintain their exact original relative order.

= Does Capo work with page caching plugins? =
Yes. Page caching plugins capture the output buffer generated by WordPress. With Capo activated, the cached HTML stored on disk or in memory will already have its `<head>` sorted, incurring 0ms runtime overhead for cached visitors.

= How can I test the difference? =
You can view any page with `?capo=off` appended to the URL to bypass reordering and compare your raw `<head>` output against the optimized output.

== Screenshots ==

1. Capo reordering status visible in WordPress Site Health diagnostics.
2. Debug performance metrics comment in HTML source code.

== Changelog ==

= 0.1.3 =
* Added support for Speculation Rules API (`<script type="speculationrules">`) classified as Weight 1 (Prefetch / Prerender) matching `@rviscomi/capo.js` v2.2.1.
* Enhanced HTML tokenizer and attribute parsing to robustly preserve tags with `>` inside quoted attributes, boolean attributes, and empty string attributes.
* Added full support for HTML conditional comments (`<!--[if ...]>`) and CDATA sections in `<head>`.
* Hardened Admin Toolbar diagnostic injection against regex backreference exploits using safe substring replacement.
* Added pass-by-reference `$analysis` parameter and static accessor/reset methods to Parser for optimized memory lifecycle management.
* Extended Site Health loopback check request timeout to 10 seconds via dynamic filter.
* Consolidated test bootstrap harness and added CI matrix testing across PHP 7.4 through 8.3.

= 0.1.2 =
* Adhered strictly to WordPress.org Plugin Directory guidelines and security standards.
* Changed debug performance HTML comment to opt-in by default and removed external URLs.
* Added uninstall.php handler to clean up database options on deletion.
* Fixed PHP 7.4 backwards compatibility in origin trial subdomain validation.
* Removed insecure sslverify override from Site Health loopback check.
* Enforced 5-tag maximum limit in readme metadata.

= 0.1.1 =
* Added `<head>` validation engine with Origin Trial binary token decoding and origin/expiry checks.
* Added live page diagnostics to frontend WordPress Admin Toolbar with scrollable warnings dropdown.
* Added HTML syntax highlighting and decoded token metadata table in WordPress Site Health.
* Improved toolbar integration and output buffering lifecycle.

= 0.1.0 =
* Initial public beta release.
* Output buffering engine for automatic `<head>` reordering.
* 1:1 parity with `@rviscomi/capo.js` rules and validation engine.
* Site Health integration and bypass mode (`?capo=off`).

== Upgrade Notice ==

= 0.1.3 =
Adds Speculation Rules API classification, tokenizer robustness for conditional comments/CDATA/quoted attributes, Admin Bar security hardening, and parity with capo.js v2.2.1.

= 0.1.2 =
Adds full WordPress.org directory compliance, opt-in debug comments, uninstall cleanup, and PHP 7.4 compatibility improvements.

= 0.1.1 =
Includes validation engine, Admin Toolbar live diagnostics, and enhanced Site Health inspection.
