Epoch

Epoch is a high-fidelity, client-side countdown timer and event reveal platform built using vanilla HTML, CSS, and JavaScript. It operates entirely in the browser with zero backend requirements or build steps, utilizing URL state serialization for absolute portability.

Core Architecture

• IIFE Module Pattern: The codebase is structured into isolated, self-executing functional modules (timer.js, themes.js, share.js, templates.js, app.js) to maintain clean namespaces and prevent scope pollution.
• State Persistence via URL Hash: Timer configurations are serialized, compressed via LZString, and stored directly in the URL hash. This client-only design ensures that any generated link is entirely self-contained and permanent.
• Zero-Dependency Hosting: Serves immediately on any static web server (such as Python's built-in HTTP server or Nginx) without compilation or npm installations.

Features

1. Thematic Background Systems

• HTML5 Canvas Renderers: Six per-theme particle systems (cosmic starfields, falling cherry blossoms, sparks/embers, snowflakes, waves, and digital binary rain) running on custom requestAnimationFrame canvas drawing loops.
• Custom Theme Engine: Supports real-time adjustments of background color stops, backdrop blur ranges, border radius styles, and neon glowing borders.

2. Event Customization & Templates

• Built-in Presets: Ten distinct event templates (New Year, Birthday, Wedding, Product Launch, Christmas, etc.) with automatic date offset calculation.
• Personalized Logic: Birthday template includes automatic recipient name prompt mapping with smart possessive suffix formatting.

3. Expiration & Security

• Cinematic Expiry Actions: Options for showing a custom text banner, initiating a count-up stopwatch, or triggering recurring intervals (daily, weekly, monthly).
• Passcode Reveals: Optional glassmorphic PIN card entry gate with CSS shake error animations, allowing creators to lock event reveal videos behind a custom code.
• Synthesized Ambient Audio: Generates low-volume ambient tick sounds (Clock Tick, Heartbeat, Digital Pulse) and expiration alarms (Zen Chime, Space Alert, Retro Arcade) directly via the Web Audio API without downloading external audio files.

4. Progress & Milestones

• Visual Milestones: Computes progress based on creation-to-target intervals, triggering subtle confetti bursts and glassmorphic toast status indicators at 25%, 50%, 75%, and 90% completion.

5. Distraction-Free Kiosk Mode

• Fullscreen Integration: Fullscreen API toggles combined with a mouse-idle detection routine that auto-fades headers, synchronizers, and action buttons after 3 seconds of inactivity.

Client-Side Share & Export Suite

• Themed QR Generation: Renders customizable, high-resolution vector QR codes locally on canvas (supporting Rounded, Dots, and Classy layouts) using the current theme's accent color and embedding a clean clock logo center.
• PNG Card Export: Utilizes html2canvas at double resolution to capture a perfectly cropped PNG representation of the countdown card with a subtle watermark.
• Animated GIF Generation: Sequential 10-frame capture using html2canvas compiled locally into a looped GIF via gifshot, generating pre-formatted HTML embed codes that link the animated GIF back to the live URL.
• Calendar Synchronization: Dynamically generates subscription links for Google Calendar, Outlook Calendar, Yahoo Calendar, and local .ics iCal files.

Local Development

To run the application locally, clone the repository and start a static file server in the project directory:

# Using Python 3
python -m http.server 8080

# Using Node.js (http-server)
npx http-server -p 8080

Open http://localhost:8080 in your web browser.

File Structure

├── css/
│   ├── main.css          # Core layouts, forms, and responsive rules
│   ├── themes.css        # HSL design tokens and CSS variables
│   └── animations.css    # Keyframe transitions and custom shake elements
├── js/
│   ├── app.js            # Main application coordinator and view routing
│   ├── timer.js          # Countdown class, particle systems, and audio synthesizers
│   ├── share.js          # URL compressor, QR styled canvas, and export suites
│   ├── templates.js      # Preset date offsets and SVG icons
│   ├── themes.js         # Theme grids, presets, and color builders
│   └── confetti.js       # Expiry confetti particle burst system
├── embed/
│   └── index.html        # Lightweight iframe embedding template
└── index.html            # Primary application entry point