@callstack/brownie 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @callstack/brownie
 
+## 3.5.0
+
+### Minor Changes
+
+- [#257](https://github.com/callstack/react-native-brownfield/pull/257) [`d0e6203`](https://github.com/callstack/react-native-brownfield/commit/d0e62039c8a080c648abbbeace047e72fadce28b) Thanks [@hurali97](https://github.com/hurali97)! - add brownie android
+
+### Patch Changes
+
+- Updated dependencies [[`d0e6203`](https://github.com/callstack/react-native-brownfield/commit/d0e62039c8a080c648abbbeace047e72fadce28b)]:
+  - @callstack/brownfield-cli@3.5.0
+
+## 3.4.0
+
+### Patch Changes
+
+- [#246](https://github.com/callstack/react-native-brownfield/pull/246) [`5484065`](https://github.com/callstack/react-native-brownfield/commit/5484065da9dc86a420af2be692fcdefa32fbb2af) Thanks [@artus9033](https://github.com/artus9033)! - chore: upgrade dependencies
+
+- [#246](https://github.com/callstack/react-native-brownfield/pull/246) [`5484065`](https://github.com/callstack/react-native-brownfield/commit/5484065da9dc86a420af2be692fcdefa32fbb2af) Thanks [@artus9033](https://github.com/artus9033)! - chore: upgrade dependencies
+
+- Updated dependencies [[`5484065`](https://github.com/callstack/react-native-brownfield/commit/5484065da9dc86a420af2be692fcdefa32fbb2af), [`dd8b8a0`](https://github.com/callstack/react-native-brownfield/commit/dd8b8a0b532fe779c1f2ce018577ad748b887ee0), [`54ab7ab`](https://github.com/callstack/react-native-brownfield/commit/54ab7ab01bd6f95439cc8b702d4124552e22ad55), [`5484065`](https://github.com/callstack/react-native-brownfield/commit/5484065da9dc86a420af2be692fcdefa32fbb2af)]:
+  - @callstack/brownfield-cli@3.4.0
+
 ## 3.3.0
 
 ### Patch Changes

package/android/build.gradle

@@ -0,0 +1,91 @@
+buildscript {
+  ext.brownie = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36,
+    cmakeVersion: "3.22.1"
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return brownie[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.callstack.brownie"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+    consumerProguardFiles "consumer-rules.pro"
+
+    externalNativeBuild {
+      cmake {
+        arguments "-DANDROID_STL=c++_shared"
+        cppFlags "-std=c++20 -fexceptions -frtti"
+      }
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  packaging {
+    jniLibs {
+      excludes += ["**/libc++_shared.so"]
+    }
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/cpp/CMakeLists.txt"
+      version getExtOrDefault("cmakeVersion")
+    }
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "com.google.code.gson:gson:2.13.1"
+}

package/android/consumer-rules.pro

@@ -0,0 +1,4 @@
+-keep class com.callstack.brownie.BrownieStoreBridge {
+    void onStoreDidChange(java.lang.String);
+    native <methods>;
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.callstack.brownie" />

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,68 @@
+cmake_minimum_required(VERSION 3.13)
+
+project(brownie)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+set(PACKAGE_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../..")
+
+SET(folly_FLAGS
+        -DFOLLY_NO_CONFIG=1
+        -DFOLLY_HAVE_CLOCK_GETTIME=1
+        -DFOLLY_USE_LIBCPP=1
+        -DFOLLY_CFG_NO_COROUTINES=1
+        -DFOLLY_MOBILE=1
+        -DFOLLY_HAVE_RECVMMSG=1
+        -DFOLLY_HAVE_PTHREAD=1
+        # Once we target android-23 above, we can comment
+        # the following line. NDK uses GNU style stderror_r() after API 23.
+        -DFOLLY_HAVE_XSI_STRERROR_R=1
+        )
+
+add_compile_options(${folly_FLAGS})
+
+add_library(
+  brownie
+  SHARED
+  JNIBrownieStoreBridge.cpp
+  "${PACKAGE_ROOT}/cpp/BrownieHostObject.cpp"
+  "${PACKAGE_ROOT}/cpp/BrownieInstaller.cpp"
+  "${PACKAGE_ROOT}/cpp/BrownieStore.cpp"
+  "${PACKAGE_ROOT}/cpp/BrownieStoreManager.cpp"
+)
+
+target_include_directories(
+  brownie
+  PRIVATE
+  "${PACKAGE_ROOT}/cpp"
+)
+
+find_library(log-lib log)
+find_package(fbjni REQUIRED CONFIG)
+find_package(ReactAndroid REQUIRED CONFIG)
+
+target_link_libraries(
+  brownie
+  PRIVATE
+  ${log-lib}
+  fbjni::fbjni
+)
+
+
+if(TARGET ReactAndroid::jsi)
+  target_link_libraries(brownie PRIVATE ReactAndroid::jsi)
+elseif(TARGET jsi)
+  target_link_libraries(brownie PRIVATE jsi)
+endif()
+
+if(TARGET ReactAndroid::reactnative)
+  target_link_libraries(brownie PRIVATE ReactAndroid::reactnative)
+endif()
+
+if(TARGET ReactAndroid::folly_runtime)
+  target_link_libraries(brownie PRIVATE ReactAndroid::folly_runtime)
+elseif(TARGET folly_runtime)
+  target_link_libraries(brownie PRIVATE folly_runtime)
+endif()
+

package/android/src/main/cpp/JNIBrownieStoreBridge.cpp

@@ -0,0 +1,233 @@
+#include <jni.h>
+#include <folly/dynamic.h>
+#include <folly/json.h>
+#include <jsi/jsi.h>
+#include <memory>
+#include <mutex>
+#include <string>
+#include "BrownieInstaller.h"
+#include "BrownieStore.h"
+#include "BrownieStoreManager.h"
+
+namespace {
+
+constexpr auto kBridgeClassName = "com/callstack/brownie/BrownieStoreBridge";
+constexpr auto kOnStoreDidChangeMethod = "onStoreDidChange";
+constexpr auto kOnStoreDidChangeSignature = "(Ljava/lang/String;)V";
+
+JavaVM *g_vm = nullptr;
+jclass g_bridgeClass = nullptr;
+jmethodID g_onStoreDidChangeMethod = nullptr;
+std::once_flag g_initMethodOnce;
+
+std::string fromJString(JNIEnv *env, jstring value) {
+  if (value == nullptr) {
+    return "";
+  }
+
+  const char *chars = env->GetStringUTFChars(value, nullptr);
+  if (chars == nullptr) {
+    return "";
+  }
+
+  std::string result(chars);
+  env->ReleaseStringUTFChars(value, chars);
+  return result;
+}
+
+jstring toJString(JNIEnv *env, const std::string &value) {
+  return env->NewStringUTF(value.c_str());
+}
+
+bool initOnStoreDidChangeMethod(JNIEnv *env) {
+  bool success = true;
+  std::call_once(g_initMethodOnce, [env, &success]() {
+    auto localBridgeClass = env->FindClass(kBridgeClassName);
+    if (localBridgeClass == nullptr) {
+      success = false;
+      return;
+    }
+
+    g_bridgeClass = reinterpret_cast<jclass>(env->NewGlobalRef(localBridgeClass));
+    env->DeleteLocalRef(localBridgeClass);
+    if (g_bridgeClass == nullptr) {
+      success = false;
+      return;
+    }
+
+    g_onStoreDidChangeMethod = env->GetStaticMethodID(
+        g_bridgeClass, kOnStoreDidChangeMethod, kOnStoreDidChangeSignature);
+    if (g_onStoreDidChangeMethod == nullptr) {
+      success = false;
+    }
+  });
+
+  return success && g_bridgeClass != nullptr && g_onStoreDidChangeMethod != nullptr;
+}
+
+void emitStoreDidChange(const std::string &storeKey) {
+  if (g_vm == nullptr) {
+    return;
+  }
+
+  JNIEnv *env = nullptr;
+  bool didAttachCurrentThread = false;
+
+  if (g_vm->GetEnv(reinterpret_cast<void **>(&env), JNI_VERSION_1_6) != JNI_OK) {
+    if (g_vm->AttachCurrentThread(&env, nullptr) != JNI_OK) {
+      return;
+    }
+    didAttachCurrentThread = true;
+  }
+
+  if (!initOnStoreDidChangeMethod(env)) {
+    if (didAttachCurrentThread) {
+      g_vm->DetachCurrentThread();
+    }
+    return;
+  }
+
+  auto jStoreKey = toJString(env, storeKey);
+  env->CallStaticVoidMethod(g_bridgeClass, g_onStoreDidChangeMethod, jStoreKey);
+  env->DeleteLocalRef(jStoreKey);
+
+  if (didAttachCurrentThread) {
+    g_vm->DetachCurrentThread();
+  }
+}
+
+std::shared_ptr<brownie::BrownieStore> getStoreOrNull(const std::string &storeKey) {
+  return brownie::BrownieStoreManager::shared().getStore(storeKey);
+}
+
+template <typename TCallback>
+void withStore(JNIEnv *env, jstring storeKey, TCallback &&callback) {
+  auto store = getStoreOrNull(fromJString(env, storeKey));
+  if (!store) {
+    return;
+  }
+
+  callback(std::move(store));
+}
+
+template <typename TCallback>
+jstring withStoreResult(JNIEnv *env, jstring storeKey, TCallback &&callback) {
+  auto store = getStoreOrNull(fromJString(env, storeKey));
+  if (!store) {
+    return nullptr;
+  }
+
+  return callback(std::move(store));
+}
+
+template <typename TCallback>
+void withParsedJson(const std::string &json, TCallback &&callback) {
+  try {
+    callback(folly::parseJson(json));
+  } catch (const std::exception &) {
+    // Keep native bridge resilient to malformed payloads from Kotlin callers.
+  }
+}
+
+jstring toJsonJStringOrNull(JNIEnv *env, const folly::dynamic &value) {
+  try {
+    return toJString(env, folly::toJson(value));
+  } catch (const std::exception &) {
+    return nullptr;
+  }
+}
+
+} // namespace
+
+extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
+  g_vm = vm;
+  return JNI_VERSION_1_6;
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_callstack_brownie_BrownieStoreBridge_nativeInstallJSIBindings(JNIEnv *,
+                                                                        jclass,
+                                                                        jlong runtimePointer) {
+  auto *runtime = reinterpret_cast<facebook::jsi::Runtime *>(runtimePointer);
+  if (runtime == nullptr) {
+    return;
+  }
+
+  brownie::BrownieInstaller::install(*runtime);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_callstack_brownie_BrownieStoreBridge_nativeRegisterStore(JNIEnv *env,
+                                                                   jclass,
+                                                                   jstring storeKey) {
+  auto store = std::make_shared<brownie::BrownieStore>();
+  auto key = fromJString(env, storeKey);
+  store->setChangeCallback([key]() { emitStoreDidChange(key); });
+  brownie::BrownieStoreManager::shared().registerStore(key, store);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_callstack_brownie_BrownieStoreBridge_nativeRemoveStore(JNIEnv *env,
+                                                                 jclass,
+                                                                 jstring storeKey) {
+  brownie::BrownieStoreManager::shared().removeStore(fromJString(env, storeKey));
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_callstack_brownie_BrownieStoreBridge_nativeSetValue(JNIEnv *env,
+                                                              jclass,
+                                                              jstring valueJson,
+                                                              jstring propKey,
+                                                              jstring storeKey) {
+  withStore(env, storeKey, [env, propKey, valueJson](std::shared_ptr<brownie::BrownieStore> store) {
+    auto key = fromJString(env, propKey);
+    auto json = fromJString(env, valueJson);
+    withParsedJson(json, [&store, &key](folly::dynamic value) { store->set(key, std::move(value)); });
+  });
+}
+
+extern "C" JNIEXPORT jstring JNICALL
+Java_com_callstack_brownie_BrownieStoreBridge_nativeGetValue(JNIEnv *env,
+                                                              jclass,
+                                                              jstring propKey,
+                                                              jstring storeKey) {
+  return withStoreResult(env, storeKey, [env, propKey](std::shared_ptr<brownie::BrownieStore> store) {
+    auto key = fromJString(env, propKey);
+    return toJsonJStringOrNull(env, store->get(key));
+  });
+}
+
+extern "C" JNIEXPORT jstring JNICALL
+Java_com_callstack_brownie_BrownieStoreBridge_nativeGetSnapshot(JNIEnv *env,
+                                                                 jclass,
+                                                                 jstring storeKey) {
+  return withStoreResult(env, storeKey, [env](std::shared_ptr<brownie::BrownieStore> store) {
+    return toJsonJStringOrNull(env, store->getSnapshot());
+  });
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_callstack_brownie_BrownieStoreBridge_nativeSetState(JNIEnv *env,
+                                                              jclass,
+                                                              jstring stateJson,
+                                                              jstring storeKey) {
+  withStore(env, storeKey, [env, stateJson](std::shared_ptr<brownie::BrownieStore> store) {
+    auto json = fromJString(env, stateJson);
+    withParsedJson(json, [&store](folly::dynamic state) { store->setState(std::move(state)); });
+  });
+}
+
+extern "C" JNIEXPORT void JNICALL JNI_OnUnload(JavaVM *, void *) {
+  if (g_vm == nullptr || g_bridgeClass == nullptr) {
+    return;
+  }
+
+  JNIEnv *env = nullptr;
+  if (g_vm->GetEnv(reinterpret_cast<void **>(&env), JNI_VERSION_1_6) != JNI_OK) {
+    return;
+  }
+
+  env->DeleteGlobalRef(g_bridgeClass);
+  g_bridgeClass = nullptr;
+  g_onStoreDidChangeMethod = nullptr;
+}

package/android/src/main/java/com/callstack/brownie/BrownieModule.kt

@@ -0,0 +1,84 @@
+package com.callstack.brownie
+
+import android.os.Handler
+import android.os.Looper
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * TurboModule entrypoint for Brownie on Android.
+ *
+ * It installs JSI bindings and forwards native store change events to JavaScript.
+ */
+class BrownieModule(reactContext: ReactApplicationContext) :
+  NativeBrownieModuleSpec(reactContext) {
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private val didInstallJSI = AtomicBoolean(false)
+  private var storeDidChangeListenerId: String? = null
+
+  private val storeDidChangeListener: (String) -> Unit = { storeKey ->
+    val eventPayload =
+      Arguments.createMap().apply {
+        putString("storeKey", storeKey)
+        putString("key", "storeKey")
+        putString("value", storeKey)
+      }
+
+    if (Looper.myLooper() == Looper.getMainLooper()) {
+      emitNativeStoreDidChange(eventPayload)
+    } else {
+      mainHandler.post { emitNativeStoreDidChange(eventPayload) }
+    }
+  }
+
+  init {
+    storeDidChangeListenerId = BrownieStoreBridge.addStoreDidChangeListener(storeDidChangeListener)
+  }
+
+  /**
+   * Called by React Native when the module is initialized.
+   */
+  override fun initialize() {
+    super.initialize()
+    installJSIBindingsIfNeeded()
+  }
+
+  /**
+   * Called when the module is being torn down.
+   */
+  override fun invalidate() {
+    storeDidChangeListenerId?.let(BrownieStoreBridge::removeStoreDidChangeListener)
+    storeDidChangeListenerId = null
+    StoreManager.shared.clear()
+    super.invalidate()
+  }
+
+  /**
+   * Installs C++ JSI globals once a valid JS runtime pointer is available.
+   */
+  private fun installJSIBindingsIfNeeded() {
+    if (didInstallJSI.get()) {
+      return
+    }
+
+    val runtimePointer = reactApplicationContext.javaScriptContextHolder?.get() ?: 0L
+    if (runtimePointer == 0L) {
+      return
+    }
+
+    BrownieStoreBridge.installJSIBindings(runtimePointer)
+    didInstallJSI.set(true)
+  }
+
+  companion object {
+    const val NAME = "Brownie"
+  }
+
+  /**
+   * Exposes this module name to React Native.
+   */
+  override fun getName(): String {
+    return NAME
+  }
+}

package/android/src/main/java/com/callstack/brownie/BrowniePackage.kt

@@ -0,0 +1,33 @@
+package com.callstack.brownie
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+/**
+ * React Native package that registers the Brownie TurboModule.
+ */
+class BrowniePackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == BrownieModule.NAME) {
+      BrownieModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+      BrownieModule.NAME to ReactModuleInfo(
+        name = BrownieModule.NAME,
+        className = BrownieModule.NAME,
+        canOverrideExistingModule = false,
+        needsEagerInit = false,
+        isCxxModule = false,
+        isTurboModule = true
+      )
+    )
+  }
+}

package/android/src/main/java/com/callstack/brownie/BrownieStoreBridge.kt

@@ -0,0 +1,116 @@
+package com.callstack.brownie
+
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Kotlin/JNI bridge for interacting with the shared C++ Brownie store runtime.
+ */
+object BrownieStoreBridge {
+  private val storeDidChangeListeners = ConcurrentHashMap<String, (String) -> Unit>()
+
+  init {
+    System.loadLibrary("brownie")
+  }
+
+  /**
+   * Registers a listener for store change notifications emitted from native.
+   *
+   * @return a listener id used to remove this listener.
+   */
+  fun addStoreDidChangeListener(listener: (String) -> Unit): String {
+    val listenerId = UUID.randomUUID().toString()
+    storeDidChangeListeners[listenerId] = listener
+    return listenerId
+  }
+
+  /**
+   * Removes a previously registered store change listener.
+   */
+  fun removeStoreDidChangeListener(listenerId: String) {
+    storeDidChangeListeners.remove(listenerId)
+  }
+
+  /**
+   * Creates and registers a C++ store for [storeKey].
+   */
+  fun registerStore(storeKey: String) {
+    nativeRegisterStore(storeKey)
+  }
+
+  /**
+   * Removes a C++ store for [storeKey].
+   */
+  fun removeStore(storeKey: String) {
+    nativeRemoveStore(storeKey)
+  }
+
+  /**
+   * Sets a single property on a store using JSON payload.
+   */
+  fun setValue(valueJson: String, propKey: String, storeKey: String) {
+    nativeSetValue(valueJson, propKey, storeKey)
+  }
+
+  /**
+   * Gets a single property from a store as JSON.
+   */
+  fun getValue(propKey: String, storeKey: String): String? {
+    return nativeGetValue(propKey, storeKey)
+  }
+
+  /**
+   * Gets the full store snapshot as JSON.
+   */
+  fun getSnapshot(storeKey: String): String? {
+    return nativeGetSnapshot(storeKey)
+  }
+
+  /**
+   * Replaces full store state with the provided JSON payload.
+   */
+  fun setState(stateJson: String, storeKey: String) {
+    nativeSetState(stateJson, storeKey)
+  }
+
+  /**
+   * Installs Brownie JSI bindings into the provided JS runtime.
+   */
+  fun installJSIBindings(runtimePointer: Long) {
+    nativeInstallJSIBindings(runtimePointer)
+  }
+
+  /**
+   * Entry point called from JNI when a store changes in the C++ layer.
+   */
+  @JvmStatic
+  private fun onStoreDidChange(storeKey: String) {
+    storeDidChangeListeners.values.forEach { listener ->
+      listener.invoke(storeKey)
+    }
+  }
+
+  /**
+   * Native bindings implemented in `JNIBrownieStoreBridge.cpp`.
+   */
+  @JvmStatic
+  private external fun nativeInstallJSIBindings(runtimePointer: Long)
+
+  @JvmStatic
+  private external fun nativeRegisterStore(storeKey: String)
+
+  @JvmStatic
+  private external fun nativeRemoveStore(storeKey: String)
+
+  @JvmStatic
+  private external fun nativeSetValue(valueJson: String, propKey: String, storeKey: String)
+
+  @JvmStatic
+  private external fun nativeGetValue(propKey: String, storeKey: String): String?
+
+  @JvmStatic
+  private external fun nativeGetSnapshot(storeKey: String): String?
+
+  @JvmStatic
+  private external fun nativeSetState(stateJson: String, storeKey: String)
+}

package/android/src/main/java/com/callstack/brownie/BrownieStoreDefinition.kt

@@ -0,0 +1,83 @@
+package com.callstack.brownie
+
+import com.google.gson.Gson
+
+/**
+ * Serializer used by [Store] to sync typed Kotlin state with the C++ store as JSON.
+ */
+interface BrownieStoreSerializer<State> {
+  /**
+   * Encodes a typed state object into a JSON string.
+   */
+  fun encode(state: State): String
+
+  /**
+   * Decodes a JSON snapshot from native into a typed state object.
+   */
+  fun decode(snapshotJson: String): State
+}
+
+/**
+ * Immutable description of a store key and its serialization strategy.
+ */
+interface BrownieStoreDefinition<State> {
+  val storeName: String
+  val serializer: BrownieStoreSerializer<State>
+}
+
+private val brownieJson = Gson()
+
+private class BrownieStoreDefinitionImpl<State>(
+  override val storeName: String,
+  override val serializer: BrownieStoreSerializer<State>,
+) : BrownieStoreDefinition<State>
+
+private class JsonBrownieStoreSerializer<State>(
+  private val clazz: Class<State>,
+) : BrownieStoreSerializer<State> {
+  override fun encode(state: State): String = brownieJson.toJson(state)
+
+  override fun decode(snapshotJson: String): State = brownieJson.fromJson(snapshotJson, clazz)
+}
+
+/**
+ * Creates a store definition backed by Gson using a runtime [Class].
+ */
+fun <State : Any> brownieStoreDefinition(
+  storeName: String,
+  clazz: Class<State>,
+): BrownieStoreDefinition<State> = brownieStoreDefinition(storeName, JsonBrownieStoreSerializer(clazz))
+
+/**
+ * Creates a store definition backed by Gson using a reified state type.
+ */
+inline fun <reified State : Any> brownieStoreDefinition(
+  storeName: String,
+): BrownieStoreDefinition<State> = brownieStoreDefinition(storeName, State::class.java)
+
+/**
+ * Creates a store definition with a custom serializer implementation.
+ */
+fun <State> brownieStoreDefinition(
+  storeName: String,
+  serializer: BrownieStoreSerializer<State>,
+): BrownieStoreDefinition<State> = BrownieStoreDefinitionImpl(storeName, serializer)
+
+/**
+ * Creates a store definition from encode/decode lambdas.
+ */
+fun <State> brownieStoreDefinition(
+  storeName: String,
+  encode: (State) -> String,
+  decode: (String) -> State,
+): BrownieStoreDefinition<State> {
+  return brownieStoreDefinition(
+    storeName = storeName,
+    serializer =
+      object : BrownieStoreSerializer<State> {
+        override fun encode(state: State): String = encode(state)
+
+        override fun decode(snapshotJson: String): State = decode(snapshotJson)
+      },
+  )
+}

package/android/src/main/java/com/callstack/brownie/BrownieStoreRegistration.kt

@@ -0,0 +1,55 @@
+package com.callstack.brownie
+
+/**
+ * Registers a new [Store] instance from this definition and the provided initial state.
+ */
+fun <State> BrownieStoreDefinition<State>.register(initialState: State): Store<State> {
+  return Store(initialState, storeName, serializer)
+}
+
+/**
+ * Convenience API that creates a definition with Gson and registers it.
+ */
+fun <State : Any> registerStore(
+  storeName: String,
+  initialState: State,
+  clazz: Class<State>,
+): Store<State> = brownieStoreDefinition(storeName, clazz).register(initialState)
+
+/**
+ * Reified overload of [registerStore].
+ */
+inline fun <reified State : Any> registerStore(
+  storeName: String,
+  initialState: State,
+): Store<State> = registerStore(storeName, initialState, State::class.java)
+
+/**
+ * Registers once per store name and returns null when the store was already registered.
+ *
+ * Idempotency is based on whether a store with this [storeName] currently exists
+ * in [StoreManager], so clearing or removing a store allows registration again
+ * within the same process.
+ */
+fun <State> BrownieStoreDefinition<State>.registerIfNeeded(initialState: () -> State): Store<State>? {
+  return StoreManager.shared.registerIfAbsent(storeName) {
+    register(initialState())
+  }
+}
+
+/**
+ * Convenience API that registers only once for the provided key.
+ */
+fun <State : Any> registerStoreIfNeeded(
+  storeName: String,
+  initialState: () -> State,
+  clazz: Class<State>,
+): Store<State>? = brownieStoreDefinition(storeName, clazz).registerIfNeeded(initialState)
+
+/**
+ * Reified overload of [registerStoreIfNeeded].
+ */
+inline fun <reified State : Any> registerStoreIfNeeded(
+  storeName: String,
+  noinline initialState: () -> State,
+): Store<State>? = registerStoreIfNeeded(storeName, initialState, State::class.java)

package/android/src/main/java/com/callstack/brownie/Store.kt

@@ -0,0 +1,173 @@
+package com.callstack.brownie
+
+import java.util.concurrent.CopyOnWriteArraySet
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.locks.ReentrantLock
+import kotlin.concurrent.withLock
+
+/**
+ * Typed Kotlin facade over a shared C++ Brownie store.
+ *
+ * It keeps local typed state in sync with native snapshots and notifies subscribers on changes.
+ */
+class Store<State>(
+  initialState: State,
+  private val storeKey: String,
+  private val serializer: BrownieStoreSerializer<State>,
+) : AutoCloseable {
+  private val stateLock = ReentrantLock()
+  private val listeners = CopyOnWriteArraySet<(State) -> Unit>()
+  private val disposed = AtomicBoolean(false)
+
+  @Volatile
+  private var _state: State = initialState
+
+  /**
+   * Latest typed state snapshot known on the Kotlin side.
+   */
+  val state: State
+    get() = stateLock.withLock { _state }
+
+  private val bridgeListenerId: String
+
+  init {
+    BrownieStoreBridge.registerStore(storeKey)
+    pushStateToCxx()
+
+    bridgeListenerId =
+      BrownieStoreBridge.addStoreDidChangeListener { updatedStoreKey ->
+        if (updatedStoreKey == storeKey) {
+          rebuildState()
+        }
+      }
+
+    StoreManager.shared.register(this, storeKey)
+  }
+
+  /**
+   * Updates state with [updater] and pushes it to C++.
+   *
+   * Listener notification is triggered via the native storeDidChange callback and [rebuildState]
+   * to keep Kotlin updates consistent with cross-runtime updates.
+   */
+  fun set(updater: (State) -> State) {
+    val newState =
+      stateLock.withLock {
+        _state = updater(_state)
+        _state
+      }
+
+    pushStateToCxx(newState)
+  }
+
+  /**
+   * Replaces state with a concrete value.
+   */
+  fun set(value: State) {
+    set { value }
+  }
+
+  /**
+   * Sets a single property in the underlying C++ store using JSON payload.
+   */
+  fun setValue(property: String, valueJson: String) {
+    BrownieStoreBridge.setValue(valueJson, property, storeKey)
+  }
+
+  /**
+   * Reads a single property from the underlying C++ store as JSON.
+   */
+  fun getValue(property: String): String? = BrownieStoreBridge.getValue(property, storeKey)
+
+  /**
+   * Subscribes to full state updates.
+   *
+   * The listener is called immediately with current state and then on every update.
+   */
+  fun subscribe(onChange: (State) -> Unit): () -> Unit {
+    listeners.add(onChange)
+    onChange(state)
+    return { listeners.remove(onChange) }
+  }
+
+  /**
+   * Releases local listeners and bridge callbacks; called by [StoreManager].
+   */
+  internal fun dispose() {
+    if (!disposed.compareAndSet(false, true)) {
+      return
+    }
+
+    BrownieStoreBridge.removeStoreDidChangeListener(bridgeListenerId)
+    listeners.clear()
+  }
+
+  /**
+   * Closes this store and removes it from [StoreManager].
+   */
+  override fun close() {
+    StoreManager.shared.removeStore(storeKey)
+  }
+
+  /**
+   * Serializes typed state and pushes it to the C++ store.
+   */
+  private fun pushStateToCxx(state: State = this.state) {
+    BrownieStoreBridge.setState(serializer.encode(state), storeKey)
+  }
+
+  /**
+   * Pulls latest snapshot from C++, decodes it, and updates local state.
+   */
+  private fun rebuildState() {
+    val snapshot = BrownieStoreBridge.getSnapshot(storeKey) ?: return
+    val rebuiltState = runCatching { serializer.decode(snapshot) }.getOrNull() ?: return
+
+    stateLock.withLock {
+      _state = rebuiltState
+    }
+
+    notifyListeners(rebuiltState)
+  }
+
+  /**
+   * Notifies all active local subscribers with [state].
+   */
+  private fun notifyListeners(state: State) {
+    listeners.forEach { listener ->
+      listener(state)
+    }
+  }
+}
+
+/**
+ * Subscribes to a selected slice of store state.
+ *
+ * The listener is invoked only when the selected value changes by `!=`.
+ */
+fun <State, Selected> Store<State>.subscribe(
+  selector: (State) -> Selected,
+  onChange: (Selected) -> Unit,
+): () -> Unit {
+  val selectorLock = ReentrantLock()
+  var hasSelection = false
+  var previousSelection: Selected? = null
+
+  return subscribe { state ->
+    val newSelection = selector(state)
+    val shouldNotify =
+      selectorLock.withLock {
+        if (!hasSelection || previousSelection != newSelection) {
+          hasSelection = true
+          previousSelection = newSelection
+          true
+        } else {
+          false
+        }
+      }
+
+    if (shouldNotify) {
+      onChange(newSelection)
+    }
+  }
+}

package/android/src/main/java/com/callstack/brownie/StoreManager.kt

@@ -0,0 +1,93 @@
+package com.callstack.brownie
+
+import java.util.concurrent.locks.ReentrantLock
+import kotlin.concurrent.withLock
+
+/**
+ * Process-wide registry of Kotlin [Store] instances keyed by store name.
+ */
+class StoreManager private constructor() {
+  companion object {
+    /**
+     * Shared singleton used by Brownie runtime and app integrations.
+     */
+    val shared: StoreManager = StoreManager()
+  }
+
+  private val lock = ReentrantLock()
+  private val stores: MutableMap<String, Any> = mutableMapOf()
+
+  /**
+   * Registers a store instance under a key.
+   */
+  fun <State> register(store: Store<State>, key: String) {
+    lock.withLock {
+      check(!stores.containsKey(key)) {
+        "Store with key '$key' is already registered. Remove the previous store first using Store.close() or StoreManager.removeStore(key)"
+      }
+      stores[key] = store
+    }
+  }
+
+  /**
+   * Registers a new store only when [key] is currently absent.
+   *
+   * Returns the created store when registration succeeds, otherwise `null`.
+   * The check and registration are atomic under [lock].
+   */
+  fun <State> registerIfAbsent(key: String, createStore: () -> Store<State>): Store<State>? {
+    return lock.withLock {
+      if (stores.containsKey(key)) {
+        return@withLock null
+      }
+
+      val store = createStore()
+      stores[key] = store
+      store
+    }
+  }
+
+  /**
+   * Retrieves a typed store by key when the runtime state type matches [clazz].
+   */
+  fun <State> store(key: String, clazz: Class<State>): Store<State>? {
+    return lock.withLock {
+      val store = stores[key] as? Store<*> ?: return@withLock null
+      runCatching { clazz.cast(store.state) }.getOrNull() ?: return@withLock null
+      @Suppress("UNCHECKED_CAST")
+      store as Store<State>
+    }
+  }
+
+  /**
+   * Removes a store from the registry and from the native bridge.
+   */
+  fun removeStore(key: String) {
+    val store = lock.withLock {
+      stores.remove(key) as? Store<*>
+    }
+
+    store?.dispose()
+    BrownieStoreBridge.removeStore(key)
+  }
+
+  /**
+   * Removes all registered stores.
+   */
+  fun clear() {
+    val keys = lock.withLock {
+      stores.keys.toList()
+    }
+
+    keys.forEach { key ->
+      removeStore(key)
+    }
+  }
+}
+
+/**
+ * Reified convenience overload for [StoreManager.store].
+ */
+inline fun <reified State : Any> StoreManager.store(key: String): Store<State>? {
+  return store(key, State::class.java)
+}

package/cpp/BrownieStore.cpp

@@ -16,16 +16,18 @@ folly::dynamic BrownieStore::get(const std::string &key) const {
 }
 
 void BrownieStore::set(const std::string &key, folly::dynamic value) {
+  ChangeCallback callback;
   {
     std::lock_guard<std::mutex> lock(mutex_);
     if (!state_.isObject()) {
       state_ = folly::dynamic::object();
     }
     state_[key] = std::move(value);
+    callback = changeCallback_;
   }
 
-  if (changeCallback_) {
-    changeCallback_();
+  if (callback) {
+    callback();
   }
 }
 
@@ -35,13 +37,15 @@ folly::dynamic BrownieStore::getSnapshot() const {
 }
 
 void BrownieStore::setState(folly::dynamic state) {
+  ChangeCallback callback;
   {
     std::lock_guard<std::mutex> lock(mutex_);
     state_ = std::move(state);
+    callback = changeCallback_;
   }
 
-  if (changeCallback_) {
-    changeCallback_();
+  if (callback) {
+    callback();
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callstack/brownie",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "license": "MIT",
   "author": "Oskar Kwaśniewski <oskarkwasniewski@icloud.com>",
   "bin": {
@@ -50,10 +50,16 @@
   "files": [
     "src",
     "lib",
+    "android",
     "ios",
     "cpp",
     "*.podspec",
     "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
     "!**/__tests__",
     "!**/__fixtures__",
     "!**/__mocks__",
@@ -69,7 +75,7 @@
     "react-native": "*"
   },
   "dependencies": {
-    "@callstack/brownfield-cli": "^3.3.0",
+    "@callstack/brownfield-cli": "^3.5.0",
     "ts-morph": "^27.0.2"
   },
   "devDependencies": {
@@ -79,14 +85,14 @@
     "@babel/runtime": "^7.25.0",
     "@react-native/babel-preset": "0.82.1",
     "@react-native/eslint-config": "0.82.1",
-    "@types/node": "^25.0.8",
+    "@types/node": "^25.5.0",
     "@types/react": "^19.1.1",
-    "eslint": "^9.28.0",
-    "globals": "^16.2.0",
+    "eslint": "^9.39.3",
+    "globals": "^17.3.0",
     "import": "^0.0.6",
-    "nodemon": "^3.1.11",
+    "nodemon": "^3.1.14",
     "react-native": "0.82.1",
-    "react-native-builder-bob": "^0.40.17",
+    "react-native-builder-bob": "^0.40.18",
     "typescript": "5.9.3"
   },
   "codegenConfig": {