stoppclock-page

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Stoppclock 🕐

Projector-friendly timers and clocks built with React + TypeScript. The SPA ships multiple specialized timers, lightweight blog/pillar pages, and a privacy-first ad/consent setup.

## What ships today
- **Timer tools (hash routes)**: Analog countdown (`#/analog`), digital countdown (`#/countdown`), stopwatch with laps (`#/stopwatch`), pomodoro (`#/pomodoro`), cooking timer (`#/cooking`), couples timer (`#/couples`), digital clock (`#/digital`), world clock (`#/world`), alarm manager (`#/alarm`), metronome (`#/metronome`), and chess clock (`#/chess`).
- **Content pages**: Time philosophy pillar (`#/time-philosophy`), timer guides (`#/timer-for-students`, `#/timer-for-productivity`, `#/timer-for-fitness`), blog posts (`#/blog/pomodoro-timer-online`, `#/blog/pomodoro-vs-countdown`), knowledge/about/imprint/privacy/contact routes.
- **Controls & persistence**: Shared keyboard shortcuts (Space start/pause, R reset, F fullscreen, L laps for stopwatch), per-tool localStorage state, and fullscreen toggles.
- **PWA shell**: Manifest + lightweight service worker that caches the app shell/manifest and keeps assets network-first.
- **Theming & accessibility**: Dark/light toggle with preference persistence, high-contrast layout, and hash-based routing that keeps pages keyboard navigable.

## Architecture
```mermaid
flowchart TD
  A[index.html] --> B[src/main.tsx]
  B --> C[App with hash-based router]
  C --> D[Timer pages]\n(#/analog ... #/chess)
  C --> E[Content pages]\n(#/time-philosophy ...)
  B --> F[Contexts]\n(PinnedTimers)
  B --> G[Shared components]\n(DarkModeToggle, Consent, Ads)
  D --> H[Hooks & utils]
  H --> H1[useKeyboardShortcuts]
  H --> H2[useAutoFitText]
  H --> H3[beep/flash]
  B --> I[Styles]\n(design-tokens.css, styles.css)
  B --> J[Service worker]\n(public/sw.js)
```

- **Entry & routing**: `src/main.tsx` registers the service worker, sets up the PinnedTimers provider, and switches content based on `window.location.hash` without React Router.
- **Pages**: Timer pages live in `src/pages/` and embed shared controls (Home button, keyboard shortcuts, fullscreen helpers). Content/SEO pages use the same hash router.
- **State & persistence**: Timers store state in `localStorage` with schema keys like `sc.v1.countdown` to survive reloads; runtime updates rely on `requestAnimationFrame` loops.
- **Styling**: Global tokens in `src/design-tokens.css` and `src/styles.css`; per-page styles live alongside components.
- **Ads & consent**: `ConsentBanner` gates `AdSenseScript` so ad code only loads after explicit consent.

## Design direction (home page)
- **Unify timer grid + descriptions**: The next redesign aims to merge the home timer tiles with the "About the Timers" blurbs. Each tile should surface its microcopy (what it does, ideal use case, key shortcut) directly inside the card, reducing the scroll between the hero grid and the descriptive section.
- **Progressive detail**: Default view shows icon + label + one-liner; hover/focus expands to a short checklist (e.g., "Space = Start/Pause, R = Reset") without shifting layout on touch devices.
- **Content reuse**: Descriptions are sourced from the existing "About the Timers" content so cards and the dedicated section stay in sync while the redesign is phased in.

## Key behaviors
- **Keyboard shortcuts**: Centralized in `src/hooks/useKeyboardShortcuts.ts` (Space start/pause, `R` reset, `F` fullscreen, `L` laps on stopwatch) and auto-disabled when typing in inputs.
- **Timer UX**: Countdown/analog timers cap durations (digital up to 12h, analog up to 4h) and emit optional beep/flash warnings. Stopwatch records laps; pomodoro persists custom durations; metronome drives audio ticks; chess clock swaps active player.
- **PWA**: `public/manifest.webmanifest` defines install metadata; `public/sw.js` keeps a cache versioned shell and cleans old caches. Assets stay network-first so deploys stay fresh.

## Routes at a glance
| Route | Purpose |
| --- | --- |
| `#/` | Home grid with timer shortcuts, design toggles, footer links |
| `#/analog` | Analog countdown with canvas dial |
| `#/countdown` | Digital HH:MM:SS countdown with warnings |
| `#/stopwatch` | Stopwatch with lap capture |
| `#/pomodoro` | Work/break cycles with persistence |
| `#/cooking` | Cooking timer presets |
| `#/couples` | Paired/couples timer |
| `#/digital` | Always-on digital clock |
| `#/world` | Multi-timezone world clock |
| `#/alarm` | Multiple alarms management |
| `#/metronome` | Adjustable BPM metronome |
| `#/chess` | Dual-player chess clock |
| `#/time-philosophy` & content routes | Editorial/SEO content and legal pages |

## Development
1. Install Node.js 18+ and npm.
2. Install dependencies: `npm install`
3. Start the dev server: `npm run dev`
4. Build for production: `npm run build`
5. Preview the production build: `npm run preview`

## Testing
Playwright specs live in `tests/e2e/` and cover the main timers (analog countdown, countdown, stopwatch, digital clock, world clock, alarm, metronome, chess clock).

Run all E2E tests locally:
```bash
npm run test:e2e
```

## AdSense Slot IDs
- `home-top`: 2954253435
- `home-middle`: 2345678901
- `setup-main`: 3456789012
- `interstitial-complete`: 4567890123
- `anchor-bottom`: 5678901234

## Contributing & support
- Please run `npm run doctor` before opening a PR to catch forbidden tokens and common issues.
- For questions or issues, open a GitHub issue with browser/OS details and repro steps.

## License
MIT

Stoppclock 🕐

Projector-friendly timers and clocks built with React + TypeScript. The SPA ships multiple specialized timers, lightweight blog/pillar pages, and a privacy-first ad/consent setup.

What ships today

Timer tools (hash routes): Analog countdown (#/analog), digital countdown (#/countdown), stopwatch with laps (#/stopwatch), pomodoro (#/pomodoro), cooking timer (#/cooking), couples timer (#/couples), digital clock (#/digital), world clock (#/world), alarm manager (#/alarm), metronome (#/metronome), and chess clock (#/chess).
Content pages: Time philosophy pillar (#/time-philosophy), timer guides (#/timer-for-students, #/timer-for-productivity, #/timer-for-fitness), blog posts (#/blog/pomodoro-timer-online, #/blog/pomodoro-vs-countdown), knowledge/about/imprint/privacy/contact routes.
Controls & persistence: Shared keyboard shortcuts (Space start/pause, R reset, F fullscreen, L laps for stopwatch), per-tool localStorage state, and fullscreen toggles.
PWA shell: Manifest + lightweight service worker that caches the app shell/manifest and keeps assets network-first.
Theming & accessibility: Dark/light toggle with preference persistence, high-contrast layout, and hash-based routing that keeps pages keyboard navigable.

Architecture

flowchart TD
  A[index.html] --> B[src/main.tsx]
  B --> C[App with hash-based router]
  C --> D[Timer pages]\n(#/analog ... #/chess)
  C --> E[Content pages]\n(#/time-philosophy ...)
  B --> F[Contexts]\n(PinnedTimers)
  B --> G[Shared components]\n(DarkModeToggle, Consent, Ads)
  D --> H[Hooks & utils]
  H --> H1[useKeyboardShortcuts]
  H --> H2[useAutoFitText]
  H --> H3[beep/flash]
  B --> I[Styles]\n(design-tokens.css, styles.css)
  B --> J[Service worker]\n(public/sw.js)

Entry & routing: src/main.tsx registers the service worker, sets up the PinnedTimers provider, and switches content based on window.location.hash without React Router.
Pages: Timer pages live in src/pages/ and embed shared controls (Home button, keyboard shortcuts, fullscreen helpers). Content/SEO pages use the same hash router.
State & persistence: Timers store state in localStorage with schema keys like sc.v1.countdown to survive reloads; runtime updates rely on requestAnimationFrame loops.
Styling: Global tokens in src/design-tokens.css and src/styles.css; per-page styles live alongside components.
Ads & consent: ConsentBanner gates AdSenseScript so ad code only loads after explicit consent.

Design direction (home page)

Unify timer grid + descriptions: The next redesign aims to merge the home timer tiles with the "About the Timers" blurbs. Each tile should surface its microcopy (what it does, ideal use case, key shortcut) directly inside the card, reducing the scroll between the hero grid and the descriptive section.
Progressive detail: Default view shows icon + label + one-liner; hover/focus expands to a short checklist (e.g., "Space = Start/Pause, R = Reset") without shifting layout on touch devices.
Content reuse: Descriptions are sourced from the existing "About the Timers" content so cards and the dedicated section stay in sync while the redesign is phased in.

Key behaviors

Keyboard shortcuts: Centralized in src/hooks/useKeyboardShortcuts.ts (Space start/pause, R reset, F fullscreen, L laps on stopwatch) and auto-disabled when typing in inputs.
Timer UX: Countdown/analog timers cap durations (digital up to 12h, analog up to 4h) and emit optional beep/flash warnings. Stopwatch records laps; pomodoro persists custom durations; metronome drives audio ticks; chess clock swaps active player.
PWA: public/manifest.webmanifest defines install metadata; public/sw.js keeps a cache versioned shell and cleans old caches. Assets stay network-first so deploys stay fresh.

Routes at a glance

Route	Purpose
`#/`	Home grid with timer shortcuts, design toggles, footer links
`#/analog`	Analog countdown with canvas dial
`#/countdown`	Digital HH:MM:SS countdown with warnings
`#/stopwatch`	Stopwatch with lap capture
`#/pomodoro`	Work/break cycles with persistence
`#/cooking`	Cooking timer presets
`#/couples`	Paired/couples timer
`#/digital`	Always-on digital clock
`#/world`	Multi-timezone world clock
`#/alarm`	Multiple alarms management
`#/metronome`	Adjustable BPM metronome
`#/chess`	Dual-player chess clock
`#/time-philosophy` & content routes	Editorial/SEO content and legal pages

Development

Install Node.js 18+ and npm.
Install dependencies: npm install
Start the dev server: npm run dev
Build for production: npm run build
Preview the production build: npm run preview

Testing

Playwright specs live in tests/e2e/ and cover the main timers (analog countdown, countdown, stopwatch, digital clock, world clock, alarm, metronome, chess clock).

Run all E2E tests locally:

npm run test:e2e

AdSense Slot IDs

home-top: 2954253435
home-middle: 2345678901
setup-main: 3456789012
interstitial-complete: 4567890123
anchor-bottom: 5678901234

Contributing & support

Please run npm run doctor before opening a PR to catch forbidden tokens and common issues.
For questions or issues, open a GitHub issue with browser/OS details and repro steps.

License

MIT