# Implementation notes

Built from this folder's `prompt.txt` and the current source files in `../01-loops/`. The event catalog uses the supplied manifest. No other app, slides, project history or source project was read.

## Decisions

- Kept the original four loop recordings, loop controls, initial loop levels of 45%, output level of 35%, start-from-beginning behavior, and loop engine.
- Added bell, bird and bubbling water cards. All sources begin disabled and silent. Event levels begin at 35%.
- Enabled means automatic events are allowed. Playing now has its own amber card and status, independent of the enabled button.
- Trigger now plays once even if automatic events are disabled. The same source cannot overlap itself. Different sources can overlap.
- Enabling chooses an initial random wait. Each natural ending chooses the next wait. No timer runs while that source is loading or playing.
- Shortest and longest waits use seconds, from 0 to 600. Crossing a bound moves the other bound to keep the range valid. Changing a pending wait replaces it using the new range.
- Add source offers every event recording in the supplied manifest. Each recording can be added once. New sources begin disabled. Adding and removing event cards does not restart loops.
- Durations come from browser metadata before playback is enabled, rather than from filenames. Unavailable files show an error and cannot play.
- All audio uses native Web Audio through the same output control. Disabling, removing and global stop invalidate pending asynchronous starts as well as clearing timers. Stop all also disables automatic events, so a fresh click is required to restart them.
- Used the unslop skill for UI and notes wording. No Matt Pocock skill or installation was used.

## Checks run

- `node --test engine.test.mjs`: 7 tests passed. Mocked Web Audio and timers cover silence before interaction, duration readiness, duplicate prevention, scheduling after natural end, one-shot playback, no self overlap, overlap between separate sources, disabling and removal, cancellation during decoding, wait bounds, and loops continuing during event changes.
- `node --check app.js` and `node --check event-catalog.js`: passed.
- Checked that every catalog URL and all four loop URLs point to a supplied audio file.
- The first attempted test command used `--experimental-default-type=module`, which this installed Node rejected. Running Node directly succeeded. No package or build step is required.

## Limits

Browser interaction, rendering, actual audio decoding, audible levels and transitions have not been verified by this implementation agent. The parent agent handles browser tests. Engine tests use mocks and cannot prove those browser behaviors.

Browser background-tab timer throttling can make an event arrive later than its chosen wait. Settings reset when the page reloads. The engine has no limiter, so enabling many sources and raising their levels can produce a loud mix.

`attempts/001/` preserves the first complete implementation and its tests. Later fixes belong in the app root, without changing that snapshot.