Native Platform Bridges
Relevant source files
The following files were used as context for generating this wiki page:
Native Platform Bridges enable the Flutter-based Conduit client to communicate with low-level iOS and Android system APIs. They facilitate specialized mobile features such as Apple Private Cloud Compute (PCC), native UI components, secure clipboard operations, and text-to-speech synthesis.
The system uses Pigeon to generate type-safe messaging contracts between Dart and the host platforms, ensuring consistent data structures across Swift and Kotlin.
Sources: ios/Runner/ConduitPlatformApis.g.swift, android/app/src/main/kotlin/app/cogwheel/conduit/ConduitPlatformApis.g.kt
Architecture and Data Flow
The bridge architecture follows a host-client model where Flutter (Dart) acts as the primary controller. The host APIs handle requests from Dart, while Flutter APIs allow the native side to push events back to the UI.
Communication Pattern
- Host API: Dart calls functions implemented in Swift (iOS) or Kotlin (Android).
- Flutter API: Native code invokes methods to update the UI or notify Dart of asynchronous events (e.g., streaming status).
- Codecs: Type-safe
StandardMessageCodecimplementations serialize complex data structures like image bytes and nested configurations.
This diagram shows the bidirectional flow between Flutter and native code via Pigeon-generated channels.
Sources: ios/Runner/ConduitPlatformApis.g.swift:1351-1400, android/app/src/main/kotlin/app/cogwheel/conduit/ConduitPlatformApis.g.kt:1450-1500
Key Native Bridges
Apple Private Cloud Compute (PCC) Bridge
The PccBridge manages interactions with Apple Intelligence and Private Cloud Compute models on iOS. It handles model status checks, usage quota management, and streaming completions.
- Status Management: Checks if Apple Intelligence is enabled or if the device is eligible.
- Streaming: Delivers token deltas to Flutter using
PlatformPccStreamEvent. - Fallback Logic: Automatically moves to on-device models if PCC network requests fail, provided the request allows it.
| Feature | Description |
|---|---|
onDevice | Local SystemLanguageModel requiring iOS 26+ |
privateCloudCompute | Remote Foundation Models requiring iOS 27+ |
quotaUsage | Tracks daily limits and suggests increases |
Sources: ios/Runner/PccBridge.swift:233-315, ios/Runner/ConduitPlatformApis.g.swift:425-450
Native Sheet Bridge
NativeSheetBridge presents platform-native UI components like settings menus, date pickers, and model selectors. This ensures the app maintains a high-fidelity native look while being controlled by Flutter business logic.
- Detail Patches: Dart can "patch" an open native sheet to update its contents without dismissing it.
- Control Events: Native interactions (toggles, sliders, text input) emit
PlatformNativeSheetControlChangedEventto update the Dart state. - Hierarchy Guides: Supports visual guides for folder structures in options selectors.
This sequence illustrates how native UI elements remain synchronized with the Flutter state.
Sources: ios/Runner/NativeSheetBridge.swift:348-410, ios/Runner/NativeSheetBridge.swift:1010-1050
Native Paste Bridge
The NativePasteBridge intercepts system paste actions to handle multimodal content (images) that the standard Flutter text input might not process efficiently.
- Swizzling: It swizzles
FlutterTextInputViewmethods likepaste(_:)andcanPerformAction(_:withSender:). - Staging: Large image data is staged in a temporary directory (
conduit-native-paste) before being passed to Dart as file paths. - Handshake: Uses a marker-based ownership system (
.pending,.dart-owned,.reclaiming) to prevent native code from deleting files that Flutter is currently using.
Sources: ios/Runner/NativePasteBridge.swift:650-710, ios/Runner/NativePasteBridge.swift:150-200
Text-to-Speech (TTS) Bridge
The NativeIosTtsBridge utilizes AVSpeechSynthesizer to provide high-quality audio feedback.
- Synthesis Types: Supports live speech and file-based synthesis for offline storage.
- Voice Discovery: Exposes native system voices, including "Personal Voice" and "Novelty" traits on iOS 17+.
- Progress Tracking: Emits events during speech including
start,progress(character ranges), andcomplete.
Sources: ios/Runner/NativeIosTtsBridge.swift:85-150, ios/Runner/NativeIosTtsBridge.swift:230-260
Data Models and Constants
Native bridges use standardized structures defined in the Pigeon schema to ensure cross-platform compatibility.
| Structure | Key Fields | Purpose |
|---|---|---|
PlatformPccStatus | availability, quotaStatus, contextSize | Reports Apple Intelligence state |
PlatformNativeSheetItem | id, kind, title, sfSymbol, value | Defines a single row in a native sheet |
PlatformBackgroundStartRequest | streamIds, requiresMicrophone, leases | Manages long-running background tasks |
PlatformRect | x, y, width, height | Coordinates for native transitions |
Sources: ios/Runner/ConduitPlatformApis.g.swift:230-260, android/app/src/main/kotlin/app/cogwheel/conduit/ConduitPlatformApis.g.kt:250-280
Summary
The Native Platform Bridges provide a critical link between the portable Flutter UI and device-specific capabilities. By leveraging Pigeon-generated APIs, the system maintains strict type safety while allowing the app to perform heavy operations like file-coordinated pasting, native UI rendering, and AI model execution using system-level frameworks.