Initial social.io Swift app

SocialIO/README.md

@@ -0,0 +1,106 @@
+# 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`