BlockSite - Focus Mode · 简体中文

A lightweight Chrome Manifest V3 extension for blocking distracting websites or specific pages and redirecting matched requests to a local blocking page.

Features

• Accepts three input formats: domain, domain + path, and full URL
• Supports per-rule durations: 1 day / 1 week / 1 month / 1 year / forever
• Supports irreversible YOLO freezing for blocking rules
• Supports one-click blocking for the current page
• Redirects matched requests to a local blocking page instead of opening the target site
• Supports local website insights with day / week / month / year views at the site level
• Stores rules locally without external services
• Uses declarative network rules plus tab-navigation fallback for more reliable blocking
• Uses tabs, windows, idle, and alarms to estimate active foreground browsing time
• Does not upload browsing data, collect account data, or rely on cloud APIs

How It Works

The extension first normalizes input into a unified rule format, for example:

• https://social.example.com/focus-room?from=feed -> social.example.com/focus-room
• https://www.example.com/ -> www.example.com

It then blocks requests through two layers:

1. declarativeNetRequest dynamic rules try to redirect matching top-level navigations.
2. A chrome.tabs background fallback redirects matched pages to local blocked.html during tab updates and navigation changes.
3. chrome.idle + chrome.tabs + chrome.windows + chrome.alarms track active foreground site time locally.

flowchart TD
    A[User enters domain or URL] --> B[Normalize rule]
    B --> C[Save to chrome.storage.local]
    C --> D[Rebuild declarativeNetRequest dynamic rules]
    D --> E{Does navigation match a rule?}
    E -- Yes --> F[Redirect to blocked.html]
    E -- No --> G[Allow normal navigation]
    D --> H[chrome.tabs.onUpdated fallback listener]
    H --> E
    H --> I[Usage tracking heartbeat and local aggregation]

Loading

Installation

1. Clone the project

git clone <your-repo-url>
cd block-site

2. Load the extension in Chrome

1. Open chrome://extensions
2. Enable Developer Mode
3. Click "Load unpacked"
4. Select the project directory

Usage

Block the current page

1. Open the page you want to block
2. Click the extension icon
3. Choose a blocking duration
4. Click "Block Current Page"

Add a rule manually

You can enter any of the following:

• example.com
• example.com/focus
• https://example.com/focus?ref=home

Available durations:

• 1 day
• 1 week
• 1 month
• 1 year
• forever

Freeze a rule

You can freeze any rule from the blocked list.

Behavior after freezing:

• The rule cannot be deleted
• Its duration cannot be changed
• Re-adding the same domain cannot override it
• Time-limited frozen rules still expire automatically
• A forever + frozen rule can only be removed by clearing extension local data or uninstalling the extension

This action is irreversible. The popup does not provide an unfreeze option.

Remove a rule

Click ✕ in the blocked list to remove a normal rule.

View insights

1. Click the extension icon
2. Switch to the "Insights" tab
3. Change between day / week / month / year to view site-level rankings

Current tracking scope:

• Only http/https pages are counted
• Only the active tab in the foreground Chrome window is counted
• Tracking stops when Chrome loses focus, the system becomes idle, or you switch away
• The first version aggregates at the hostname level and strips www.

Privacy

This project runs locally by default. The current version:

• Uses only chrome.storage.local for blocking rules and usage statistics
• Does not upload rule data or usage statistics
• Does not send telemetry
• Does not collect cookies, tokens, accounts, browsing history, or personal identity data

Notes:

• forever + frozen rules remain in local data indefinitely
• To remove them, you must clear the extension's local data or uninstall the extension

Additional permissions:

• alarms: periodically clears expired rules and flushes local usage heartbeats
• idle: reduces counting errors when the browser is open but the user is away

Local Development

Run tests

node --test test/url-pattern-utils.test.cjs test/blocking-rule-utils.test.cjs test/usage-insights-utils.test.cjs

Syntax checks

node --check popup.js
node --check service-worker.js
node --check url-pattern-utils.js
node --check blocking-rule-utils.js
node --check usage-insights-utils.js

Apply changes during development

After editing frontend or background scripts, manually click "Reload" in chrome://extensions.

Project Structure

block-site/
├── blocking-rule-utils.js
├── blocked.css
├── blocked.html
├── blocked.js
├── icons/
├── manifest.json
├── popup.css
├── popup.html
├── popup.js
├── README.md
├── README.zh-CN.md
├── service-worker.js
├── test/
│   ├── blocking-rule-utils.test.cjs
│   ├── usage-insights-utils.test.cjs
│   └── url-pattern-utils.test.cjs
├── usage-insights-utils.js
└── url-pattern-utils.js

Core Files

• manifest.json: extension manifest and permissions
• popup.html / popup.js / popup.css: popup UI and interaction logic
• service-worker.js: background rule sync, expiry cleanup, usage tracking, and reporting API
• blocking-rule-utils.js: pure logic for durations, migration, and expiry display
• usage-insights-utils.js: pure logic for site normalization, cross-day aggregation, and reporting
• url-pattern-utils.js: URL normalization, matching, and rule-construction helpers
• blocked.html / blocked.js / blocked.css: blocking page
• test/*.test.cjs: tests for rule handling, aggregation, and URL utilities

Possible Next Improvements

• Rule import / export
• Rule groups
• Temporary unblocking
• Whitelist mode
• Configurable blocking copy and themes