⏱️ Timestamp

Your stamp on time.

Try it now → No signup. No install. Just go.

What is Timestamp?

Timestamp is a countdown app where every countdown is a URL. Pick a date, choose a theme, add a message. Your countdown gets a unique link that works for anyone who opens it. Pure client-side magic.

Use it for:

• 🎆 New Year's Eve countdowns with friends worldwide
• ⏱️ Pomodoro timers and meeting breaks
• 🚀 Product launches and livestream hype
• 🎂 Birthday countdowns to share on social media

Three Countdown Modes

Timestamp supports three distinct countdown modes, each designed for different use cases:

Mode	Try it	What it does
🏠 Local Time — Wall clock	🎆 New Year 2027	Countdown to midnight in your timezone. Each city celebrates at their own midnight.
🌐 Same Moment — Absolute time	🚀 Product launch	Everyone counts to the same instant worldwide. Perfect for product launches or global livestreams.
⏱️ Timer — Your countdown	⏱️ 5-minute break	Fixed duration countdown. Starts when you open the link. Great for Pomodoro sessions.

💡 Tip: The timer example is great for seeing the celebration animation when it hits zero!

Available Themes

Find all the themes in the Theme Gallery, and experience them for yourself on Timestamp.

Features

🔗 Instant URL Sharing

Every configuration generates a shareable URL. Change any setting and the URL updates automatically — just copy and share.

📱 Install as an App

Timestamp is a Progressive Web App (PWA), which means you can install it from your browser:

• Desktop (Chrome/Edge): Click ⊕ in the address bar
• iOS: Share → "Add to Home Screen"
• Android: Menu → "Install app"

PWA Features

• Offline support: The app works without an internet connection after the first visit
• Full-screen mode: Runs like a native app when installed
• Automatic updates: The app checks for updates and prompts you to refresh

Note on notifications: Notifications were investigated but are not currently implemented. Local browser notifications only work on macOS/iOS while the app is open. Arguably this could be useful if you're switching browser tabs, but may not be worth the additional complexity. Background notifications would require server infrastructure (Web Push via APNs/FCM). See PWA instructions for details.

🗺️ World Map

Wall-clock mode shows a day/night map with real-time solar position. You can see which cities are celebrating and which are waiting.

♿ Accessibility

• Full keyboard navigation with shortcuts (see below)
• Screen reader announcements for countdown updates (via orchestrator's AccessibilityManager)
• Orchestrator provides accessibility hooks (onAnimationStateChange) and foundations (reducedMotionManager, data-reduced-motion attribute, container ARIA attributes) that themes implement to ensure consistent behavior across all themes

⌨️ Keyboard Shortcuts

Timer mode supports global keyboard shortcuts for hands-free control:

See Keyboard Shortcuts Guide for complete documentation.

Key	Action	Notes
Space	Play/Pause toggle	Works in fullscreen and normal view
Enter	Reset timer	Resets to original duration
R	Reset timer	Case-insensitive alternative
Escape	Exit fullscreen	Browser default, also supported

Smart behavior: Shortcuts are disabled when:

• Typing in any text input or textarea
• Modal dialogs are open (e.g., theme picker on the timer page)
• Timer-only shortcuts are disabled when you're in wall-clock or absolute modes

💡 Fullscreen tip: In timer mode, move your mouse in fullscreen to reveal timer controls alongside the exit button. They auto-hide after 3 seconds (or stay visible while hovering).

Run Locally

git clone https://github.com/chrisreddington/timestamp.git
cd timestamp
npm install
npm run dev

Open http://localhost:5173. That's it.

Prefer ephemeral environments? Development works great in GitHub Codespaces or Dev Containers.

For Developers

Timestamp uses a modular, pluggable architecture. The core app handles timing and state management, and provides accessibility foundations (reduced motion detection, screen reader announcements, ARIA structure). Themes handle rendering and implement accessibility hooks (responding to animation state changes, ensuring color contrast). This separation means you can build wildly creative themes without touching countdown logic.

Quick Links

I want to...	Go here
Build a new theme	Theme Development Guide
Understand the architecture	Architecture Overview
See URL parameters	Deep Linking Reference
Fix a bug or add a feature	Contributing Guide

Architecture at a Glance

src/
├── app/
│   ├── orchestrator/     # Core coordinator — timing, state, theme lifecycle
│   └── pwa/              # Service worker and PWA setup
├── themes/               # Pluggable visual renderers
│   ├── registry/         # Single source of truth for theme metadata
│   ├── contribution-graph/
│   ├── fireworks/
│   └── shared/           # Cleanup utilities shared by all themes
├── components/           # UI components (landing page, buttons, world map)
└── core/                 # Shared types, state management, utilities

Key concept: The orchestrator decides when to update. Themes decide how to render. The orchestrator handles timing accuracy, tab visibility, reduced motion, and celebration state — themes just respond to lifecycle callbacks.

📖 Full details: Architecture Overview

Build a Theme in 5 Minutes

npm run theme create my-theme
npm run generate:previews -- --theme=my-theme
npm run dev

Visit http://localhost:5173/?mode=timer&duration=30&theme=my-theme to see your theme in action.

📖 Full guide: Theme Development Guide

Contributing

I want to...	Start here
Report a bug	Open an issue
Build a theme	Theme Development Guide
Fix something	Open issues · Contributing Guide

Validation Before PR

npm run validate:iteration

This runs: typecheck → lint → unit tests → build → E2E tests

Learn More

Topic	Link
Architecture deep dive	docs/ARCHITECTURE.md
Building themes	docs/THEME_DEVELOPMENT.md
URL parameters	docs/DEEP-LINKING.md
Code of Conduct	CODE_OF_CONDUCT.md
Security Policy	SECURITY.md

License

MIT

Try the app →