refactor(shared-image): replace temp file approach with native Capacitor plugins

Replace the buggy temp file polling mechanism with direct native-to-JS communication via custom Capacitor plugins for iOS and Android. This eliminates race conditions, file management complexity, and polling overhead. BREAKING CHANGE: Removes backward compatibility with temp file approach. Android minSdkVersion upgraded from 22 to 23. Changes: - iOS: Created SharedImagePlugin (CAPBridgedPlugin) and SharedImageUtility - Uses App Group UserDefaults for data sharing between extension and app - Implements getSharedImage() and hasSharedImage() methods - Removes temp file writing/reading logic from AppDelegate - Android: Created SharedImagePlugin with @CapacitorPlugin annotation - Uses SharedPreferences for data storage instead of temp files - Implements same interface as iOS plugin - Removes temp file handling from MainActivity - TypeScript: Added plugin definitions and registration - Created SharedImagePlugin interface and web fallback - Updated main.capacitor.ts to use plugin instead of Filesystem API - Removed pollForFileExistence() and related file I/O code - Android: Upgraded minSdkVersion from 22 to 23 - Required for SharedPreferences improvements and better API support Benefits: - Eliminates race conditions from file polling - Removes file cleanup complexity - Direct native-to-JS communication (no file I/O) - Better performance (no polling overhead) - More reliable data transfer between share extension and app - Cleaner architecture with proper plugin abstraction
2025-12-04 18:03:47 +08:00
parent eeac7fdb66
commit 84983ee10b
14 changed files with 1498 additions and 218 deletions
--- a/doc/android-api-23-upgrade-impact-analysis.md
+++ b/doc/android-api-23-upgrade-impact-analysis.md
@@ -0,0 +1,259 @@
+# Android API 23 Upgrade Impact Analysis
+
+**Date:** 2025-12-03  
+**Current minSdkVersion:** 22 (Android 5.1 Lollipop)  
+**Proposed minSdkVersion:** 23 (Android 6.0 Marshmallow)  
+**Impact Assessment:** Low to Moderate
+
+## Executive Summary
+
+Upgrading from API 22 to API 23 will have **minimal code impact** but may affect device compatibility. The main change is that API 23 introduced runtime permissions, but since the app uses Capacitor plugins which handle permissions, the impact is minimal.
+
+## Code Impact Analysis
+
+### ✅ No Breaking Changes in Existing Code
+
+#### 1. API Level Checks in Code
+All existing API level checks are for **much higher APIs** than 23, so they won't be affected:
+
+**MainActivity.java:**
+- `Build.VERSION_CODES.R` (API 30+) - Edge-to-edge display
+- `Build.VERSION_CODES.TIRAMISU` (API 33+) - Intent extras handling
+- Legacy path (API 21-29) - Will still work, but API 22 devices won't be supported
+
+**SafeAreaPlugin.java:**
+- `Build.VERSION_CODES.R` (API 30+) - Safe area insets
+
+**Conclusion:** No code changes needed for API level checks.
+
+#### 2. Permissions Handling
+
+**Current Permissions in AndroidManifest.xml:**
+- `INTERNET` - Normal permission (no runtime needed)
+- `READ_EXTERNAL_STORAGE` - Dangerous permission (runtime required on API 23+)
+- `WRITE_EXTERNAL_STORAGE` - Dangerous permission (runtime required on API 23+)
+- `CAMERA` - Dangerous permission (runtime required on API 23+)
+
+**Current Implementation:**
+- ✅ App uses **Capacitor plugins** for camera and file access
+- ✅ Capacitor plugins **already handle runtime permissions** automatically
+- ✅ No manual permission request code found in the codebase
+- ✅ QR Scanner uses Capacitor's BarcodeScanner plugin which handles permissions
+
+**Conclusion:** No code changes needed - Capacitor handles runtime permissions automatically.
+
+#### 3. Dependencies Compatibility
+
+**AndroidX Libraries:**
+- `androidx.appcompat:appcompat:1.6.1` - ✅ Supports API 23+
+- `androidx.core:core:1.12.0` - ✅ Supports API 23+
+- `androidx.fragment:fragment:1.6.2` - ✅ Supports API 23+
+- `androidx.coordinatorlayout:coordinatorlayout:1.2.0` - ✅ Supports API 23+
+- `androidx.core:core-splashscreen:1.0.1` - ✅ Supports API 23+
+
+**Capacitor Plugins:**
+- `@capacitor/core:6.2.0` - ✅ Requires API 23+ (official requirement)
+- `@capacitor/camera:6.0.0` - ✅ Handles runtime permissions
+- `@capacitor/filesystem:6.0.0` - ✅ Handles runtime permissions
+- `@capacitor-community/sqlite:6.0.2` - ✅ Supports API 23+
+- `@capacitor-mlkit/barcode-scanning:6.0.0` - ✅ Supports API 23+
+
+**Third-Party Libraries:**
+- No Firebase or other libraries with API 22-specific requirements found
+- All dependencies appear compatible with API 23+
+
+**Conclusion:** All dependencies are compatible with API 23.
+
+#### 4. Build Configuration
+
+**Current Configuration:**
+- `compileSdkVersion = 36` (Android 14)
+- `targetSdkVersion = 36` (Android 14)
+- `minSdkVersion = 22` (Android 5.1) ← **Only this needs to change**
+
+**Required Change:**
+```gradle
+// android/variables.gradle
+ext {
+    minSdkVersion = 23  // Change from 22 to 23
+    // ... rest stays the same
+}
+```
+
+**Conclusion:** Only one line needs to be changed.
+
+## Device Compatibility Impact
+
+### Device Coverage Loss
+
+**API 22 (Android 5.1 Lollipop):**
+- Released: March 2015
+- Market share: ~0.1% of active devices (as of 2024)
+- Devices affected: Very old devices from 2015-2016
+
+**API 23 (Android 6.0 Marshmallow):**
+- Released: October 2015
+- Market share: ~0.3% of active devices (as of 2024)
+- Still very low, but slightly higher than API 22
+
+**Impact:** Losing support for ~0.1% of devices (essentially negligible)
+
+### User Base Impact
+
+**Recommendation:** Check your analytics to see actual usage:
+- If you have analytics, check percentage of users on API 22
+- If < 0.5%, upgrade is safe
+- If > 1%, consider the business impact
+
+## Runtime Permissions (API 23 Feature)
+
+### What Changed in API 23
+
+**Before API 23 (API 22 and below):**
+- Permissions granted at install time
+- User sees all permissions during installation
+- No runtime permission dialogs
+
+**API 23+ (Runtime Permissions):**
+- Dangerous permissions must be requested at runtime
+- User sees permission dialogs when app needs them
+- Better user experience and privacy
+
+### Current App Status
+
+**✅ Already Compatible:**
+- App uses Capacitor plugins which **automatically handle runtime permissions**
+- Camera plugin requests permissions when needed
+- Filesystem plugin requests permissions when needed
+- No manual permission code needed
+
+**Conclusion:** App is already designed for runtime permissions via Capacitor.
+
+## Potential Issues to Watch
+
+### 1. APK Size
+- Some developers report APK size increases after raising minSdkVersion
+- **Action:** Monitor APK size after upgrade
+- **Expected Impact:** Minimal (API 22 → 23 is a small jump)
+
+### 2. Testing Requirements
+- Need to test on API 23+ devices
+- **Action:** Test on Android 6.0+ devices/emulators
+- **Current:** App likely already tested on API 23+ devices
+
+### 3. Legacy Code Path
+- MainActivity has legacy code for API 21-29
+- **Impact:** This code will still work, but API 22 devices won't be supported
+- **Action:** No code changes needed, but legacy path becomes API 23-29
+
+### 4. Capacitor Compatibility
+- Capacitor 6.2.0 officially requires API 23+
+- **Current Situation:** App runs on API 22 (may be working due to leniency)
+- **After Upgrade:** Officially compliant with Capacitor requirements
+- **Benefit:** Better compatibility guarantees
+
+## Files That Need Changes
+
+### 1. Build Configuration
+**File:** `android/variables.gradle`
+```gradle
+ext {
+    minSdkVersion = 23  // Change from 22
+    // ... rest unchanged
+}
+```
+
+### 2. Documentation
+**Files to Update:**
+- `doc/shared-image-plugin-implementation-plan.md` - Update version notes
+- Any README files mentioning API 22
+- Build documentation
+
+### 3. No Code Changes Required
+- ✅ No Java/Kotlin code changes needed
+- ✅ No AndroidManifest.xml changes needed
+- ✅ No permission handling code changes needed
+
+## Testing Checklist
+
+After upgrading to API 23, test:
+
+- [ ] App builds successfully
+- [ ] App installs on API 23 device/emulator
+- [ ] Camera functionality works (permissions requested)
+- [ ] File access works (permissions requested)
+- [ ] Share functionality works
+- [ ] QR code scanning works
+- [ ] Deep linking works
+- [ ] All Capacitor plugins work correctly
+- [ ] No crashes or permission-related errors
+- [ ] APK size is acceptable
+
+## Rollback Plan
+
+If issues arise:
+
+1. Revert `android/variables.gradle` to `minSdkVersion = 22`
+2. Rebuild and test
+3. Document issues encountered
+4. Address issues before retrying upgrade
+
+## Recommendation
+
+### ✅ **Proceed with Upgrade**
+
+**Reasons:**
+1. **Minimal Code Impact:** Only one line needs to change
+2. **Already Compatible:** App uses Capacitor which handles runtime permissions
+3. **Device Impact:** Negligible (~0.1% of devices)
+4. **Capacitor Compliance:** Officially meets Capacitor 6 requirements
+5. **Future-Proofing:** Better alignment with modern Android development
+
+**Timeline:**
+- **Low Risk:** Can be done anytime
+- **Recommended:** Before implementing SharedImagePlugin (cleaner baseline)
+- **Testing:** 1-2 hours of testing on API 23+ devices
+
+## Migration Steps
+
+1. **Update Build Configuration:**
+   ```bash
+   # Edit android/variables.gradle
+   minSdkVersion = 23
+   ```
+
+2. **Sync Gradle:**
+   ```bash
+   cd android
+   ./gradlew clean
+   ```
+
+3. **Build and Test:**
+   ```bash
+   npm run build:android:test
+   # Test on API 23+ device/emulator
+   ```
+
+4. **Verify Permissions:**
+   - Test camera access
+   - Test file access
+   - Verify permission dialogs appear
+
+5. **Update Documentation:**
+   - Update any docs mentioning API 22
+   - Update implementation plan
+
+## Summary
+
+| Aspect | Impact | Status |
+|--------|--------|--------|
+| **Code Changes** | None required | ✅ Safe |
+| **Dependencies** | All compatible | ✅ Safe |
+| **Permissions** | Already handled | ✅ Safe |
+| **Device Coverage** | ~0.1% loss | ⚠️ Minimal |
+| **Build Config** | 1 line change | ✅ Simple |
+| **Testing** | Standard testing | ✅ Required |
+| **Risk Level** | Low | ✅ Low Risk |
+
+**Final Recommendation:** Proceed with upgrade. The benefits (Capacitor compliance, future-proofing) outweigh the minimal risks (negligible device loss, no code changes needed).
+
--- a/doc/shared-image-plugin-implementation-plan.md
+++ b/doc/shared-image-plugin-implementation-plan.md
@@ -0,0 +1,528 @@
+# Shared Image Plugin Implementation Plan
+
+**Date:** 2025-12-03 15:40:38 PST  
+**Status:** Planning  
+**Goal:** Replace temp file approach with native Capacitor plugins for iOS and Android
+
+## Minimum OS Version Compatibility Analysis
+
+### Current Project Configuration:
+- **iOS Deployment Target**: 13.0 (Podfile and Xcode project)
+- **Android minSdkVersion**: 23 (API 23 - Android 6.0 Marshmallow) ✅ **Upgraded**
+- **Capacitor Version**: 6.2.0
+
+### Capacitor 6 Requirements:
+- **iOS**: Requires iOS 13.0+ ✅ **Compatible** (current: 13.0)
+- **Android**: Requires API 23+ ✅ **Compatible** (current: API 23)
+
+### Plugin API Compatibility:
+
+#### iOS Plugin APIs:
+- ✅ `CAPPlugin` base class: Available in iOS 13.0+ (Capacitor requirement)
+- ✅ `CAPPluginCall`: Available in iOS 13.0+ (Capacitor requirement)
+- ✅ `UserDefaults(suiteName:)`: Available since iOS 8.0 (well below iOS 13.0)
+- ✅ `@objc` annotations: Available since iOS 8.0
+- ✅ Swift 5.0: Compatible with iOS 13.0+
+
+**Conclusion**: iOS 13.0 is fully compatible with the plugin implementation. **No iOS version update required.**
+
+#### Android Plugin APIs:
+- ✅ `Plugin` base class: Available in API 21+ (Capacitor requirement)
+- ✅ `PluginCall`: Available in API 21+ (Capacitor requirement)
+- ✅ `SharedPreferences`: Available since API 1 (works on all Android versions)
+- ✅ `@CapacitorPlugin` annotation: Available in API 21+ (Capacitor requirement)
+- ✅ `@PluginMethod` annotation: Available in API 21+ (Capacitor requirement)
+
+**Conclusion**: Android API 23 is fully compatible with the plugin implementation and officially meets Capacitor 6 requirements. ✅ **No Android version concerns.**
+
+### Share Extension Compatibility:
+- **iOS Share Extension**: Uses same deployment target as main app (iOS 13.0)
+- **App Group**: Available since iOS 8.0, fully compatible
+- No additional version requirements for share extension functionality
+
+## Overview
+
+This document outlines the migration from the current temp file approach to implementing dedicated Capacitor plugins for handling shared images. This will eliminate file I/O, polling, and timing issues, providing a more direct and reliable native-to-JS bridge.
+
+## Current Implementation Issues
+
+### Temp File Approach Problems:
+1. **Timing Issues**: Requires polling with exponential backoff to wait for file creation
+2. **Race Conditions**: File may not exist when JS checks, or may be read multiple times
+3. **File Management**: Need to delete temp files after reading to prevent re-processing
+4. **Platform Differences**: Different directories (Documents vs Data) add complexity
+5. **Error Handling**: File I/O errors can be hard to debug
+6. **Performance**: File system operations are slower than direct native calls
+
+## Proposed Solution: Capacitor Plugins
+
+### Benefits:
+- ✅ Direct native-to-JS communication (no file I/O)
+- ✅ Synchronous/async method calls (no polling needed)
+- ✅ Type-safe TypeScript interfaces
+- ✅ Better error handling and debugging
+- ✅ Lower latency
+- ✅ More maintainable and follows Capacitor best practices
+
+## Implementation Layout
+
+### 1. iOS Plugin Implementation
+
+#### 1.1 Create iOS Plugin File
+**Location:** `ios/App/App/SharedImagePlugin.swift`
+
+**Structure:**
+```swift
+import Foundation
+import Capacitor
+
+@objc(SharedImagePlugin)
+public class SharedImagePlugin: CAPPlugin {
+    private let appGroupIdentifier = "group.app.timesafari"
+    
+    @objc func getSharedImage(_ call: CAPPluginCall) {
+        // Read from App Group UserDefaults
+        // Return base64 and fileName
+        // Clear data after reading
+    }
+    
+    @objc func hasSharedImage(_ call: CAPPluginCall) {
+        // Check if shared image exists without reading it
+        // Useful for quick checks
+    }
+}
+```
+
+**Key Points:**
+- Use existing `getSharedImageData()` logic from AppDelegate
+- Return data as JSObject with `base64` and `fileName` keys
+- Clear UserDefaults after reading to prevent re-reading
+- Handle errors gracefully with `call.reject()`
+- **Version Compatibility**: Works with iOS 13.0+ (current deployment target)
+
+#### 1.2 Register Plugin in iOS
+**Location:** `ios/App/App/AppDelegate.swift`
+
+**Changes:**
+- Remove `writeSharedImageToTempFile()` method
+- Remove temp file writing from `application(_:open:options:)`
+- Remove temp file writing from `checkForSharedImageOnActivation()`
+- Keep `getSharedImageData()` method (or move to plugin)
+- Plugin auto-registers via Capacitor's plugin system
+
+**Note:** Capacitor plugins are auto-discovered if they follow naming conventions and are in the app bundle.
+
+### 2. Android Plugin Implementation
+
+#### 2.1 Create Android Plugin File
+**Location:** `android/app/src/main/java/app/timesafari/sharedimage/SharedImagePlugin.java`
+
+**Structure:**
+```java
+package app.timesafari.sharedimage;
+
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+@CapacitorPlugin(name = "SharedImage")
+public class SharedImagePlugin extends Plugin {
+    
+    @PluginMethod
+    public void getSharedImage(PluginCall call) {
+        // Read from SharedPreferences or Intent extras
+        // Return base64 and fileName
+        // Clear data after reading
+    }
+    
+    @PluginMethod
+    public void hasSharedImage(PluginCall call) {
+        // Check if shared image exists without reading it
+    }
+}
+```
+
+**Key Points:**
+- Use SharedPreferences to store shared image data between share intent and plugin call
+- Store base64 and fileName when processing share intent
+- Read and clear in `getSharedImage()` method
+- Handle Intent extras if app was just launched
+- **Version Compatibility**: Works with Android API 22+ (current minSdkVersion)
+
+#### 2.2 Update MainActivity
+**Location:** `android/app/src/main/java/app/timesafari/MainActivity.java`
+
+**Changes:**
+- Remove `writeSharedImageToTempFile()` method
+- Remove `TEMP_FILE_NAME` constant
+- Update `processSharedImage()` to store in SharedPreferences instead of file
+- Register plugin: `registerPlugin(SharedImagePlugin.class);`
+- Store shared image data in SharedPreferences when processing share intent
+
+**SharedPreferences Approach:**
+```java
+// In processSharedImage():
+SharedPreferences prefs = getSharedPreferences("shared_image", MODE_PRIVATE);
+SharedPreferences.Editor editor = prefs.edit();
+editor.putString("base64", base64String);
+editor.putString("fileName", actualFileName);
+editor.putBoolean("hasSharedImage", true);
+editor.apply();
+```
+
+### 3. TypeScript/JavaScript Integration
+
+#### 3.1 Create TypeScript Plugin Definition
+**Location:** `src/plugins/SharedImagePlugin.ts` (new file)
+
+**Structure:**
+```typescript
+import { registerPlugin } from '@capacitor/core';
+
+export interface SharedImageResult {
+  base64: string;
+  fileName: string;
+}
+
+export interface SharedImagePlugin {
+  getSharedImage(): Promise<SharedImageResult | null>;
+  hasSharedImage(): Promise<{ hasImage: boolean }>;
+}
+
+const SharedImage = registerPlugin<SharedImagePlugin>('SharedImage', {
+  web: () => import('./SharedImagePlugin.web').then(m => new m.SharedImagePluginWeb()),
+});
+
+export * from './definitions';
+export { SharedImage };
+```
+
+#### 3.2 Create Web Implementation (for development)
+**Location:** `src/plugins/SharedImagePlugin.web.ts` (new file)
+
+**Structure:**
+```typescript
+import { WebPlugin } from '@capacitor/core';
+import type { SharedImagePlugin, SharedImageResult } from './definitions';
+
+export class SharedImagePluginWeb extends WebPlugin implements SharedImagePlugin {
+  async getSharedImage(): Promise<SharedImageResult | null> {
+    // Return null for web platform
+    return null;
+  }
+
+  async hasSharedImage(): Promise<{ hasImage: boolean }> {
+    return { hasImage: false };
+  }
+}
+```
+
+#### 3.3 Create Type Definitions
+**Location:** `src/plugins/definitions.ts` (new file)
+
+**Structure:**
+```typescript
+export interface SharedImageResult {
+  base64: string;
+  fileName: string;
+}
+
+export interface SharedImagePlugin {
+  getSharedImage(): Promise<SharedImageResult | null>;
+  hasSharedImage(): Promise<{ hasImage: boolean }>;
+}
+```
+
+#### 3.4 Update main.capacitor.ts
+**Location:** `src/main.capacitor.ts`
+
+**Changes:**
+- Remove `pollForFileExistence()` function
+- Remove temp file reading logic from `checkAndStoreNativeSharedImage()`
+- Replace with direct plugin call:
+
+```typescript
+async function checkAndStoreNativeSharedImage(): Promise<{
+  success: boolean;
+  fileName?: string;
+}> {
+  if (isProcessingSharedImage) {
+    logger.debug("[Main] ⏸️ Shared image processing already in progress, skipping");
+    return { success: false };
+  }
+
+  isProcessingSharedImage = true;
+
+  try {
+    if (!Capacitor.isNativePlatform() || 
+        (Capacitor.getPlatform() !== "ios" && Capacitor.getPlatform() !== "android")) {
+      isProcessingSharedImage = false;
+      return { success: false };
+    }
+
+    // Direct plugin call - no polling needed!
+    const { SharedImage } = await import('./plugins/SharedImagePlugin');
+    const result = await SharedImage.getSharedImage();
+
+    if (result && result.base64) {
+      await storeSharedImageInTempDB(result.base64, result.fileName);
+      isProcessingSharedImage = false;
+      return { success: true, fileName: result.fileName };
+    }
+
+    isProcessingSharedImage = false;
+    return { success: false };
+  } catch (error) {
+    logger.error("[Main] Error checking for native shared image:", error);
+    isProcessingSharedImage = false;
+    return { success: false };
+  }
+}
+```
+
+**Remove:**
+- `pollForFileExistence()` function (lines 71-98)
+- All Filesystem plugin imports related to temp file reading
+- Temp file path constants and directory logic
+
+### 4. Data Flow Comparison
+
+#### Current (Temp File) Flow:
+```
+Share Extension/Intent
+  ↓
+Native writes temp file
+  ↓
+JS polls for file existence (with retries)
+  ↓
+JS reads file via Filesystem plugin
+  ↓
+JS parses JSON
+  ↓
+JS deletes temp file
+  ↓
+JS stores in temp DB
+```
+
+#### New (Plugin) Flow:
+```
+Share Extension/Intent
+  ↓
+Native stores in UserDefaults/SharedPreferences
+  ↓
+JS calls plugin.getSharedImage()
+  ↓
+Native reads and clears data
+  ↓
+Native returns data directly
+  ↓
+JS stores in temp DB
+```
+
+## File Changes Summary
+
+### New Files to Create:
+1. `ios/App/App/SharedImagePlugin.swift` - iOS plugin implementation
+2. `android/app/src/main/java/app/timesafari/sharedimage/SharedImagePlugin.java` - Android plugin
+3. `src/plugins/SharedImagePlugin.ts` - TypeScript plugin registration
+4. `src/plugins/SharedImagePlugin.web.ts` - Web fallback implementation
+5. `src/plugins/definitions.ts` - TypeScript type definitions
+
+### Files to Modify:
+1. `ios/App/App/AppDelegate.swift` - Remove temp file writing
+2. `android/app/src/main/java/app/timesafari/MainActivity.java` - Remove temp file writing, add SharedPreferences
+3. `src/main.capacitor.ts` - Replace temp file logic with plugin calls
+
+### Files to Remove:
+- No files need to be deleted, but code will be removed from existing files
+
+## Implementation Considerations
+
+### 1. Data Storage Strategy
+
+#### iOS:
+- **Current**: App Group UserDefaults (already working)
+- **Plugin**: Read from same UserDefaults, no changes needed
+- **Clearing**: Clear immediately after reading in plugin method
+
+#### Android:
+- **Current**: Temp file in app's internal files directory
+- **New**: SharedPreferences (persistent key-value store)
+- **Alternative**: Could use Intent extras if app is launched fresh, but SharedPreferences is more reliable for backgrounded apps
+
+### 2. Timing and Lifecycle
+
+#### When to Check for Shared Images:
+1. **App Launch**: Check in `checkForSharedImageAndNavigate()` (already exists)
+2. **App Becomes Active**: Check in `appStateChange` listener (already exists)
+3. **Deep Link**: Check in `handleDeepLink()` for empty path URLs (already exists)
+
+#### Plugin Call Timing:
+- Plugin calls are synchronous from JS perspective
+- No polling needed - native side handles data availability
+- If no data exists, plugin returns `null` immediately
+
+### 3. Error Handling
+
+#### Plugin Error Scenarios:
+- **No shared image**: Return `null` (not an error)
+- **Data corruption**: Return error via `call.reject()`
+- **Missing permissions**: Return error (shouldn't happen with App Group/SharedPreferences)
+
+#### JS Error Handling:
+- Wrap plugin calls in try-catch
+- Log errors appropriately
+- Don't crash app if plugin fails
+
+### 4. Backward Compatibility
+
+#### Migration Path:
+- Keep temp file code temporarily (commented out) for rollback
+- Test thoroughly on both platforms
+- Remove temp file code after verification
+
+### 5. Testing Considerations
+
+#### Test Cases:
+1. **Share from Photos app** → Verify image appears in app
+2. **Share while app is backgrounded** → Verify image appears when app becomes active
+3. **Share while app is closed** → Verify image appears on app launch
+4. **Multiple rapid shares** → Verify only latest image is processed
+5. **Share then close app before processing** → Verify image persists
+6. **Share then clear app data** → Verify graceful handling
+
+#### Edge Cases:
+- Very large images (memory concerns)
+- Multiple images shared simultaneously
+- App killed by OS before processing
+- Network interruptions during processing
+
+### 6. Performance Considerations
+
+#### Benefits:
+- **Latency**: Direct calls vs file I/O (faster)
+- **CPU**: No polling overhead
+- **Memory**: No temp file storage
+- **Battery**: Less file system activity
+
+#### Potential Issues:
+- Large base64 strings in memory (same as current approach)
+- UserDefaults/SharedPreferences size limits (shouldn't be an issue for single image)
+
+### 7. Type Safety
+
+#### TypeScript Benefits:
+- Full type checking for plugin methods
+- Autocomplete in IDE
+- Compile-time error checking
+- Better developer experience
+
+### 8. Plugin Registration
+
+#### iOS:
+- Capacitor auto-discovers plugins via naming convention
+- Ensure plugin is in app target (not extension target)
+- No manual registration needed in AppDelegate
+
+#### Android:
+- Register in `MainActivity.onCreate()`:
+  ```java
+  registerPlugin(SharedImagePlugin.class);
+  ```
+
+### 9. Capacitor Version Compatibility
+
+#### Check Current Version:
+- Verify Capacitor version supports custom plugins
+- Ensure plugin API hasn't changed
+- Test with current Capacitor version first
+
+### 10. Build and Deployment
+
+#### Build Steps:
+1. Create plugin files
+2. Register Android plugin in MainActivity
+3. Update TypeScript code
+4. Test on iOS simulator
+5. Test on Android emulator
+6. Test on physical devices
+7. Remove temp file code
+8. Update documentation
+
+#### Deployment:
+- No changes to build scripts needed
+- No changes to CI/CD needed
+- No changes to app configuration needed
+
+## Migration Steps
+
+### Phase 1: Create Plugins (Non-Breaking)
+1. Create iOS plugin file
+2. Create Android plugin file
+3. Create TypeScript definitions
+4. Register Android plugin
+5. Test plugins independently (don't use in main code yet)
+
+### Phase 2: Update JS Integration (Breaking)
+1. Create TypeScript plugin wrapper
+2. Update `checkAndStoreNativeSharedImage()` to use plugin
+3. Remove temp file reading logic
+4. Test on both platforms
+
+### Phase 3: Cleanup Native Code (Breaking)
+1. Remove temp file writing from iOS AppDelegate
+2. Remove temp file writing from Android MainActivity
+3. Update to use SharedPreferences on Android
+4. Test thoroughly
+
+### Phase 4: Final Cleanup
+1. Remove `pollForFileExistence()` function
+2. Remove Filesystem imports related to temp files
+3. Update comments and documentation
+4. Final testing
+
+## Rollback Plan
+
+If issues arise:
+1. Revert JS changes to use temp file approach
+2. Re-enable temp file writing in native code
+3. Keep plugins for future migration attempt
+4. Document issues encountered
+
+## Success Criteria
+
+✅ Plugin methods work on both iOS and Android  
+✅ No polling or file I/O needed  
+✅ Shared images appear correctly in app  
+✅ No memory leaks or performance issues  
+✅ Error handling works correctly  
+✅ All test cases pass  
+✅ Code is cleaner and more maintainable  
+
+## Additional Notes
+
+### iOS App Group:
+- Current App Group ID: `group.app.timesafari`
+- Ensure plugin has access to same App Group
+- Share Extension already writes to this App Group
+
+### Android Share Intent:
+- Current implementation handles `ACTION_SEND` and `ACTION_SEND_MULTIPLE`
+- SharedPreferences key: `shared_image` (or similar)
+- Store both base64 and fileName
+
+### Future Enhancements:
+- Consider adding event listeners for real-time notifications
+- Could add method to clear shared image without reading
+- Could add method to get image metadata without full data
+
+## References
+
+- [Capacitor Plugin Development Guide](https://capacitorjs.com/docs/plugins)
+- Existing plugin example: `SafeAreaPlugin.java`
+- Current temp file implementation: `main.capacitor.ts` lines 166-271
+- iOS AppDelegate: `ios/App/App/AppDelegate.swift`
+- Android MainActivity: `android/app/src/main/java/app/timesafari/MainActivity.java`
+
--- a/doc/shared-image-plugin-pre-implementation-decisions.md
+++ b/doc/shared-image-plugin-pre-implementation-decisions.md
@@ -0,0 +1,329 @@
+# Shared Image Plugin - Pre-Implementation Decision Checklist
+
+**Date:** 2025-12-03  
+**Status:** Pre-Implementation Planning  
+**Purpose:** Identify and document decisions needed before implementing SharedImagePlugin
+
+## ✅ Completed Decisions
+
+### 1. Minimum OS Versions
+- ✅ **iOS**: Keep at 13.0 (no changes needed)
+- ✅ **Android**: Upgraded from API 22 to API 23 (completed)
+- ✅ **Rationale**: Meets Capacitor 6 requirements, minimal device impact
+
+### 2. Data Storage Strategy
+- ✅ **iOS**: Use App Group UserDefaults (already implemented in Share Extension)
+- ✅ **Android**: Use SharedPreferences (to be implemented)
+- ✅ **Rationale**: Direct, efficient, no file I/O needed
+
+## 🔍 Decisions Needed Before Implementation
+
+### 1. Plugin Method Design
+
+#### Decision: What methods should the plugin expose?
+
+**Options:**
+- **Option A (Minimal)**: Only `getSharedImage()` - read and clear in one call
+- **Option B (Recommended)**: `getSharedImage()` + `hasSharedImage()` - allows checking without reading
+- **Option C (Extended)**: Add `clearSharedImage()` - explicit clearing without reading
+
+**Recommendation:** **Option B**
+- `getSharedImage()`: Returns `{ base64: string, fileName: string } | null`
+- `hasSharedImage()`: Returns `{ hasImage: boolean }` - useful for quick checks
+
+**Decision Needed:** ✅ Confirm Option B or choose alternative
+
+---
+
+### 2. Error Handling Strategy
+
+#### Decision: How should the plugin handle errors?
+
+**Options:**
+- **Option A**: Return `null` for all errors (no shared image = no error)
+- **Option B**: Use `call.reject()` for actual errors, return `null` only when no image exists
+- **Option C**: Return error object in result: `{ error: string } | { base64: string, fileName: string }`
+
+**Recommendation:** **Option B**
+- `getSharedImage()` returns `null` when no image exists (normal case)
+- `call.reject()` for actual errors (UserDefaults unavailable, data corruption, etc.)
+- Clear distinction between "no data" (normal) vs "error" (exceptional)
+
+**Decision Needed:** ✅ Confirm Option B or choose alternative
+
+---
+
+### 3. Data Clearing Strategy
+
+#### Decision: When should shared image data be cleared?
+
+**Current Behavior (temp file approach):**
+- Data cleared after reading (immediate)
+
+**Options:**
+- **Option A**: Clear immediately after reading (current behavior)
+- **Option B**: Clear on next read (allow re-reading until consumed)
+- **Option C**: Clear after successful storage in temp DB (JS confirms receipt)
+
+**Recommendation:** **Option A** (immediate clearing)
+- Prevents accidental re-reading
+- Simpler implementation
+- Matches current behavior
+- If JS fails to store, user can share again
+
+**Decision Needed:** ✅ Confirm Option A or choose alternative
+
+---
+
+### 4. iOS Plugin Registration
+
+#### Decision: How should the iOS plugin be registered?
+
+**Options:**
+- **Option A**: Auto-discovery (Capacitor finds plugins by naming convention)
+- **Option B**: Manual registration in AppDelegate
+- **Option C**: Hybrid (auto-discovery with manual registration as fallback)
+
+**Recommendation:** **Option A** (auto-discovery)
+- Follows Capacitor best practices
+- Less code to maintain
+- Other plugins in project use auto-discovery (SafeAreaPlugin uses manual, but that's older pattern)
+
+**Note:** Need to verify plugin naming convention:
+- Class name: `SharedImagePlugin`
+- File name: `SharedImagePlugin.swift`
+- Location: `ios/App/App/SharedImagePlugin.swift`
+
+**Decision Needed:** ✅ Confirm Option A, or if auto-discovery doesn't work, use Option B
+
+---
+
+### 5. TypeScript Interface Design
+
+#### Decision: What should the TypeScript interface look like?
+
+**Proposed Interface:**
+```typescript
+export interface SharedImageResult {
+  base64: string;
+  fileName: string;
+}
+
+export interface SharedImagePlugin {
+  getSharedImage(): Promise<SharedImageResult | null>;
+  hasSharedImage(): Promise<{ hasImage: boolean }>;
+}
+```
+
+**Questions:**
+- Should `fileName` be optional? (Currently always provided, but could be empty string)
+- Should we include metadata (image size, MIME type)?
+- Should `hasSharedImage()` return more info (like fileName without reading)?
+
+**Recommendation:** Keep simple for now:
+- `fileName` is always a string (may be default "shared-image.jpg")
+- No metadata initially (can add later if needed)
+- `hasSharedImage()` only returns boolean (keep it lightweight)
+
+**Decision Needed:** ✅ Confirm interface design or request changes
+
+---
+
+### 6. Android Data Storage Timing
+
+#### Decision: When should Android store shared image data in SharedPreferences?
+
+**Current Flow:**
+1. Share intent received in MainActivity
+2. Image processed and written to temp file
+3. JS reads temp file
+
+**New Flow Options:**
+- **Option A**: Store in SharedPreferences immediately when share intent received (in `processSharedImage()`)
+- **Option B**: Store when plugin is first called (lazy loading)
+- **Option C**: Store in both places during transition (backward compatibility)
+
+**Recommendation:** **Option A** (immediate storage)
+- Data available immediately when plugin is called
+- No timing issues
+- Matches iOS pattern (data stored by Share Extension)
+
+**Implementation:**
+- Update `processSharedImage()` in MainActivity to store in SharedPreferences
+- Remove temp file writing
+- Plugin reads from SharedPreferences
+
+**Decision Needed:** ✅ Confirm Option A
+
+---
+
+### 7. Migration Strategy
+
+#### Decision: How to handle the transition from temp file to plugin?
+
+**Options:**
+- **Option A (Clean Break)**: Remove temp file code immediately, use plugin only
+- **Option B (Gradual)**: Support both approaches temporarily, remove temp file later
+- **Option C (Feature Flag)**: Use feature flag to switch between approaches
+
+**Recommendation:** **Option A** (clean break)
+- Simpler implementation
+- Less code to maintain
+- Temp file approach is buggy anyway (why we're replacing it)
+- Can rollback via git if needed
+
+**Rollback Plan:**
+- Keep temp file code in git history
+- If plugin has issues, can revert commit
+- Test thoroughly before removing temp file code
+
+**Decision Needed:** ✅ Confirm Option A
+
+---
+
+### 8. Plugin Naming
+
+#### Decision: What should the plugin be named?
+
+**Options:**
+- **Option A**: `SharedImage` (matches file/class names)
+- **Option B**: `SharedImagePlugin` (more explicit)
+- **Option C**: `NativeShare` (more generic, could handle other share types)
+
+**Recommendation:** **Option A** (`SharedImage`)
+- Matches Capacitor naming conventions (plugins are referenced without "Plugin" suffix)
+- Examples: `Capacitor.Plugins.Camera`, `Capacitor.Plugins.Filesystem`
+- TypeScript: `SharedImage.getSharedImage()`
+
+**Decision Needed:** ✅ Confirm Option A
+
+---
+
+### 9. iOS: Reuse getSharedImageData() or Move to Plugin?
+
+#### Decision: Should the plugin reuse AppDelegate's `getSharedImageData()` or implement its own?
+
+**Current Code:**
+- `AppDelegate.getSharedImageData()` exists and works
+- Reads from App Group UserDefaults
+- Clears data after reading
+
+**Options:**
+- **Option A**: Plugin calls `getSharedImageData()` from AppDelegate
+- **Option B**: Plugin implements its own logic (duplicate code)
+- **Option C**: Move `getSharedImageData()` to a shared utility, both use it
+
+**Recommendation:** **Option C** (shared utility)
+- DRY principle
+- Single source of truth
+- But: May be overkill for simple logic
+
+**Alternative Recommendation:** **Option B** (plugin implements own logic)
+- Plugin is self-contained
+- No dependency on AppDelegate
+- Logic is simple (just UserDefaults read/clear)
+- Can remove `getSharedImageData()` from AppDelegate after migration
+
+**Decision:** ✅ **Option C** (shared utility) - **CONFIRMED**
+- Create shared utility for reading from App Group UserDefaults
+- Both AppDelegate and plugin use the shared utility
+- Single source of truth for shared image data access
+
+---
+
+### 10. Android: SharedPreferences Key Names
+
+#### Decision: What keys should be used in SharedPreferences?
+
+**Proposed Keys:**
+- `shared_image_base64` - Base64 string
+- `shared_image_file_name` - File name
+- `shared_image_ready` - Boolean flag (optional, for quick checks)
+
+**Alternative:**
+- Use a single JSON object: `shared_image_data` = `{ base64: "...", fileName: "..." }`
+
+**Recommendation:** Separate keys (first option)
+- Simpler to read/write
+- No JSON parsing needed
+- Matches iOS pattern (separate UserDefaults keys)
+- Flag is optional but useful for `hasSharedImage()`
+
+**Decision Needed:** ✅ Confirm key naming or request changes
+
+---
+
+### 11. Testing Strategy
+
+#### Decision: What testing approach should we use?
+
+**Options:**
+- **Option A**: Manual testing only
+- **Option B**: Manual + automated unit tests for plugin methods
+- **Option C**: Manual + integration tests
+
+**Recommendation:** **Option A** (manual testing) for now
+- Plugins are hard to unit test (require native environment)
+- Manual testing is sufficient for initial implementation
+- Can add automated tests later if needed
+
+**Test Scenarios:**
+1. Share image from Photos app → Verify appears in app
+2. Share while app backgrounded → Verify appears when app becomes active
+3. Share while app closed → Verify appears on app launch
+4. Multiple rapid shares → Verify only latest is processed
+5. Share then close app before processing → Verify data persists
+6. Share then clear app data → Verify graceful handling
+
+**Decision Needed:** ✅ Confirm testing approach
+
+---
+
+### 12. Documentation Updates
+
+#### Decision: What documentation needs updating?
+
+**Files to Update:**
+- ✅ Implementation plan (this document)
+- ⚠️ `doc/native-share-target-implementation.md` - Update to reflect plugin approach
+- ⚠️ `doc/ios-share-implementation-status.md` - Mark plugin as implemented
+- ⚠️ Code comments in `main.capacitor.ts` - Update to reflect plugin usage
+
+**Decision Needed:** ✅ Confirm documentation update list
+
+---
+
+## Summary of Decisions Needed
+
+| # | Decision | Recommendation | Status |
+|---|----------|----------------|--------|
+| 1 | Plugin Methods | Option B: `getSharedImage()` + `hasSharedImage()` | ✅ Confirmed |
+| 2 | Error Handling | Option B: `null` for no data, `reject()` for errors | ✅ Confirmed |
+| 3 | Data Clearing | Option A: Clear immediately after reading | ✅ Confirmed |
+| 4 | iOS Registration | Option A: Auto-discovery | ✅ Confirmed |
+| 5 | TypeScript Interface | Proposed interface (see above) | ✅ Confirmed |
+| 6 | Android Storage Timing | Option A: Store immediately on share intent | ✅ Confirmed |
+| 7 | Migration Strategy | Option A: Clean break, remove temp file code | ✅ Confirmed |
+| 8 | Plugin Naming | Option A: `SharedImage` | ✅ Confirmed |
+| 9 | iOS Code Reuse | Option C: Shared utility | ✅ Confirmed |
+| 10 | Android Key Names | Separate keys: `shared_image_base64`, `shared_image_file_name` | ✅ Confirmed |
+| 11 | Testing Strategy | Option A: Manual testing | ✅ Confirmed |
+| 12 | Documentation | Update listed files | ✅ Confirmed |
+| - | Multiple Images | Single image only (SharedPhotoView requirement) | ✅ Confirmed |
+| - | Backward Compatibility | No temp file backward compatibility | ✅ Confirmed |
+
+## Next Steps
+
+1. **Review this checklist** and confirm or modify recommendations
+2. **Make decisions** on all pending items
+3. **Update implementation plan** with confirmed decisions
+4. **Begin implementation** with clear specifications
+
+## Questions to Consider
+
+- Are there any edge cases not covered?
+- Should we support multiple images (currently only first image)?
+- Should we add image metadata (size, MIME type) in the future?
+- Do we need backward compatibility with temp file approach?
+- Should plugin methods be synchronous or async? (Capacitor plugins are async by default)
+