# SocialIO Swift App

Multiplatform SwiftUI mail client scaffold for macOS, iPadOS, and iOS.

## What is included

- One shared SwiftUI app target
- Mocked mail backend with seeded conversations
- Three-column mail UI that adapts across Apple platforms
- Compose flow, search, unread filters, favorites, and message detail
- Backend-driven navigation hooks for mailboxes, threads, and compose flows
- Screenshot/test automation route IDs and accessibility identifiers

## Open the project

1. Install/select full Xcode on this Mac.
2. Open `SocialIO/SocialIO.xcodeproj`.
3. Build the `SocialIO` scheme for:
   - `My Mac`
   - an iPad simulator
   - an iPhone simulator

## App control contract

The app can be driven in three ways:

- Launch with `SOCIALIO_ROUTE`
- Launch with `SOCIALIO_COMMAND_JSON`
- Keep a running app subscribed to a mocked backend control file with `SOCIALIO_CONTROL_FILE`

### Deep link examples

```text
socialio://mailbox/inbox
socialio://mailbox/starred?unreadOnly=true
socialio://thread/launch-copy
socialio://open?thread=launch-copy&message=launch-copy-2
socialio://compose?to=grandma@example.com&subject=Family%20Photos&body=Hi%20Grandma
```

### JSON command examples

```json
{"kind":"mailbox","mailbox":"archive","search":"roadmap"}
{"kind":"thread","threadID":"launch-copy","messageID":"launch-copy-2"}
{"kind":"compose","to":"grandma@example.com","subject":"Family Photos","body":"Hi Grandma"}
```

### Stable mock route IDs

- Threads: `launch-copy`, `daily-sync-status`, `investor-update`, `search-ranking-polish`, `welcome-to-socialio`, `roadmap-notes`
- Messages: `launch-copy-1`, `launch-copy-2`, `investor-update-1`, `roadmap-notes-1`, and similar seeded IDs

## Mock backend control

When `SOCIALIO_CONTROL_FILE` points at a text file, the running app polls it and applies the latest command whenever the file contents change.

Examples:

```bash
echo 'socialio://open?thread=launch-copy&message=launch-copy-2' > /tmp/socialio-control.txt
echo '{"kind":"compose","to":"grandma@example.com","subject":"Photos","body":"Hi Grandma"}' > /tmp/socialio-control.txt
```

That gives us a mocked backend transport now, and we can swap the same command model behind a real API later.

## Screenshot automation

After the app is built and installed in Simulator, run:

```bash
/Users/philkunz/gitea/social.io-swiftapp/Scripts/capture-controlled-screenshots.sh booted /tmp/socialio-shots
```

The script launches the app with `SOCIALIO_CONTROL_FILE`, rewrites that file with a series of routes, and saves screenshots for each destination.

## Standard UI review loop

For UI-affecting changes, use the one-shot verification script:

```bash
/Users/philkunz/gitea/social.io-swiftapp/Scripts/verify-ios-ui.sh
```

That standard flow:

- builds the iPhone simulator app
- installs it into Simulator
- runs the backend-control screenshot pass
- saves the review set to `/tmp/socialio-ui-review`

The screenshot list lives in `/Users/philkunz/gitea/social.io-swiftapp/Scripts/ui-screenshot-routes.txt`, so we can keep expanding the review set as the app grows.

## UI test hooks

Key controls now expose stable accessibility identifiers such as:

- `mailbox.inbox`
- `filter.unread`
- `thread.launch-copy`
- `message.launch-copy-2`
- `compose.view`
- `compose.to`
- `compose.subject`
- `compose.body`
- `compose.send`