1jehuang--jcode/docs/IOS_APP.md

# jcode iOS App

> Status: v2 rebuild. Pure Swift. This replaces the earlier prototype and the
> Rust-mobile-core/simulator direction, both removed in the `ios-app-restart`
> branch history.

## Product definition

A native iOS remote control for jcode servers running on your own machines.
The phone renders conversations and drives sessions; all heavy lifting (LLM
calls, tools, git, files, MCP) stays on the server. Reachability is assumed to
be Tailscale (or LAN); the app never talks to LLM providers directly.

Design identity: dark, calm, terminal-native without being retro. Mint accent
(`#4DD9A6`) for live/connected state. Dense information in touchable cards.

## Architecture decision: pure Swift

The app is a thin client over an existing, server-owned protocol. Behavior
worth sharing lives server-side already. A shared Rust core would duplicate
the server protocol a third time and require an FFI bridge, custom renderer
work, and a parallel simulator to stay honest. Instead:

- **Swift owns the client.** SwiftUI for UI, Swift 6 concurrency, `@Observable`.
- **The server protocol is the single source of truth.** The Swift codec is
  validated by fixture tests against real wire JSON; drift fails tests.
- **Testability without devices** comes from layering, not a simulator:
  everything below the view layer builds and tests on macOS via `swift test`.

## Layering

```
ios/
  Package.swift              SPM package, builds on macOS + iOS
  Sources/JCodeKit/          platform-free client core (no UIKit)
    Gateway.swift            endpoints: /health, /pair, /ws
    Pairing.swift            pairing code -> auth token
    Wire.swift               Request/ServerEvent codecs (NDJSON over WS)
    Transport.swift          WebSocketTransport protocol + URLSession impl
    Connection.swift         actor: connect/auth/reconnect, AsyncStream<ServerEvent>
    SessionReducer.swift     pure state machine: events -> transcript/app state
    CredentialStore.swift    Keychain-backed server credentials (protocol + impl)
  Sources/JCodeMobile/       SwiftUI app shell (iOS only)
    JCodeMobileApp.swift     entry
    AppModel.swift           @Observable glue: Connection + Reducer -> views
    Views/                   Pairing, Chat, Transcript, Sessions, Settings
    QRScannerView.swift      camera pairing
    Theme.swift              colors/typography tokens
  Tests/JCodeKitTests/       swift test on macOS: codec fixtures, reducer, pairing
  project.yml                XcodeGen spec for the app target
```

Rules:

- `JCodeKit` never imports UIKit/SwiftUI. It must compile for macOS so the
  whole behavior layer is testable headlessly by agents on this machine.
- Views contain no protocol or state-transition logic. `AppModel` only
  forwards actions and publishes reducer output.
- `SessionReducer` is a pure function `(State, ServerEvent) -> State`
  (plus local user intents). All streaming/tool/session edge cases are unit
  tested there, replacing the old Rust simulator's role.

## Protocol

Server side (already shipped, unchanged):

- `jcode pair` CLI generates a 6-digit code (5 min TTL) and QR with
  `jcode://pair?host=H&port=P&code=C`.
- `POST http://host:7643/pair` with `{code, device_id, device_name}` returns
  `{token, server_name, server_version}`. Token is stored hashed server-side.
- `GET /health` for reachability checks.
- `ws://host:7643/ws?token=...` upgrades to a WebSocket carrying the same
  newline-delimited JSON protocol as Unix-socket TUI clients
  (`crates/jcode-protocol/src/wire.rs`, `#[serde(tag = "type")]`).

Client v1 requests: `subscribe`, `message`, `cancel`, `soft_interrupt`,
`ping`, `get_history`, `resume_session`, `set_model`, `rename_session`,
`clear`.

Client v1 events consumed: `ack`, `text_delta`, `reasoning_delta`,
`reasoning_done`, `text_replace`, `tool_start`, `tool_input`, `tool_exec`,
`tool_done`, `message_end`, `done`, `error`, `pong`, `state`, `session`,
`session_renamed`, `history`, `model_changed`, `available_models_updated`,
`tokens`, `interrupted`, `status_detail`, `notification`, `compaction`.
Unknown event types are ignored by design (forward compatibility).

## Feature scope

v1 (this rebuild):

- Pair via QR scan or manual host/port/code; multiple saved servers in Keychain
- Connect/disconnect lifecycle with automatic reconnect + backoff
- Chat: send, streamed assistant text, markdown rendering, reasoning indicator
- Tool calls rendered as collapsible cards with live status
- Interrupt (cancel) and soft-interrupt (queue a message mid-run)
- Session list (from history payload), switch via `resume_session`, rename
- Model picker from `available_models`
- Token usage + connection status surfaces
- Error and disconnect banners that never silently drop user input

Later (explicitly out of v1): push notifications (APNs), Live Activities,
voice input, image attachments, tool approval UX, ambient/swarm dashboards,
widgets, Mac Catalyst polish.

## Testing strategy

1. `swift test` (macOS, no Xcode project needed):
   - codec round-trips against fixture JSON captured from the real server
   - `SessionReducer` streaming scenarios (deltas, tool lifecycle, history
     replay, interrupts, errors, reconnect resubscribe)
   - pairing client against a stubbed URLProtocol
   - connection actor against a fake `WebSocketTransport`
2. `xcodebuild build` of the app target (XcodeGen) keeps the UI compiling.
3. Manual/automated device pass via `xcrun simctl` once a simulator runtime is
   installed; not a CI gate.

## CI

A macOS job runs `swift test` in `ios/` plus `xcodegen` + `xcodebuild build`
for the app target. TestFlight delivery can be re-added later (the previous
Codemagic pipeline was removed with the prototype).