feat(ios): implement native share target for images

Implement iOS Share Extension to enable native image sharing from Photos and other apps directly into TimeSafari. Users can now share images from the iOS share sheet, which will open in SharedPhotoView for use as gifts or profile pictures. iOS Native Implementation: - Add TimeSafariShareExtension target with ShareViewController - Configure App Groups for data sharing between extension and main app - Implement ShareViewController to process shared images and convert to base64 - Store shared image data in App Group UserDefaults - Add ShareImageBridge utility to read shared data from App Group - Update AppDelegate to handle shared-photo deep link and bridge data to JS JavaScript Integration: - Add checkAndStoreNativeSharedImage() in main.capacitor.ts to read shared images from native layer via temporary file bridge - Convert base64 data to data URL format for compatibility with base64ToBlob - Integrate with existing SharedPhotoView component - Add "shared-photo" to deep link validation schema Build System: - Integrate Xcode 26 / CocoaPods compatibility workaround into build-ios.sh - Add run_pod_install_with_workaround() for explicit pod install - Add run_cap_sync_with_workaround() for Capacitor sync (which runs pod install internally) - Automatically detect project format version 70 and apply workaround - Remove standalone pod-install-workaround.sh script Code Cleanup: - Remove verbose debug logs from ShareViewController, AppDelegate, and main.capacitor.ts - Retain essential logger calls for production debugging Documentation: - Add ios-share-extension-setup.md with manual Xcode setup instructions - Add ios-share-extension-git-commit-guide.md for version control best practices - Add ios-share-implementation-status.md tracking implementation progress - Add native-share-target-implementation.md with overall architecture - Add xcode-26-cocoapods-workaround.md documenting the compatibility issue The implementation uses a temporary file bridge (AppDelegate writes to Documents directory, JS reads via Capacitor Filesystem plugin) as a workaround for Capacitor plugin auto-discovery issues. This can be improved in the future by properly registering ShareImagePlugin in Capacitor's plugin registry.
2025-11-24 20:46:58 +08:00
parent 1b4ab7a500
commit ae49c0e907
16 changed files with 1839 additions and 4 deletions
--- a/doc/ios-share-extension-git-commit-guide.md
+++ b/doc/ios-share-extension-git-commit-guide.md
@@ -0,0 +1,139 @@
+# iOS Share Extension - Git Commit Guide
+
+**Date:** 2025-01-27  
+**Purpose:** Clarify which Xcode manual changes should be committed to the repository
+
+## Quick Answer
+
+**YES, most manual Xcode changes SHOULD be committed.** The only exceptions are user-specific settings that are already gitignored.
+
+## What Gets Modified (and Should Be Committed)
+
+When you create the Share Extension target and configure App Groups in Xcode, the following files are modified:
+
+### 1. `ios/App/App.xcodeproj/project.pbxproj` ✅ **COMMIT THIS**
+
+This is the main Xcode project file that tracks:
+- **New targets** (Share Extension target)
+- **File references** (which files belong to which targets)
+- **Build settings** (compiler flags, deployment targets, etc.)
+- **Build phases** (compile sources, link frameworks, etc.)
+- **Capabilities** (App Groups configuration)
+- **Target dependencies**
+
+**This file IS tracked in git** (not in `.gitignore`), so changes should be committed.
+
+### 2. Entitlements Files ✅ **COMMIT THESE**
+
+When you enable App Groups capability, Xcode creates/modifies:
+- `ios/App/App/App.entitlements` (for main app)
+- `ios/App/TimeSafariShareExtension/TimeSafariShareExtension.entitlements` (for extension)
+
+These files contain the App Group identifiers and should be committed.
+
+### 3. Share Extension Source Files ✅ **ALREADY COMMITTED**
+
+The following files are already in the repo:
+- `ios/App/TimeSafariShareExtension/ShareViewController.swift`
+- `ios/App/TimeSafariShareExtension/Info.plist`
+- `ios/App/App/ShareImageBridge.swift`
+
+These should already be committed (they were created as part of the implementation).
+
+## What Should NOT Be Committed
+
+### 1. User-Specific Settings ❌ **ALREADY GITIGNORED**
+
+These are in `ios/.gitignore`:
+- `xcuserdata/` - User-specific scheme selections, breakpoints, etc.
+- `*.xcuserstate` - User's current Xcode state
+
+### 2. Signing Identities ❌ **USER-SPECIFIC**
+
+While the **App Groups capability** should be committed (it's in `project.pbxproj` and entitlements), your **personal signing identity/team** is user-specific and Xcode handles this automatically per developer.
+
+## What Happens When You Commit
+
+When you commit the changes:
+
+1. **Other developers** who pull the changes will:
+   - ✅ Get the new Share Extension target automatically
+   - ✅ Get the App Groups capability configuration
+   - ✅ Get file references and build settings
+   - ✅ See the Share Extension in their Xcode project
+
+2. **They will still need to:**
+   - Configure their own signing team/identity (Xcode prompts for this)
+   - Build the project (which may trigger CocoaPods updates)
+   - But they **won't** need to manually create the target or configure App Groups
+
+## Step-by-Step: What to Commit
+
+After completing the Xcode setup steps:
+
+```bash
+# Check what changed
+git status
+
+# You should see:
+# - ios/App/App.xcodeproj/project.pbxproj (modified)
+# - ios/App/App/App.entitlements (new or modified)
+# - ios/App/TimeSafariShareExtension/TimeSafariShareExtension.entitlements (new)
+# - Possibly other project-related files
+
+# Review the changes
+git diff ios/App/App.xcodeproj/project.pbxproj
+
+# Commit the changes
+git add ios/App/App.xcodeproj/project.pbxproj
+git add ios/App/App/App.entitlements
+git add ios/App/TimeSafariShareExtension/TimeSafariShareExtension.entitlements
+git commit -m "Add iOS Share Extension target and App Groups configuration"
+```
+
+## Important Notes
+
+### Merge Conflicts in project.pbxproj
+
+The `project.pbxproj` file can have merge conflicts because:
+- It's auto-generated by Xcode
+- Multiple developers might modify it
+- It uses UUIDs that can conflict
+
+**If you get merge conflicts:**
+1. Open the project in Xcode
+2. Xcode will often auto-resolve conflicts
+3. Or manually resolve by keeping both sets of changes
+4. Test that the project builds
+
+### Team/Developer IDs
+
+The `DEVELOPMENT_TEAM` setting in `project.pbxproj` might be user-specific:
+- Some teams commit this (if everyone uses the same team)
+- Some teams use `.xcconfig` files to override per developer
+- Check with your team's practices
+
+If you see `DEVELOPMENT_TEAM = GM3FS5JQPH;` in the project file, this is already committed, so your team likely commits team IDs.
+
+## Verification
+
+After committing, verify that:
+1. The Share Extension target appears in Xcode for other developers
+2. App Groups capability is configured
+3. The project builds successfully
+4. No user-specific files were accidentally committed
+
+## Summary
+
+| Change Type | Commit? | Reason |
+|------------|---------|--------|
+| New target creation | ✅ Yes | Modifies `project.pbxproj` |
+| App Groups capability | ✅ Yes | Creates/modifies entitlements files |
+| File target membership | ✅ Yes | Modifies `project.pbxproj` |
+| Build settings | ✅ Yes | Modifies `project.pbxproj` |
+| Source files (Swift, plist) | ✅ Yes | Already in repo |
+| User scheme selections | ❌ No | In `xcuserdata/` (gitignored) |
+| Personal signing identity | ⚠️ Maybe | Depends on team practice |
+
+**Bottom line:** Commit all the Xcode project configuration changes. Other developers will get the Share Extension target automatically when they pull, and they'll only need to configure their personal signing settings.
+
--- a/doc/ios-share-extension-setup.md
+++ b/doc/ios-share-extension-setup.md
@@ -0,0 +1,140 @@
+# iOS Share Extension Setup Instructions
+
+**Date:** 2025-01-27  
+**Purpose:** Step-by-step instructions for setting up the iOS Share Extension in Xcode
+
+## Prerequisites
+
+- Xcode installed
+- iOS project already set up with Capacitor
+- Access to Apple Developer account (for App Groups)
+
+## Step 1: Create Share Extension Target
+
+1. Open `ios/App/App.xcodeproj` in Xcode
+2. In the Project Navigator, select the **App** project (top-level item)
+3. Click the **+** button at the bottom of the Targets list
+4. Select **iOS** → **Share Extension**
+5. Click **Next**
+6. Configure:
+   - **Product Name:** `TimeSafariShareExtension`
+   - **Bundle Identifier:** `app.timesafari.shareextension` (must match main app's bundle ID with `.shareextension` suffix)
+   - **Language:** Swift
+7. Click **Finish**
+
+## Step 2: Configure Share Extension Files
+
+The following files have been created in `ios/App/TimeSafariShareExtension/`:
+
+- `ShareViewController.swift` - Main extension logic
+- `Info.plist` - Extension configuration
+
+**Verify these files exist and are added to the Share Extension target.**
+
+## Step 3: Configure App Groups
+
+App Groups allow the Share Extension and main app to share data.
+
+### For Main App Target:
+
+1. Select the **App** target in Xcode
+2. Go to **Signing & Capabilities** tab
+3. Click **+ Capability**
+4. Select **App Groups**
+5. Click **+** to add a new group
+6. Enter: `group.app.timesafari`
+7. Ensure it's checked/enabled
+
+### For Share Extension Target:
+
+1. Select the **TimeSafariShareExtension** target
+2. Go to **Signing & Capabilities** tab
+3. Click **+ Capability**
+4. Select **App Groups**
+5. Click **+** to add a new group
+6. Enter: `group.app.timesafari` (same as main app)
+7. Ensure it's checked/enabled
+
+**Important:** Both targets must use the **exact same** App Group identifier.
+
+## Step 4: Configure Share Extension Info.plist
+
+The `Info.plist` file should already be configured, but verify:
+
+1. Select `TimeSafariShareExtension/Info.plist` in Xcode
+2. Ensure it contains:
+   - `NSExtensionPointIdentifier` = `com.apple.share-services`
+   - `NSExtensionPrincipalClass` = `$(PRODUCT_MODULE_NAME).ShareViewController`
+   - `NSExtensionActivationSupportsImageWithMaxCount` = `1`
+
+## Step 5: Add ShareImageBridge to Main App
+
+1. The file `ios/App/App/ShareImageBridge.swift` has been created
+2. Ensure it's added to the **App** target (not the Share Extension target)
+3. In Xcode, select the file and check the **Target Membership** in the File Inspector
+
+## Step 6: Build and Test
+
+1. Select the **App** scheme (not the Share Extension scheme)
+2. Build and run on a device or simulator
+3. Open Photos app
+4. Select an image
+5. Tap **Share** button
+6. Look for **TimeSafari Share** in the share sheet
+7. Select it
+8. The app should open and navigate to the shared photo view
+
+## Step 7: Troubleshooting
+
+### Share Extension doesn't appear in share sheet
+
+- Verify the Share Extension target builds successfully
+- Check that `Info.plist` is correctly configured
+- Ensure the extension's bundle identifier follows the pattern: `{main-app-bundle-id}.shareextension`
+- Clean build folder (Product → Clean Build Folder)
+
+### App Group access fails
+
+- Verify both targets have the same App Group identifier
+- Check that App Groups capability is enabled for both targets
+- Ensure you're signed in with a valid Apple Developer account
+- For development, you may need to enable App Groups in your Apple Developer account
+
+### Shared image not appearing
+
+- Check Xcode console for errors
+- Verify `ShareViewController.swift` is correctly implemented
+- Ensure the deep link `timesafari://shared-photo` is being handled
+- Check that the native bridge method is being called
+
+### Build errors
+
+- Ensure Swift version matches between targets
+- Check that all required frameworks are linked
+- Verify deployment targets match between main app and extension
+
+## Step 8: Native Bridge Implementation (TODO)
+
+Currently, the JavaScript code needs a way to call the native `getSharedImageData()` method. This requires one of:
+
+1. **Option A:** Create a minimal Capacitor plugin
+2. **Option B:** Use Capacitor's existing bridge mechanisms
+3. **Option C:** Expose the method via a custom URL scheme parameter
+
+The current implementation in `main.capacitor.ts` has a placeholder that needs to be completed.
+
+## Next Steps
+
+After the Share Extension is set up and working:
+
+1. Complete the native bridge implementation to read from App Group
+2. Test end-to-end flow: Share image → Extension stores → App reads → Displays
+3. Implement Android version
+4. Add error handling and edge cases
+
+## References
+
+- [Apple Share Extensions Documentation](https://developer.apple.com/documentation/social)
+- [App Groups Documentation](https://developer.apple.com/documentation/xcode/configuring-app-groups)
+- [Capacitor Native Bridge](https://capacitorjs.com/docs/guides/building-plugins)
+
--- a/doc/ios-share-implementation-status.md
+++ b/doc/ios-share-implementation-status.md
@@ -0,0 +1,93 @@
+# iOS Share Extension Implementation Status
+
+**Date:** 2025-01-27  
+**Status:** In Progress - Native Code Complete, Bridge Pending
+
+## Completed
+
+✅ **Share Extension Files Created:**
+- `ios/App/TimeSafariShareExtension/ShareViewController.swift` - Handles image sharing
+- `ios/App/TimeSafariShareExtension/Info.plist` - Extension configuration
+
+✅ **Native Bridge Created:**
+- `ios/App/App/ShareImageBridge.swift` - Native method to read from App Group
+
+✅ **JavaScript Integration Started:**
+- `src/services/nativeShareHandler.ts` - Service to handle native shared images
+- `src/main.capacitor.ts` - Updated to check for native shared images on deep link
+
+✅ **Documentation:**
+- `doc/native-share-target-implementation.md` - Complete implementation guide
+- `doc/ios-share-extension-setup.md` - Xcode setup instructions
+
+## Pending
+
+⚠️ **Xcode Configuration (Manual Steps Required):**
+1. Create Share Extension target in Xcode
+2. Configure App Groups for both main app and extension
+3. Add ShareImageBridge.swift to App target
+4. Build and test
+
+⚠️ **JavaScript-Native Bridge:**
+The current implementation has a placeholder for calling the native `ShareImageBridge.getSharedImageData()` method from JavaScript. This needs to be completed using one of:
+
+**Option A: Minimal Capacitor Plugin** (Recommended for Option 1)
+- Create a small plugin that exposes the method
+- Clean and maintainable
+- Follows Capacitor patterns
+
+**Option B: Direct Bridge Call**
+- Use Capacitor's executePlugin or similar mechanism
+- Requires understanding Capacitor's internal bridge
+- Less maintainable
+
+**Option C: AppDelegate Integration**
+- Have AppDelegate check on launch and expose via a different mechanism
+- Workaround approach
+- Less clean but functional
+
+## Next Steps
+
+1. **Complete Xcode Setup:**
+   - Follow `doc/ios-share-extension-setup.md`
+   - Create Share Extension target
+   - Configure App Groups
+   - Build and verify extension appears in share sheet
+
+2. **Implement JavaScript-Native Bridge:**
+   - Choose one of the options above
+   - Complete the `checkAndStoreNativeSharedImage()` function in `main.capacitor.ts`
+   - Test end-to-end flow
+
+3. **Testing:**
+   - Share image from Photos app
+   - Verify Share Extension appears
+   - Verify app opens and displays shared image
+   - Test "Record Gift" and "Save as Profile" flows
+
+## Current Flow
+
+1. ✅ User shares image → Share Extension receives
+2. ✅ Share Extension converts to base64
+3. ✅ Share Extension stores in App Group UserDefaults
+4. ✅ Share Extension opens app with `timesafari://shared-photo?fileName=...`
+5. ⚠️ App receives deep link (handled)
+6. ⚠️ App checks App Group UserDefaults (bridge needed)
+7. ⚠️ App stores in temp database (pending bridge)
+8. ✅ SharedPhotoView reads from temp database (already works)
+
+## Code Locations
+
+- **Share Extension:** `ios/App/TimeSafariShareExtension/`
+- **Native Bridge:** `ios/App/App/ShareImageBridge.swift`
+- **JavaScript Handler:** `src/services/nativeShareHandler.ts`
+- **Deep Link Integration:** `src/main.capacitor.ts`
+- **View Component:** `src/views/SharedPhotoView.vue` (already complete)
+
+## Notes
+
+- The Share Extension code is complete and ready to use
+- The main missing piece is the JavaScript-to-native bridge
+- Once the bridge is complete, the entire flow should work end-to-end
+- The existing `SharedPhotoView.vue` doesn't need changes - it already handles images from temp storage
+
--- a/doc/native-share-target-implementation.md
+++ b/doc/native-share-target-implementation.md
@@ -0,0 +1,507 @@
+# Native Share Target Implementation Guide
+
+**Date:** 2025-01-27  
+**Purpose:** Enable TimeSafari native iOS and Android apps to receive shared images from other apps
+
+## Current State
+
+The app currently supports **PWA/web share target** functionality:
+- Service worker intercepts POST to `/share-target`
+- Images stored in temp database as base64
+- `SharedPhotoView.vue` processes and displays shared images
+
+**This does NOT work for native iOS/Android builds** because:
+- Service workers don't run in native app contexts
+- Native platforms use different sharing mechanisms (Share Extensions on iOS, Intent Filters on Android)
+
+## Required Changes
+
+### 1. iOS Implementation
+
+#### 1.1 Create Share Extension Target
+
+1. Open `ios/App/App.xcodeproj` in Xcode
+2. File → New → Target
+3. Select "Share Extension" template
+4. Name it "TimeSafariShareExtension"
+5. Bundle Identifier: `app.timesafari.shareextension`
+6. Language: Swift
+
+#### 1.2 Configure Share Extension Info.plist
+
+Add to `ios/App/TimeSafariShareExtension/Info.plist`:
+
+```xml
+<key>NSExtension</key>
+<dict>
+    <key>NSExtensionPointIdentifier</key>
+    <string>com.apple.share-services</string>
+    <key>NSExtensionPrincipalClass</key>
+    <string>$(PRODUCT_MODULE_NAME).ShareViewController</string>
+    <key>NSExtensionActivationRule</key>
+    <dict>
+        <key>NSExtensionActivationSupportsImageWithMaxCount</key>
+        <integer>1</integer>
+        <key>NSExtensionActivationSupportsFileWithMaxCount</key>
+        <integer>1</integer>
+    </dict>
+</dict>
+```
+
+#### 1.3 Implement ShareViewController
+
+Create `ios/App/TimeSafariShareExtension/ShareViewController.swift`:
+
+```swift
+import UIKit
+import Social
+import MobileCoreServices
+import Capacitor
+
+class ShareViewController: SLComposeServiceViewController {
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        self.title = "Share to TimeSafari"
+    }
+    
+    override func isContentValid() -> Bool {
+        return true
+    }
+    
+    override func didSelectPost() {
+        guard let extensionItem = extensionContext?.inputItems.first as? NSExtensionItem,
+              let itemProvider = extensionItem.attachments?.first else {
+            self.extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
+            return
+        }
+        
+        // Handle image sharing
+        if itemProvider.hasItemConformingToTypeIdentifier(kUTTypeImage as String) {
+            itemProvider.loadItem(forTypeIdentifier: kUTTypeImage as String, options: nil) { [weak self] (item, error) in
+                guard let self = self else { return }
+                
+                if let url = item as? URL {
+                    // Handle file URL
+                    self.handleSharedImage(url: url)
+                } else if let image = item as? UIImage {
+                    // Handle UIImage directly
+                    self.handleSharedImage(image: image)
+                } else if let data = item as? Data {
+                    // Handle image data
+                    self.handleSharedImage(data: data)
+                }
+            }
+        }
+    }
+    
+    private func handleSharedImage(url: URL? = nil, image: UIImage? = nil, data: Data? = nil) {
+        var imageData: Data?
+        var fileName: String?
+        
+        if let url = url {
+            imageData = try? Data(contentsOf: url)
+            fileName = url.lastPathComponent
+        } else if let image = image {
+            imageData = image.jpegData(compressionQuality: 0.8)
+            fileName = "shared-image.jpg"
+        } else if let data = data {
+            imageData = data
+            fileName = "shared-image.jpg"
+        }
+        
+        guard let imageData = imageData else {
+            self.extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
+            return
+        }
+        
+        // Convert to base64
+        let base64String = imageData.base64EncodedString()
+        
+        // Store in shared UserDefaults (accessible by main app)
+        let userDefaults = UserDefaults(suiteName: "group.app.timesafari")
+        userDefaults?.set(base64String, forKey: "sharedPhotoBase64")
+        userDefaults?.set(fileName ?? "shared-image.jpg", forKey: "sharedPhotoFileName")
+        userDefaults?.synchronize()
+        
+        // Open main app with deep link
+        let url = URL(string: "timesafari://shared-photo?fileName=\(fileName?.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? "shared-image.jpg")")!
+        var responder = self as UIResponder?
+        while responder != nil {
+            if let application = responder as? UIApplication {
+                application.open(url, options: [:], completionHandler: nil)
+                break
+            }
+            responder = responder?.next
+        }
+        
+        // Close share extension
+        self.extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
+    }
+    
+    override func configurationItems() -> [Any]! {
+        return []
+    }
+}
+```
+
+#### 1.4 Configure App Groups
+
+1. In Xcode, select main app target → Signing & Capabilities
+2. Add "App Groups" capability
+3. Create group: `group.app.timesafari`
+4. Repeat for Share Extension target with same group name
+
+#### 1.5 Update Main App to Read from App Group
+
+The main app needs to check for shared images on launch. This should be added to `AppDelegate.swift` or handled in JavaScript.
+
+### 2. Android Implementation
+
+#### 2.1 Update AndroidManifest.xml
+
+Add intent filter to `MainActivity` in `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity
+    android:name=".MainActivity"
+    ... existing attributes ...>
+    
+    ... existing intent filters ...
+    
+    <!-- Share Target Intent Filter -->
+    <intent-filter>
+        <action android:name="android.intent.action.SEND" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <data android:mimeType="image/*" />
+    </intent-filter>
+    
+    <!-- Multiple images support (optional) -->
+    <intent-filter>
+        <action android:name="android.intent.action.SEND_MULTIPLE" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <data android:mimeType="image/*" />
+    </intent-filter>
+</activity>
+```
+
+#### 2.2 Handle Intent in MainActivity
+
+Update `android/app/src/main/java/app/timesafari/MainActivity.java`:
+
+```java
+package app.timesafari;
+
+import android.content.Intent;
+import android.net.Uri;
+import android.os.Bundle;
+import android.util.Base64;
+import android.util.Log;
+import com.getcapacitor.BridgeActivity;
+import com.getcapacitor.Plugin;
+import java.io.InputStream;
+import java.io.ByteArrayOutputStream;
+
+public class MainActivity extends BridgeActivity {
+    private static final String TAG = "MainActivity";
+    
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        handleShareIntent(getIntent());
+    }
+    
+    @Override
+    protected void onNewIntent(Intent intent) {
+        super.onNewIntent(intent);
+        setIntent(intent);
+        handleShareIntent(intent);
+    }
+    
+    private void handleShareIntent(Intent intent) {
+        if (intent == null) return;
+        
+        String action = intent.getAction();
+        String type = intent.getType();
+        
+        if (Intent.ACTION_SEND.equals(action) && type != null && type.startsWith("image/")) {
+            Uri imageUri = intent.getParcelableExtra(Intent.EXTRA_STREAM);
+            if (imageUri != null) {
+                handleSharedImage(imageUri, intent.getStringExtra(Intent.EXTRA_TEXT));
+            }
+        } else if (Intent.ACTION_SEND_MULTIPLE.equals(action) && type != null && type.startsWith("image/")) {
+            // Handle multiple images (optional - for now just take first)
+            java.util.ArrayList<Uri> imageUris = intent.getParcelableArrayListExtra(Intent.EXTRA_STREAM);
+            if (imageUris != null && !imageUris.isEmpty()) {
+                handleSharedImage(imageUris.get(0), null);
+            }
+        }
+    }
+    
+    private void handleSharedImage(Uri imageUri, String fileName) {
+        try {
+            // Read image data
+            InputStream inputStream = getContentResolver().openInputStream(imageUri);
+            if (inputStream == null) {
+                Log.e(TAG, "Failed to open input stream for shared image");
+                return;
+            }
+            
+            ByteArrayOutputStream buffer = new ByteArrayOutputStream();
+            byte[] data = new byte[8192];
+            int nRead;
+            while ((nRead = inputStream.read(data, 0, data.length)) != -1) {
+                buffer.write(data, 0, nRead);
+            }
+            buffer.flush();
+            byte[] imageBytes = buffer.toByteArray();
+            
+            // Convert to base64
+            String base64String = Base64.encodeToString(imageBytes, Base64.NO_WRAP);
+            
+            // Extract filename from URI or use default
+            String actualFileName = fileName;
+            if (actualFileName == null || actualFileName.isEmpty()) {
+                String path = imageUri.getPath();
+                if (path != null) {
+                    int lastSlash = path.lastIndexOf('/');
+                    if (lastSlash >= 0 && lastSlash < path.length() - 1) {
+                        actualFileName = path.substring(lastSlash + 1);
+                    }
+                }
+                if (actualFileName == null || actualFileName.isEmpty()) {
+                    actualFileName = "shared-image.jpg";
+                }
+            }
+            
+            // Store in SharedPreferences (accessible by JavaScript via Capacitor)
+            android.content.SharedPreferences prefs = getSharedPreferences("TimeSafariShared", MODE_PRIVATE);
+            android.content.SharedPreferences.Editor editor = prefs.edit();
+            editor.putString("sharedPhotoBase64", base64String);
+            editor.putString("sharedPhotoFileName", actualFileName);
+            editor.apply();
+            
+            // Trigger JavaScript event or navigate to shared-photo route
+            // This will be handled by JavaScript checking for shared data on app launch
+            Log.d(TAG, "Shared image stored, filename: " + actualFileName);
+            
+        } catch (Exception e) {
+            Log.e(TAG, "Error handling shared image", e);
+        }
+    }
+}
+```
+
+#### 2.3 Add Required Permissions
+
+Ensure `AndroidManifest.xml` has:
+
+```xml
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" /> <!-- Android 13+ -->
+```
+
+### 3. JavaScript Layer Updates
+
+#### 3.1 Create Native Share Handler
+
+Create `src/services/nativeShareHandler.ts`:
+
+```typescript
+/**
+ * Native Share Handler
+ * Handles shared images from native iOS and Android platforms
+ */
+
+import { Capacitor } from "@capacitor/core";
+import { App } from "@capacitor/app";
+import { Filesystem, Directory, Encoding } from "@capacitor/filesystem";
+import { logger } from "../utils/logger";
+import { SHARED_PHOTO_BASE64_KEY } from "../libs/util";
+import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
+
+/**
+ * Check for shared images from native platforms and store in temp database
+ */
+export async function checkForNativeSharedImage(
+  platformService: InstanceType<typeof PlatformServiceMixin>
+): Promise<boolean> {
+  if (!Capacitor.isNativePlatform()) {
+    return false;
+  }
+
+  try {
+    if (Capacitor.getPlatform() === "ios") {
+      return await checkIOSSharedImage(platformService);
+    } else if (Capacitor.getPlatform() === "android") {
+      return await checkAndroidSharedImage(platformService);
+    }
+  } catch (error) {
+    logger.error("Error checking for native shared image:", error);
+  }
+
+  return false;
+}
+
+/**
+ * Check for shared image on iOS (from App Group UserDefaults)
+ */
+async function checkIOSSharedImage(
+  platformService: InstanceType<typeof PlatformServiceMixin>
+): Promise<boolean> {
+  // iOS uses App Groups to share data between extension and main app
+  // We need to use a Capacitor plugin or native code to read from App Group
+  // For now, this is a placeholder - requires native plugin implementation
+  
+  // Option 1: Use Capacitor plugin to read from App Group
+  // Option 2: Use native code bridge
+  
+  logger.debug("Checking for iOS shared image (not yet implemented)");
+  return false;
+}
+
+/**
+ * Check for shared image on Android (from SharedPreferences)
+ */
+async function checkAndroidSharedImage(
+  platformService: InstanceType<typeof PlatformServiceMixin>
+): Promise<boolean> {
+  // Android stores in SharedPreferences
+  // We need a Capacitor plugin to read from SharedPreferences
+  // For now, this is a placeholder - requires native plugin implementation
+  
+  logger.debug("Checking for Android shared image (not yet implemented)");
+  return false;
+}
+
+/**
+ * Store shared image in temp database
+ */
+async function storeSharedImage(
+  base64Data: string,
+  fileName: string,
+  platformService: InstanceType<typeof PlatformServiceMixin>
+): Promise<void> {
+  try {
+    const existing = await platformService.$getTemp(SHARED_PHOTO_BASE64_KEY);
+    
+    if (existing) {
+      await platformService.$updateEntity(
+        "temp",
+        { blobB64: base64Data },
+        "id = ?",
+        [SHARED_PHOTO_BASE64_KEY]
+      );
+    } else {
+      await platformService.$insertEntity(
+        "temp",
+        { id: SHARED_PHOTO_BASE64_KEY, blobB64: base64Data },
+        ["id", "blobB64"]
+      );
+    }
+    
+    logger.debug("Stored shared image in temp database");
+  } catch (error) {
+    logger.error("Error storing shared image:", error);
+    throw error;
+  }
+}
+```
+
+#### 3.2 Update main.capacitor.ts
+
+Add check for shared images on app launch:
+
+```typescript
+// In main.capacitor.ts, after app mount:
+
+import { checkForNativeSharedImage } from "./services/nativeShareHandler";
+
+// Check for shared images when app becomes active
+App.addListener("appStateChange", async (state) => {
+  if (state.isActive) {
+    // Check for native shared images
+    const hasSharedImage = await checkForNativeSharedImage(/* platformService */);
+    if (hasSharedImage) {
+      // Navigate to shared-photo view
+      await router.push({
+        name: "shared-photo",
+        query: { source: "native" }
+      });
+    }
+  }
+});
+
+// Also check on initial launch
+App.getLaunchUrl().then((result) => {
+  if (result?.url) {
+    // Handle deep link
+  } else {
+    // Check for shared image
+    checkForNativeSharedImage(/* platformService */).then((hasShared) => {
+      if (hasShared) {
+        router.push({ name: "shared-photo", query: { source: "native" } });
+      }
+    });
+  }
+});
+```
+
+#### 3.3 Update SharedPhotoView.vue
+
+The existing `SharedPhotoView.vue` should work as-is, but we may want to add detection for native vs web sources.
+
+### 4. Alternative Approach: Capacitor Plugin
+
+Instead of implementing native code directly, consider creating a Capacitor plugin:
+
+1. **Create plugin**: `@capacitor-community/share-target` or custom plugin
+2. **Plugin methods**:
+   - `checkForSharedImage()`: Returns shared image data if available
+   - `clearSharedImage()`: Clears shared image data after processing
+
+This would be cleaner and more maintainable.
+
+### 5. Testing Checklist
+
+- [ ] Test sharing image from Photos app on iOS
+- [ ] Test sharing image from Gallery app on Android
+- [ ] Test sharing from other apps (Safari, Chrome, etc.)
+- [ ] Verify image appears in SharedPhotoView
+- [ ] Test "Record Gift" flow with shared image
+- [ ] Test "Save as Profile" flow with shared image
+- [ ] Test cancel flow
+- [ ] Verify temp storage cleanup
+- [ ] Test app launch with shared image pending
+- [ ] Test app already running when image is shared
+
+### 6. Implementation Priority
+
+**Phase 1: Android (Simpler)**
+1. Update AndroidManifest.xml
+2. Implement MainActivity intent handling
+3. Create JavaScript handler
+4. Test end-to-end
+
+**Phase 2: iOS (More Complex)**
+1. Create Share Extension target
+2. Implement ShareViewController
+3. Configure App Groups
+4. Create JavaScript handler
+5. Test end-to-end
+
+### 7. Notes
+
+- **App Groups (iOS)**: Required for sharing data between Share Extension and main app
+- **SharedPreferences (Android)**: Standard way to share data between app components
+- **Base64 Encoding**: Both platforms convert images to base64 for JavaScript compatibility
+- **File Size Limits**: Consider large image handling and memory management
+- **Permissions**: Android 13+ requires `READ_MEDIA_IMAGES` instead of `READ_EXTERNAL_STORAGE`
+
+### 8. References
+
+- [iOS Share Extensions](https://developer.apple.com/documentation/social)
+- [Android Share Targets](https://developer.android.com/training/sharing/receive)
+- [Capacitor App Plugin](https://capacitorjs.com/docs/apis/app)
+- [Capacitor Native Bridge](https://capacitorjs.com/docs/guides/building-plugins)
+
--- a/doc/xcode-26-cocoapods-workaround.md
+++ b/doc/xcode-26-cocoapods-workaround.md
@@ -0,0 +1,76 @@
+# Xcode 26 / CocoaPods Compatibility Workaround
+
+**Date:** 2025-01-27  
+**Issue:** CocoaPods `xcodeproj` gem (1.27.0) doesn't support Xcode 26's project format version 70
+
+## The Problem
+
+Xcode 26.1.1 uses project format version 70, but the `xcodeproj` gem (1.27.0) only supports up to version 56. This causes CocoaPods to fail with:
+
+```
+ArgumentError - [Xcodeproj] Unable to find compatibility version string for object version `70`.
+```
+
+## Solutions
+
+### Option 1: Temporarily Downgrade Project Format (Recommended for Now)
+
+**Before running `pod install` or `npm run build:ios`:**
+
+1. Edit `ios/App/App.xcodeproj/project.pbxproj`
+2. Change line 6 from: `objectVersion = 70;` to: `objectVersion = 56;`
+3. Run your build/sync command
+4. Change it back to: `objectVersion = 70;` (Xcode will likely change it back automatically)
+
+**Warning:** Xcode may automatically upgrade the format back to 70 when you open the project. This is okay - just repeat the process when needed.
+
+### Option 2: Wait for xcodeproj Update
+
+The `xcodeproj` gem maintainers will eventually release a version that supports format 70. You can:
+- Check for updates: `bundle update xcodeproj`
+- Monitor: https://github.com/CocoaPods/Xcodeproj/issues
+
+### Option 3: Use Xcode Directly (Bypass CocoaPods for Now)
+
+Since the Share Extension is already set up:
+1. Open the project in Xcode
+2. Build directly from Xcode (Product → Build)
+3. Skip `npm run build:ios` for now
+4. Test the Share Extension functionality
+
+### Option 4: Automated Workaround (Integrated into Build Script) ✅
+
+The workaround is now **automatically integrated** into `scripts/build-ios.sh`. When you run:
+
+```bash
+npm run build:ios
+```
+
+The build script will:
+1. Automatically detect if the project format is version 70
+2. Temporarily downgrade to version 56
+3. Run `pod install`
+4. Restore to version 70
+5. Continue with the build
+
+**No manual steps required!** The workaround is transparent and only applies when needed.
+
+To remove the workaround in the future:
+1. Check if `xcodeproj` gem supports format 70: `bundle exec gem list xcodeproj`
+2. Test if `pod install` works without the workaround
+3. If it works, remove the `run_pod_install_with_workaround()` function from `scripts/build-ios.sh`
+4. Replace it with a simple `pod install` call
+
+## Current Status
+
+- ✅ Share Extension target exists
+- ✅ Share Extension files are in place
+- ✅ Workaround integrated into build script
+- ✅ `npm run build:ios` works automatically
+
+## Recommendation
+
+**Use `npm run build:ios`** - the workaround is handled automatically. No manual intervention needed.
+
+Once `xcodeproj` is updated to support format 70, the workaround can be removed from the build script.
+