Reflect/docs/Apple-Features.md

# Apple Platform Features

This document covers the new Apple-specific features integrated into Feels, including how to trigger and test each one.

---

## 1. Control Center Widget

**File:** `FeelsWidget2/FeelsWidget.swift` (FeelsMoodControlWidget)

**What it does:** Adds a quick-access button to Control Center that opens Feels to log your mood.

### How to Add to Control Center
1. Open **Settings** > **Control Center**
2. Scroll down to find **Feels - Log Mood**
3. Tap the **+** button to add it
4. Alternatively: Swipe down from top-right, tap **+** button, find Feels

### How to Test
1. Add the widget to Control Center (steps above)
2. Open Control Center (swipe down from top-right corner)
3. Tap the "Log Mood" button
4. Feels app should open

### Implementation Details
- Uses `ControlWidget` and `StaticControlConfiguration`
- `OpenFeelsIntent` (AppIntent) handles the button tap
- `openAppWhenRun = true` ensures the app opens

---

## 2. HealthKit State of Mind API

**File:** `Shared/HealthKitManager.swift`

**What it does:** Syncs mood entries to Apple Health using the State of Mind API, allowing users to see mood correlations with sleep, exercise, and other health metrics.

### Setup Required
1. Enable HealthKit in **Settings** > **Feels** > **Health**
2. Grant write permission for "State of Mind"

### How to Test
1. Go to Feels settings and enable HealthKit sync
2. Log a mood entry
3. Open **Apple Health** app
4. Go to **Browse** > **Mental Wellbeing** > **State of Mind**
5. Your mood entry should appear with the corresponding valence

### Mood to Valence Mapping
| Mood | Valence | HealthKit Labels |
|------|---------|------------------|
| Horrible | -1.0 | stressed, anxious |
| Bad | -0.5 | sad, discouraged |
| Average | 0.0 | peaceful, content |
| Good | 0.5 | happy, joyful |
| Great | 1.0 | excited, grateful |

### Implementation Details
- Uses `HKStateOfMind` with `kind: .dailyMood`
- Valence ranges from -1.0 (very unpleasant) to 1.0 (very pleasant)
- Automatically syncs when mood is logged (if enabled)

---

## 3. App Intents / Siri Shortcuts

**File:** `Shared/AppShortcuts.swift`

**What it does:** Enables voice-activated mood logging via Siri and adds shortcuts to the Shortcuts app.

### Available Shortcuts

#### Log Mood
- **Phrases:**
  - "Log my mood in Feels"
  - "Log mood as [mood] in Feels"
  - "Record my mood in Feels"
  - "I'm feeling [mood] in Feels"
  - "Track my mood in Feels"

#### Check Today's Mood
- **Phrases:**
  - "What's my mood today in Feels"
  - "Check today's mood in Feels"
  - "How am I feeling in Feels"

#### Get Mood Streak
- **Phrases:**
  - "What's my mood streak in Feels"
  - "Check my streak in Feels"
  - "How many days in a row in Feels"

### How to Test
1. Say "Hey Siri, log my mood in Feels"
2. Siri will prompt you to select a mood (Horrible, Bad, Average, Good, Great)
3. Confirm selection
4. Siri responds with confirmation and shows a visual snippet

### How to Add to Shortcuts App
1. Open **Shortcuts** app
2. Tap **+** to create new shortcut
3. Search for "Feels"
4. Available actions: Log Mood, Check Today's Mood, Get Mood Streak

### Implementation Details
- `MoodEntity` provides the mood options for Siri parameter selection
- `LogMoodIntent` saves to DataController and optionally syncs to HealthKit
- `MoodLoggedSnippetView` shows visual confirmation in Siri

---

## 4. Custom Tips System

**Files:**
- `Shared/FeelsTips.swift` (Tips definitions and manager)
- `Shared/Views/TipModalView.swift` (Modal UI)

**What it does:** Shows themed modal tips to help users discover features throughout the app. Tips appear as beautiful sheets that match the app's current theme.

### Available Tips

| Tip | Location | Trigger |
|-----|----------|---------|
| CustomizeLayoutTip | Customize screen | First visit |
| AIInsightsTip | Insights tab | After 7 moods logged |
| SiriShortcutTip | Settings | After 3 mood logs |
| HealthKitSyncTip | Settings | After viewing settings |
| WidgetVotingTip | Day view | After 2 days usage |
| TimeViewTip | Day view | First visit |
| MoodStreakTip | Day view | When streak >= 3 |

### How to Test
1. Tips appear automatically based on conditions (one per session)
2. To reset tips for testing:
```swift
FeelsTipsManager.shared.resetAllTips()
```
3. To disable tips globally:
```swift
FeelsTipsManager.shared.tipsEnabled = false
```

### Implementation Details
- `FeelsTipsManager.shared.resetSession()` called in `FeelsApp.init()`
- Each tip has `isEligible` property based on user activity parameters
- Tips show as themed modal sheets with gradient headers
- Only one tip shown per app session

---

## 5. Live Activities

**Files:**
- `Shared/MoodStreakActivity.swift` (Manager + Attributes)
- `FeelsWidget2/FeelsWidget.swift` (Widget views)

**What it does:** Shows mood streak progress on the Lock Screen and Dynamic Island.

### How to Start a Live Activity
```swift
// In your code where you want to start tracking
await LiveActivityManager.shared.startStreakActivity(
    streak: currentStreak,
    lastMood: todaysMood,
    hasLoggedToday: true
)
```

### How to Update After Mood Log
```swift
LiveActivityManager.shared.updateActivity(
    streak: newStreak,
    mood: loggedMood
)
```

### How to End Activity
```swift
await LiveActivityManager.shared.endAllActivities()
```

### Live Activity Views

#### Lock Screen View
- Shows flame icon with streak count
- Displays today's mood with color indicator
- Shows "Don't break your streak!" prompt if not logged

#### Dynamic Island
- **Compact:** Flame icon + streak number
- **Expanded:** Full streak info, mood status, voting window countdown
- **Minimal:** Flame icon only

### How to Test
1. Ensure Live Activities are enabled: **Settings** > **Feels** > **Live Activities**
2. Start a Live Activity (see code above)
3. Lock your phone to see Lock Screen view
4. On iPhone 14 Pro+, check Dynamic Island

### Requirements
- iPhone with iOS 16.1+ (Lock Screen)
- iPhone 14 Pro/Pro Max+ for Dynamic Island
- `NSSupportsLiveActivities = true` in Info.plist (already configured)

### Implementation Details
- `MoodStreakAttributes` defines the activity data structure
- `ActivityConfiguration` renders both Lock Screen and Dynamic Island
- Activities automatically end at midnight via `scheduleActivityEnd()`

---

## Entry Types

New entry types added to track mood entry sources:

| Type | Raw Value | Description |
|------|-----------|-------------|
| `.siri` | 7 | Logged via Siri voice command |
| `.controlCenter` | 8 | Logged via Control Center widget |
| `.liveActivity` | 9 | Logged via Live Activity tap |

---

## Entitlements & Info.plist

### Entitlements (`Feels (iOS).entitlements`)
- `com.apple.developer.healthkit` - HealthKit access
- `com.apple.developer.healthkit.access` - health-records

### Info.plist (`Feels--iOS--Info.plist`)
- `NSSupportsLiveActivities` - Enables Live Activities
- `NSHealthShareUsageDescription` - HealthKit read permission description
- `NSHealthUpdateUsageDescription` - HealthKit write permission description

### Widget Info.plist (`FeelsWidgetExtension-Info.plist`)
- `NSSupportsLiveActivities` - Enables Live Activity widget

---

## Testing Checklist

- [ ] Control Center widget appears and opens app
- [ ] Siri responds to "Log my mood in Feels"
- [ ] Siri shows mood options and confirms selection
- [ ] HealthKit sync writes State of Mind entries
- [ ] Tips appear at appropriate times
- [ ] Live Activity shows on Lock Screen
- [ ] Dynamic Island updates (iPhone 14 Pro+)
- [ ] Entry types correctly recorded in database