🎯 Meme Gatekeeper

A Chrome extension that helps you manage time spent on social media by displaying a fun meme overlay when you exceed your usage limit.

⚡ Forked from Cat Gatekeeper by ZOKUZOKU
Original extension: Cat Gatekeeper

✨ Features

⏱️ Time Management

• Set usage limit (1-480 minutes)
• Set break time (1-60 minutes)
• Global unified timer: Time is accumulated across all tracked domains (YouTube + Facebook + custom sites combined)

📱 Target Sites

• Pre-configured for: X (Twitter), Facebook, Reddit, YouTube, Threads, Bluesky
• Custom domain support: Add your own target domains
• Visual domain list with add/remove functionality

🎬 Custom Assets

• Upload local files (video/image) or enter URL
• Two asset slots:
  • Active: Shows at the start of break
  • Idle: Loops during break time
• Sources links provided: Giphy, Tenor, Pixabay, Coverr
• Reset to default neko anytime
• Maximum file size: 5MB

🌍 Multi-language Support

• English
• Tiếng Việt (Vietnamese)
• 日本語 (Japanese)
• 简体中文 (Chinese)
• 한국어 (Korean)
• Français (French)
• Español (Spanish)
• Português (Portuguese)
• हिन्दी (Hindi)

🎮 Developer Tools

• Preview/Test Button: Test the gate on any website
• Draggable countdown: Position the break timer anywhere on screen
• Draggable corner timer: Float timer showing remaining time, can be dragged to any position (position saved across sessions)

📊 Usage Progress

• Real-time progress bar in popup showing how much time has been used
• Reset button to manually reset the global timer

🎨 UI Features

• Dark theme with orange accent color
• Responsive design
• Smooth animations and transitions

📦 Installation

1. Clone this repository or download the code
2. Open Chrome and navigate to chrome://extensions/
3. Enable Developer mode (top right corner)
4. Click Load unpacked and select the extension folder
5. Configure your settings in the popup

📂 Project Structure

Meme_Gatekeeper/
├── manifest.json          # Extension configuration (MV3)
├── background.js           # Service worker — global timer + gate broadcasting
├── popup.html              # Settings popup UI
├── popup.js                # Popup logic
├── content.js              # Content script (runs on target sites)
├── content.css             # Overlay + corner timer styling
├── assets/                 # Icons and default videos
│   ├── emot.png           # Extension icon
│   ├── neko1.webm         # Default active video
│   └── neko2.webm         # Default idle video
└── _locales/              # Internationalization
    ├── en/
    ├── vi/
    ├── ja/
    ├── zh_CN/
    ├── ko/
    ├── fr/
    ├── es/
    ├── pt/
    └── hi/

🔧 Architecture (Manifest V3)

Service Worker (background.js)

• Global timer: Accumulates time across all tracked domains/tabs
• Gate broadcasting: When limit is reached, sends SHOW_GATE to all tabs simultaneously
• State persistence: Writes globalSeconds to storage every second; reads on startup via top-level await

Content Script (content.js)

• Per-tab TICK: Each tracked tab sends TICK messages to service worker every second
• Draggable corner timer: Shows remaining time (MM:SS), can be repositioned by drag
• Visibility-aware: Stops ticking when tab hidden, resumes with correct time when visible
• Storage fallback: If service worker is unavailable, reads progress directly from chrome.storage.local

How It Works

1. User sets usage limit (e.g., 60 minutes) and break time (e.g., 5 minutes)
2. Any tracked site (YouTube, Facebook, Twitter, custom domains) sends ticks to the service worker
3. The service worker accumulates time in a single global counter
4. When limit is reached, service worker broadcasts SHOW_GATE to all open tabs
5. Every tab shows the gate overlay — user must wait for break to end
6. Break ends → counter resets → tracking resumes on all tabs

⚙️ Permissions

• storage: Save user settings and global timer state
• activeTab: Get current tab information
• scripting: Execute content scripts
• host_permissions: <all_urls> — Required for MV3 content script injection on all websites

📝 License

MIT License

👤 Authors

• Original Idea: ZOKUZOKU - Creator of Cat Gatekeeper
• Fork & Customization: dinhtuandev