OS Share Extensions
Relevant source files
The following files were used as context for generating this wiki page:
OS Share Extensions allow users to ingest content from other applications directly into Conduit prompts. The system supports sharing text, URLs, and files from the host operating system's native share sheets.
Conduit implements these extensions through platform-specific native components that capture shared data, stage it in temporary storage, and notify the main Flutter application for processing. This ensures that multimodal prompts and text ingestion work seamlessly without requiring the user to manually copy and paste content between apps.
Sources: README.md, ios/ShareExtension/ShareViewController.swift
iOS Share Extension Architecture
The iOS implementation uses a separate App Extension target containing a ShareViewController. This controller manages the lifecycle of a share session and coordinates with the main app via a shared App Group container.
Data Ingestion and Staging
The ShareViewController iterates through extensionContext.inputItems to find compatible data types. It prioritizes specific content types and handles them accordingly:
- Text/URLs: Extracted directly from
NSItemProvider. - Files: Staged in a shared directory within the App Group container.
- Images: Encoded or downloaded (if sharing a lone link to an image) and saved to the staging area.
The extension uses a NativeShareEnvelopeStore to manage persistence in the App Group. This store ensures that the main app can retrieve the shared payload even after the extension process terminates.
Sources: ios/ShareExtension/ShareViewController.swift:1-100, ios/Runner/ShareImportBridge.swift:450-500
Image Handling Logic
The extension performs specialized processing for images to ensure they are compatible with the main app's prompt system.
- In-Memory Images: Encodes
UIImageobjects (e.g., from the screenshot editor) into PNG or JPEG data. - Lone Links: If a user shares a single URL pointing to an image file (e.g., from Safari), the extension downloads the image directly to the staging area.
Sources: ios/RunnerTests/RunnerTests.swift:1250-1300, ios/ShareExtension/ShareViewController.swift:150-200
Android Text Processing
On Android, the "Process Text" feature allows users to select text in any app and send it to Conduit via the system context menu.
ProcessTextActivity
The ProcessTextActivity handles the ACTION_PROCESS_TEXT intent. When triggered, it:
- Retrieves the selected text from the intent.
- Determines if the text is read-only or editable.
- Launches the main Conduit activity with the text as an extra.
Share Import Bridge
The ShareImportBridge acts as the receiver inside the main iOS application. It monitors the shared App Group container for new "envelopes" published by the Share Extension.
Validation and Cleanup
The bridge performs strict validation on imported payloads to prevent unauthorized file access:
- Verifies that file paths reside strictly within the known share staging directory.
- Resolves symbolic links to ensure the final path is valid and owned by the app group.
- Reclaims (deletes) staging files once they are successfully consumed by the Flutter application or if the import is superseded by a newer share action.
| Component | Function |
|---|---|
NativeShareEnvelopeStore | Manages the atomic handoff of data between the extension and main app. |
NativeSharePayloadEnvelope | A data structure containing the items (text/paths) and an optional user message. |
NativeShareStatus | Tracks the progress of an import (e.g., isInProgress, expectedFileCount). |
Sources: ios/Runner/ShareImportBridge.swift:30-120, ios/RunnerTests/RunnerTests.swift:1500-1550
Technical Specifications
File Staging Constraints
The system enforces limits to ensure stability and prevent resource exhaustion during heavy share operations.
| Parameter | Value / Constraint |
|---|---|
| Max Filename Length | 255 bytes (standardized for filesystem compatibility) |
| Max Item Count | 10 items per share session |
| Max Text Size | 1 MB per text item |
| Max Aggregate Text | 4 MB per envelope |
| Supported Image Types | PNG, JPEG, HEIC, WEBP, GIF |
Sources: ios/Runner/ShareImportBridge.swift:20-50, ios/RunnerTests/RunnerTests.swift:1200-1220
Security and Privacy
The share system implements "NoFollow" logic during directory reconciliation. It explicitly avoids following symbolic links to directories outside the App Group to prevent directory traversal attacks. Markers (hidden files) are used to track ownership of staged files, ensuring that only files explicitly shared and acknowledged are retained.
Sources: ios/Runner/ShareImportBridge.swift:550-600, ios/RunnerTests/RunnerTests.swift:1450-1480
Conclusion
OS Share Extensions provide a critical bridge between Conduit and the wider mobile ecosystem. By leveraging native iOS App Extensions and Android Intent filters, the project enables high-fidelity data ingestion of text and multimodal media. The architecture emphasizes atomic handoffs and strict file validation to maintain performance and security while handling user data across process boundaries.