# Jentelle Belle

A gentle bell instead of an abrupt alarm. You choose when your loud alarm goes off, and how long before it a gentle sequence should begin. In between, the volume follows an arc you draw, and you drop sounds onto that arc: chimes, birdsong, a background that swells, your own MP3s, a voice that reads the time. It lives in the toolbox at `tools/public/jentelle-belle/` → `/jentelle-belle` as a public work in progress, and is meant to leave the toolbox one day and become an installable phone app in its own repository. "Jentelle Belle" is a working name; other candidates are Gentle Bell, Gentle Belle, Belle, Gentile and Jentelle.

Start here, then read the others as needed:

| File | What it is |
|---|---|
| `CLAUDE.md` | Rules for anyone (human or agent) changing code here, including the data rules and what to run before pushing |
| `README.md` | This file: what exists, how it is built, how to run and test it |
| `PLAN.md` | The vision, the architecture, the road from this web prototype to an installed Android app, and the phases |
| `TASKS.md` | The live checklist by phase. Update it when you finish or add work |
| `DECISIONS.md` | Judgment calls made so far and the open questions for Austin |
| `DATA-MODEL.md` | Exact shapes of alarms, cues and sound files, the backup format, and how the volume arc is computed |
| `DISTRIBUTION.md` | How the app will be shipped without the Play Store and how the in-app "Update" button will work |
| `LEARNINGS.md` | Bugs found and lessons, so the next session does not repeat them |
| `info.md` | The short public write-up shown at `/jentelle-belle/info` |
| `meta.json` | Toolbox metadata (title, status, storage disclosure) |
| `version.json` | The latest web version, read by Settings → Check for updates |

## What works today (v0.1)

- **Alarms.** A list of alarms; each has a name, a loud alarm time, days, and a gentle start measured as minutes before the loud alarm (10 minutes up to 4 hours). A new install starts with one example alarm, "Morning".
- **The volume arc.** An SVG chart with time on the x axis (labelled in clock time, from the gentle start to the loud alarm) and volume on the y axis. Drag the left dot for the starting volume, the right dot for the ending volume and the small middle dot to bend the curve. Presets: Linear, Slow build, Quick rise and Flat (start and end the same).
- **Cues on the arc.** Three kinds: a **Sound** plays at a moment (once, or repeating every 1 to 15 minutes until a chosen end, with a "sprinkle" setting that randomizes the timing a little each time), a **Background** fades in at a moment and loops until an end point, and a **Voice** speaks text such as "It's {time}" using the phone or browser's built-in speech. Each cue has its own level relative to the arc, so a cue is always as loud as the arc is at that moment times its own level. Drag a cue along the arc to move it.
- **Sounds.** Built-in sounds are synthesized in the browser (soft chime, small bell, birdsong, water drop, ocean swell, rain, warm pad), so there are no audio files to ship. You can also add your own audio files in Settings → Your sounds and use them as a sound, a background loop or the final alarm.
- **Preview.** Plays the whole sequence on a fast clock (1 minute per second, 5 per second, or real time) with a moving playhead, then rings the final alarm until you stop it. "Hear it" plays a single cue at the level the arc gives it.
- **Settings.** Check for updates (web version), your sounds, download and import a backup (alarms only), erase everything.
- **Storage.** Alarms in `localStorage` under `jb.v1`, audio blobs in IndexedDB database `jb-audio`. Nothing leaves the device.

## What does not work yet, on purpose

- **Nothing rings with the page closed.** A web page cannot wake a phone at a set time. That is the single biggest reason the real product is an installed app. See `PLAN.md`.
- Alarms cannot be switched on or off or scheduled yet; the editor only designs and previews them.
- Backups do not include your own audio files.
- No text-to-speech into an MP3, no sleep tracking, no sync between devices.

## How it is built

Plain JavaScript modules with no build step, so the folder can be copied out of the toolbox as it is. Code that does not need a browser is kept separate so it can be unit tested and later reused by the native app.

| Path | Role |
|---|---|
| `index.html`, `assets/app.css` | Page shell and styles (dark by default, light follows the system setting) |
| `assets/js/app.js` | Starts the app, owns the state and the hash router (`#/`, `#/alarm/<id>`, `#/settings`) |
| `assets/js/model.js` | Defaults, the built-in sound catalogue, normalizers that repair any stored or imported data, the starter alarm |
| `assets/js/envelope.js` | Pure functions: the volume arc, where repeating cues land, the slider-to-amplitude curve. Unit tested |
| `assets/js/clock.js` | Time formatting and the clock time at any point of a sequence |
| `assets/js/store.js` | Debounced `localStorage` saves and IndexedDB audio blobs, with in-memory fallbacks when storage is blocked |
| `assets/js/sounds.js` | Web Audio synthesis of the built-in sounds, backgrounds and final alarms; speech |
| `assets/js/engine.js` | Plays a sequence on a simulated clock; the playback logic the native app will have to reimplement |
| `assets/js/chart.js` | The arc editor (SVG, pointer events) |
| `assets/js/ui.js` | Small DOM helpers (`h` for HTML, `s` for SVG), toast, download |
| `assets/js/views/` | The alarm list, the editor and the settings page |
| `dev/make-icons.mjs` | Regenerates `icons/` (the SVG is the source of truth, PNGs are rendered with Playwright) |
| `tests/` | Unit tests and a Playwright smoke test |

The card thumbnail is `shell/images/thumbs/jentelle-belle.svg` in the toolbox shell, and the card icon is `ti-bell` in `shell/icons/sprite.svg`. Both are first guesses and expected to change.

## Running and testing

```
npm run dev                                                   # from the repo root: build the toolbox and serve it at http://localhost:4173
node --test tools/public/jentelle-belle/tests/unit/*.test.mjs
node tools/public/jentelle-belle/tests/e2e/smoke.mjs --shots /tmp/jb-shots   # needs the server above and Playwright
node tools/public/jentelle-belle/dev/make-icons.mjs           # only when the logo changes
```

Open `/jentelle-belle/` on a phone on the same network for the real feel; audio needs a tap to start (the Preview button), which the browser requires anyway.

## Moving out of the toolbox

The folder is self-contained: copy it to a new repository, and the only toolbox-specific files are `meta.json` and `info.md`. The thumbnail lives in the toolbox's shell, not here. When the native app exists, this web version can stay in the toolbox as the editor and demo.
