capacitor-sora-editor 1.2.1 → 1.8.2

package/DEPENDENCY_SOLUTION.md

@@ -1,87 +1,87 @@
-# Dependency Solution: Full Source Integration (Standalone Mode)
-
-## Problem Statement
-
-This Capacitor plugin (`capacitor-sora-editor`) needs to include the `sora-editor` library. We initially tried:
-1. **Local Project Dependency** ❌ (Fails for end-users without source)
-2. **JitPack Build** ❌ (Unreliable, environment errors)
-3. **Remote AAR via Ivy** ❌ (Requires manual GitHub Release uploads and complex Gradle configuration for consumers)
-4. **Local AAR Bundling** ❌ (Strict Gradle restriction for Library modules)
-
-## Final (Best) Solution: Full Source Integration
-
-We have integrated the primary modules of `sora-editor` directly into the plugin as source code. This makes the plugin **completely standalone** and **zero-configuration** for users.
-
-### Architecture
-
-The following modules from `sora-editor` have been copied into `capacitor-sora-editor/android/sora-editor/`:
-- `editor`: The core editor UI and logic.
-- `language-textmate`: TextMate grammar support.
-- `oniguruma-native`: JNI bindings for the Oniguruma regex engine.
-
-### Implementation Details
-
-#### 1. Source Sets Configuration
-In the plugin's `android/build.gradle`, we manually include these source directories in the `main` sourceSet:
-
-```gradle
-sourceSets {
-    main {
-        java.srcDirs = [
-            'src/main/java',
-            'sora-editor/editor/src/main/java',
-            'sora-editor/language-textmate/src/main/java',
-            'sora-editor/oniguruma-native/src/main/java'
-        ]
-        res.srcDirs = [
-            'src/main/res',
-            'sora-editor/editor/src/main/res',
-            'sora-editor/language-textmate/src/main/res',
-            'sora-editor/oniguruma-native/src/main/res'
-        ]
-        assets.srcDirs = [
-            'src/main/assets',
-            'sora-editor/editor/src/main/assets',
-            'sora-editor/language-textmate/src/main/assets',
-            'sora-editor/oniguruma-native/src/main/assets'
-        ]
-    }
-}
-```
-
-#### 2. Native Build (C++)
-The Oniguruma engine is compiled using CMake directly from the integrated source:
-
-```gradle
-externalNativeBuild {
-    cmake {
-        path = file("sora-editor/oniguruma-native/src/main/cpp/CMakeLists.txt")
-        version = "3.22.1"
-    }
-}
-ndkVersion = "29.0.14206865"
-```
-
-#### 3. Module Namespace
-To match the existing source code packagename and resource references, the plugin's `namespace` is set to:
-`io.github.abc15018045126.sora`
-
-## Why This is the Best Approach
-
-| Feature | Remote AAR | Source Integration |
-|---------|------------|--------------------|
-| **Setup for Users** | Complex (Requires Ivy repo config) | **Zero (Standard npm install)** |
-| **Development** | Slow (Build -> Upload -> Download) | **Fast (Direct source edits)** |
-| **Stability** | Depends on remote server | **Self-contained** |
-| **Binary Size** | Fixed | Optimized by user's proguard/R8 |
-| **Sync Issues** | Common (missing AAR in build cache) | **None** |
-
-## Maintenance
-
-As the author, you can now modify the editor code directly within the plugin's `sora-editor` directory. These changes will be picked up immediately by any app using the local plugin (e.g., the `notes` app).
-
-When you are ready to release, simply:
-1. `npm version patch`
-2. `npm publish`
-
-The complete source code will be packaged into the npm tarball, and Gradle will compile it on the user's machine during their app's build process.
+# Dependency Solution: Full Source Integration (Standalone Mode)
+
+## Problem Statement
+
+This Capacitor plugin (`capacitor-sora-editor`) needs to include the `sora-editor` library. We initially tried:
+1. **Local Project Dependency** ❌ (Fails for end-users without source)
+2. **JitPack Build** ❌ (Unreliable, environment errors)
+3. **Remote AAR via Ivy** ❌ (Requires manual GitHub Release uploads and complex Gradle configuration for consumers)
+4. **Local AAR Bundling** ❌ (Strict Gradle restriction for Library modules)
+
+## Final (Best) Solution: Full Source Integration
+
+We have integrated the primary modules of `sora-editor` directly into the plugin as source code. This makes the plugin **completely standalone** and **zero-configuration** for users.
+
+### Architecture
+
+The following modules from `sora-editor` have been copied into `capacitor-sora-editor/android/sora-editor/`:
+- `editor`: The core editor UI and logic.
+- `language-textmate`: TextMate grammar support.
+- `oniguruma-native`: JNI bindings for the Oniguruma regex engine.
+
+### Implementation Details
+
+#### 1. Source Sets Configuration
+In the plugin's `android/build.gradle`, we manually include these source directories in the `main` sourceSet:
+
+```gradle
+sourceSets {
+    main {
+        java.srcDirs = [
+            'src/main/java',
+            'sora-editor/editor/src/main/java',
+            'sora-editor/language-textmate/src/main/java',
+            'sora-editor/oniguruma-native/src/main/java'
+        ]
+        res.srcDirs = [
+            'src/main/res',
+            'sora-editor/editor/src/main/res',
+            'sora-editor/language-textmate/src/main/res',
+            'sora-editor/oniguruma-native/src/main/res'
+        ]
+        assets.srcDirs = [
+            'src/main/assets',
+            'sora-editor/editor/src/main/assets',
+            'sora-editor/language-textmate/src/main/assets',
+            'sora-editor/oniguruma-native/src/main/assets'
+        ]
+    }
+}
+```
+
+#### 2. Native Build (C++)
+The Oniguruma engine is compiled using CMake directly from the integrated source:
+
+```gradle
+externalNativeBuild {
+    cmake {
+        path = file("sora-editor/oniguruma-native/src/main/cpp/CMakeLists.txt")
+        version = "3.22.1"
+    }
+}
+ndkVersion = "29.0.14206865"
+```
+
+#### 3. Module Namespace
+To match the existing source code packagename and resource references, the plugin's `namespace` is set to:
+`io.github.abc15018045126.sora`
+
+## Why This is the Best Approach
+
+| Feature | Remote AAR | Source Integration |
+|---------|------------|--------------------|
+| **Setup for Users** | Complex (Requires Ivy repo config) | **Zero (Standard npm install)** |
+| **Development** | Slow (Build -> Upload -> Download) | **Fast (Direct source edits)** |
+| **Stability** | Depends on remote server | **Self-contained** |
+| **Binary Size** | Fixed | Optimized by user's proguard/R8 |
+| **Sync Issues** | Common (missing AAR in build cache) | **None** |
+
+## Maintenance
+
+As the author, you can now modify the editor code directly within the plugin's `sora-editor` directory. These changes will be picked up immediately by any app using the local plugin (e.g., the `notes` app).
+
+When you are ready to release, simply:
+1. `npm version patch`
+2. `npm publish`
+
+The complete source code will be packaged into the npm tarball, and Gradle will compile it on the user's machine during their app's build process.

package/DEVELOPMENT.md

@@ -1,152 +1,152 @@
-# Development Workflow
-
-This document describes the development workflow for `capacitor-sora-editor` and its integration with the Notes applications.
-
-## Project Structure
-
-```
-notes/
-├── capacitor-sora-editor/         # Plugin source code (standalone)
-│   └── android/sora-editor/       # Integrated sora-editor source (CORE)
-├── sora-editor/                   # Original Android library source (External)
-├── notes/                         # Development app (uses local plugin)
-└── notes-new/                     # Testing app (uses npm published plugin)
-```
-
-## Development Environments
-
-### `notes` - Development Environment
-
-**Purpose**: Active development and debugging of `capacitor-sora-editor`.
-
-**Configuration**:
-```json
-{
-  "dependencies": {
-    "capacitor-sora-editor": "file:capacitor-sora-editor"
-  }
-}
-```
-
-**Usage**:
-- Modify plugin code directly in `capacitor-sora-editor/android/src`
-- Modify core editor code in `capacitor-sora-editor/android/sora-editor/`
-- Changes are immediately reflected upon rebuilding the app.
-
-### `notes-new` - Testing Environment
-
-**Purpose**: Validate published npm package as end-users would experience it.
-
-**Configuration**:
-```json
-{
-  "dependencies": {
-    "capacitor-sora-editor": "^1.1.0"
-  }
-}
-```
-
-**Usage**:
-- Install from npm registry.
-- Test the exact package users will receive.
-- No special Gradle configuration required for users.
-
-## Development Workflow
-
-### 1. Developing New Features
-
-Work in the `notes` project for rapid iteration. You can modify either the plugin wrapper or the editor core:
-
-```bash
-cd notes
-
-# 1. Edit code in capacitor-sora-editor/android/
-#    - Wrapper: src/main/java/...
-#    - Core Editor: sora-editor/editor/...
-
-# 2. Build and test
-npm run build
-npx cap sync android
-cd android && ./gradlew.bat assembleDebug
-
-# 3. Install to device
-./gradlew.bat installDebug
-```
-
-### 2. Updating Core Logic (sora-editor)
-
-Since the source is integrated, you no longer need to build AARs or upload to GitHub Releases for functional updates. Simply editing the files in `capacitor-sora-editor/android/sora-editor/` is enough for local development.
-
-## Publishing Workflow
-
-When you are satisfied with your changes and want to release to npm:
-
-### Step 1: Bump Version & Build
-
-```bash
-cd capacitor-sora-editor
-
-# Update version (e.g., 1.1.0 -> 1.1.1)
-npm version patch
-
-# Build the web part of the plugin
-npm run build
-```
-
-### Step 2: Publish to npm
-
-```bash
-cd capacitor-sora-editor
-npm publish
-```
-
-The entire `android/sora-editor` source tree will be included in the npm package.
-
-### Step 3: Validate in notes-new
-
-```bash
-cd notes-new
-
-# Install the latest version
-npm install capacitor-sora-editor@latest
-
-# Standard Capacitor sync and build
-npx cap sync android
-cd android && ./gradlew.bat assembleDebug
-```
-
-## Troubleshooting
-
-### Issue: "Unresolved reference: R"
-
-**Cause**: Package namespace mismatch.
-**Solution**: The plugin namespace is set to `io.github.abc15018045126.sora` in `android/build.gradle` to match the core editor's resource usage. Ensure all new activity/fragment code uses the correct R import if necessary.
-
-### Issue: C++ Compilation Errors
-
-**Cause**: Missing NDK or CMake issues.
-**Solution**: Ensure you have NDK `29.0.14206865` installed via Android Studio SDK Manager. The build will automatically compile the Oniguruma engine using CMake.
-
-### Issue: Changes not reflected
-
-**Cause**: Gradle cache.
-**Solution**:
-```bash
-cd android
-./gradlew.bat clean
-```
-
-## Quick Reference
-
-| Task | Command |
-|------|---------|
-| Local Test | `cd notes && npm run build && npx cap sync android` |
-| Sync Android | `npx cap sync android` |
-| Build (Dev) | `cd android && ./gradlew.bat assembleDebug` |
-| Install | `cd android && ./gradlew.bat installDebug` |
-| Publish | `cd capacitor-sora-editor && npm publish` |
-
-## Related Documentation
-
-- [DEPENDENCY_SOLUTION.md](./DEPENDENCY_SOLUTION.md) - Why we use source integration.
-- [NO_JITPACK_WARNING.md](./NO_JITPACK_WARNING.md) - Why we avoid JitPack.
+# Development Workflow
+
+This document describes the development workflow for `capacitor-sora-editor` and its integration with the Notes applications.
+
+## Project Structure
+
+```
+notes/
+├── capacitor-sora-editor/         # Plugin source code (standalone)
+│   └── android/sora-editor/       # Integrated sora-editor source (CORE)
+├── sora-editor/                   # Original Android library source (External)
+├── notes/                         # Development app (uses local plugin)
+└── notes-new/                     # Testing app (uses npm published plugin)
+```
+
+## Development Environments
+
+### `notes` - Development Environment
+
+**Purpose**: Active development and debugging of `capacitor-sora-editor`.
+
+**Configuration**:
+```json
+{
+  "dependencies": {
+    "capacitor-sora-editor": "file:capacitor-sora-editor"
+  }
+}
+```
+
+**Usage**:
+- Modify plugin code directly in `capacitor-sora-editor/android/src`
+- Modify core editor code in `capacitor-sora-editor/android/sora-editor/`
+- Changes are immediately reflected upon rebuilding the app.
+
+### `notes-new` - Testing Environment
+
+**Purpose**: Validate published npm package as end-users would experience it.
+
+**Configuration**:
+```json
+{
+  "dependencies": {
+    "capacitor-sora-editor": "^1.1.0"
+  }
+}
+```
+
+**Usage**:
+- Install from npm registry.
+- Test the exact package users will receive.
+- No special Gradle configuration required for users.
+
+## Development Workflow
+
+### 1. Developing New Features
+
+Work in the `notes` project for rapid iteration. You can modify either the plugin wrapper or the editor core:
+
+```bash
+cd notes
+
+# 1. Edit code in capacitor-sora-editor/android/
+#    - Wrapper: src/main/java/...
+#    - Core Editor: sora-editor/editor/...
+
+# 2. Build and test
+npm run build
+npx cap sync android
+cd android && ./gradlew.bat assembleDebug
+
+# 3. Install to device
+./gradlew.bat installDebug
+```
+
+### 2. Updating Core Logic (sora-editor)
+
+Since the source is integrated, you no longer need to build AARs or upload to GitHub Releases for functional updates. Simply editing the files in `capacitor-sora-editor/android/sora-editor/` is enough for local development.
+
+## Publishing Workflow
+
+When you are satisfied with your changes and want to release to npm:
+
+### Step 1: Bump Version & Build
+
+```bash
+cd capacitor-sora-editor
+
+# Update version (e.g., 1.1.0 -> 1.1.1)
+npm version patch
+
+# Build the web part of the plugin
+npm run build
+```
+
+### Step 2: Publish to npm
+
+```bash
+cd capacitor-sora-editor
+npm publish
+```
+
+The entire `android/sora-editor` source tree will be included in the npm package.
+
+### Step 3: Validate in notes-new
+
+```bash
+cd notes-new
+
+# Install the latest version
+npm install capacitor-sora-editor@latest
+
+# Standard Capacitor sync and build
+npx cap sync android
+cd android && ./gradlew.bat assembleDebug
+```
+
+## Troubleshooting
+
+### Issue: "Unresolved reference: R"
+
+**Cause**: Package namespace mismatch.
+**Solution**: The plugin namespace is set to `io.github.abc15018045126.sora` in `android/build.gradle` to match the core editor's resource usage. Ensure all new activity/fragment code uses the correct R import if necessary.
+
+### Issue: C++ Compilation Errors
+
+**Cause**: Missing NDK or CMake issues.
+**Solution**: Ensure you have NDK `29.0.14206865` installed via Android Studio SDK Manager. The build will automatically compile the Oniguruma engine using CMake.
+
+### Issue: Changes not reflected
+
+**Cause**: Gradle cache.
+**Solution**:
+```bash
+cd android
+./gradlew.bat clean
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Local Test | `cd notes && npm run build && npx cap sync android` |
+| Sync Android | `npx cap sync android` |
+| Build (Dev) | `cd android && ./gradlew.bat assembleDebug` |
+| Install | `cd android && ./gradlew.bat installDebug` |
+| Publish | `cd capacitor-sora-editor && npm publish` |
+
+## Related Documentation
+
+- [DEPENDENCY_SOLUTION.md](./DEPENDENCY_SOLUTION.md) - Why we use source integration.
+- [NO_JITPACK_WARNING.md](./NO_JITPACK_WARNING.md) - Why we avoid JitPack.

package/NO_JITPACK_WARNING.md

@@ -1,14 +1,14 @@
-# WARNING: DO NOT USE JITPACK
-
-This project strictly avoids using JitPack for dependency resolution.
-
-## Reasons:
-1.  **Build Instability**: JitPack builds frequently fail or time out, especially with complex Gradle configurations or submodules (e.g., `sora-editor` structure).
-2.  **Environment Mismatches**: JitPack's build environment (Java version, Android SDK) often differs from local or production environments, leading to `Cannot find a Java installation` errors.
-3.  **Local Control**: We distribute a pre-built `editor-release.aar` bundled directly within `capacitor-sora-editor`. This ensures that exactly what works locally is what users get.
-
-## Instructions for Maintainers:
-*   **NEVER** add `maven { url 'https://jitpack.io' }` to `android/build.gradle`.
-*   **ALWAYS** use the local AAR located in `android/libs/editor-release.aar`.
-*   **Dependency Format**: Use `compileOnly files("libs/editor-release.aar")` in the plugin's `build.gradle` to avoid "Direct local .aar file dependencies are not supported" errors during packaging.
-*   **Consumer Setup**: Consumers (apps using this plugin) will need to ensure the AAR is correctly included or accessible if not automatically handled by Capacitor's tooling.
+# WARNING: DO NOT USE JITPACK
+
+This project strictly avoids using JitPack for dependency resolution.
+
+## Reasons:
+1.  **Build Instability**: JitPack builds frequently fail or time out, especially with complex Gradle configurations or submodules (e.g., `sora-editor` structure).
+2.  **Environment Mismatches**: JitPack's build environment (Java version, Android SDK) often differs from local or production environments, leading to `Cannot find a Java installation` errors.
+3.  **Local Control**: We distribute a pre-built `editor-release.aar` bundled directly within `capacitor-sora-editor`. This ensures that exactly what works locally is what users get.
+
+## Instructions for Maintainers:
+*   **NEVER** add `maven { url 'https://jitpack.io' }` to `android/build.gradle`.
+*   **ALWAYS** use the local AAR located in `android/libs/editor-release.aar`.
+*   **Dependency Format**: Use `compileOnly files("libs/editor-release.aar")` in the plugin's `build.gradle` to avoid "Direct local .aar file dependencies are not supported" errors during packaging.
+*   **Consumer Setup**: Consumers (apps using this plugin) will need to ensure the AAR is correctly included or accessible if not automatically handled by Capacitor's tooling.

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