CLAUDE.md

1# iOS Package (Native iOS App)
2 
3This package contains the native SwiftUI iOS/iPadOS app for Nimbalyst. It provides a mobile interface for viewing and interacting with AI sessions synced from the desktop Electron app via end-to-end encrypted WebSocket sync.
4 
5The app is **pure Swift/SwiftUI** with no Capacitor or web framework dependency. The only web view is `TranscriptWebView` (WKWebView) which renders the rich chat transcript using the same React components as the desktop app.
6 
7## Package Structure
8 
9```
10packages/ios/
11  NimbalystNative/          # Swift Package - all business logic and UI
12    Sources/
13      App/                  # AppState (root observable), ContentView, navigation
14      Auth/                 # AuthManager (Stytch OAuth via ASWebAuthenticationSession)
15      Crypto/               # CryptoManager (AES-256-GCM, PBKDF2), KeychainManager
16      Database/             # DatabaseManager (GRDB migrations, queries)
17      Models/               # GRDB record types: Project, Session, Message, QueuedPrompt, SyncState
18      Notifications/        # NotificationManager (push notification registration)
19      Sync/                 # SyncManager, WebSocketClient, SyncProtocol types
20      Utils/                # RelativeTimestamp, NimbalystColors
21      Views/                # All SwiftUI views
22    Tests/                  # Unit and integration tests (68 tests)
23    Package.swift           # Swift Package Manager manifest (GRDB dependency)
24 
25  NimbalystApp/             # Xcode app target
26    Sources/                # App entry point (@main), DebugMenu
27    Resources/              # Assets.xcassets (AppIcon, Splash), transcript-dist bundle
28    project.yml             # XcodeGen project definition
29 
30  CryptoCompatibility/      # CommonCrypto bridging header for PBKDF2 key derivation
31 
32  src/transcript/           # React transcript web bundle (loaded in WKWebView)
33    main.tsx                # Entry point with Swift <-> JS bridge
34    styles.css              # Styles with bundled Material Symbols font
35    fonts/                  # Locally bundled Material Symbols TTF
36 
37  vite.config.transcript.ts # Vite config for transcript bundle (IIFE format for file://)
38  transcript.html           # HTML entry point for Vite build
39  dist-transcript/          # Build output (not committed)
40```
41 
42## Key Architecture Decisions
43 
44### Authentication Flow
451. QR pairing stores encryption seed + server URL in Keychain
462. Stytch OAuth stores JWT + user ID in Keychain
473. When both paired AND authenticated, managers initialize
484. Encryption key derived from seed + user ID via PBKDF2
49 
50### Data Flow
51- **Sync**: WebSocket connection to CollabV3 Durable Object (same server as desktop)
52- **Encryption**: All session data encrypted with AES-256-GCM before transmission
53- **Storage**: GRDB (SQLite) with reactive `ValueObservation` for live UI updates
54- **Transcript**: WKWebView loads bundled React app, communicates via `webkit.messageHandlers.bridge`
55 
56### iPad Support
57- `NavigationSplitView` for regular size class (sidebar + detail)
58- `NavigationStack` for compact size class (iPhone)
59 
60## Development
61 
62### Prerequisites
63- Xcode 16+
64- Node.js 20+ (for transcript bundle)
65- XcodeGen (`brew install xcodegen`)
66 
67### Commands
68```bash
69# From monorepo root:
70npm run ios:test:swift          # Run all 68 Swift tests
71npm run ios:build:transcript    # Build transcript web bundle
72 
73# From packages/ios/:
74cd NimbalystNative && swift test                    # Run tests directly
75cd NimbalystApp && xcodegen generate                # Regenerate .xcodeproj
76open NimbalystApp/NimbalystApp.xcodeproj            # Open in Xcode
77```
78 
79### Transcript Bundle
80The Xcode pre-build script in `project.yml` automatically builds the transcript with Vite and copies it to `Resources/transcript-dist/`. You can also build manually:
81 
82```bash
83npm run ios:build:transcript
84```
85 
86Output: `dist-transcript/transcript.html` + `dist-transcript/assets/` (JS bundle + Material Symbols font).
87 
88After building, copy the output to Xcode resources:
89```bash
90rm -f NimbalystApp/Resources/transcript-dist/assets/transcript-*.js
91cp dist-transcript/transcript.html NimbalystApp/Resources/transcript-dist/transcript.html
92cp dist-transcript/assets/* NimbalystApp/Resources/transcript-dist/assets/
93```
94 
95**CRITICAL: React hooks rules in `src/transcript/main.tsx`**
96 
97The transcript React app runs inside WKWebView where errors are invisible (cross-origin `window.onerror` reports "Script error." with no details). This makes hooks violations especially dangerous -- the screen goes blank with no diagnostic information.
98 
99Rules for editing `TranscriptApp` in `main.tsx`:
100- **All hooks (`useState`, `useRef`, `useCallback`, `useMemo`, `useEffect`) must come BEFORE any early returns.** React requires the same hooks to run in the same order on every render. An early `return` before a hook means that hook runs on some renders but not others, crashing React with "Rendered more hooks than during the previous render."
101- **The `TranscriptErrorBoundary` wraps the app** to catch render errors and display them on screen + report to the native bridge. Do not remove it.
102- **The `postErrorToNative` helper** sends error details through `webkit.messageHandlers.bridge` so they appear in Xcode console logs with full stack traces. Use it in any new try-catch blocks.
103- **Test after any change**: Always rebuild the transcript (`npm run ios:build:transcript`), copy to Xcode resources, and rebuild in Xcode. Vite build success does NOT mean React will render correctly at runtime.
104 
105## Key Files
106 
107| File | Purpose |
108|------|---------|
109| `Sources/App/AppState.swift` | Root observable object; owns database, crypto, and sync managers |
110| `Sources/Sync/SyncManager.swift` | WebSocket sync with CollabV3; processes index responses and broadcasts |
111| `Sources/Sync/SyncProtocol.swift` | All wire protocol types (Codable structs with CodingKeys) |
112| `Sources/Database/DatabaseManager.swift` | GRDB schema migrations, queries, and project stats refresh |
113| `Sources/Crypto/CryptoManager.swift` | AES-256-GCM encrypt/decrypt, deterministic project ID encryption |
114| `Sources/Views/TranscriptWebView.swift` | WKWebView + Coordinator with JS bridge, TranscriptController |
115| `Sources/Views/SessionDetailView.swift` | Session detail with transcript, scroll-to-top, jump-to-prompt |
116| `Sources/Views/SessionListView.swift` | Time-grouped session list with search and swipe-to-delete |
117| `Sources/Views/ProjectListView.swift` | Project list sorted by last activity with desktop connection indicator |
118| `src/transcript/main.tsx` | React transcript app with `scrollToTop`, `scrollToMessage`, `getPromptList` JS bridge |
119 
120## Testing
121- 68 Swift tests covering database, crypto, sync integration, and web view
122- See [TESTING.md](./TESTING.md) for CI/CD pipeline details
123- Tests run on both macOS (via Swift Package Manager) and iOS simulator (via Xcode)
124