Pomodoro Timer Floating Widget

WHAT IT DOES

Pomodoro Timer Floating Widget adds a fully functional Pomodoro timer to any webpage you visit. The compact floating widget displays a countdown timer with a visual progress ring, color-coded by session type—red for work sessions, green for breaks, and yellow for long breaks. Start, pause, and reset controls let you manage your focus sessions easily. A session counter tracks completed Pomodoro sessions, and the widget automatically transitions between work and break sessions based on your configured intervals. Sound notifications play at session start and end, and desktop notifications alert you when it's time to switch. You can drag the widget anywhere on the screen, and the timer state is automatically saved so it resumes correctly if you reload the page.

WHERE IT RUNS

This script runs on every website (matching all URLs), adding the floating timer widget across the entire web. It works on any page—whether you're working, studying, or browsing—and stays visible as you navigate between pages.

HOW TO USE

After installing through the BotGentz extension, the floating Pomodoro widget appears on every webpage. Click the ▶ button to start a focus session. The timer counts down and automatically transitions to a break when the session ends. Use the configuration panel to customize your experience: set work, break, and long break durations in minutes, configure the number of sessions before a long break, toggle desktop notifications on or off, enable or disable sound notifications, and enable or disable auto-start for the next session. The panel displays real-time statistics including total sessions completed and total focus time. Use the "Show Widget" button if the widget is hidden, or "Reset Timer" to reset the current session. Drag the widget by its header to reposition it anywhere on the screen.

PROGRESS RING AND STATE PERSISTENCE ENGINE

This script implements a Pomodoro timer with a visual progress ring using SVG stroke-dasharray and stroke-dashoffset calculations. The ring updates in real-time every 200ms for smooth animations. The timer engine uses a state machine with four states: idle, work, break, and long-break. Session transitions are automatic based on the configured work/break intervals and the session count. The state persistence system uses GM_setValue to save the timer state (status, time remaining, session count, and running status) every 200ms, enabling recovery across page reloads. The drag system uses mousedown/mousemove/mouseup events with offset calculation and boundary detection to keep the widget within the viewport. Sound notifications use the Web Audio API to generate simple beeps without requiring external audio files.

THE PANEL

The configuration panel is fully draggable and remembers its position per-site using GM_setValue. It snaps to screen edges when dragged near them, collapses to a compact bubble when minimized, and supports Escape key for quick collapse. All settings—including timer durations, notification preferences, and auto-start—are persisted across sessions.

PLEASE NOTE

This script requires the free BotGentz extension to run. The script runs on all websites and stores timer state locally using GM_setValue. It does not capture, store, or transmit any personal information. The widget is designed to be non-intrusive and can be positioned anywhere on the screen. Sound notifications use the Web Audio API and may not work on all browsers or require user interaction to initialize audio context. Desktop notifications require browser notification permissions. This tool is provided for productivity and informational purposes only.