# SafeGaze Browser Scripts

A collection of browser scripts designed to enhance digital wellbeing and provide a safer, more focused browsing experience. These scripts work with the SafeGaze browser extension to block distracting content and track usage patterns.

## 🌟 Overview

SafeGaze scripts help you:
- **Limit exposure to addictive short-form content** (Facebook Reels, YouTube Shorts)
- **Block advertisements** on YouTube
- **Track your time** spent on websites with detailed analytics
- **Regain control** over your digital habits

## 📦 Available Scripts

### 1. Facebook Reels Blocker
**Version:** 1.0.0 | **Updated:** December 28, 2025

Limit the time spent watching Facebook Reels with configurable rate limiting and scroll blocking.

**Features:**
- Rate limiting with configurable daily limits
- Scroll and navigation blocking within Reels
- Automatic overlay display when limit is reached
- Mouse hover tracking for Reels containers
- Works across page navigations (SPA)
- CSP-compliant implementation
- Network-level blocking patterns for mobile devices

**Technical Details:**
- Uses postMessage bridge for rate limit communication
- Detects Reels via multiple selectors and URL patterns
- Prevents scroll, keyboard, and touch navigation
- Shows countdown timer with progress bar

### 2. YouTube Shorts Blocker
**Version:** 1.0.0 | **Updated:** December 28, 2025

Hide YouTube Shorts from feeds and limit viewing time when you do watch them.

**Features:**
- Hides Shorts from homepage, search results, and channel pages
- Rate limiting with configurable time windows
- Scroll blocking within Shorts player
- Automatic limit overlay with countdown
- Continuous DOM monitoring for dynamically loaded content
- Context-aware detection for different page types
- Mobile YouTube support (ytm-* selectors)

**Technical Details:**
- Comprehensive CSS hiding with 60+ selectors
- DOM observer for dynamic content removal
- Adaptive monitoring intervals based on page type
- Grid reflow optimization to prevent layout issues
- Touch, keyboard, and scroll event blocking

### 3. YouTube Ads Blocker
**Version:** 2.0.0 | **Updated:** December 28, 2025

Advanced 4-layer YouTube ad blocking system with enhanced December 2025 selector support.

**Features:**
- **Layer 1:** Player data interception (ytInitialPlayerResponse, fetch, XHR hooks)
- **Layer 2:** Network-level URL pattern blocking
- **Layer 3:** DOM-based fallback detection and skipping
- **Layer 4:** Feed ad monitoring and removal
- Auto-skip video ads with instant jumping
- Hide sponsored content from home/search feeds
- Remove ad overlays and banners
- Grid reflow optimization

**Technical Details:**
- Updated ad container selectors (ytd-ad-slot-renderer, etc.)
- Modern badge detection (ad-badge-view-model, badge-shape)
- Enhanced fetch() interception skipping video CDN
- Comprehensive CSS hiding for 2025 YouTube structure
- Sponsored content detection with strict validation

### 4. Site Time Tracker
**Version:** 1.0.0 | **Updated:** December 28, 2025

Universal site time tracking that works on ALL websites with accurate incremental tracking.

**Features:**
- Accurate delta-based time tracking (prevents overwrites)
- Persistent sessions across navigation (same tab)
- Auto-reset on hard refresh
- Rolling 7-day weekly statistics
- Real-time popup notifications every 10 minutes
- Daily and weekly time summaries
- CSP-compliant implementation
- Works on all domains with automatic TLD detection

**Technical Details:**
- Incremental (delta) updates every 60 seconds
- Session persistence via sessionStorage
- Navigation detection via Performance API
- Automatic cleanup of data older than 7 days
- Popup with session, daily, and weekly time display
- Country-specific TLD handling (co.uk, com.au, etc.)

## 🚀 Installation

### Requirements
- **Minimum Extension Version:** 3.4.1
- **Browser:** Chrome, Firefox, Edge, Safari, or any Chromium-based browser
- **Permissions:** ActiveTab, Storage, and appropriate host permissions

### Setup Instructions

1. **Install SafeGaze Extension**
   - Install from your browser's extension store
   - Or sideload the extension in developer mode

2. **Add Scripts**
   - Each script can be enabled/disabled individually
   - Scripts auto-update when new versions are available
   - Configuration options available in extension settings

3. **Verify Installation**
   - Check browser console for `[SafeGaze]` log messages
   - Look for script indicators on supported websites
   - Test functionality on target platforms

## 🔧 Configuration

Most scripts work out of the box with sensible defaults, but can be customized:

- **Rate Limits:** Adjust daily time limits for Reels/Shorts
- **Tracking:** Enable/disable time tracking per domain
- **Notifications:** Configure popup frequency and style
- **Blocking:** Choose aggressive or standard blocking modes

## 🛡️ Technical Specifications

### Platform Compatibility
- **Desktop:** Chrome 90+, Firefox 88+, Edge 90+, Safari 14+
- **Mobile:** Android WebView, iOS WKWebView (via SafeGaze mobile app)
- **Architecture:** Multi-world script execution (MAIN + ISOLATED worlds)

### Security & Privacy
- **CSP Compliant:** All scripts work with strict Content Security Policy
- **No External Calls:** All processing happens locally
- **No Telemetry:** No data is sent to external servers
- **Storage:** Uses browser localStorage/sessionStorage only

### Performance Optimizations
- **Zero-Cloning:** Modifies objects in-place where possible
- **Selective Interception:** Skips video CDN traffic to prevent buffering
- **Debounced Operations:** Batches DOM mutations for efficiency
- **RequestAnimationFrame:** Uses browser-optimized rendering timing

## 🔍 Script URLs

Each script is hosted on GitLab with SHA256 integrity verification:

```
Facebook Reels Blocker:
https://gitlab.kahf.co.uk/kahf-browser-scripts/safegaze-scripts/-/raw/main/facebook-reels-blocker/facebook-reels-blocker.js

YouTube Shorts Blocker:
https://gitlab.kahf.co.uk/kahf-browser-scripts/safegaze-scripts/-/raw/main/youtube-shorts-blocker/youtube-shorts-blocker.js

YouTube Ads Blocker:
https://gitlab.kahf.co.uk/kahf-browser-scripts/safegaze-scripts/-/raw/main/youtube-ads-blocker/youtube-ads-blocker.js

Site Time Tracker:
https://gitlab.kahf.co.uk/kahf-browser-scripts/safegaze-scripts/-/raw/main/site-time-tracker/site-time-tracker.js
```

### Development Guidelines
- Maintain CSP compliance (no inline scripts/styles in HTML)
- Use defensive coding (check for null/undefined)
- Add console logging for debugging (`[SafeGaze]` prefix)
- Ensure cross-browser compatibility
- Document complex logic with comments