feat: add VFS audio resource loading and upgrade to Elementary v4

- Add loadAudioResource/unloadAudioResource APIs for loading audio files
- Use miniaudio for cross-platform audio decoding (WAV, MP3, FLAC, etc.)
- Upgrade Elementary submodule and @elemaudio/core to v4.0.3
- Update JS Renderer for Elementary v4 API (sendMessage-only constructor)
- Fix audio buffer zeroing to prevent noise when no graph is active
- Add AudioBufferResource for proper multi-channel sample support

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: txbrown

.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/ricardoabreu/Development/oss/react-native-elementary-main log --oneline)",
+      "Bash(gh issue view:*)",
+      "Bash(git submodule:*)",
+      "WebSearch",
+      "WebFetch(domain:www.elementary.audio)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(yarn install:*)",
+      "Bash(pod install)",
+      "Bash(npx pod-install)",
+      "Bash(yarn build:ios:*)",
+      "Bash(sudo xcode-select:*)",
+      "Bash(xcodebuild:*)",
+      "Bash(DEVELOPER_DIR=/Applications/Xcode-16.4.0.app/Contents/Developer xcodebuild:*)",
+      "Bash(yarn build:android:*)",
+      "Bash(yarn android)",
+      "Bash(adb shell:*)",
+      "Bash(adb push:*)"
+    ]
+  }
+}

AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working with code in this repository.
+
+## Project Overview
+
+**react-native-elementary** is a React Native library that bridges Elementary Audio with React Native, enabling audio synthesis and processing. It uses C++ audio processing (via miniAudio and Elementary Runtime) with platform-specific wrappers for iOS (Objective-C++/AVAudioEngine) and Android (Kotlin/JNI).
+
+## Common Commands
+
+```bash
+# Install dependencies
+yarn
+
+# Start Metro bundler for example app
+yarn example start
+
+# Run example app
+yarn example ios
+yarn example android
+
+# Type checking
+yarn typecheck
+
+# Linting (uses ESLint + Prettier)
+yarn lint
+yarn lint --fix
+
+# Run tests
+yarn test
+
+# Build library
+yarn prepack
+
+# Setup project (install deps + pods)
+yarn bootstrap
+```
+
+## Architecture
+
+### Code Flow
+```
+JavaScript (useRenderer hook)
+    ↓
+NativeElementary.ts (TurboModule spec)
+    ↓
+┌─────────────────────────────────────┐
+│  iOS: Elementary.mm (Obj-C++)       │
+│  Android: ElementaryModule.kt       │
+└─────────────────────────────────────┘
+    ↓
+C++ Layer (cpp/audioengine.cpp)
+    ↓
+Elementary Runtime + miniAudio
+```
+
+### Key Source Files
+- `src/index.tsx` - Public API: `getSampleRate()`, `NativeRenderer`, `useRenderer()`
+- `src/NativeElementary.ts` - TurboModule interface definition
+- `ios/Elementary.mm` - iOS native implementation using AVAudioEngine
+- `android/src/main/java/com/elementary/ElementaryModule.kt` - Android native module
+- `android/cpp-adapter.cpp` - JNI bridge to C++ layer
+- `cpp/audioengine.cpp` - Cross-platform audio engine using miniAudio
+
+### New vs Old Architecture
+The library supports both React Native architectures:
+- **New Architecture**: TurboModules with JSI (controlled by `RCT_NEW_ARCH_ENABLED`)
+- **Old Architecture**: Standard bridge
+- Source sets in `android/src/newarch/` and `android/src/oldarch/` handle this
+
+### Native Development
+- **iOS**: Open `example/ios/ElementaryExample.xcworkspace`, sources at `Pods > Development Pods > react-native-elementary`
+- **Android**: Open `example/android` in Android Studio, sources at `react-native-elementary` module
+
+## Conventions
+
+- **Package Manager**: Use `yarn` (not npm)
+- **Commit Messages**: Conventional Commits format (`fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`)
+- **Code Style**: Single quotes, 2-space indent, ES5 trailing commas (enforced by Prettier)
+- **Node**: Requires >= 16.0.0

android/CMakeLists.txt

@@ -7,6 +7,7 @@ set(CMAKE_CXX_STANDARD 17)  # Updated to C++17
 add_library(react-native-elementary SHARED
             ../cpp/react-native-elementary.cpp
             ../cpp/audioengine.cpp
+            ../cpp/AudioResourceLoader.cpp
             cpp-adapter.cpp
 )
 

android/cpp-adapter.cpp

@@ -26,7 +26,7 @@ Java_com_elementary_ElementaryModule_nativeApplyInstructions(JNIEnv *env, jclass
 
 
         env->ReleaseStringUTFChars(instructions, instrCStr);
-        
+
         auto jsonInstructions = elem::js::parseJSON(instrStr);
 
         audioEngine->getRuntime().applyInstructions(jsonInstructions);
@@ -38,3 +38,78 @@ JNIEXPORT jint JNICALL
 Java_com_elementary_ElementaryModule_nativeGetSampleRate(JNIEnv *env, jclass type)  {
     return audioEngine.get() ? audioEngine->getSampleRate() : 0;
 }
+
+extern "C"
+JNIEXPORT jobject JNICALL
+Java_com_elementary_ElementaryModule_nativeLoadAudioResource(JNIEnv *env, jclass type, jstring key, jstring filePath) {
+    if (!audioEngine) {
+        return nullptr;
+    }
+
+    const char *keyCStr = env->GetStringUTFChars(key, nullptr);
+    const char *filePathCStr = env->GetStringUTFChars(filePath, nullptr);
+
+    if (!keyCStr || !filePathCStr) {
+        if (keyCStr) env->ReleaseStringUTFChars(key, keyCStr);
+        if (filePathCStr) env->ReleaseStringUTFChars(filePath, filePathCStr);
+        return nullptr;
+    }
+
+    std::string keyStr(keyCStr);
+    std::string filePathStr(filePathCStr);
+
+    env->ReleaseStringUTFChars(key, keyCStr);
+    env->ReleaseStringUTFChars(filePath, filePathCStr);
+
+    // Load the audio resource
+    elementary::AudioLoadResult result = audioEngine->loadAudioResource(keyStr, filePathStr);
+
+    // Find the AudioResourceInfo class
+    jclass infoClass = env->FindClass("com/elementary/AudioResourceInfo");
+    if (!infoClass) {
+        return nullptr;
+    }
+
+    // Get the constructor
+    jmethodID constructor = env->GetMethodID(infoClass, "<init>", "(ZLjava/lang/String;Ljava/lang/String;IJID)V");
+    if (!constructor) {
+        return nullptr;
+    }
+
+    // Create the result object
+    jstring jKey = env->NewStringUTF(result.info.key.c_str());
+    jstring jError = env->NewStringUTF(result.error.c_str());
+
+    jobject infoObj = env->NewObject(
+        infoClass,
+        constructor,
+        static_cast<jboolean>(result.success),
+        jError,
+        jKey,
+        static_cast<jint>(result.info.channels),
+        static_cast<jlong>(result.info.sampleCount),
+        static_cast<jint>(result.info.sampleRate),
+        static_cast<jdouble>(result.info.durationMs)
+    );
+
+    return infoObj;
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_elementary_ElementaryModule_nativeUnloadAudioResource(JNIEnv *env, jclass type, jstring key) {
+    if (!audioEngine) {
+        return JNI_FALSE;
+    }
+
+    const char *keyCStr = env->GetStringUTFChars(key, nullptr);
+    if (!keyCStr) {
+        return JNI_FALSE;
+    }
+
+    std::string keyStr(keyCStr);
+    env->ReleaseStringUTFChars(key, keyCStr);
+
+    bool result = audioEngine->unloadAudioResource(keyStr);
+    return result ? JNI_TRUE : JNI_FALSE;
+}

android/src/main/java/com/elementary/ElementaryModule.kt

@@ -4,8 +4,24 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReactContextBaseJavaModule
 import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
+import java.io.File
+import java.io.FileOutputStream
+
+/**
+ * Data class for audio resource information returned from native code
+ */
+data class AudioResourceInfo(
+  val success: Boolean,
+  val error: String,
+  val key: String,
+  val channels: Int,
+  val sampleCount: Long,
+  val sampleRate: Int,
+  val durationMs: Double
+)
 
 class ElementaryModule(reactContext: ReactApplicationContext) :
   ReactContextBaseJavaModule(reactContext) {
@@ -34,6 +50,70 @@ class ElementaryModule(reactContext: ReactApplicationContext) :
     // No-op
   }
 
+  @ReactMethod
+  fun loadAudioResource(key: String, filePath: String, promise: Promise) {
+    Thread {
+      try {
+        val result = nativeLoadAudioResource(key, filePath)
+        if (result == null) {
+          promise.reject("E_NATIVE_ERROR", "Native audio engine not initialized")
+          return@Thread
+        }
+
+        if (!result.success) {
+          promise.reject("E_LOAD_FAILED", result.error)
+          return@Thread
+        }
+
+        val info = Arguments.createMap().apply {
+          putString("key", result.key)
+          putInt("channels", result.channels)
+          putDouble("sampleCount", result.sampleCount.toDouble())
+          putInt("sampleRate", result.sampleRate)
+          putDouble("durationMs", result.durationMs)
+        }
+        promise.resolve(info)
+      } catch (e: Exception) {
+        promise.reject("E_LOAD_FAILED", e.message, e)
+      }
+    }.start()
+  }
+
+  @ReactMethod
+  fun unloadAudioResource(key: String, promise: Promise) {
+    try {
+      val result = nativeUnloadAudioResource(key)
+      promise.resolve(result)
+    } catch (e: Exception) {
+      promise.reject("E_UNLOAD_FAILED", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun getDocumentsDirectory(promise: Promise) {
+    val documentsDir = reactApplicationContext.filesDir.absolutePath
+    promise.resolve(documentsDir)
+  }
+
+  @ReactMethod
+  fun copyAssetToFiles(assetPath: String, destPath: String, promise: Promise) {
+    Thread {
+      try {
+        val destFile = File(destPath)
+        destFile.parentFile?.mkdirs()
+
+        reactApplicationContext.assets.open(assetPath).use { input ->
+          FileOutputStream(destFile).use { output ->
+            input.copyTo(output)
+          }
+        }
+        promise.resolve(destPath)
+      } catch (e: Exception) {
+        promise.reject("E_COPY_FAILED", e.message, e)
+      }
+    }.start()
+  }
+
   // Helper to emit events
   private fun sendEvent(eventName: String, params: WritableMap?) {
     reactApplicationContext
@@ -54,7 +134,9 @@ class ElementaryModule(reactContext: ReactApplicationContext) :
     nativeStartAudioEngine();
   }
 
-  external fun nativeGetSampleRate(): Int;
-  external fun nativeApplyInstructions(message: String);
-  external fun nativeStartAudioEngine();
+  external fun nativeGetSampleRate(): Int
+  external fun nativeApplyInstructions(message: String)
+  external fun nativeStartAudioEngine()
+  external fun nativeLoadAudioResource(key: String, filePath: String): AudioResourceInfo?
+  external fun nativeUnloadAudioResource(key: String): Boolean
 }

android/src/newarch/com/elementary/ElementaryTurboModule.java

@@ -32,4 +32,24 @@ public void addListener(String eventName) {
     public void removeListeners(double count) {
         module.removeListeners(count);
     }
-} 
+
+    @Override
+    public void loadAudioResource(String key, String filePath, Promise promise) {
+        module.loadAudioResource(key, filePath, promise);
+    }
+
+    @Override
+    public void unloadAudioResource(String key, Promise promise) {
+        module.unloadAudioResource(key, promise);
+    }
+
+    @Override
+    public void getDocumentsDirectory(Promise promise) {
+        module.getDocumentsDirectory(promise);
+    }
+
+    @Override
+    public void copyAssetToFiles(String assetPath, String destPath, Promise promise) {
+        module.copyAssetToFiles(assetPath, destPath, promise);
+    }
+}

cpp/AudioResourceLoader.cpp

@@ -0,0 +1,61 @@
+#include "AudioResourceLoader.h"
+#include "miniaudio.h"
+
+namespace elementary {
+
+    AudioLoadResult AudioResourceLoader::loadFile(const std::string& key, const std::string& filePath) {
+        AudioLoadResult result;
+        result.success = false;
+        result.info.key = key;
+
+        ma_decoder decoder;
+        ma_decoder_config config = ma_decoder_config_init(ma_format_f32, 0, 0);
+
+        ma_result initResult = ma_decoder_init_file(filePath.c_str(), &config, &decoder);
+        if (initResult != MA_SUCCESS) {
+            result.error = "Failed to open audio file: " + filePath;
+            return result;
+        }
+
+        ma_uint64 totalFrames;
+        ma_result lengthResult = ma_decoder_get_length_in_pcm_frames(&decoder, &totalFrames);
+        if (lengthResult != MA_SUCCESS) {
+            result.error = "Failed to get audio file length";
+            ma_decoder_uninit(&decoder);
+            return result;
+        }
+
+        uint32_t channels = decoder.outputChannels;
+        uint32_t sampleRate = decoder.outputSampleRate;
+
+        std::vector<float> interleavedData(totalFrames * channels);
+        ma_uint64 framesRead;
+        ma_result readResult = ma_decoder_read_pcm_frames(&decoder, interleavedData.data(), totalFrames, &framesRead);
+
+        ma_decoder_uninit(&decoder);
+
+        if (readResult != MA_SUCCESS && readResult != MA_AT_END) {
+            result.error = "Failed to read audio data";
+            return result;
+        }
+
+        interleavedData.resize(framesRead * channels);
+
+        // Deinterleave into separate channel data
+        result.data.resize(framesRead * channels);
+        for (uint32_t ch = 0; ch < channels; ++ch) {
+            for (ma_uint64 frame = 0; frame < framesRead; ++frame) {
+                result.data[ch * framesRead + frame] = interleavedData[frame * channels + ch];
+            }
+        }
+
+        result.info.channels = channels;
+        result.info.sampleCount = static_cast<uint64_t>(framesRead);
+        result.info.sampleRate = sampleRate;
+        result.info.durationMs = (static_cast<double>(framesRead) / static_cast<double>(sampleRate)) * 1000.0;
+
+        result.success = true;
+        return result;
+    }
+
+} // namespace elementary