docs: add sunrise/sunset widget feature design spec

1 files changed, 123 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-03-23-sunrise-sunset-widget-design.md b/docs/superpowers/specs/2026-03-23-sunrise-sunset-widget-design.md
new file mode 100644
index 0000000..27f7dbd
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-23-sunrise-sunset-widget-design.md
@@ -0,0 +1,123 @@
+# Sunrise/Sunset Times Widget Feature
+
+**Date:** 2026-03-23
+**Status:** Design Approved
+
+## Overview
+
+Add sunrise and sunset time display to both small and medium widgets. Times are calculated locally using the existing NOAA solar position algorithm, formatted as HH:mm, and updated daily at midnight based on user location.
+
+## Requirements
+
+- Display sunrise/sunset times in HH:mm format on widgets
+- Calculate times locally using existing `SunTimes` utility
+- Use user's current location for calculations
+- Update once daily at midnight (aligned with current refresh policy)
+- Show nothing if location permission is denied or unavailable
+- Apply to both small and medium widget families
+
+## Architecture
+
+### Data Model
+
+Extend `SolvervDef` to include sunrise/sunset times:
+```
+SolvervDef
+├── date: Date
+├── bg: String
+├── sunriseTime: Date? (optional, time only)
+└── sunsetTime: Date? (optional, time only)
+```
+
+Extend `SolvervEntry` to propagate the times:
+```
+SolvervEntry
+├── date: Date
+├── def: SolvervDef (contains sunrise/sunset)
+```
+
+### Timeline Provider Logic
+
+Update `Provider.getTimeline()`:
+
+1. Get user's cached location (latitude, longitude)
+2. If location unavailable → create entry with nil sunrise/sunset
+3. Initialize `SunTimes(latitude, longitude, date: currentDate)`
+4. Extract sunrise and sunset times
+5. Create entry with times
+6. Refresh at next midnight
+
+### Data Calculation Flow
+
+```
+Location Permission Check
+    ↓ (if granted)
+Get Cached Coordinates
+    ↓
+SunTimes Calculator
+    ├─ Input: latitude, longitude, date
+    ├─ Output: sunrise Date, sunset Date
+    └─ Fallback: nil (polar regions, edge cases)
+    ↓
+Format as HH:mm
+    ↓
+SolvervDef/Entry
+    ↓
+Widget Display
+```
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Location permission denied | No sunrise/sunset displayed |
+| Location unavailable/stale | No sunrise/sunset displayed |
+| SunTimes returns nil (polar) | No sunrise/sunset displayed |
+| Date parsing fails | Widget shows current time's calculation |
+
+## Implementation Details
+
+### Changes to SolvervDef
+
+Add properties and computed properties for formatted times:
+- `sunriseTime: Date?` — raw sunrise time
+- `sunsetTime: Date?` — raw sunset time
+- `sunriseFormatted: String` — "HH:mm" or empty
+- `sunsetFormatted: String` — "HH:mm" or empty
+
+### Changes to Provider
+
+Modify `getTimeline()` to:
+1. Fetch location from cache (use existing location service)
+2. If available, calculate sun times via `SunTimes`
+3. Pass times to `SolvervDef` constructor
+4. Return timeline refreshing at next midnight
+
+### Widget View Updates
+
+**SmallWidgetView:** Add sunrise/sunset display (layout TBD)
+**MediumWidgetView:** Add sunrise/sunset display (layout TBD)
+
+Display format: sunrise time and sunset time as HH:mm when available.
+
+## Timeline & Refresh
+
+- **Frequency:** Once per day at midnight
+- **Rationale:** Sun times change gradually; daily updates are sufficient
+- **Alignment:** Matches existing solstice countdown refresh policy
+
+## Testing
+
+- Test with various locations (tropics, temperate, near poles)
+- Test without location permission
+- Test at date boundaries (midnight refresh)
+- Verify formatted times display correctly
+- Verify nil times result in no display
+
+## Future Considerations
+
+- Visualization of sunrise/sunset (charts, gradients)
+- Daylight duration calculation and trend
+- Multiple locations support
+- Custom location override
+