# TheNoiseClock

TheNoiseClock is a SwiftUI iOS app that blends a bold, full-screen digital clock with white noise playback and a rich alarm system. It is optimized for iOS 26+ with Swift 6, built on a modular architecture, and styled with the Bedrock design system. Alarms use AlarmKit for reliable wake-up alerts that cut through Focus modes and silent mode.

---

## App Store Information

### App Name
TheNoiseClock

### Subtitle (30 chars max)
Clock, noise, and alarms

### Promotional Text (170 chars max)
A clean, full-screen clock with ambient soundscapes and a powerful alarm editor. Customize colors, fonts, and glow for a distraction-free display.

### Keywords (100 chars max)
clock,alarm,white noise,ambient,sleep,timer,focus,night mode,bedside

### Description
TheNoiseClock is a distraction-free digital clock with built-in white noise and a fully featured alarm system. Designed for late-night focus, bedside use, and calm environments, it fills the screen with bold, stable digits and lets you tune the look and sound to your space.

**Clock**
- Full-screen, orientation-aware clock with optional seconds and AM/PM
- Fixed-width digits prevent layout "jumping"
- Auto-fit sizing and manual scale control
- Custom fonts, weights, and designs with live preview
- Glow and opacity controls for low-light comfort
- Clock tab hides the status bar for a distraction-free display
- Selectable animation styles: None, Spring, Bounce, and Glitch
- Modern iOS 26 animations: numeric transitions, phase-based bounces, glitch effects, and breathing colons
- Automatic full-screen: UI fades out after 5 seconds of inactivity, tap to restore
- Optional mini-controls for alarms and white noise directly on the clock face

**White Noise**
- Multiple ambient categories and curated sound packs
- Seamless looping with background audio support
- Quick preview on long-press, instant play/stop controls

**Alarms (Powered by AlarmKit)**
- Unlimited alarms with labels, repeat schedules, and snooze options
- Alarm sound library with preview (MP3 format)
- Vibration and volume controls per alarm
- AlarmKit integration: alarms cut through Focus modes and silent mode
- Live Activity countdown shows 5 minutes before alarm fires
- Dynamic Island displays countdown and alarm status
- Lock Screen shows alarm countdown with custom UI
- Full-screen in-app alarm screen with Snooze/Stop when active
- Snooze support via AlarmKit's countdown feature

**Display Mode**
- Automatic full-screen display after 5 seconds of inactivity
- Tap anywhere to restore navigation and status bar
- Optional wake-lock to keep the screen on

### What's New
- First-launch onboarding with feature highlights and notification setup
- Branded launch experience with Bedrock theming
- Redesigned settings interface with cards, toggles, and sliders
- Centralized build identifiers via xcconfig

---

## Features

- Real-time digital clock with full customization
- Full-screen display mode and Dynamic Island awareness
- White noise playback with categories and previews
- Rich alarm editor with scheduling and snooze controls
- Full-screen in-app alarm screen with Snooze/Stop controls
- Bedrock-based theming and branded launch
- iPhone and iPad support with adaptive layouts
- First-launch onboarding with feature highlights and permission setup

---

## Requirements

- iOS 26.0+
- Xcode 26+
- Swift 6

---

## Build & Run

Open `TheNoiseClock.xcodeproj` and run the `TheNoiseClock` scheme.

### Terminal Build
```bash
cd /Users/mattbruce/Documents/Projects/iPhone/TheNoiseClock
xcodebuild -project TheNoiseClock/TheNoiseClock.xcodeproj -scheme TheNoiseClock -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.2' build
```

### Terminal Test
```bash
cd /Users/mattbruce/Documents/Projects/iPhone/TheNoiseClock
xcodebuild -project TheNoiseClock/TheNoiseClock.xcodeproj -scheme TheNoiseClock -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.2' test
```

---

## Branding & Theming

The app uses Bedrock for theme tokens, settings UI, and the launch experience.

- Theme: `TheNoiseClock/Shared/Design/NoiseClockTheme.swift`
- Branding config: `TheNoiseClock/Shared/Design/BrandingConfig.swift`
- Launch screen: `TheNoiseClock/Resources/LaunchScreen.storyboard`

To generate an app icon in DEBUG:
1. Open Clock Settings -> Debug
2. Tap **Icon Generator**
3. Export `AppIcon.png` and drop it into `Assets.xcassets/AppIcon`

---

## Build Configuration (xcconfig)

Identifiers are centralized in xcconfig files:

- `TheNoiseClock/Configuration/Base.xcconfig`
- `TheNoiseClock/Configuration/Debug.xcconfig`
- `TheNoiseClock/Configuration/Release.xcconfig`

Update `COMPANY_IDENTIFIER` and `DEVELOPMENT_TEAM` in `Base.xcconfig` to migrate to a new account.

Swift access is provided via:
`TheNoiseClock/Configuration/AppIdentifiers.swift`

---

## Recent Engineering Updates

- Alarm defaults now use `digital-alarm.mp3` for consistent AlarmKit scheduling.
- Alarm sound metadata loading now caches decoded data and falls back safely if configuration files are missing/corrupt.
- Alarm UI refresh uses a dedicated `alarmsDidUpdate` notification instead of reusing clock-style notifications.
- Date overlay formatting now uses cached formatters to reduce repeated allocation overhead.
- Shared scheme configuration includes both unit and UI tests under `xcodebuild ... -scheme TheNoiseClock test`.
- Onboarding now updates Keep Awake through `ClockViewModel` (single source of truth) instead of direct `UserDefaults` writes.
- Alarm scheduling failures now surface user-visible errors and rollback failed add/update/toggle operations.
- Added accessibility identifiers for critical controls and updated UI tests to use stable identifiers instead of coordinate heuristics.

---

## Architecture

TheNoiseClock follows a clean, modular structure:

```
TheNoiseClock/
├── AudioPlaybackKit/            # Reusable audio package
├── TheNoiseClock/               # Main app target
│   ├── App/                     # App entry, TabView
│   ├── Configuration/           # xcconfig + AppIdentifiers
│   ├── Features/                # Clock, Alarms, Noise
│   ├── Shared/                  # Theme, branding, utilities
│   └── Resources/               # Bundles, JSON, assets
└── TheNoiseClock.xcodeproj/
```

---

## Support & Contact

For feedback, feature requests, or support:
support@thenoiseclock.app