# Wheel

Wheel is an always-on game-show clock and countdown for a spare phone or tablet. The time, the date and your countdown to the show are spelled out on a puzzle board of tiles, a wheel turns slowly through the day, and soft alerts and a finish play as the moment nears. It is built to run all day and all night without burning the screen, draining the battery or going blank. It lives at `/wheel` on the toolbox. Status: v0.1, work in progress; read `info.md` for what a visitor sees.

## Where to start

1. `CLAUDE.md` — the rules for anyone changing this folder.
2. `TASKS.md` — the live checklist; start with "Next up".
3. `DECISIONS.md` — what is decided, and the questions waiting on Austin.
4. `PLAN.md` — the concept and how it is built.
5. `DATA-MODEL.md` — exactly what is saved.
6. `LEARNINGS.md` — bugs and lessons.

## What it does (v0.1)

- **Board.** Four rows of tiles (12, 14, 14 and 12 across). Only the tiles that changed flip. A category plate sits under it.
- **Countdown that solves itself.** The default countdown is "Wheel of Countdown" at 7:30 PM every day (change the name and time in Settings). Its name starts as blank white tiles and the letters turn over as the time gets closer, finishing at zero.
- **Soft alerts.** A chime and a glow at 30, 10, 5 and 1 minutes before (editable), a quiet tick for the last 10 seconds, and a finish at the moment: tiles turn in a wave, the wheel spins and lands, a fanfare plays. Sounds are synthesized on the device. A browser only allows sound after one tap on the page, so the screen says "Tap to turn sound on" until then.
- **Day wheel.** 24 wedges, one per hour, turning once a day so now is under the pointer. Countdowns are gold wedges.
- **Four views** (countdown board, clock board, day wheel, both), upright or sideways, picked from a control strip that appears when the screen is tapped and hides itself. Optional rotation between views.
- **Options.** 12 or 24 hour time, seconds, countdown in words or digits, three looks (stage, classic green, quiet black), three motion levels (calm, lively, showtime), the plate and the big readout on or off, hold time after the moment.
- **Always on.** Screen wake lock (where the browser allows, with an honest status), full screen, picture drift against burn-in, night dimming by schedule (dim layer or a minimal clock), silence at night, offline once opened.
- **Data.** Countdowns and settings in `localStorage` under `wheel.state.v1`, with backup, restore and reset.

## Layout

- `index.html`, `manifest.webmanifest`, `sw.js`, `favicon.svg`, `icons/icon.svg` — the page and its offline shell, relative paths only so it works under `/wheel/`. Every new file must be added to `CORE` in `sw.js`, and `VERSION` bumped on each release.
- `assets/app.css` — all styling; looks are tokens on `:root[data-look]`.
- `assets/js/clock.js` — pure time math (occurrences, countdown text, 12-hour text, night, drift). Takes `now`, never reads the clock.
- `assets/js/layout.js` — pure text layout onto the 12/14/14/12 board.
- `assets/js/reveal.js` — pure seeded reveal order for the self-solving puzzle.
- `assets/js/events.js` — countdown events, normalizer, which one is featured, puzzle progress.
- `assets/js/alerts.js` — pure: which alerts fire between two readings.
- `assets/js/scenes.js` — pure: what the board shows (tiles, plate, readout, screen-reader text).
- `assets/js/wheelmath.js` — pure wheel geometry and spin timing.
- `assets/js/model.js` — settings and state, normalizers, storage, backup.
- `assets/js/board.js`, `wheel.js`, `audio.js`, `keepawake.js`, `ui.js` — the DOM, SVG, sound and wake-lock layers.
- `assets/js/settings.js`, `app.js` — the settings page, boot, routing and the redraw loop.
- `tests/unit/` and `tests/e2e/smoke.mjs` — tests.

## Tests

```
node --test tools/public/wheel/tests/unit/*.test.mjs
npm run dev    # in another terminal
node tools/public/wheel/tests/e2e/smoke.mjs --shots <dir>
```

The end-to-end test needs Playwright, fakes the clock with `page.clock`, and covers the countdown, alerts, finish, wheel, settings, night, backup and phone sizes. Look at the screenshots as well as the pass count.

## Related tools

- **Simple Count Down** (`/simple-count-down`) is the plain version of the same job. They share nothing; see `DECISIONS.md` for a later import.
- **Horizon** (`/horizon`) is the time-awareness dashboard. **Jentelle Belle** (`/jentelle-belle`) is the gentle alarm and follows the same honesty rule: do not promise what the web page cannot do.
