Architecture
A Manifest V3 extension with one service worker, a small set of content scripts, fifteen declarative rulesets and a React popup.
File map
| Path | Role | Size |
|---|---|---|
manifest.json | MV3 entry point: permissions, content scripts, ruleset list, icons | 4 KB |
background.js | Service worker: settings cache, suspension engine, ruleset switching, message router, alarms | 190 KB |
i18n.js | Locale catalogue and formatting helpers, shared by the popup and content scripts | 84 KB |
smart-recovery.js | Detects pages that broke after blocking and offers a per-site fix | 26 KB |
rules/ | Fifteen static declarativeNetRequest rulesets | 34 MB |
chunks/ + assets/ | Popup React bundle and its design tokens | 310 KB |
_locales/ | 59 locale catalogues, __MSG_appName__ style manifest strings | 450 KB |
scripts/ | Version bump, version verify and packaging helpers | — |
Runtime flow
- Boot. The service worker hydrates a settings cache from
chrome.storage.local, registers alarms and applies every feature through a singleapplyAllSettings()pass. - Blocking.
declarativeNetRequest.updateEnabledRulesets()switches the rulesets that match the current blocking levels. The four low blocklists are always on; medium and pro tiers, script tiers, font tiers, image blocking and the YouTube ad ruleset are toggled on demand. - Injection. Features that need page code register content scripts
dynamically with
chrome.scripting— the throttler, DNS prefetcher, preloader, prioritizer, popup blocker and the cosmetic-blocking engine. - Suspension. A one-minute alarm evaluates idle tabs. Level 3 adds an adaptive fast-path that sleeps tabs above a memory threshold sooner.
- Reporting. The popup asks the worker for status
(
getSuspensionStatus,getAdaptiveSettings) and reads metrics from storage. All counters are local.
Declarative rulesets
| Ruleset | Enabled by default | Used by |
|---|---|---|
low_blocklist_1…4 | on | Ads and trackers, level 1+ |
med_blocklist_1…3 | off | Ads and trackers, level 2+ |
pro_blocklist_1 | off | Ads and trackers, level 3 |
script_low_ruleset | on | Third-party scripts, level 1 |
script_med_ruleset | off | Third-party scripts, level 2 |
script_pro_ruleset | off | Third-party scripts, level 3 |
font_low_ruleset, font_med_ruleset | off | Faster fonts, levels 1–2 |
image_block_ruleset | off | Block images |
yt_ad_ruleset | off | Video ads |
Message actions
The popup and content scripts talk to the worker through
chrome.runtime.sendMessage. The router understands these actions:
| Action | Sent by | Purpose |
|---|---|---|
suspendAllInactive | popup | Manual "suspend everything now" |
getSuspensionStatus | popup | Last cycle summary for the status line |
getAdaptiveSettings / setAdaptiveSettings | popup | Read and write the adaptive sleep thresholds |
updateWhitelist | popup | Save the per-site whitelist |
enableSafeMode / disableSafeMode | content scripts | Pause or resume everything on one site |
flushMetrics | popup | Persist the counters before the popup closes |
stopCosmeticBlocking, brokeSiteHintAccept, brokeSiteHintDismiss | worker → content script | Page-cleanup and recovery controls |
Popup stack
The popup is a small React app compiled into two chunks and styled by a single stylesheet.
Colours come from CSS custom properties using light-dark(), so the System / Light /
Dark setting is one color-scheme switch rather than a second theme file — the same
token set drives both modes.
assets/popup-*.css
:root {
--canvas: light-dark(#EDF1F5, #0B1220);
--ink: light-dark(#0F1B2A, #E8EEF5);
--accent: light-dark(#0E7490, #5EEAD4);
--r-1: 10px;
}