Architecture

A Manifest V3 extension with one service worker, a small set of content scripts, fifteen declarative rulesets and a React popup.

File map

PathRoleSize
manifest.jsonMV3 entry point: permissions, content scripts, ruleset list, icons4 KB
background.jsService worker: settings cache, suspension engine, ruleset switching, message router, alarms190 KB
i18n.jsLocale catalogue and formatting helpers, shared by the popup and content scripts84 KB
smart-recovery.jsDetects pages that broke after blocking and offers a per-site fix26 KB
rules/Fifteen static declarativeNetRequest rulesets34 MB
chunks/ + assets/Popup React bundle and its design tokens310 KB
_locales/59 locale catalogues, __MSG_appName__ style manifest strings450 KB
scripts/Version bump, version verify and packaging helpers—

Runtime flow

  1. Boot. The service worker hydrates a settings cache from chrome.storage.local, registers alarms and applies every feature through a single applyAllSettings() pass.
  2. 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.
  3. 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.
  4. Suspension. A one-minute alarm evaluates idle tabs. Level 3 adds an adaptive fast-path that sleeps tabs above a memory threshold sooner.
  5. Reporting. The popup asks the worker for status (getSuspensionStatus, getAdaptiveSettings) and reads metrics from storage. All counters are local.

Declarative rulesets

RulesetEnabled by defaultUsed by
low_blocklist_1…4onAds and trackers, level 1+
med_blocklist_1…3offAds and trackers, level 2+
pro_blocklist_1offAds and trackers, level 3
script_low_rulesetonThird-party scripts, level 1
script_med_rulesetoffThird-party scripts, level 2
script_pro_rulesetoffThird-party scripts, level 3
font_low_ruleset, font_med_rulesetoffFaster fonts, levels 1–2
image_block_rulesetoffBlock images
yt_ad_rulesetoffVideo ads

Message actions

The popup and content scripts talk to the worker through chrome.runtime.sendMessage. The router understands these actions:

ActionSent byPurpose
suspendAllInactivepopupManual "suspend everything now"
getSuspensionStatuspopupLast cycle summary for the status line
getAdaptiveSettings / setAdaptiveSettingspopupRead and write the adaptive sleep thresholds
updateWhitelistpopupSave the per-site whitelist
enableSafeMode / disableSafeModecontent scriptsPause or resume everything on one site
flushMetricspopupPersist the counters before the popup closes
stopCosmeticBlocking, brokeSiteHintAccept, brokeSiteHintDismissworker → content scriptPage-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;
}