Update spec with detailed clarifications on algorithm, widget refresh, AppGroup schema, images, and offline behavior

1 files changed, 62 insertions, 11 deletions

diff --git a/docs/superpowers/specs/2026-03-23-solstice-widget-design.md b/docs/superpowers/specs/2026-03-23-solstice-widget-design.md
index f3b889c..1271435 100644
--- a/docs/superpowers/specs/2026-03-23-solstice-widget-design.md
+++ b/docs/superpowers/specs/2026-03-23-solstice-widget-design.md
@@ -65,9 +65,29 @@ Build an iOS app that displays a countdown to the next solstice or equinox, with
 
 ### Data Sharing
 
-- **AppGroup Container:** Store user location (lat/lon) and cached sunrise/sunset times
-- **Widget Timeline:** Update once daily using WidgetKit's `.atEnd` policy
+**AppGroup Container:** Store user location and cached sunrise/sunset times using the container ID `group.com.ivarlovlie.solverv`
+
+**AppGroup Data Schema:**
+```json
+{
+  "userLocation": {
+    "latitude": Double,
+    "longitude": Double,
+    "timestamp": Date (when location was last updated),
+    "isDefaultLocation": Boolean (true if using Greenwich fallback)
+  },
+  "sunTimes": {
+    "date": Date (which day these times are for),
+    "sunrise": Date (full DateTime in local timezone),
+    "sunset": Date (full DateTime in local timezone),
+    "timestamp": Date (when this was calculated)
+  }
+}
+```
+
+- **Widget Timeline:** Updates at midnight (local time) using `timelineReloadPolicy: .after(nextMidnight)`
 - Both app and widget read from the same AppGroup container for consistency
+- Cache invalidation: Sunrise/sunset cache is recalculated if stored date differs from today or location changes
 
 ---
 
@@ -78,21 +98,21 @@ Build an iOS app that displays a countdown to the next solstice or equinox, with
   - Seasonal image (fills most of space)
   - Event name (small caption)
   - Countdown in days (large, bold text)
-- **Refresh:** Daily
+- **Refresh:** `timelineReloadPolicy: .after(nextMidnight)` — refreshes at midnight local time to update countdown
 - **Purpose:** Quick glance at how many days remain
 
 ### Medium Widget (364×169)
 - **Layout:** Horizontal split
   - Left: Seasonal image (square)
   - Right: Vertical stack with event name, countdown (large), progress bar
-- **Refresh:** Daily
+- **Refresh:** `timelineReloadPolicy: .after(nextMidnight)` — refreshes at midnight local time to update countdown
 - **Purpose:** Balance of visual and numeric information
 
 ### Large Widget (364×364)
 - **Layout:** Vertical stack
   - Top half: Seasonal image
   - Bottom half: Event name, countdown, progress bar, preview of next 3 upcoming events (mini list)
-- **Refresh:** Daily
+- **Refresh:** `timelineReloadPolicy: .after(nextMidnight)` — refreshes at midnight local time to update countdown
 - **Purpose:** Comprehensive view with upcoming events preview
 
 ### Images
@@ -100,6 +120,13 @@ Build an iOS app that displays a countdown to the next solstice or equinox, with
 - Sourced from Assets.xcassets
 - Same image shown for all events in that season
 
+**Image Specifications:**
+- Aspect ratio: 1:1 (square)
+- Resolutions: 1x (1024×1024), 2x (2048×2048), 3x (3072×3072)
+- Variants: One version each for light mode and dark mode
+- Safe area: Ensure important visual content avoids outer 20-point margin
+- Format: PNG with alpha channel (for light/dark transparency support)
+
 ---
 
 ## Main App Info Screen
@@ -108,7 +135,8 @@ Build an iOS app that displays a countdown to the next solstice or equinox, with
 - Seasonal image (landscape orientation friendly)
 - Next event name (large)
 - Countdown in days (very large, prominent)
-- Progress bar (days elapsed / total days)
+- Progress bar showing days elapsed since the previous solstice/equinox divided by total days in that cycle
+  - Example: If Winter Solstice (Dec 21) is passed and Summer Solstice (Jun 21) is upcoming, on Jan 21 the progress is 31/183 days elapsed
 
 ### Middle Section
 - **Today's Sun Times**
@@ -122,8 +150,11 @@ Build an iOS app that displays a countdown to the next solstice or equinox, with
 ### Bottom Section
 - **Upcoming Events List** (scrollable)
   - Shows next 8-12 events
-  - Each row: Event name | Date/Time | Days remaining | Season color indicator
-  - Searchable/filterable by season (optional enhancement)
+  - Each row displays:
+    - Event name (e.g., "Spring Equinox")
+    - Date/Time in local timezone, 12-hour format with AM/PM (e.g., "Mar 20, 2026 2:46 PM")
+    - Days remaining as integer (e.g., "45 days")
+    - Season color indicator: 12pt circle matching the season's primary color (spring: green, summer: yellow, autumn: orange, winter: blue)
 
 ### Navigation
 - Tab bar or simple navigation to this screen
@@ -145,9 +176,11 @@ Build an iOS app that displays a countdown to the next solstice or equinox, with
 - Sunrise/sunset calculated for user's timezone and location
 
 ### Sunrise/Sunset Algorithm
-- Use NOAA solar position algorithm (lightweight, no external API)
-- Built into iOS or implement a simplified version
-- Cache results in AppGroup container to avoid recalculation
+- Implement a simplified solar position algorithm based on the NOAA Sunrise/Sunset and Solar Equinoxes/Solstices algorithm
+- No external APIs or third-party dependencies
+- Algorithm inputs: latitude, longitude, date
+- Algorithm output: sunrise time, sunset time (in local timezone)
+- Cache results in AppGroup container to avoid recalculation on each app launch
 
 ---
 
@@ -211,6 +244,24 @@ Build an iOS app that displays a countdown to the next solstice or equinox, with
 
 ---
 
+## Additional Clarifications
+
+### Solstice Date Coverage
+- Hardcoded data spans 2025–2030
+- After 2030, app continues functioning but upcoming events won't display beyond December 2030
+- Plan for data expansion before 2030: extend to 2040+ in an app update
+
+### Season Assignment
+- The displayed season for an event is always the season being celebrated
+- Example: Spring Equinox always displays spring imagery (green), even if shown during late winter on the calendar
+
+### Offline Functionality
+- **First Launch:** Location permission is requested. If granted, app calculates and caches sunrise/sunset. If denied, app uses Greenwich (0°, 0°) and displays all features with default location times.
+- **Subsequent Use:** App and widget work entirely offline; all solstice dates and countdown calculations are local
+- **Sunrise/Sunset:** Cached and recalculated daily or when location changes. If unavailable (permission denied), widget displays countdown only
+
+---
+
 ## Success Criteria
 
 ✅ Widget displays countdown in days