# JetBlocker 2.1 - Developer Guide

## Runtime architecture
- WordPress Settings API stores configuration in `jetblocker_settings`.
- The front-end runtime is native JavaScript and does not require jQuery.
- Detection details are exposed in `window.JetBlockerLastDetection` when a scan completes.
- Debug logs use the `[JetBlocker]` console prefix.

## Detection signals
JetBlocker 2.1 can combine:
1. Local blocker-sensitive `assets/js/ads.js` canary.
2. Multiple dynamic DOM bait selectors commonly affected by cosmetic filters.
3. Remote advertising-script canary in Enhanced/Maximum modes.
4. Existing ad-element visibility inspection in Maximum mode.
5. Delayed rescans in Maximum mode.

A positive supported signal is treated as ad blocking. Remote canary errors can also be caused by CSP, DNS/network policy, or upstream filtering, so Maximum/Enhanced should be tested against the target production environment.

## JavaScript events
JetBlocker dispatches:
- `jetblocker:detected`
- `jetblocker:clear`

Example:

```js
document.addEventListener('jetblocker:detected', (event) => {
    console.log('Blocked', event.detail);
});
```

## PHP helper
Theme/plugin developers can wrap ad markup with:

```php
echo jetblocker_revenue_slot( $primary_html, array( 'class' => 'my-slot' ) );
```

## Shortcodes
Conditional recovery slot:

`[jetblocker_recovery_slot class="sidebar-ad"][your_ad_shortcode][/jetblocker_recovery_slot]`

Always-first-party creative:

`[jetblocker_first_party]`

## Security model
- Admin settings require `manage_options`.
- Settings are sanitized through one Settings API callback.
- Event endpoints use WordPress nonces.
- The administrator detector-test URL uses a dedicated nonce.
- Front-end text and URLs are escaped/sanitized before output.

## Caching/CDN considerations
After plugin upgrades, purge page cache, object cache where relevant, optimization/minification cache, and CDN cache. Verify that `assets/js/jb-runtime.js` is not being combined in a way that defers it beyond page interaction. If a script optimizer rewrites or delays external canary creation, exclude the JetBlocker runtime from JavaScript delay as a troubleshooting step.

## Production release checklist
- Lint all PHP files on PHP 8.0+.
- Syntax-check all JavaScript files.
- Test logged-out frontend behavior.
- Test Standard/Enhanced/Maximum modes.
- Test with at least one network blocker and one cosmetic-filter blocker.
- Test cache/minification enabled and disabled.
- Test Chrome/Chromium, Firefox, and Safari/WebKit where supported.
- Test mobile layout.
- Verify no false popup with ad blockers disabled.
- Verify recovery shortcode behavior.