Lody iOS

Independent iOS Native Client · AI Collaboration & Session Companion for Mobile

Install the current build on your iPhone through TestFlight:

https://testflight.apple.com/join/1rR6Ku8f

Requires iOS 26 or later. Beta builds track main and update automatically; they are pre-release and may be unstable, as described above.

Lody iOS is an independent open-source client crafted for iPhone, providing a lightweight and secure bridge between remote Lody services and local workspaces.

The project uses a hybrid architecture of React Native + a deeply customized Swift native module (LodyKit). While preserving the rapid iteration advantages of declarative cross-platform UI, critical interactions (infinite chat collection, streaming text rendering, code diff highlighting, file tree, etc.) are built with native Swift and CoreText to deliver an authentic iOS system feel.

Lody iOS started as a one-day prototype and became a usable TestFlight client in about a week, driven by coding agents under tight product constraints: iOS only, one native kit module, system UI when React Native cannot meet HIG, and an offscreen WebView for Flock/Loro because official Node/CRDT packages do not bundle in Metro.

The full first-person write-up is Prototype in a Day, Shipped in a Week: Building Lody iOS in Live.

What that week actually looked like:

• Constraints before features. The first prompt named the architecture (RN template, one Kit module, no Android, Swift when RN is not enough) and left product surface to be inferred.
• Decide, then implement. Navigation chrome, search, iPad shell, and onboarding were argued in the open; rejected paths stayed off main.
• HIG as acceptance, not taste. Native UIBarButtonItem, system sheets, and semantic colors were required; RN fakes of system chrome were rejected on screenshots.
• Verify without login. Offline Debug scenes, leased Simulators, screenshots for visual state, and video for temporal behavior became the gate: if the verify script was right, the change shipped.
• RN as the base, Swift where it matters. Chat, composer, list rows, and diffs moved into LodyKit. Swift grew from a few hundred lines on day one to nearly half the UI surface by the end of the week.

• Human Interface Guidelines Compliance: Native adoption of iOS semantic colors, automatic light and dark mode adaptation, and Dynamic Type with SF Pro and SF Mono.
• Native Navigation: A single Expo Router native Stack with typed routes, transparent headers, and automatic scroll edge effects. Transient flows open as native sheets through the shared present() runtime, and system grouped rows use UIKit UICollectionViewListCell via LodyGroupedList.
• Bilingual by Default: English and Simplified Chinese product copy lives in apps/mobile/locales, is checked in CI, and is projected into native xcstrings catalogs by the local withLocales config plugin.

• Virtualized Chat Collection: The chat view is backed by native Swift UICollectionView, maintaining full 60/120 fps smoothness even with extensive message histories.
• CoreText Markdown Rendering: Deeply integrated with MarkdownView and Litext, natively supporting complex tables, syntax-highlighted code blocks, task lists, LaTeX math formulas, and system text selection handles.
• Smooth Character Fade-In: Balanced batch scheduling paired with low-level CTRunDraw character alpha transitions delivers gentle, flicker-free streaming output during AI generation.
• Native Input (ChatComposerView): Pixel-perfect keyboard avoidance matching system input methods, local draft persistence with automatic restoration, and real-time model thinking effort controls.

• Turn Changes Overview: Automatically summarizes file changes for each conversation turn, with one-tap access to all modified files.
• Word-Level Diff Highlighting: Full-screen diffs reuse a prewarmed Expo DOM WebView running @pierre/diffs. Tool-detail diffs render natively in LodyKit.
• Remote Workspace File Tree: Browse project directories and files on remote Macs or servers at any time, with previews via native code view LodyCodeView or system Quick Look.

Agent Conversation Sync in Settings lists supported local projects and agents on your own computers. Refresh their history, select conversations to import, and explicitly confirm any conflict replacement. Imports run in batches and retain partial progress; this is a manual history import, not automatic device-to-device mirroring.

• Preview Chip: When an agent reports a local dev server, a chip above the composer opens it through the machine's Lody Quick Tunnel. Long-press copies the share link, opens it in Safari, or stops sharing. The control proof is signed natively with the Keychain credential; only short-lived tunnel links reach the app.
• Native Simulator Viewer: A baguette server behind the tunnel opens a pushed native page instead of a web view. H.264 frames decode into AVSampleBufferDisplayLayer, touches go back over the same WebSocket, and the device frame and its side buttons are drawn natively. Hardware actions (Home, lock, rotate, shake, volume, screenshot) sit in the navigation bar.

• Seamless CRDT Collaboration: Executes official Loro / Flock CRDT incremental sync cores and Streams clients in a Swift-managed offscreen WKWebView, completely avoiding Node/CRDT/Zstd dependency bundling issues in React Native.
• Watchdog Protection: Native Swift probing keeps background execution resilient, supporting graceful hot recovery if an anomaly occurs.
• Multi-Session Background Sync: Local SQLite display projections ensure millisecond cold starts, while background synchronization maintains real-time bi-directional updates for active sessions.

• Standard Device Flow Auth: Authorizes via the official Better Auth Device Flow.
• System Keychain Storage: All authentication credentials and sensitive communication keys are strictly isolated in the iOS Keychain and never exposed in app-accessible shared storage.

flowchart TB
    subgraph UI ["React Native Presentation Layer (Expo Router)"]
        direction TB
        Nav["Native Stack · Typed Routes"]
        Presentation["definePage / present() Presentation Runtime"]
        Screens["Session Details / File Tree / Diff Viewer / Settings"]
    end

    subgraph NativeKit ["Local Native Module (modules/lody-kit)"]
        direction TB
        LodyKitModule["LodyKit NativeModule Facade"]
        ChatView["LodyChatView (UICollectionView)"]
        Markdown["MarkdownView & Litext (CoreText Glyph Fade-In)"]
        DiffView["Shared DOM Diff + Native Inline Diff"]
        Composer["ChatComposerView (Native Input & Keyboard Avoidance)"]
    end

    subgraph DataEngine ["Offscreen Data Engine (Swift Watchdog)"]
        direction TB
        OffscreenWV["Offscreen WKWebView"]
        Flock["Flock WASM / Loro Streams Incremental Core"]
        Watchdog["Swift Native Watchdog (2s Probing / Hot Restart)"]
        SQLite["Local SQLite View Projection Snapshot"]
    end

    subgraph External ["System & Cloud Communication"]
        Keychain["iOS Keychain Credential Storage"]
        CloudStreams["Remote Lody Cloud Streams / Machine RPC"]
    end

    UI -->|"Invocations & Event Subscriptions"| NativeKit
    NativeKit -->|"State Changes & Dispatches"| DataEngine
    DataEngine -->|"Read-Only Incremental Projections"| UI
    DataEngine -->|"Encrypted Envelope Requests"| CloudStreams
    DataEngine -->|"Snapshot Persistence"| SQLite
    NativeKit -->|"Credential Operations"| Keychain

lody-ios/
├── apps/
│   └── mobile/
│       ├── src/
│       │   ├── app/                 # Expo Router routes (typed routes) and the Stack declaration
│       │   ├── screens/             # *Screen pages defined with definePage
│       │   ├── features/            # Domain logic (sessions, diff, licenses)
│       │   ├── cloud/               # Cloud protocol (auth, catalog, send, kv, settings)
│       │   ├── models/              # Shared data shapes
│       │   ├── ui/                  # Shared React Native base components
│       │   ├── hooks/               # Screen bindings (session nav, page runtime, process sheet)
│       │   └── lib/                 # Infrastructure (presentation, i18n, theme)
│       ├── modules/
│       │   └── lody-kit/            # First-party local native Swift module (LodyKit)
│       │       ├── ios/             # Swift / UIKit / CoreText native code
│       │       ├── data-runtime/    # Offscreen data runtime RPC and adapter scripts
│       │       ├── decoder/         # Flock decoder bundled into the offscreen WebView
│       │       ├── src/             # Typed native component interfaces for React Native
│       │       └── verification/    # Deterministic Swift behavior checks
│       ├── verification/            # Offline UI/native baselines and Simulator tooling
│       ├── tests/                   # Node test-runner suites
│       ├── locales/                 # en / zh-Hans catalogs (projected into xcstrings)
│       ├── plugins/                 # Local Expo config plugins (MarkdownView, locales)
│       ├── scripts/                 # native:assets, license generation, locale checks
│       └── package.json
├── packages/
│   └── dom-webview/                 # Vendored Expo DOM WebView (MIT) hosting the shared diff view
├── docs/                            # Architecture design, specs, and evolution docs
├── package.json                     # Monorepo root configuration
└── pnpm-workspace.yaml

• macOS: Sequoia or later — GitHub iOS verification and TestFlight use the macOS 27 preview image
• Xcode: 26.5 or later with Command Line Tools — local offline Simulator baselines default to iOS 26.5; GitHub iOS jobs use the Xcode 27 preview image and iOS 27.0
• Node.js: >= 22.13 (React Native 0.86 also accepts ^20.19.4, ^24.3, and >= 25)
• pnpm: 11.10.0 (corepack enable)
• Ruby & Bundler: apps/mobile/Gemfile pins cocoapods ~> 1.16 and cocoapods-spm

1. Clone the repository and install JavaScript dependencies:

   git clone https://github.com/Innei/lody-ios.git
   cd lody-ios
   pnpm install

2. Install the CocoaPods toolchain (into apps/mobile/vendor/bundle):

   cd apps/mobile
   bundle install
   cd ../..

3. Generate the native project and launch simulator:

   pnpm ios

   [!TIP] This project uses cocoapods-spm to integrate SPM static library dependencies. pnpm ios runs native:assets, generates the native project, and executes bundle exec pod install to fetch dependencies and link symbols. After building native code once, run pnpm start directly when modifying only JavaScript to connect to the hot reload server.

4. Update native assets:

   If you modify runtime assets in modules/lody-kit/data-runtime/ or modules/lody-kit/decoder/, run:

   pnpm --filter @lody-ios/mobile native:assets

pnpm check            # TypeScript, locale catalogs, generated license notices, Prettier
pnpm test             # Node test suites, Simulator tooling tests, vendored DOM WebView tests
pnpm bundle           # Verify iOS Hermes JavaScript production bundle integrity
pnpm licenses:build   # Regenerate the in-app notices after dependency changes

UI baselines run without login, user credentials, cloud access, or a connected machine: EXPO_PUBLIC_UI_VERIFY=1 injects deterministic data at the Auth/Catalog boundary, and every case starts from the development-only Debug page.

pnpm verify:simulator --name '<current verify>' -- <command>   # Lease a Lody * Verify Simulator
pnpm verify:native                                             # Swift behavior checks
pnpm verify:ui --app /absolute/path/to/Lody.app                # Offline UI baselines
pnpm verify:ui --suite core --embedded --app /absolute/path/to/Lody.app  # PR core paths, Release app

The runner captures screenshots for visual states and video for temporal behavior; missing scenes and timeouts fail the run. See apps/mobile/verification/ui/README.md for the case inventory and Simulator leasing rules.

Pushing to main runs .github/workflows/ship.yml. A push always archives a TestFlight build through .github/workflows/release.yml; a manual dispatch publishes an OTA update to the configured expo-updates server when the Expo fingerprint matches the published baseline, and falls back to TestFlight when it changes. Native runtime assets are regenerated before either route. Join the beta at https://testflight.apple.com/join/1rR6Ku8f.

Lody iOS is released under the GNU Affero General Public License v3.0 (AGPL-3.0-only). You may use, modify, and distribute it, including commercially, provided that derivative works and network-served modifications stay under the same license and their source stays available to users.

Bundled third-party libraries and assets keep their own licenses. The full list and license texts are available in the app under Settings → Open Source Licenses. The notices are generated from the production dependency closure by pnpm licenses:build and verified in CI by pnpm check.

Lody iOS is made possible thanks to these open-source projects and creators:

• FlowDown: Thanks to Lakr233 and contributors. Lody's native message collection view, stream batching mechanism, and dynamic measurement cache architecture drew significant inspiration from FlowDown.
• unixzii: Original author of Litext, the CoreText rich-text engine underneath MarkdownView and Lody's native chat rendering. Also a generous teacher — a great deal of this project's iOS knowledge came from him.
• MarkdownView & Litext: High-performance, extensible CoreText Markdown rendering and typography for iOS.
• @pierre/diffs: Word-level diff algorithms and the full-screen DOM viewer.
• Loro: High-performance, production-grade next-generation CRDT state synchronization.
• Expo DOM WebView: Vendored under packages/dom-webview (MIT) and extended to host the shared diff view.
• AXe: Simulator UI automation driving the offline UI baselines.
• baguette: Headless iOS Simulator control and streaming (Apache-2.0). The native simulator viewer is a client of its HTTP and WebSocket protocol; baguette itself runs on the Mac and is not bundled.
• vphone-client: Its native remote iPhone viewer (hardware decode into AVSampleBufferDisplayLayer, raw UIKit touch forwarding, never dropping input behind video) shaped the design of Lody's simulator viewer.