Project Architecture
File map
| File | Purpose |
|---|---|
manifest.json | Extension manifest (MV3) |
background.js | Service worker - schedules breaks, alarms, notifications, tab handling, idle detection, video call detection |
popup.html / popup.js / popup.css | Toolbar popup - live countdown, enable/disable switch, reset |
options.html / options.js / options.css | Full settings page - timing, alerts, pause behavior, DND, idle detection |
break.html / break.js / break.css | The full-tab break screen shown when a break starts |
common.js | Shared defaults/helpers used by all the above |
icons/ | Generated eye icons (normal / alert-flash / off states) |
How the pieces talk to each other
background.jsis the source of truth. It owns the alarm schedule, decides when a break starts/ends, shows notifications, and tracks idle/DND/exception state.popup.htmlandbreak.htmlare both extension pages - they askbackground.jsfor status via message passing (GET_STATUS) rather than keeping their own independent timers, so everything stays in sync even if you open multiple views at once.options.htmlwrites directly tochrome.storage.sync, then notifiesbackground.js(SETTINGS_UPDATED) so the running schedule picks up the change immediately, without requiring a reload.common.jsholds shared defaults (like the base 20/20 settings object) and small helpers (like time formatting), included by every other context so the "shape" of settings stays consistent across the popup, options page, break tab, and background worker.
Storage shape
chrome.storage.sync- user-facing settings (work interval, break length, alert preferences, DND hours, exception list, idle threshold, auto-resume duration). Synced automatically across signed-in devices.chrome.storage.local- runtime/device-specific state (current countdown target, whether a break or exception pause is active). Deliberately not synced, since it reflects "what's happening on this device right now."