Skip to content

feat: expand AI ad detection and harden YouTube blocking #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Edmon02 wants to merge 6 commits into
base: main
Choose a base branch
from
Open

feat: expand AI ad detection and harden YouTube blocking #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0e56fcb
fix: Resolve YouTube playback time and scroll lock issues
Edmon02 Mar 14, 2026
13aad8c
fix: Implement aggressive real-time scroll lock prevention
Edmon02 Mar 14, 2026
3a4b801
fix: Implement scroll position interception to block YouTube's active…
Edmon02 Mar 14, 2026
a339b79
fix: Resolve video autoplay pause issue and enable mouse wheel scrolling
Edmon02 Mar 14, 2026
eab2275
feat: Add AI-powered ad detection with LLM API integration
Edmon02 Apr 24, 2026
4b7cbea
feat: harden YouTube blocking with diagnostics and session rules
Edmon02 May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 144 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,51 +22,75 @@
## Features

### 🎯 Core Functionality

- **YouTube Ad Blocking**: Blocks video ads, overlays, banners, sponsored content, and skippable/non-skippable pre-rolls
- **YouTube Hardening Pipeline**: Combines document-start injection, main-world payload sanitization, player-surface suppression, and runtime session rules
- **Universal Blocking**: Works on all websites including news sites, social media, and sites with Google AdSense
- **500+ Ad Domains**: Comprehensive blocklist covering all major ad networks
- **DeclarativeNetRequest**: Uses Manifest V3's efficient network blocking API

### 🚀 Performance

- **< 50ms Overhead**: Optimized for minimal performance impact
- **Debounced Observers**: Smart MutationObserver implementation prevents CPU spikes
- **Memory Efficient**: Uses WeakSet for element tracking to prevent memory leaks

### 🤖 AI-Powered Ad Detection

- **LLM API Integration**: Connect your own API key from OpenAI, Anthropic, OpenRouter, Groq, or any OpenAI-compatible endpoint
- **Intelligent Classification**: LLM analyzes page element metadata to detect ads that evade traditional pattern-matching
- **Searchable Model Picker**: Browse and search hundreds of models with live pricing from OpenRouter
- **Response Caching**: LRU cache with domain-level pattern learning reduces API calls
- **Smooth Removal**: Detected ads fade out and collapse seamlessly, including parent containers
- **Video Ad Interception**: Main-world player patching neutralizes pre-roll ad queues on streaming/movie sites before they play
- **Privacy-First**: Only element metadata (tag names, classes, dimensions) is sent to your chosen provider — no personal data, cookies, or history

### 🔒 Privacy

- **No Data Collection**: All processing happens locally
- **No Telemetry**: No analytics, tracking pixels, or user profiling
- **Local-First Operation**: Blocking and detection run on-device (optional rule updates can be fetched when auto-update is enabled)
- **Local Diagnostics Export**: YouTube diagnostics can be exported manually for debugging without sending data to a server
- **On-Device ML**: Optional TensorFlow.js-based ad detection runs entirely in your browser
- **Your API Key, Your Control**: AI detection keys are stored locally and never leave your device

### 📊 Features Overview

| Feature | Description |
|---------|-------------|
| Video Ad Blocking | Skips YouTube video ads automatically |
| Banner Ad Blocking | Removes banner ads across all sites |
| Popup Blocking | Prevents popup and overlay ads |
| Anti-Adblock Bypass | Defeats adblock detection scripts |
| Custom Rules | Add your own CSS selectors per site |
| Whitelist | Disable blocking on specific sites |
| Statistics | Track blocked ads and saved time |
| Dark Mode | Full dark theme support |
| Import/Export | Backup and restore settings |
| Feature | Description |
| ---------------------- | ------------------------------------------------------ |
| Video Ad Blocking | Skips YouTube video ads automatically |
| YouTube Session Rules | Runtime DNR session rules harden first-party YouTube ad suppression |
| Payload Sanitization | MAIN-world sanitization strips ad payloads before UI hydration |
| Banner Ad Blocking | Removes banner ads across all sites |
| Popup Blocking | Prevents popup and overlay ads |
| Anti-Adblock Bypass | Defeats adblock detection scripts |
| AI Ad Detection | LLM-powered intelligent ad classification |
| Video Pre-roll Bypass | Intercepts and skips movie/streaming pre-roll ad queues |
| Diagnostics Export | Export local YouTube diagnostics snapshots for missed-ad triage |
| Custom Rules | Add your own CSS selectors per site |
| Whitelist | Disable blocking on specific sites |
| Statistics | Track blocked ads and saved time |
| Dark Mode | Full dark theme support |
| Import/Export | Backup and restore settings |

---

## Installation

### Chrome Web Store (Recommended)
*Coming soon*

_Coming soon_

### Firefox Add-ons
*Coming soon*

_Coming soon_

### Manual Installation

#### Chrome / Chromium-based Browsers

1. Download or clone this repository:

```bash
git clone https://github.com/Edmon02/adeclipse.git
cd adeclipse
Expand Down Expand Up @@ -130,15 +154,22 @@ AdEclipse/
├── src/
│ ├── background/
│ │ ├── background.js # Service worker
│ │ ├── youtube-diagnostics.js # Local YouTube diagnostics manager
│ │ ├── youtube-session-rules.js # Runtime YouTube session rule builder
│ │ ├── storage.js # Settings management
│ │ ├── stats.js # Statistics tracking
│ │ └── rules.js # Dynamic rules
│ ├── content/
│ │ ├── youtube.js # YouTube-specific blocking
│ │ ├── youtube-mainworld.js # MAIN-world YouTube payload sanitizer
│ │ ├── youtube.css # YouTube ad hiding styles
│ │ ├── general.js # General site blocking
│ │ ├── general.css # General ad hiding styles
│ │ └── anti-adblock.js # Adblock detection bypass
│ │ ├── anti-adblock.js # Adblock detection bypass
│ │ ├── ai-scanner.js # AI element scanner
│ │ ├── ai-scanner.css # AI removal animations
│ │ ├── video-ad-interceptor.js # Video pre-roll interceptor
│ │ └── player-mainworld-patch.js # Main-world player ad neutralizer
│ ├── popup/
│ │ ├── popup.html # Popup interface
│ │ ├── popup.css # Popup styles
Expand All @@ -149,7 +180,11 @@ AdEclipse/
│ │ └── options.js # Settings logic
│ └── ml/
│ ├── detector.js # ML-based ad detection
│ └── features.js # Feature extraction
│ ├── features.js # Feature extraction
│ ├── ai-provider.js # Multi-provider LLM client
│ ├── ai-detector.js # AI detection orchestrator
│ ├── ai-cache.js # LRU verdict cache
│ └── prompt-templates.js # LLM prompt engineering
├── icons/
│ └── *.png # Extension icons
└── tests/
Expand All @@ -175,19 +210,22 @@ npm run test:watch

# Run specific test file
npm test -- --testPathPattern=youtube

# Run the YouTube hardening regression slice
npx jest tests/unit/youtube.test.js tests/unit/youtube-diagnostics.test.js tests/unit/youtube-session-rules.test.js tests/unit/storage.test.js --runInBand
```

### Test Structure

```javascript
// Example test for ad detection
describe('YouTubeAdBlocker', () => {
test('should detect video ads', () => {
const adElement = createMockElement('.ytp-ad-module');
describe("YouTubeAdBlocker", () => {
test("should detect video ads", () => {
const adElement = createMockElement(".ytp-ad-module");
expect(isVideoAd(adElement)).toBe(true);
});

test('should skip detected ads', async () => {
test("should skip detected ads", async () => {
const video = createMockVideo({ ad: true });
await skipAd(video);
expect(video.currentTime).toBe(video.duration);
Expand Down Expand Up @@ -237,28 +275,42 @@ Create a new content script or add selectors to `rules/site-selectors.json`:

### Blocking Modes

| Mode | Description |
|------|-------------|
| Balanced | Recommended default with performance optimization |
| Aggressive | Maximum blocking, may affect some content |
| Light | Essential ads only, less intrusive |
| Mode | Description |
| ---------- | ------------------------------------------------- |
| Balanced | Recommended default with performance optimization |
| Aggressive | Maximum blocking, may affect some content |
| Light | Essential ads only, less intrusive |

### YouTube Settings

| Setting | Default | Description |
|---------|---------|-------------|
| Auto-skip | On | Automatically skip skippable ads |
| Skip/End Ad Handling | On | Seeks ad playback to end and triggers skip when available |
| Mute | On | Mute ads during playback |
| Overlay Cleanup | On | Removes YouTube ad overlays and promoted UI elements |
| Setting | Default | Description |
| -------------------- | ------- | --------------------------------------------------------- |
| Auto-skip | On | Automatically skip skippable ads |
| Skip/End Ad Handling | On | Seeks ad playback to end and triggers skip when available |
| Mute | On | Mute ads during playback |
| Document-start inject| On | Registers YouTube scripts as early as possible before hydration |
| Overlay Cleanup | On | Removes YouTube ad overlays and promoted UI elements |
| Diagnostics export | On in Debug | Captures local YouTube diagnostics snapshots for troubleshooting |

### AI Detection Settings

| Setting | Default | Description |
| -------------------- | ------- | ------------------------------------------------ |
| AI Provider | OpenAI | OpenAI, Anthropic, OpenRouter, Groq, or Custom |
| Scan Mode | Smart | Smart (heuristic + AI), AI-only, or AI-assist |
| Confidence Threshold | 70% | Minimum confidence to remove detected elements |
| Continuous Scan | On | Re-scan on dynamic content changes |
| Smooth Removal | On | Animated fade-out and collapse |
| Cache Duration | 24h | How long AI verdicts are cached |

### Performance Settings

| Setting | Default | Description |
|---------|---------|-------------|
| Observer debounce | 100ms | MutationObserver throttling |
| Performance mode | Off | Reduces observation frequency |
| ML detection | Off | Enable TensorFlow.js detection |
| Setting | Default | Description |
| ----------------- | ------- | ------------------------------ |
| Lazy load | On | Defers non-essential scripts |
| Cache blocked UI | On | Reuses known blocked elements |
| Observer debounce | 100ms | MutationObserver throttling |
| ML detection | Off | Enable TensorFlow.js detection |

---

Expand All @@ -268,22 +320,41 @@ Create a new content script or add selectors to `rules/site-selectors.json`:

```javascript
// Get current settings
const settings = await chrome.runtime.sendMessage({ type: 'GET_SETTINGS' });
const settings = await chrome.runtime.sendMessage({ type: "GET_SETTINGS" });

// Update settings
await chrome.runtime.sendMessage({
type: 'UPDATE_SETTINGS',
data: { enabled: true, mode: 'balanced' }
type: "UPDATE_SETTINGS",
data: { enabled: true, mode: "balanced" },
});

// Get statistics
const stats = await chrome.runtime.sendMessage({ type: 'GET_STATS' });
const stats = await chrome.runtime.sendMessage({ type: "GET_STATS" });
console.log(`Blocked today: ${stats.today.adsBlocked}`);

// Record blocked ad
await chrome.runtime.sendMessage({
type: 'INCREMENT_BLOCKED',
data: { type: 'videoAd', domain: 'youtube.com' }
type: "INCREMENT_BLOCKED",
data: { type: "videoAd", domain: "youtube.com" },
});
```

### AI Detection Messages

```javascript
// Scan elements for ads using AI
const results = await chrome.runtime.sendMessage({
type: "AI_SCAN_ELEMENTS",
data: { elements: [{ tag: "div", classes: "ad-banner", ... }] },
});

// Test AI connection
const test = await chrome.runtime.sendMessage({ type: "AI_TEST_CONNECTION" });

// Fetch available models for a provider
const { models } = await chrome.runtime.sendMessage({
type: "AI_FETCH_MODELS",
data: { provider: "openrouter", apiKey: "sk-..." },
});
```

Expand All @@ -292,13 +363,18 @@ await chrome.runtime.sendMessage({
```javascript
// Get site state for current page
const siteState = await chrome.runtime.sendMessage({
type: 'GET_SITE_ENABLED'
type: "GET_SITE_ENABLED",
});

// Request selectors for hostname
const selectors = await chrome.runtime.sendMessage({
type: 'GET_SELECTORS',
data: { hostname: window.location.hostname }
type: "GET_SELECTORS",
data: { hostname: window.location.hostname },
});

// Export local YouTube diagnostics
const diagnostics = await chrome.runtime.sendMessage({
type: "EXPORT_YOUTUBE_DIAGNOSTICS",
});
```

Expand All @@ -311,7 +387,8 @@ const selectors = await chrome.runtime.sendMessage({
1. Make sure AdEclipse is enabled (check the popup)
2. Check if the site is whitelisted
3. Try switching to "Aggressive" mode
4. Add custom selectors for the specific ads
4. Enable Debug Mode and export YouTube diagnostics from Options → Advanced
5. Add custom selectors for the specific ads

### Performance Issues?

Expand All @@ -324,20 +401,21 @@ const selectors = await chrome.runtime.sendMessage({
1. Check for error messages in the browser console
2. Try reloading the extension
3. Clear browser cache and reload the page
4. Check for conflicts with other extensions
4. Re-open the Options page to confirm rules loaded successfully
5. Check for conflicts with other extensions

---

## Browser Compatibility

| Browser | Version | Status |
|---------|---------|--------|
| Chrome | 111+ | ✅ Full support |
| Edge | 111+ | ✅ Full support |
| Firefox | 109+ | ✅ Full support |
| Brave | Latest | ✅ Full support |
| Opera | 97+ | ✅ Full support |
| Safari | - | ❌ Not supported |
| Browser | Version | Status |
| ------- | ------- | ---------------- |
| Chrome | 111+ | ✅ Full support |
| Edge | 111+ | ✅ Full support |
| Firefox | 109+ | ✅ Full support |
| Brave | Latest | ✅ Full support |
| Opera | 97+ | ✅ Full support |
| Safari | - | ❌ Not supported |

---

Expand Down Expand Up @@ -382,7 +460,18 @@ MIT License - see [LICENSE](LICENSE) for details.

## Changelog

### v1.1.0

- **AI-Powered Ad Detection** — connect OpenAI, Anthropic, OpenRouter, Groq, or any OpenAI-compatible LLM to classify and remove ads intelligently
- **Searchable Model Picker** — browse hundreds of models with live pricing from OpenRouter
- **Video Pre-roll Bypass** — main-world player patching intercepts ad queues on streaming/movie sites (JWPlayer, Video.js, Hls.js, Shaka)
- **Empty Space Collapse** — parent containers are recursively collapsed after ad removal, eliminating blank gaps
- **Masked API Key Preview** — saved keys display securely in the settings UI
- **Improved Settings Persistence** — robust rehydration of AI settings on page load with auto-save on input
- **62 Unit Tests** — comprehensive coverage for AI provider, cache, detector, and scanner modules

### v1.0.0 (Initial Release)

- YouTube video ad blocking
- General website ad blocking
- Anti-adblock bypass
Expand All @@ -400,6 +489,7 @@ MIT License - see [LICENSE](LICENSE) for details.
- Manifest V3 migration guidance from Google Chrome team
- Community filter lists for domain references
- TensorFlow.js for ML capabilities
- OpenRouter for multi-model API access and pricing data

---

Expand Down
9 changes: 9 additions & 0 deletions babel.config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"env": {
"test": {
"presets": [
["@babel/preset-env", { "targets": { "node": "current" } }]
]
}
}
}
3 changes: 2 additions & 1 deletion manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@
"resources": [
"rules/*.json",
"src/content/*.js",
"src/content/*.css"
"src/content/*.css",
"src/ml/*.js"
],
"matches": ["<all_urls>"]
}
Expand Down
28 changes: 28 additions & 0 deletions project_plan.prompt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
Build a complete, fully functional browser extension called 'AdEclipse' using Manifest V3 for Chrome and Firefox compatibility. The extension should primarily block all types of ads on YouTube (including video ads, overlay ads, banner ads, sponsored content, and skippable/non-skippable pre-rolls) by intercepting requests, mutating DOM elements, and using content scripts. Then, extend it to block ads on other websites, such as article-based sites like news portals (e.g., CNN, Reddit, or any site with embedded Google AdSense, banners, pop-ups, or interstitials).

Key requirements for sophistication and best user experience:
- **Core Functionality**:
- Use declarativeNetRequest to block ad-related domains and URLs (e.g., googlevideo.com for YouTube ads, doubleclick.net, adservice.google.com for general ads). Include a comprehensive, updatable list of over 500 common ad domains, categorized by site type (YouTube-specific, general web).
- Inject content scripts to dynamically detect and remove ad elements via CSS selectors, XPath, or mutation observers (e.g., hide '.ytp-ad-module' on YouTube, or '.ad-container' on generic sites). Use AI-like heuristics (simple regex or optional TensorFlow.js for pattern recognition) to identify and block evolving ad formats without hardcoding.
- Handle YouTube specifics: Skip ads automatically if possible (simulate skip button clicks), mute during ads, or fast-forward. For other sites: Remove inline ads in articles, sidebars, pop-unders, and auto-playing videos.
- Extensibility: Allow easy addition of new site rules via a JSON config file (e.g., users can add custom domains or selectors for sites like Twitter/X or blogs).

- **Advanced Features**:
- **Machine Learning Integration**: Optionally integrate TensorFlow.js (load via CDN) for on-device ad classification – train a simple model (provide sample code) to detect ad images/text based on keywords, sizes, or positions, falling back to rule-based if disabled for performance.
- **Performance Optimization**: Use lazy loading for scripts, debounce mutation observers to avoid CPU spikes, and cache blocked elements. Ensure the extension doesn't slow down page loads (target <50ms overhead).
- **User Customization**: Include a popup UI with toggles for enabling/disabling per-site (whitelist/blacklist), ad types (e.g., video vs. banner), and modes (aggressive vs. light blocking). Add a stats dashboard showing blocked ads count, data saved, and time saved (e.g., 'Skipped 5 ads today, saving 2 minutes').
- **Privacy and Security**: No data collection; all processing local. Handle edge cases like ad blockers detectors (anti-anti-adblock) by spoofing requests or injecting stealth scripts.
- **UI/UX Polish**: Use modern web tech (HTML/CSS/JS with Tailwind CSS or Bootstrap for styling). Popup should be responsive, dark-mode compatible, with animations (e.g., fade-out for removed ads). Options page for advanced settings, import/export rules, and auto-updates from a GitHub repo (fetch JSON rules periodically).
- **Error Handling and Logging**: Robust try-catch, console logging only in debug mode, and a report bug feature that sends anonymized logs to a placeholder email.
- **Testing and Compatibility**: Provide unit tests (using Jest) for key functions like ad detection. Ensure it works on mobile browsers if possible. Handle updates to YouTube/web APIs by making selectors configurable.

Structure the project as a ZIP-ready folder with:
- manifest.json (V3 compliant, with permissions: declarativeNetRequest, storage, tabs, webRequest, etc.).
- background.js for request blocking and event handling.
- content.js for DOM manipulation.
- popup.html/js/css for the UI.
- options.html/js for settings.
- rules.json for ad domains/selectors (initially populated with YouTube and 10+ common sites like nytimes.com, forbes.com).
- Include a README.md with installation instructions, how to build/test, and how to extend for new sites.

Output the full code for all files, zipped structure description, and any setup commands (e.g., for loading in Chrome). Make it sophisticated, production-ready, and focused on delivering the smoothest ad-free experience without breaking site functionality.
Loading