Traffic Light Timer

A desktop timer widget application built with Electron that visually transitions from green to red over a set duration, helping you track time with an intuitive color-coded system.

Features

🎯 Main Timer Widget

• Compact Design: Small, circular widget (100x100px default, customizable 20-200px)
• Color Transitions: Smooth progression from green → yellow → red
• Smart Positioning: Choose from preset positions (corners, center) or drag anywhere
• Adjustable Opacity: Control widget transparency for subtle desktop integration
• Always on Top: Stays visible above all other windows (toggleable)
• Completion Indicator: Stays red when timer finishes with optional flashing
• Responsive Text: Timer display scales proportionally with widget size
• Transparent: Frameless design that blends with your desktop

🎨 Visual System

• Smooth Animations: 60fps color interpolation using HSL color space
• Clean Design: Simple circular widget with smooth color transitions
• Real-time Updates: Millisecond-precision timer with live color feedback

🔧 Widget Positioning & Behavior

• Position Maintenance: Widget size can be changed while maintaining its screen position
• Precision Sizing: Minimum widget size reduced to 20px for ultra-compact use

🎛️ Control Panel

• Tabbed Interface: Timer controls and settings in one window
• Timer Controls: Start, Stop, Pause, Resume, Restart
• Quick Add Time: +1 min, +5 min, +15 min buttons
• Quick Reduce Time: -1 min, -5 min, -15 min buttons
• Custom Duration: Set any time with minutes:seconds input
• Live Display: Current time remaining and timer status
• Settings Tab: All customization options easily accessible

⚙️ Settings & Customization

• Widget Position: Choose from preset positions (Top Left, Top Right, Bottom Left, Bottom Right, Center)
• Size Adjustment: Scale from 20px to 200px with proportional text scaling and position maintenance
• Opacity Control: Adjust widget transparency from 20% to 100%
• Default Duration: Set your preferred starting time
• Display Options:
  • Toggle time display on widget
  • Enable flashing when timer completes
  • Always-on-top functionality
• Completion Alerts:
  • Optional popup message when timer completes
  • Customizable completion message text
  • Popup appears on top of other windows
• Persistent Storage: All settings and timer state saved automatically

Download

🚀 Download Pre-built Releases

Download the latest version for your platform from the Releases page.

Available Downloads:

• Windows:
  • .exe installer (recommended) - Full installation with Start Menu shortcuts
  • Portable .exe - No installation required, just run
• macOS:
  • .dmg disk image - Drag to Applications folder
  • .zip archive - Extract and run
• Linux:
  • .AppImage - Universal package, works on most distributions
  • .deb - For Ubuntu, Debian, and derivatives
  • .rpm - For Fedora, RHEL, openSUSE

📦 Installation Instructions

Windows

1. Download the .exe installer from releases
2. Double-click to run the installer
3. Follow the installation wizard
4. Launch from Start Menu or Desktop shortcut

macOS

1. Download the .dmg file from releases
2. Double-click to mount the disk image
3. Drag Traffic Light Timer to Applications folder
4. Launch from Applications or Launchpad

Linux

• AppImage:

  chmod +x Traffic-Light-Timer-*.AppImage
  ./Traffic-Light-Timer-*.AppImage

• DEB (Ubuntu/Debian):

  sudo dpkg -i traffic-light-timer_*.deb

• RPM (Fedora/RHEL):

  sudo rpm -i traffic-light-timer-*.rpm

Building from Source

Prerequisites

• Node.js (v16 or higher)
• npm (comes with Node.js)

Development Setup

# Clone the repository
git clone https://github.com/yourusername/traffic-light-timer.git
cd traffic-light-timer

# Install dependencies
npm install

# Run in development mode
npm start

Usage

Getting Started

1. Launch the app - A small green circle appears in the bottom-right corner (default)
2. Click the widget - Opens the control panel
3. Start timing - Timer automatically begins with default 5-minute duration
4. Watch the transition - Widget smoothly changes from green to yellow to red
5. Timer completion - Widget stays red when finished (optional flashing available)

Timer Controls

• Pause/Resume: Click the pause button to pause, shows "Resume" when paused (with improved synchronization)
• Add Time: Use quick buttons (+1, +5, +15 min) or set custom duration
• Reduce Time: Use quick buttons (-1, -5, -15 min) to decrease remaining time
• Restart: Reset timer to default or last set duration
• Stop: Stop timer and reset to beginning
• Smart Resume: Timer resumes from exact paused position with fixed state synchronization

Customization

1. Click the widget to open controls
2. Click the "Settings" tab at the top
3. Choose your preferred:
   • Screen position (corners or center)
   • Size (20px - 200px) with auto-scaling text
   • Opacity (20% - 100%) for transparency control
   • Default timer duration
   • Display options (time visibility, flashing, always on top)
   • Completion alerts (popup message with custom text)
4. Click "Save Settings" to apply changes

Building for Distribution

Create Standalone Executable

# Build for current platform
npm run build

# Build for all platforms
npm run dist

Built applications will be in the dist/ folder.

Supported Platforms

• Windows: Creates .exe installer and portable executable
• macOS: Creates .dmg and .zip packages for Intel and Apple Silicon
• Linux: Creates .AppImage, .deb, and .rpm packages

Creating a New Release

1. Update version in package.json:

   "version": "1.1.0"

2. Commit your changes:

   git add .
   git commit -m "Release version 1.1.0"

3. Create and push a version tag:

   git tag v1.1.0
   git push origin main
   git push origin v1.1.0

4. GitHub Actions will automatically:

   • Build the app for all platforms
   • Create a new GitHub release
   • Upload all distribution files

The release will be available at https://github.com/yourusername/traffic-light-timer/releases

Project Structure

traffic-light-timer/
├── package.json              # Project configuration & dependencies
├── src/
│   ├── main.js              # Main Electron process
│   ├── timer.js             # Timer logic and state management
│   ├── windows/             # HTML files
│   │   ├── widget.html      # Main timer widget
│   │   ├── controls.html    # Control panel
│   │   └── settings.html    # Settings page
│   ├── css/                 # Stylesheets
│   │   ├── widget.css       # Widget styling and shapes
│   │   ├── controls.css     # Control panel styling
│   │   └── settings.css     # Settings page styling
│   ├── js/                  # Renderer processes
│   │   ├── widget-renderer.js    # Widget window logic
│   │   ├── controls-renderer.js  # Controls window logic
│   │   └── settings-renderer.js  # Settings window logic
│   └── assets/
│       └── icon.png         # Application icon
└── dist/                    # Built applications (after npm run build)

Technical Details

Architecture

• Main Process: Window management, IPC coordination, settings persistence
• Renderer Processes: UI logic for widget, controls, and settings windows
• Timer Engine: High-precision countdown with pause/resume functionality

Key Features

• State Persistence: Timer state and window positions saved across app restarts
• IPC Communication: Seamless data flow between widget and control windows
• Color Interpolation: Smooth HSL-based transitions for natural color progression
• Shape System: CSS-based geometric shapes using clip-path
• Cross-platform: Native look and feel on Windows, macOS, and Linux

Performance

• 60 FPS Updates: Smooth color transitions
• Low Resource Usage: Minimal CPU and memory footprint
• Efficient Rendering: Optimized for desktop widget use

Development

Development Mode

npm run dev

File Structure Notes

• Settings stored in user data directory
• Timer state persisted automatically
• Window positions remembered between sessions

Troubleshooting

Common Issues

App won't start

• Ensure Node.js v16+ is installed
• Check that all dependencies installed: npm install
• On Linux: May need additional system libraries (libnss3, libdrm2, etc.)

Widget not draggable

• Widget uses -webkit-app-region: drag CSS property
• Some Linux desktop environments may require additional configuration

Settings not saving

• Check write permissions to user data directory
• Settings file location varies by OS:
  • Windows: %APPDATA%/traffic-light-timer/
  • macOS: ~/Library/Application Support/traffic-light-timer/
  • Linux: ~/.config/traffic-light-timer/

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit your changes: git commit -am 'Add feature'
4. Push to the branch: git push origin feature-name
5. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with Electron
• Color transitions inspired by traffic light systems
• Icon design using SVG graphics

---

Need help? Open an issue on GitHub.