TimeSnap

Overview

TimeSnap is a polished, timer application designed for desktop (NW.js), mobile (Apache Cordova), and web browsers. This version includes comprehensive bug fixes and a completely redesigned, modern interface.

---

JavaScript Fixes

1. Timer State Management

• Fixed: Timer pause/resume logic now properly tracks remaining time
• Fixed: Timer state is properly managed across start/pause/resume cycles
• Fixed: remainingTime is correctly calculated when pausing
• Added: isPaused flag to prevent state conflicts

2. Sound Selection

• Fixed: Preset and custom sound selection now works correctly
• Added: Visual feedback when sounds are selected (active state)
• Added: setSelectedSound() and getSelectedSound() helper functions
• Added: Sound validation (file type, size limits)
• Added: Duplicate name detection with replace confirmation

3. Button State Management

• Fixed: Pause/Resume buttons now show/hide correctly
• Fixed: All timer buttons are properly disabled during countdown
• Fixed: Reset button re-enables all controls correctly
• Added: Dynamic button display logic

4. Error Handling

• Added: Try-catch blocks for audio playback
• Added: File validation for uploads (type, size)
• Added: User-friendly error messages
• Added: Graceful degradation for missing elements

5. Custom Sound Upload

• Fixed: Max 50 sounds limit (previously documented as 5)
• Added: File size limit (5MB)
• Added: File type validation (MP3, WAV, OGG)
• Added: Better file name truncation for long names
• Added: Input clearing after upload/error

6. Timer Display

• Fixed: Display updates consistently every second
• Fixed: Display properly clears on finish/reset
• Added: "Ready to start" status message

---

UI/UX Improvements

Desktop Layout

• Modern card-based design with clean sections
• Horizontal quick timer grid (3-4 columns on desktop)
• Proper spacing and visual hierarchy
• Large, readable timer display with gradient background
• Icon-based buttons for intuitive controls
• Hover effects and animations for better feedback

Mobile Layout (Responsive)

• 3-column grid for quick timers on tablets
• 2-column grid on small phones
• Stacked time inputs with proper labels
• Full-width control buttons for easy tapping
• Touch-friendly button sizes (min 44x44px)
• Optimized spacing for mobile viewports

Design System

• Custom CSS variables for consistent theming
• Beautiful typography using Outfit and JetBrains Mono
• Smooth transitions on all interactive elements
• Professional color palette with primary/secondary variants
• Proper focus states for accessibility
• Shadow system for depth perception

Dark Mode

• Automatic color switching with CSS variables
• Persistent preference saved to localStorage
• Smooth transitions between modes
• Optimized contrast for readability
• Icon toggle (moon/sun)

---

New Features

Sound Management

1. Visual Selection Feedback

   • Active state on selected preset sounds
   • Highlighted selected custom sounds
   • Select, play, and remove buttons with icons

2. Better Upload Experience

   • Clear file requirements displayed
   • Progress feedback during upload
   • Duplicate handling with confirmation
   • File validation before processing

3. Sound Library

   • Up to 10 custom sounds (local storage)
   • Preset sounds with descriptive icons
   • Preview sounds before selecting
   • Easy removal of custom sounds

Timer Enhancements

1. Express Timer Dials

   • 12 preset durations (1min - 6hrs)
   • Large, tappable buttons
   • Clear time display on each button
   • Single-click/tap to start

2. Custom Timer

   • Separate hours, minutes, seconds inputs
   • Visual time separator (:)
   • Number input validation
   • Clear labeling for each field

3. Timer Controls

   • Start/Pause/Resume/Reset buttons
   • Smart button visibility (show only relevant actions)
   • Disabled state during countdown
   • Clear visual feedback

Additional Features

• Back to Top Button - Appears after scrolling 200px
• Sticky Header - Always accessible navigation
• Smooth Scrolling - Better user experience
• Loading States - Proper feedback during operations

---

Platform Compatibility

Web Browser

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Responsive design for all screen sizes

Desktop (NW.js)

• Windows, macOS, Linux support
• Native-like experience
• Local file system access for sounds

Mobile (Apache Cordova)

• iOS and Android support
• Touch-optimized interface
• Mobile audio playback
• File picker integration

---

Usage

Quick Start

1. Click any quick timer button (1min, 2min, etc.)
2. Select an alert sound (optional)
3. Timer starts immediately

Custom Timer

1. Enter hours, minutes, and seconds
2. Select an alert sound (optional)
3. Click "Start" button

Custom Sounds

1. Click "Upload Sound" button
2. Select an audio file (MP3, WAV, OGG, max 5MB)
3. Click the select icon (✓) to use it as your alert sound
4. Preview with play button (▶)
5. Remove with trash icon (🗑)

Pause/Resume

• Click "Pause" during countdown
• Click "Resume" to continue from where you left off
• Click "Reset" to clear the timer

---

File Structure

/
├── index.html          # Main HTML structure
├── styles.css          # Complete styling (light/dark mode)
├── index.js            # Application logic and event handlers
├── utils.js           # Timer and sound utilities
└── assets/
    └── audio/         # Preset sound files
        ├── bell.mp3
        ├── chime.mp3
        ├── alarm.mp3
        └── notification.mp3
   all other assets...

---

Color Palette

Light Mode

• Background: #FAFBFC
• Surface: #FFFFFF
• Primary: #2563EB
• Text: #1E293B

Dark Mode

• Background: #0F172A
• Surface: #1E293B
• Primary: #3B82F6
• Text: #F1F5F9

---

Technical Details

localStorage Usage

• darkMode: User's theme preference
• uploadedSounds: Array of custom sound objects (base64)
  • Max 10 sounds
  • Max 1MB per file
  • Stores: {name: string, url: base64}

Audio Support

• Preset sounds from /assets/audio/
• Custom sounds stored as base64 in localStorage
• Automatic error handling for playback issues
• Supported formats: MP3, WAV, OGG

Timer Accuracy

• Updates every second (1000ms)
• Uses Date.now() for accurate elapsed time calculation
• Prevents drift with elapsed time tracking
• Properly handles pause/resume states

---

Browser Support

• Chrome/Edge: Full support
• Firefox: Full support
• Safari: Full support (iOS 12+)
• Opera: Full support

---

Known Limitations

1. Background Execution: Timers only run when app is active (foreground)

   • Not a system-level timer like iOS or Android Clock app
   • Closing the app stops the timer
   • This is a browser/PWA limitation

2. Sound Storage: Limited by browser localStorage (~5-10MB)

   • Maximum 10 custom sounds
   • Maximum 1MB per sound file

3. Audio Autoplay: Some browsers require user interaction before playing audio

   • Handled gracefully with error messages

---

Platform-Specific Security Notes

Web Browser

• Use HTTPS (required for Service Workers)
• localStorage is origin-isolated (secure)
• No additional concerns

Desktop (NW.js)

• App runs in isolated context
• No Node.js integration needed for this app

Mobile (Apache Cordova)

• App runs in WebView (sandboxed)
• No special permissions needed
• localStorage is app-private
• Bundle fonts/icons in app assets

📄 License

MIT LICENSE

Copyright © 2026 TimeSnap. All rights reserved.

---

🙏 Credits

• Fonts: (Google Fonts)
• Icons: Bootstrap Icons
• Design: Pretty Modern UI

---

💡 Tips

1. Mobile: Add to home screen for app-like experience
2. Dark Mode: Automatically saves your preference
3. Custom Sounds: Keep files under 1MB for best performance
4. Quick Access: Use keyboard shortcuts where available
5. Reset: Always available to start fresh

---

Enjoy using TimeSnap!