2026-06-13 01:12:55 -07:00
|
|
|
|
# NucleicRemote (iPhone client)
|
|
|
|
|
|
|
2026-08-07 03:59:17 -07:00
|
|
|
|
The iOS remote client for Nucleic: a projection of the Mac hosts, with no local git or CLI — the
|
|
|
|
|
|
Mac stays the single authority. It monitors sessions, reads transcripts/diffs, **answers
|
|
|
|
|
|
approvals**, and sends follow-up input at scope `approve`; a device granted scope `control` also
|
|
|
|
|
|
starts chats, interrupts, integrates/discards, retitles and archives, sets a session's
|
|
|
|
|
|
model/effort/Intelligence stop, manages todos and projects, mints pairing codes, brokers agent
|
|
|
|
|
|
sign-in, and syncs account settings — each control verb additionally gated on the host
|
|
|
|
|
|
advertising the matching `WireCapabilities` bit, so an older Mac degrades instead of erroring.
|
|
|
|
|
|
See [`docs/UX_IOS.md`](../../docs/UX_IOS.md) and
|
|
|
|
|
|
[`docs/SYNC_PROTOCOL.md`](../../docs/SYNC_PROTOCOL.md).
|
2026-06-13 01:12:55 -07:00
|
|
|
|
|
|
|
|
|
|
## Architecture
|
|
|
|
|
|
|
|
|
|
|
|
All wire/crypto logic is shared with the Mac via the **`NucleicProtocol`** SwiftPM library
|
|
|
|
|
|
(this Xcode project links it as a local package at `../..`):
|
|
|
|
|
|
|
2026-08-07 03:59:17 -07:00
|
|
|
|
- **Transports** — three, all carrying the same Noise-encrypted frames end-to-end:
|
|
|
|
|
|
**LAN** (`NWFrameChannel` over NWConnection + `LANDiscovery`, Bonjour `_nucleic._tcp`),
|
|
|
|
|
|
**tailnet** (an embedded `NucleicTailnet` node dialing the Mac's tailnet address), and the
|
2026-08-11 18:04:53 -07:00
|
|
|
|
**cloud relay** (`RelayFrameChannel` against the Hydrangea Worker room — which is E2EE-opaque
|
2026-08-07 03:59:17 -07:00
|
|
|
|
and forwards bytes it can't read). A relay session may upgrade to a hole-punched `direct` path.
|
2026-06-13 01:12:55 -07:00
|
|
|
|
- **Engine** — `NucleicProtocol.SyncClient` runs the Noise handshake (XXpsk0 to pair, IK to
|
|
|
|
|
|
reconnect), exchanges hello/welcome, and turns `HostMsg`s into a `SyncClient.Event` stream.
|
|
|
|
|
|
- **State** — `RemoteStore` (`ObservableObject`) is the single on-device UI state, a pure
|
2026-08-07 03:59:17 -07:00
|
|
|
|
projection of the hosts. It is **multi-host**: one `HostConnection` per entry in
|
|
|
|
|
|
`IdentityStore.pairedHosts()`, all connected at once and merged into one session list (no host
|
|
|
|
|
|
switcher). Identity + the paired-host registry live in `IdentityStore` (Keychain +
|
|
|
|
|
|
UserDefaults).
|
|
|
|
|
|
- **UI** — SwiftUI: `SessionsView`/`HomeView` (attention-first list), `SessionDetailView`
|
|
|
|
|
|
(transcript/diff + status-driven action area), `ApprovalCardView` (approve/deny, high-risk
|
|
|
|
|
|
answered in-app), `Composer` + `IntelligenceRail`, `ProjectsView`, `TodosView`, `MeshInfoView`,
|
|
|
|
|
|
`PairingScannerView`, `SettingsView`.
|
|
|
|
|
|
- **Push** — `PushRegistrar`/`Notifications` (APNs approval wakes, actionable for low/medium
|
|
|
|
|
|
risk) and `LiveActivityManager` (one aggregate Live Activity, host-pushed so it stays fresh
|
|
|
|
|
|
while locked).
|
2026-06-13 01:12:55 -07:00
|
|
|
|
|
|
|
|
|
|
## Build & run
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
# Resolves the local NucleicProtocol package automatically.
|
|
|
|
|
|
xcodebuild -project ios/NucleicRemote/NucleicRemote.xcodeproj \
|
|
|
|
|
|
-scheme NucleicRemote \
|
|
|
|
|
|
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' build
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Or open `NucleicRemote.xcodeproj` in Xcode and run. To pair, start the sync server on the Mac
|
2026-08-07 03:59:17 -07:00
|
|
|
|
(Nucleic ▸ Settings ▸ Add iPhone shows the QR), then scan it. Pairing over LAN needs both devices
|
|
|
|
|
|
on the same Wi‑Fi; the QR can also carry a tailnet or relay hint, which work from anywhere.
|
2026-06-13 01:12:55 -07:00
|
|
|
|
|
|
|
|
|
|
## Status
|
|
|
|
|
|
|
2026-08-07 03:59:17 -07:00
|
|
|
|
Shipped. The pair → list → subscribe → approve → reconnect path, the control-scope verbs, all
|
|
|
|
|
|
three transports, multi-host, push notifications and the Live Activity (UX_IOS §5.1/§5.3) are all
|
|
|
|
|
|
in place; the protocol/server side is covered by tests in `Tests/NucleicProtocolTests` and
|
|
|
|
|
|
`Tests/NucleicCoreTests`, and the relay/APNS Worker by `cloud/nucleic-edge/test/`.
|
