# Color Timer

A countdown timer drawn as a clock face: set it by tapping or dragging the minute hand around the 60-minute dial, or type a duration or a target time, and a coloured wedge shows how much time is left. It is for anyone who wants to see time running out instead of reading it, such as a work sprint, a cooking timer or a nudge to leave for a meeting. Live at `/color-timer` on the toolbox (app.austinpranger.com). Read `info.md` for the behavior as a visitor sees it.

It has no build step: the folder is copied into the site byte for byte and served under `/color-timer/`, so use relative paths for anything you add. It carries its own docs and tests so it can move to its own repository later as a plain copy. The logic that needs no browser lives in `assets/js/model.js` and is unit-tested; `assets/js/app.js` wires it to the page.

| File | What it is |
|---|---|
| `CLAUDE.md` | Rules for anyone changing things here. Read before touching code |
| `README.md` | This file |
| `TASKS.md` | The live checklist and the "Next up" list |
| `DECISIONS.md` | What is decided, and the questions waiting on Austin |
| `DATA-MODEL.md` | Exactly what is saved and the backup file format |
| `LEARNINGS.md` | Bugs found and lessons, so they are not repeated |
| `info.md` | The public write-up shown at `/color-timer/info` |
| `meta.json` | Toolbox metadata: title, status, dates, storage disclosure |
| `index.html` | The page markup (the dial is drawn by `app.js`) |
| `assets/app.css` | All styling; colours are tokens on `:root` |
| `assets/js/model.js` | Pure logic: saved state and settings, timer transitions, time since it ended, parsing typed times, dial geometry (countdown and overtime wedges), the alarm sound scores, formatting, backup. No DOM, time is always passed in |
| `assets/js/app.js` | The page: drawing, the drag and keyboard handling, the clock loop, the alarm (sound synthesis and effects), idle dimming, full screen, screen wake, backup buttons |
| `favicon.svg` | The icon the tool's own page and the toolbox pages use |
| `tests/unit/model.test.mjs` | Unit tests for `model.js` |
| `tests/e2e/smoke.mjs` | Playwright smoke test of the real page |

## Run and test

```
npm run dev     # at the repo root: builds and serves http://localhost:4173
node --test tools/public/color-timer/tests/unit/*.test.mjs
node tools/public/color-timer/tests/e2e/smoke.mjs --shots /tmp/color-timer-shots
```

The end-to-end test needs Playwright and the dev server running. It runs real short timers and waits out a five-second idle dim, so it takes about half a minute. Look at the screenshots as well as the pass count.

## Storage

Key `colortimer.state.v1` in `localStorage`, registered in `shell/shared/storage-registry.json`. See `DATA-MODEL.md`. `normalize()` in `model.js` is the only way data is read back.
