# 15. Home Screen Widgets

meta:
  id: ios-production-15
  feature: ios-production
  priority: P2
  depends_on: []
  tags: [native-features, widgets, production]

objective:
- Implement home screen widgets to display threat score and recent alerts at a glance

deliverables:
- Widget extension target
- Small, medium, and large widget sizes
- Widget configuration intent
- Timelines with refresh strategy

steps:
1. Create widget extension:
   - Add Widget Extension target in Xcode
   - Configure app group for data sharing
   - Set up widget bundle with multiple widgets
2. Design widgets:
   - Small widget: Threat score gauge only
   - Medium widget: Threat score + 2 recent alerts
   - Large widget: Threat score + alert list + quick actions
   - Use SwiftUI for widget UI
   - Match app design system colors
3. Implement widget timeline:
   - Create TimelineProvider
   - Fetch data from shared UserDefaults or App Group
   - Update every 15 minutes (widget limit)
   - Handle placeholder, snapshot, and timeline entries
4. Add widget configuration:
   - Intent for selecting widget type (if multiple variants)
   - Intent for filtering alerts by severity
   - Configuration UI in widget gallery
5. Share data with widget:
   - Write threat score and alerts to shared container
   - Update shared data when app refreshes
   - Use WidgetCenter to reload timelines after app update
6. Add deep linking:
   - Tap widget → open app to relevant screen
   - Tap alert in widget → open alert detail
   - Tap threat score → open dashboard

tests:
- Unit: Test timeline provider data formatting
- UI: Test widget rendering in all sizes
- Integration: Test data sharing between app and widget

acceptance_criteria:
- Widget extension building and running
- Small widget showing threat score
- Medium widget showing threat score + recent alerts
- Large widget showing full alert summary
- Widgets update every 15 minutes
- Data shared correctly between app and widget
- Deep links from widget to correct app screens
- Widgets match app design system
- Placeholder and snapshot states look good
- Widgets work in dark mode
- No crashes when widget data is missing

validation:
- Add widget to home screen → displays current threat score
- Receive new alert → widget updates within 15 minutes
- Tap widget → app opens to dashboard
- Tap specific alert in widget → alert detail opens
- Check widget in dark mode → colors correct

notes:
- Widgets cannot make network requests directly
- App must write data to shared container for widgets to read
- Widget memory limits are strict (especially for small widgets)
- Use WidgetCenter.reloadTimelines(ofKind:) to force updates