Defense Against Distractions

Defense Against Distractions is a browser extension that helps you avoid procrastination by blocking pages when distracting words or phrases appear in their text.

Instead of only blocking entire domains, you can define plan entries with websites and keywords. When a matching page reaches the configured distraction score, the extension redirects it to a block page.

Features

• Block pages based on keywords, phrases, and weighted keyword scores.
• Organize websites and keywords inside enableable plans.
• Give plans their own allowed websites, schedules, and optional UI cleanup assignments.
• Use locked schedules to make focus rules harder to relax during chosen time windows.
• Allow websites inside a plan so that plan does not scan them.
• Protect the options page with a password.
• Hide distracting UI elements with a popup-based element picker. See UI Element Blocking.
• Export and import extension settings.
• Reset extension data from Settings before uninstalling or starting over.
• Localized UI through Chrome extension locales.

How It Works

Create a plan, add one or more entries with websites and keywords, then decide when that plan should be active. Different protection contexts can be enabled, disabled, scheduled, and adjusted independently.

Keywords can be entered in three formats:

• video games blocks as soon as the phrase is detected.
• news, 50 adds 50 points each time the keyword is found.
• news, *, 10 multiplies the current page score when the keyword is found.

Pages are blocked when their score reaches 1000.

Locked Schedules

Locked schedules let you define times when the extension should resist being weakened. During an active locked schedule, the extension prevents changes such as deleting active schedules, weakening plan entries, relaxing schedule constraints, adding allowed websites, or changing password protection.

Each scheduled day must keep at least one hour unlocked.

Installation For Development

1. Clone this repository.
2. Open your Chromium-based browser's extensions page.
3. Enable developer mode.
4. Choose "Load unpacked".
5. Select this repository folder.

The extension uses Manifest V3 and does not require a build step.

Packaging

Run npm run package to generate release archives in dist/:

• Defense_against_Distractions-vX.Y.Z-extension.zip contains only the runtime extension files for loading or store upload.
• Defense_against_Distractions-vX.Y.Z-source.zip contains the source tree, tests, docs, scripts, screenshots, and promotional assets.

Run npm run verify:playbook to check README, privacy, license, package metadata, and store-listing alignment against the shared browser-extension playbook. Run npm run verify:browser-load after packaging to smoke-test loading the generated unpacked extension in Chrome, Edge, or Chromium. Run npm run verify:package after packaging to check the generated runtime output for manifest/import consistency, source-map policy, and remote executable code. Run npm run verify:release to check the generated archives and the package gate together. See Release Readiness for the full automated and manual release gates.

The dist/ directory is generated output and is not the source of truth. If a file in dist/source/ looks stale, rerun npm run package instead of editing the generated copy directly.

Chrome Web Store API release helpers are documented in Chrome Web Store API. They use environment variables for OAuth credentials and never store CWS secrets in the repository.

Project Structure

• _locales/ contains translated extension messages.
• src/options.html contains the options page.
• src/instructions.html contains the in-extension guide.
• src/blocked.html contains the block page.
• src/app/ contains runtime entry points such as the MV3 background service worker.
• src/features/ contains feature-owned source modules that can be imported by runtime entries.
• src/platform/ contains browser API wrappers and platform adapters.
• src/app/background/index.js contains the service worker entry point.
• src/app/popup/index.js contains the popup entry point.
• src/app/options/index.js contains the options page entry point.
• src/app/instructions/index.js contains the instructions page entry point.
• src/app/blocked/index.js contains the blocked page entry point.
• src/app/content/index.js contains the classic content-script entry point.
• src/js/shared/ contains shared parsing, URL, UI helpers, and compatibility barrels; feature-owned models live under src/features/, and Chrome API wrappers live under src/platform/.
• src/css/ contains extension styles.

Runtime extension files are the files that must ship inside the extension ZIP. Source-only project files such as docs, tests, scripts, screenshots, promotional images, and store listing text are kept in the repository and source ZIP, but are intentionally excluded from the runtime extension package.

Release-facing assets use the shared browser-extension playbook shape:

• assets/icons/ contains packaged extension icons referenced by the manifest.
• store/promo/ contains Chrome Web Store promotional images.
• store/screenshots/ contains Chrome Web Store screenshots.
• store/store-listing/ contains plain text Chrome Web Store listing copy.

Architecture and release notes live in docs/. The current future-facing product model is documented in Protection Model, the planned user-facing plan structure is documented in Plans Architecture, reviewer-facing browser limitations are documented in Reviewer Notes, and release gates are documented in Release Readiness.

Privacy

Defense Against Distractions is local-first. It stores configuration and bounded diagnostics in Chrome extension storage, does not use analytics, ads, tracking pixels, telemetry, or remote executable code, and does not require a server for core blocking behavior. See PRIVACY.md.

Contributing

Bug reports, ideas, and pull requests are welcome. If you find an issue, please open a GitHub issue with the browser version, extension version, steps to reproduce, and what you expected to happen.

For code changes, keep the extension behavior focused: improve clarity, reliability, and maintainability without expanding permissions unless there is a strong reason.

Support

If this extension saves you time and you want to support its development:

License

Licensed under GPL-3.0-only. See LICENSE.

Source: https://github.com/molodchyk/Defense_against_Distractions