=== RobArt CatchNet ===

Contributors: robword
Tags: performance, debugging, layout shift, cls, fouc
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.8.10
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Copyright: Copyright © Rob Art | Illustration 2026

Watches a page load and names the CSS rule behind FOUC flashes, layout shifts, phantom scroll and lingering overlays — the culprit, not a score.

== Description ==

**Fix the cause, not the score.** RobArt CatchNet watches your page paint during load, then tells you the **exact CSS rule** behind the problem — a white/unstyled flash, a layout shift, a phantom horizontal scroll, an overlay that never went away. Other tools hand you a number; CatchNet names the culprit selector and the moment it happened.

It runs only for logged-in administrators, on the front end. Your visitors never load it and it adds nothing to their page.

Open it from the **CatchNet** item in the front-end admin bar. A floating panel records the early frames of the load and lets you scrub through them.

**What it catches**

* Transient flashes — a value that appeared then reverted (the classic white/unstyled flash).
* Unstyled / FOUC flashes before the real styles land.
* Layout shifts (CLS) — an element whose box jumps abruptly as content reflows or a late image sizes.
* Phantom horizontal scroll — content wider than the viewport, naming the element that overhangs.
* Content shrink and rogue positioning during load.
* Lingering overlays — a splash or modal that never cleaned itself up.

**How it helps**

* **Most likely cause** — a single ranked verdict naming the culprit selector, the frame, and a confidence score. When several detectors agree, confidence rises.
* **Findings** — every issue detected, ranked; click one to jump to its frame; dismiss anything that isn't a real bug.
* **Scrub the load** — step through the recorded frames and see the winning CSS rule for each watched property at every moment.
* **Reproduce a frame** — re-apply a recorded frame's state to the live page so the bug snaps back on screen, then restore it exactly.
* **Copy report** — a plain-text summary of the verdict, findings and inspected frame, ready to paste into a bug report or an AI chat.
* **Watch list** — auto-detects suspicious elements each load, and lets you watch a specific element by clicking it or typing a CSS selector.
* **See-through mode** — make the panel transparent so you can watch the page underneath while it stays open; tune how transparent at rest and how solid on hover.

Everything is deterministic — a rule engine, not a guess. Nothing about your page is sent anywhere.

= Free vs Pro =

Free is the whole diagnostic: the recorder, the panel, the ranked verdict, findings, reproduce, copy report, the watch list and see-through mode.

Pro adds the **Visual filmstrip**: a real, saveable reconstruction of how the page *looked* at each recorded frame. Snapshot one frame or build the whole strip; frames with a finding are marked; click a thumbnail for a big pop-out view with prev/next arrows; and export the frames as a ZIP (WebP or PNG). Reconstructions are produced entirely in your browser — nothing is uploaded. Only the paid Pro add-on validates a licence key with the author's licence server; the free plugin makes no external calls.

== Installation ==

1. Upload to `/wp-content/plugins/robart-catchnet` (or install via the Plugins screen).
2. Activate via the **Plugins** menu.
3. View any page on the front end while logged in as an administrator, and click **CatchNet** in the admin bar.
4. Settings and licence live under **Tools → CatchNet**.

== Uninstall ==

When you delete RobArt CatchNet from the Plugins screen, its uninstall script runs automatically and removes everything the plugin stored in your WordPress database:

* The see-through opacity settings and the filmstrip export format
* The stored licence record and its cached licence tier (Pro)
* Older settings left over from before the plugin was renamed

CatchNet keeps nothing else on your server. Your dismissed findings, watch list and panel layout are saved in your own browser (local storage), not on the site, so they stay in that browser until you clear its site data.

Deactivating the plugin without deleting it keeps your settings.

== Frequently Asked Questions ==

= Does this run for my visitors? =

No. CatchNet only loads for logged-in administrators on the front end. Visitors and non-admins never load any of it, so it adds nothing to a real visitor's page.

= Does it send my page anywhere? =

No. The diagnostic runs entirely in your browser. The Pro Visual filmstrip also reconstructs frames locally — no image is uploaded. Only the paid Pro add-on contacts the author's licence server, and only to validate your licence key and site URL.

= Why does the panel say "an unidentified rule" sometimes? =

Some flashes are caused by a style applied directly by JavaScript (an inline style), not by a stylesheet rule. There is no CSS selector to name in that case, so CatchNet says so honestly rather than blaming the wrong rule.

= The panel stutters an animation while I'm testing. =

The recorder samples the page as it loads, which can briefly compete with a page's own load-time animation on your admin view (never a visitor's). It samples every other frame to minimise this; a splash or heavy animation will still be perfectly smooth for your visitors.

= What is the Visual filmstrip? =

A Pro feature that reconstructs how the page actually looked at each recorded frame as a real image, so you can see the flash or shift, not just read about it. Export the strip as a ZIP to attach to a bug report.

== Screenshots ==

1. The floating panel — ranked verdict, findings and the frame scrubber.
2. Frame detail — the winning CSS rule per property at the inspected frame.
3. The Visual filmstrip (Pro) — a reconstruction of every load frame.
4. A frame popped out for a closer look, with prev/next arrows.
5. Tools → CatchNet — status, see-through sliders, licence and export options.

== Changelog ==

= 0.8.10 =
* Changed: the front-end recorder is now loaded through WordPress's standard enqueue system (register plus enqueue) rather than a printed tag, while still running in the document head ahead of the stylesheets so it can sample the first paint. No change to behaviour. (WordPress.org compliance.)

= 0.8.9 =
* Fixed: "Reproduce a frame" no longer distorts the page around the diagnostic notice — the reconstruction never re-anchors fixed elements, so the on-page finding notice stays a clean floating overlay instead of appearing to drop into the layout.
* The on-page finding notice now has a larger, clearer warning icon.
* Tools → CatchNet now shows an in-page overview of what Pro adds and its one-off pricing (single site, five sites, unlimited), replacing the licence-key field the free build can't include.

= 0.8.8 =
* Fixed: the diagnostic panel no longer reports its own floating window as a lingering overlay — CatchNet now excludes its own interface from the page it inspects, so findings describe the page under test, not the tool.
* Fixed: the panel's icons are escaped at the point of output, satisfying the WordPress.org output-escaping checks with no change to what you see.
* Translation template (POT) added under /languages.

= 0.8.7 =
* WordPress.org compliance pass (PCP + scanner): the engine, panel and Visual scripts and the panel stylesheet now load through the standard enqueue system with proper dependencies; the recorder stays inline in the document head (it must run before the page styles to catch the first paint). Input on the settings page is sanitised on read, and the short description trimmed. No functional change.

= 0.8.6 =
* The scrubber's on-page bug notice is now tier-aware: Pro points to the Visual filmstrip; free explains the bug was detected and that Pro reconstructs it — no dangling of a feature you don't have.
* Reliability: if the filmstrip is built but a detected bug can't be re-drawn on the finished page (every frame identical), it now says so honestly instead of showing identical frames as if nothing happened.

= 0.8.3 =
* The Visual filmstrip now reconstructs layout shifts: the recorder watches a dimension-less image (or flat block) from its collapsed state, and reproducing an early frame restores that geometry, so the shift is visible frame-to-frame.
* The on-page finding notice is hidden while the filmstrip renders, so it never flashes on the page or appears in a thumbnail.

= 0.8.2 =
* The frame scrubber now shows an on-page notice when the current frame carries a detected issue, so scrubbing a transient bug (which the finished page can't re-draw) no longer looks like nothing is wrong — it points you to the Visual filmstrip.
* The filmstrip scrolls the highlighted frame into view as you scrub.
* The filmstrip reconstruction shows a load flash more faithfully (it paints the frame's recorded page background), and the scrubber range now covers every recorded frame, including the late post-load checkpoints.

= 0.8.1 =
* Pro gating is now real: the tier resolves from an admin bypass, a dev-config bypass, or a validated licence, and the Visual filmstrip only appears when Pro is active.
* New Tools → CatchNet settings page: status, licence activation, filmstrip export format (WebP/PNG), and see-through opacity sliders, in the standard two-column layout with an About / Support / Credits sidebar.
* The filmstrip now opens each frame in a pop-out viewer (bigger image, prev/next arrows, per-frame download) and exports all rendered frames as a ZIP.
* Bundled documentation: a User Manual, README and Licence, viewable inside the plugin.
* Plugins-screen row links (Settings / Docs / Support).

= 0.8.0 =
First public build. The full diagnostic (recorder, panel, ranked verdict, findings, reproduce, copy report, watch list, see-through mode) plus the Pro Visual filmstrip with a pop-out viewer and ZIP export. Nine detection rules for flashes, layout shifts, phantom scroll, content shrink, rogue positioning and lingering overlays.

== Upgrade Notice ==

= 0.8.7 =
WordPress.org compliance pass — enqueue, sanitise, readme.

= 0.8.6 =
Tier-aware bug notice; filmstrip is honest when it can't reconstruct.

= 0.8.3 =
The filmstrip now shows layout shifts; notice hidden during render.

= 0.8.2 =
Scrubber now flags bug frames on-page; filmstrip + flash fixes.

= 0.8.1 =
Real Pro gating, a settings page, the filmstrip pop-out viewer + ZIP export, and bundled docs.

= 0.8.0 =
First public build of RobArt CatchNet.
