# Orb for iOS
Native SwiftUI iOS client for **Orb**, located in `SandboxedDashboard/Orb`.
> **Note:** The iOS target builds `Orb.app` (`PRODUCT_NAME: "Orb"`) and connects to your Core backend.
## Features
- **Projects & Synced Colors** (`OrbProjects.swift`, `OrbProjectAppearance.swift`) — Browse projects with synchronized colors, mission trees, and finished groups.
- **Live Conversations & Rich Transcripts** (`OrbConversation*.swift`, `OrbTranscriptModel.swift`, `OrbTranscriptScroll.swift`, `OrbWorkFold.swift`, `OrbRichText.swift`) — Follow real-time SSE streams, expand `Worked — …` tool and thinking folds, answer interactive agent questions (`OrbQuestions.swift`), view KaTeX math, and send or queue follow-ups.
- **Shared Project Context & Files** (`OrbDocuments.swift`, `OrbAttachments.swift`, `OrbMessageImages.swift`) — Read and edit synchronized Markdown `@context` files, preview images, and upload attachments.
- **Unified Settings** (`OrbSettings.swift`, `OrbMachinesSettings.swift`, `OrbProvidersSettings.swift`) — Configure your **Backend** connection, manage **Providers** (including CLIProxyAPI OAuth logins and quota inspection), and view **Machines** (registered remote nodes plus the shared `/api/settings/ssh-hosts` address book).
## Performance
- **Streaming replies** (`OrbStreamText.swift`, spec `lean/Orb/Stream.lean`) — text deltas are coalesced to one update per frame, only the streaming bubble observes them, and the Markdown parser re-parses only the open tail after the committed prefix (checked against `shared/orb-spec/fixtures/stream-commit.json`).
- **Bounded memory** — tool results are kept to their first 4 KB (`StoredEvent.compacted`; the work fold shows 1,200 characters), orchestration results stay whole.
- **Measuring** — `OrbPerformanceUITests` (open, scroll, stream, browse memory) against `TestsSupport/orb_fixture_server.py`. XCUITest queries snapshot the app's whole accessibility tree on its main thread, so compare instructions retired or a Time Profiler trace of a query-free window, not raw CPU time; and measure on an idle machine.
## Presentation
Native surfaces, Inbox density and device checks follow the [mobile UI contract](../docs/ui/mobile.md).
## Requirements
- Xcode 16.0+ (with iOS 26 SDK in CI)
- Swift 6.0
- [XcodeGen](https://github.com/yonaskolb/XcodeGen) (`brew install xcodegen`)
## Building
Generate the Xcode project from `project.yml` and build:
```bash
cd ios_dashboard
xcodegen generate
open SandboxedDashboard.xcodeproj
```
Or build from the command line:
```bash
xcodebuild -project SandboxedDashboard.xcodeproj \
-scheme SandboxedDashboard \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
build
```
## Xcode Cloud & CI
1. `ci_scripts/ci_post_clone.sh` runs automatically in Xcode Cloud and GitHub Actions (`iOS Build`).
2. It downloads pinned XcodeGen `2.46.0`, regenerates `SandboxedDashboard.xcodeproj`, and fails if the committed project file is out of sync with `project.yml`.
3. GitHub’s `iOS Build` workflow compiles without signing (`CODE_SIGNING_ALLOWED=NO`). TestFlight distribution is handled by Xcode Cloud on the `master` branch.
4. `ci_scripts/ci_pre_xcodebuild.sh` stamps archives as `.` (the version lives once, in `project.yml`; both Info.plists read `$(MARKETING_VERSION)` / `$(CURRENT_PROJECT_VERSION)`) so each upload has a new build number; App Store Connect rejects a repeated one. Keep "Manage Version and Build Number" off in the workflow's Archive action.
## Project Structure
```text
ios_dashboard/
├── project.yml # XcodeGen specification (builds Orb.app)
├── ci_scripts/
│ ├── ci_post_clone.sh # Xcode Cloud & CI project verification hook
│ └── ci_pre_xcodebuild.sh # Xcode Cloud unique build number per archive
├── SandboxedDashboard/
│ ├── SandboxedDashboardApp.swift # App entrypoint
│ ├── ContentView.swift # Auth gate + OrbHome root view
│ ├── Orb/ # Primary Orb iOS UI
│ │ ├── OrbCore.swift
│ │ ├── OrbProjects.swift
│ │ ├── OrbProjectAppearance.swift
│ │ ├── OrbConversation.swift
│ │ ├── OrbRichText.swift
│ │ ├── OrbQuestions.swift
│ │ ├── OrbDocuments.swift
│ │ ├── OrbAttachments.swift
│ │ ├── OrbMessageImages.swift
│ │ ├── OrbSettings.swift
│ │ ├── OrbMachinesSettings.swift
│ │ └── OrbProvidersSettings.swift
│ ├── Models/ # StoredEvent, AnyCodable, FIDO request models
│ └── Services/ # FIDO approvals (the HTTP client is Orb/OrbClient.swift: OrbCore)
├── SandboxedDashboardTests/ # Unit tests
└── SandboxedDashboardUITests/ # UI & fixture server tests
```