swiftapp/readme.md

# 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 `swift/SocialIO.xcodeproj`.
3. Build the `SocialIO` scheme for:
   - `My Mac`
   - an iPad simulator
   - an iPhone simulator

## tsswift workflow

From the repo root:

```bash
corepack pnpm install
corepack pnpm swift:doctor
corepack pnpm swift:emulators
corepack pnpm swift:build
corepack pnpm swift:test
corepack pnpm swift:run
corepack pnpm swift:launch
corepack pnpm swift:review
```

This repo now uses `@git.zone/tsswift` with project config in `swift/.smartconfig.json`.

- `build` targets macOS, iPhone Simulator, and iPad Simulator in parallel
- `test` targets macOS, which matches the current test bundle setup
- `run` defaults to macOS unless you pass `--platform ios` or `--platform ipad`
- `launch` starts the app with the configured control-file transport enabled
- `review` replaces the old shell-script review loop and captures screenshot sets for iPhone, iPad, and macOS

Useful direct commands:

```bash
corepack pnpm exec tsswift prefer-emulator --path swift/SocialIO.xcodeproj --platform ios --udid <iphone-simulator-udid>
corepack pnpm exec tsswift prefer-emulator --path swift/SocialIO.xcodeproj --platform ipad --udid <ipad-simulator-udid>
corepack pnpm exec tsswift command --path swift/SocialIO.xcodeproj --route 'socialio://open?thread=launch-copy&message=launch-copy-2'
```

## 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

Single-platform capture examples:

```bash
corepack pnpm swift:screenshots:ios
corepack pnpm swift:screenshots:ipad
corepack pnpm swift:screenshots:macos
```

The route list now lives in `swift/Automation/ui-screenshot-routes.txt`.

## Standard UI review loop

For UI-affecting changes, use:

```bash
corepack pnpm swift:review
```

That flow now:

- builds and captures an iPhone review pass
- builds and captures an iPad review pass
- builds and captures a macOS review pass
- saves the review set to `/tmp/socialio-ui-review/ios`, `/tmp/socialio-ui-review/ipad`, and `/tmp/socialio-ui-review/macos`

Simulator selection is now handled through `tsswift emulators` and `tsswift prefer-emulator`, and the chosen devices are written into `swift/.smartconfig.json`.

The macOS capture path still needs Accessibility and Screen Recording permission for the terminal app that runs the command, because `tsswift` positions the app window before each screenshot.

## 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`