# iOS Widget Extension Setup

This document describes how the ConduitWidget extension was added and how to configure it.

## Overview

The widget extension was created via Xcode and provides quick access buttons:

- **Ask Conduit** - Opens app with new chat, focuses composer
- **Camera** - Opens app, creates new chat, launches camera
- **Photos** - Opens app, creates new chat, opens photo picker  
- **Clipboard** - Opens app with clipboard contents as prompt

## Files Structure

```
ios/ConduitWidget/
├── Assets.xcassets/           # Asset catalog
│   ├── AccentColor.colorset/  # Theme accent color
│   ├── AppIcon.appiconset/    # Widget icon (uses app icon)
│   └── WidgetBackground.colorset/  # Light/dark backgrounds
├── ConduitWidget.entitlements # App group for data sharing
├── ConduitWidget.swift        # Main widget implementation
├── ConduitWidgetBundle.swift  # Widget bundle entry point
└── Info.plist                 # Extension configuration
```

## App Group Configuration

Both the main app and widget share data via the app group `group.app.cogwheel.conduit`.

**Important:** Ensure both targets have this app group in their capabilities:

1. Select the **Runner** target → Signing & Capabilities → App Groups
2. Verify `group.app.cogwheel.conduit` is listed

3. Select the **ConduitWidget** target → Signing & Capabilities → App Groups  
4. Verify `group.app.cogwheel.conduit` is listed

## Deep Link Handling

The widget uses `homewidget://` URL scheme to communicate with the Flutter app:

| Action | URL |
|--------|-----|
| New Chat | `homewidget://new_chat` |
| Camera | `homewidget://camera` |
| Photos | `homewidget://photos` |
| Clipboard | `homewidget://clipboard` |

These are handled by `HomeWidgetCoordinator` in the Flutter code.

## Widget Design (Native iOS)

```
┌─────────────────────────────────────┐
│  ✨  Ask Conduit                    │  ← System tint color
│                                     │
├───────────┬───────────┬─────────────┤
│  📷       │  🖼️       │  📋        │
│ Camera    │ Photos    │ Clipboard   │  ← Secondary system bg
└───────────┴───────────┴─────────────┘
```

- **Size**: Medium widget (systemMedium)
- **Primary button**: System tint color (follows app accent)
- **Secondary buttons**: `secondarySystemGroupedBackground`
- **Icons**: SF Symbols with hierarchical rendering
- **Typography**: SF Rounded font
- **Supports**: Light/dark mode, Dynamic Type

## Building

The widget extension is built automatically when you build the main app:

```bash
flutter build ios
```

Or build from Xcode:

1. Open `ios/Runner.xcworkspace`
2. Select the **Runner** scheme
3. Build (⌘B)

## Testing

1. Build and run the main app on a device/simulator
2. Go to home screen
3. Long press → tap **+** to add widgets
4. Search for "Conduit"
5. Add the medium widget

## Troubleshooting

### Widget not appearing in picker

- Ensure the widget extension builds without errors
- Check deployment target is iOS 17.0+
- Clean build folder (⇧⌘K) and rebuild

### Widget actions don't work

- Verify the `homewidget://` URL scheme is handled
- Check `HomeWidgetCoordinator` is initialized in app startup
- Ensure app group is configured on both targets

### Widget doesn't update

- The widget uses `.never` refresh policy (static content)
- Call `HomeWidget.updateWidget()` from Flutter to trigger refresh

## Adding to a Fresh Clone

If cloning the repo fresh, the widget extension should already be configured in the Xcode project. Just ensure:

1. Team/signing is set for both targets
2. App groups capability is enabled
3. Pod install has been run