capacitor-sora-editor 1.8.1 → 1.8.2

package/README.md

@@ -199,5 +199,41 @@ The Android source is located in `android/src/main/java/com/abc15018045126/capac
 | `cursorWidth` | `number` | `2.0` | Width of the cursor caret in px |
 | `horizontalPadding` | `number` | `12` | Left/right editor padding |
 
+## 6. Android Content URI & Permissions Guide
+
+If you are using this plugin on Android 11+ (SDK level 30+) and want to edit files outside of your app's scoped storage (e.g., in `Documents/Repo`), you must handle two critical things:
+
+### 1. File Access Permissions
+To access absolute paths (e.g., `/storage/emulated/0/...`), your app likely needs the `MANAGE_EXTERNAL_STORAGE` permission. Standard broad filesystem access is restricted on modern Android.
+
+**Step 1:** Add permission to `AndroidManifest.xml`:
+```xml
+<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
+```
+
+**Step 2:** Request permission at runtime. Capacitor's built-in `Filesystem` plugin only requests scoped storage permissions. You may need a custom plugin or simple native code to trigger `Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION`.
+
+### 2. Resolving Content URIs
+When using the system file picker (like `@capawesome/capacitor-file-picker`), Android returns `content://` URIs (e.g., `content://com.android.providers.media.documents/document/document%3A1234`).
+**Sora Editor cannot always open `content://` URIs directly.** It strongly prefers `file://` URIs or absolute paths for optimal performance and file system access.
+
+**You must resolve `content://` URIs to absolute paths before passing them to `openEditor`.**
+
+#### Example Solution
+Do not pass the raw result from a Content URI based file picker directly unless you are sure it resolves to a file descriptor we can use. For best results with `MANAGE_EXTERNAL_STORAGE`:
+
+```typescript
+// BAD (Might fail if the editor expects a File object)
+await SoraEditor.openEditor({ filePath: 'content://com.android...' });
+
+// GOOD
+const absolutePath = '/storage/emulated/0/MyFolder/MyFile.txt';
+await SoraEditor.openEditor({ 
+  filePath: 'file://' + absolutePath 
+});
+```
+
+*Note: You will need to implement the URI-to-Path resolution in your native Android code, as JavaScript cannot directly access the mapping between Content IDs and file paths.*
+
 ## License
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "capacitor-sora-editor",
-    "version": "1.8.1",
+    "version": "1.8.2",
     "description": "SoraEditor plugin for Capacitor",
     "main": "dist/plugin.js",
     "module": "dist/esm/index.js",