react-native-unistyles 3.4.0 → 3.5.0

package/README.md

@@ -12,16 +12,18 @@
 [![platform - ssr](https://img.shields.io/badge/SSR-black?style=for-the-badge&logo=next.js&logoColor=white)](https://nextjs.org/)
 
 
-## Installation
+## Requirements
 
-```shell
-yarn add react-native-unistyles
-```
+- React Native 0.81+ with the New Architecture
+- React 19+
+- Expo SDK 54+ (if you use Expo, development builds only, Expo Go is not supported)
 
-Install dependencies:
+Need support for older React Native versions or the Old Architecture? Use [Unistyles 2.0](https://v2.unistyl.es).
+
+## Installation
 
 ```shell
-yarn add react-native-nitro-modules
+yarn add react-native-unistyles react-native-nitro-modules
 ```
 
 | react-native-unistyles | Minimum react-native-nitro-modules     |
@@ -29,6 +31,8 @@ yarn add react-native-nitro-modules
 | >= 3.0.0               | >= 0.33.9                              |
 | >= 3.1.0               | >= 0.35.0                              |
 | >= 3.2.0               | >= 0.35.2                              |
+| >= 3.3.0               | >= 0.36.1                              |
+| >= 3.4.0               | >= 0.37.1                              |
 
 > **Note:** Since v3.1.0, `react-native-edge-to-edge` is an **optional** dependency. We strongly recommend setting `edgeToEdgeEnabled=true` in your `android/gradle.properties` — it enforces translucent system bars on modals, disables legacy StatusBar hacks, and enables additional React Native core fixes. **Expo SDK 54+** enables this automatically. You can still install `react-native-edge-to-edge` for ecosystem compatibility with libraries like `react-native-bootsplash` or `react-native-permissions`.
 
@@ -39,7 +43,19 @@ Then follow [installation guides](https://unistyl.es/v3/start/getting-started) f
 - [Migration from Unistyles 2.0](https://unistyl.es/v3/start/migration-guide)
 - [Learn how Unistyles 3.0 works](https://unistyl.es/v3/start/how-unistyles-works)
 - [API](https://unistyl.es/v3/references/stylesheet)
-- [Examples](https://unistyl.es/v3/examples/examples)
+- [Tutorial](https://unistyl.es/v3/tutorial/intro)
+- [LLMs](https://unistyl.es/v3/llms/info)
+
+## AI agent skills
+
+This repository ships skills for AI coding agents (Claude Code, Codex, Cursor and others):
+
+- `react-native-unistyles-v3` - setup, theming, responsive styles, variants, web and 3rd party integrations
+- `unistyles-v2-to-v3-migration` - step by step migration from Unistyles 2.0
+
+```shell
+npx skills add jpudysz/react-native-unistyles
+```
 
 ## Features
 - 🚀 Shared core with C++ and JSI bindings

package/android/build.gradle

@@ -18,9 +18,20 @@ def reactNativeArchitectures() {
 }
 
 apply plugin: 'com.android.library'
-apply plugin: 'org.jetbrains.kotlin.android'
+// AGP 9 ships built-in Kotlin support and registers the `kotlin` extension
+// itself. Applying the Kotlin plugin on top of it fails configuration with
+// "Cannot add extension with name 'kotlin'". Only apply it when nothing has
+// registered that extension yet.
+if (project.extensions.findByName('kotlin') == null) {
+    apply plugin: 'org.jetbrains.kotlin.android'
+}
+
 apply from: '../nitrogen/generated/android/unistyles+autolinking.gradle'
 
+// Nitrogen adds its generated Kotlin files to java.srcDirs, which AGP 9 built-in Kotlin
+// doesn't compile. It only compiles Kotlin directories from the kotlin source set.
+android.sourceSets.main.kotlin.srcDirs += ["${project.projectDir}/../nitrogen/generated/android/kotlin"]
+
 def resolveBuildType() {
     Gradle gradle = getGradle()
     String tskReqStr = gradle.getStartParameter().getTaskRequests()['args'].toString()

package/android/src/main/cxx/NativeUnistylesModule.cpp

@@ -31,11 +31,15 @@ void UnistylesModule::registerNatives() {
 }
 
 jni::local_ref<BindingsInstallerHolder::javaobject> UnistylesModule::getBindingsInstaller(jni::alias_ref<UnistylesModule::javaobject> jobj) {
-    auto& runtimeExecutor = jobj->cthis()->_runtimeExecutor;
-    auto& nativePlatform = jobj->cthis()->_nativePlatform;
+    auto* self = jobj->cthis();
+    auto& runtimeExecutor = self->_runtimeExecutor;
+    auto& nativePlatform = self->_nativePlatform;
 
-    return BindingsInstallerHolder::newObjectCxxArgs([&runtimeExecutor, &nativePlatform](jsi::Runtime& rt) {
+    return BindingsInstallerHolder::newObjectCxxArgs([self, &runtimeExecutor, &nativePlatform](jsi::Runtime& rt) {
         // function is called on: first init and every live reload
+        // newest runtime owns the registry, previous runtime's state is kept until it releases ownership
+        self->_generation = core::UnistylesRegistry::get().takeOwnership();
+
         // check if this is live reload, if so let's replace UnistylesRuntime with new runtime
         auto hasUnistylesRuntime = HybridObjectRegistry::hasHybridObject("UnistylesRuntime");
 
@@ -52,7 +56,7 @@ jni::local_ref<BindingsInstallerHolder::javaobject> UnistylesModule::getBindings
         };
 
         // init hybrids
-        auto unistylesRuntime = std::make_shared<HybridUnistylesRuntime>(nativePlatform, runOnJSThread);
+        auto unistylesRuntime = std::make_shared<HybridUnistylesRuntime>(nativePlatform, runOnJSThread, self->_generation);
         auto styleSheet = std::make_shared<HybridStyleSheet>(unistylesRuntime);
 
         HybridObjectRegistry::registerHybridObjectConstructor("UnistylesRuntime", [unistylesRuntime]() -> std::shared_ptr<HybridObject>{

package/android/src/main/cxx/NativeUnistylesModule.h

@@ -29,7 +29,10 @@ struct UnistylesModule : public jni::HybridClass<UnistylesModule> {
         jni::alias_ref<JHybridNativePlatformSpec::JavaPart> nativePlatform
     );
     static void invalidateNative(jni::alias_ref<jhybridobject> jThis) {
-        core::UnistylesRegistry::get().destroy();
+        auto* self = jThis->cthis();
+
+        // releases this runtime's state, also when a newer runtime already replaced it
+        core::UnistylesRegistry::get().releaseOwnership(self->_generation);
     }
 
     static jni::local_ref<BindingsInstallerHolder::javaobject> getBindingsInstaller(jni::alias_ref<UnistylesModule::javaobject> jThis);
@@ -37,6 +40,7 @@ struct UnistylesModule : public jni::HybridClass<UnistylesModule> {
 private:
     RuntimeExecutor _runtimeExecutor;
     std::shared_ptr<HybridNativePlatformSpec> _nativePlatform;
+    uint64_t _generation = 0;
 };
 
 }

package/components/native/ActivityIndicator/package.json

@@ -2,5 +2,5 @@
   "main": "../../../lib/commonjs/components/native/ActivityIndicator.js",
   "module": "../../../lib/module/components/native/ActivityIndicator.js",
   "browser": "../../../lib/module/components/native/ActivityIndicator.js",
-  "react-native": "../../../src/components/native/ActivityIndicator.tsx"
+  "react-native": "../../../src/components/native/ActivityIndicator.native.tsx"
 }

package/cxx/common/UnistylesConstants.h

@@ -12,5 +12,6 @@ static const std::string EXOTIC_STYLE_KEY = "_exotic";
 static const std::string ARGUMENTS = "__uni__args";
 static const std::string GET_STYLES = "uni__getStyles";
 static const std::string UNDEFINED_MARKER = "__unistyles_undefined__";
+static const std::string RUNTIME_REPLACED_ERROR = "Unistyles: this runtime was replaced (reload in progress)";
 
 }

package/cxx/converters/TransformOriginConverter.cpp

@@ -1,13 +1,117 @@
 #include "TransformOriginConverter.h"
 
+#include <cxxreact/ReactNativeVersion.h>
+
+// facebook::react::parseUnprocessedTransformOriginString was introduced in
+// React Native 0.85, while conversions.h is available in every supported
+// version, so the include alone is not enough to detect the parser.
 #if defined(RN_SERIALIZABLE_STATE) &&                                          \
+    (REACT_NATIVE_VERSION_MAJOR > 0 || REACT_NATIVE_VERSION_MINOR >= 85) &&    \
     __has_include(<react/renderer/components/view/conversions.h>)
 #include <react/renderer/components/view/conversions.h>
 #define UNISTYLES_HAS_RN_TRANSFORM_ORIGIN_PARSER 1
+#elif defined(RN_SERIALIZABLE_STATE)
+#include <algorithm>
+#include <cctype>
+#include <cstdlib>
+#include <regex>
+#define UNISTYLES_HAS_TRANSFORM_ORIGIN_FALLBACK 1
 #endif
 
 namespace margelo::nitro::unistyles::converters {
 
+#ifdef UNISTYLES_HAS_TRANSFORM_ORIGIN_FALLBACK
+namespace {
+
+// Port of React Native's processTransformOrigin.js. Android forwards raw props
+// to the view manager, which expects the processed [x, y, z] array, so a string
+// must not reach it. Returns null (default origin) for an invalid value.
+folly::dynamic processTransformOriginString(const std::string &value) {
+  static const std::regex tokenRegex(
+      "(top|bottom|left|right|center|\\d+(?:%|px)|0)", std::regex::icase);
+  constexpr size_t INDEX_X = 0;
+  constexpr size_t INDEX_Y = 1;
+  constexpr size_t INDEX_Z = 2;
+
+  auto toLower = [](std::string token) {
+    std::transform(token.begin(), token.end(), token.begin(),
+                   [](unsigned char c) { return std::tolower(c); });
+
+    return token;
+  };
+
+  folly::dynamic result = folly::dynamic::array("50%", "50%", 0);
+  size_t index = INDEX_X;
+  auto it = std::sregex_iterator(value.begin(), value.end(), tokenRegex);
+  const auto end = std::sregex_iterator();
+
+  for (; it != end; ++it) {
+    if (index > INDEX_Z) {
+      return nullptr;
+    }
+
+    auto token = toLower(it->str());
+    auto nextIndex = index + 1;
+
+    if (token == "left" || token == "right") {
+      if (index != INDEX_X) {
+        return nullptr;
+      }
+
+      result[INDEX_X] = token == "left" ? folly::dynamic(0) : folly::dynamic("100%");
+    } else if (token == "top" || token == "bottom") {
+      if (index == INDEX_Z) {
+        return nullptr;
+      }
+
+      result[INDEX_Y] = token == "top" ? folly::dynamic(0) : folly::dynamic("100%");
+
+      // [ center | left | right ] after a vertical keyword in the first place
+      if (index == INDEX_X) {
+        if (++it == end) {
+          break;
+        }
+
+        auto horizontal = toLower(it->str());
+
+        if (horizontal == "left") {
+          result[INDEX_X] = 0;
+        } else if (horizontal == "right") {
+          result[INDEX_X] = "100%";
+        } else if (horizontal == "center") {
+          result[INDEX_X] = "50%";
+        } else {
+          return nullptr;
+        }
+
+        nextIndex = INDEX_Z;
+      }
+    } else if (token == "center") {
+      if (index == INDEX_Z) {
+        return nullptr;
+      }
+
+      result[index] = "50%";
+    } else if (token.back() == '%') {
+      if (index == INDEX_Z) {
+        return nullptr;
+      }
+
+      result[index] = token;
+    } else {
+      // 0 or <digits>px
+      result[index] = std::strtod(token.c_str(), nullptr);
+    }
+
+    index = nextIndex;
+  }
+
+  return result;
+}
+
+} // namespace
+#endif
+
 bool isTransformOriginPropName(const std::string &propertyName) {
   return propertyName == "transformOrigin";
 }
@@ -25,6 +129,8 @@ parseTransformOriginString(const std::string &transformOriginString) {
   }
 
   return static_cast<folly::dynamic>(transformOrigin);
+#elif defined(UNISTYLES_HAS_TRANSFORM_ORIGIN_FALLBACK)
+  return processTransformOriginString(transformOriginString);
 #else
   return std::nullopt;
 #endif

package/cxx/core/StyleSheetRegistry.cpp

@@ -4,15 +4,15 @@
 using namespace margelo::nitro::unistyles::core;
 using namespace facebook;
 
-std::shared_ptr<StyleSheet> StyleSheetRegistry::addStyleSheetFromValue(jsi::Runtime& rt, jsi::Object rawStyleSheet) {
+std::shared_ptr<StyleSheet> StyleSheetRegistry::addStyleSheetFromValue(jsi::Runtime& rt, uint64_t generation, jsi::Object rawStyleSheet) {
     if (rawStyleSheet.isFunction(rt)) {
-        return this->addFromFunction(rt, rawStyleSheet.asFunction(rt));
+        return this->addFromFunction(rt, generation, rawStyleSheet.asFunction(rt));
     }
 
-    return this->addFromObject(rt, std::move(rawStyleSheet));
+    return this->addFromObject(rt, generation, std::move(rawStyleSheet));
 }
 
-std::shared_ptr<StyleSheet> StyleSheetRegistry::addFromFunction(jsi::Runtime& rt, jsi::Function styleSheetFn) {
+std::shared_ptr<StyleSheet> StyleSheetRegistry::addFromFunction(jsi::Runtime& rt, uint64_t generation, jsi::Function styleSheetFn) {
     auto numberOfArgs = styleSheetFn.getProperty(rt, "length").getNumber();
 
     helpers::assertThat(rt, numberOfArgs <= 2, "StyleSheet.create expected up to 2 arguments.");
@@ -23,20 +23,20 @@ std::shared_ptr<StyleSheet> StyleSheetRegistry::addFromFunction(jsi::Runtime& rt
     if (numberOfArgs == 0) {
         auto staticStyleSheet = styleSheetFn.call(rt).asObject(rt);
 
-        return registry.addStyleSheet(rt, core::StyleSheetType::Static, std::move(staticStyleSheet));
+        return registry.addStyleSheet(rt, generation, core::StyleSheetType::Static, std::move(staticStyleSheet));
     }
 
     // stylesheet depends only on theme
     if (numberOfArgs == 1) {
-        return registry.addStyleSheet(rt, core::StyleSheetType::Themable, std::move(styleSheetFn));
+        return registry.addStyleSheet(rt, generation, core::StyleSheetType::Themable, std::move(styleSheetFn));
     }
 
     // stylesheet depends on theme and mini runtime
-    return registry.addStyleSheet(rt, core::StyleSheetType::ThemableWithMiniRuntime, std::move(styleSheetFn));
+    return registry.addStyleSheet(rt, generation, core::StyleSheetType::ThemableWithMiniRuntime, std::move(styleSheetFn));
 }
 
-std::shared_ptr<StyleSheet> StyleSheetRegistry::addFromObject(jsi::Runtime& rt, jsi::Object rawStyleSheet) {
+std::shared_ptr<StyleSheet> StyleSheetRegistry::addFromObject(jsi::Runtime& rt, uint64_t generation, jsi::Object rawStyleSheet) {
     auto& registry = UnistylesRegistry::get();
 
-    return registry.addStyleSheet(rt, core::StyleSheetType::Static, std::move(rawStyleSheet));
+    return registry.addStyleSheet(rt, generation, core::StyleSheetType::Static, std::move(rawStyleSheet));
 }

package/cxx/core/StyleSheetRegistry.h

@@ -16,11 +16,11 @@ struct StyleSheetRegistry {
     StyleSheetRegistry(const StyleSheetRegistry&) = delete;
     StyleSheetRegistry(StyleSheetRegistry&&) = delete;
 
-    virtual std::shared_ptr<StyleSheet> addStyleSheetFromValue(jsi::Runtime& rt, jsi::Object rawStyleSheet);
+    virtual std::shared_ptr<StyleSheet> addStyleSheetFromValue(jsi::Runtime& rt, uint64_t generation, jsi::Object rawStyleSheet);
 
 private:
-    virtual std::shared_ptr<StyleSheet> addFromFunction(jsi::Runtime& rt, jsi::Function styleSheetFn);
-    virtual std::shared_ptr<StyleSheet> addFromObject(jsi::Runtime& rt, jsi::Object rawStyleSheet);
+    virtual std::shared_ptr<StyleSheet> addFromFunction(jsi::Runtime& rt, uint64_t generation, jsi::Function styleSheetFn);
+    virtual std::shared_ptr<StyleSheet> addFromObject(jsi::Runtime& rt, uint64_t generation, jsi::Object rawStyleSheet);
 };
 
 }

package/cxx/core/UnistyleWrapper.h

@@ -157,7 +157,19 @@ inline static jsi::Value objectFromUnistyle(jsi::Runtime& rt, std::shared_ptr<Hy
         [unistyleID = unistyle->unid, unistylesRuntime, variants, parsedArguments](jsi::Runtime &rt, const jsi::Value &thisValue, const jsi::Value *args, size_t count
     ) {
         auto& registry = UnistylesRegistry::get();
-        auto unistyle = registry.getUnistyleById(unistyleID);
+        // ids repeat across runtimes, so a replaced runtime can't look up its unistyle anymore
+        auto unistyle = unistylesRuntime->ownsRegistry()
+            ? registry.getUnistyleById(unistyleID)
+            : nullptr;
+
+        // the unistyle may have been unregistered while this call was in flight,
+        // eg. during a reload while the outgoing runtime still executes queued work
+        if (unistyle == nullptr) {
+            throw jsi::JSError(rt, R"(Unistyles: Style is no longer registered!
+
+You likely accessed a style while the runtime was being torn down (eg. during a reload).)");
+        }
+
         auto scopedTheme = registry.getScopedTheme();
         parser::Parser parser(unistylesRuntime);
 

package/cxx/core/UnistylesRegistry.cpp

@@ -9,7 +9,13 @@ using namespace facebook::react;
 
 std::atomic<int> core::UnistylesRegistry::_nextStyleSheetTag{0};
 
-void core::UnistylesRegistry::registerTheme(jsi::Runtime& rt, std::string name, jsi::Value& theme) {
+void core::UnistylesRegistry::registerTheme(jsi::Runtime& rt, uint64_t generation, std::string name, jsi::Value& theme) {
+    std::lock_guard<std::mutex> lock(this->_ownershipMutex);
+
+    if (!this->isCurrent(generation)) {
+        throw std::runtime_error(helpers::RUNTIME_REPLACED_ERROR);
+    }
+
     auto& state = this->getState();
 
     state._jsThemes.emplace(name, std::move(theme));
@@ -46,7 +52,7 @@ void core::UnistylesRegistry::createState() {
     this->_state = std::make_unique<UnistylesState>();
 }
 
-void core::UnistylesRegistry::updateTheme(jsi::Runtime& rt, std::string& themeName, jsi::Function&& callback) {
+void core::UnistylesRegistry::updateTheme(jsi::Runtime& rt, uint64_t generation, std::string& themeName, jsi::Function&& callback) {
     auto& state = this->getState();
     auto it = state._jsThemes.find(themeName);
 
@@ -56,25 +62,38 @@ void core::UnistylesRegistry::updateTheme(jsi::Runtime& rt, std::string& themeNa
 
     helpers::assertThat(rt, result.isObject(), "Unistyles: Returned theme is not an object. Please check your updateTheme function.");
 
-    it->second = result.asObject(rt);
+    auto theme = result.asObject(rt);
+    std::lock_guard<std::mutex> lock(this->_ownershipMutex);
+
+    if (!this->isCurrent(generation)) {
+        throw std::runtime_error(helpers::RUNTIME_REPLACED_ERROR);
+    }
+
+    it->second = std::move(theme);
 }
 
 void core::UnistylesRegistry::linkShadowNodeWithUnistyle(
     jsi::Runtime& rt,
+    uint64_t generation,
     const std::shared_ptr<const ShadowNodeFamily>& shadowNodeFamily,
     std::vector<std::shared_ptr<UnistyleData>>& unistylesData,
     std::optional<folly::dynamic> initialScopedUpdate
 ) {
     // released after unlocking, so a family destructor never runs within the lock
     ReleasedFamilies releasedFamilies;
+    std::lock_guard<std::mutex> lock(this->_ownershipMutex);
+
+    if (!this->isCurrent(generation)) {
+        return;
+    }
 
     this->trafficController.withLock([this, &unistylesData, &shadowNodeFamily, &initialScopedUpdate, &releasedFamilies](){
         auto family = shadowNodeFamily.get();
         auto it = this->_shadowRegistry.find(family);
 
         // Clear suspension state if this family was previously suspended
+        // native props stay, they hold values from theme changes that React doesn't know about
         if (it != this->_shadowRegistry.end() && it->second.isSuspended) {
-            shadow::resetNativeProps(family);
             // Clear old registry entries to prevent stale UnistyleData accumulation
             // and any stale traffic controller entry (e.g. from a theme change during suspension)
             this->forgetFamilyUnsafe(family, releasedFamilies);
@@ -183,7 +202,13 @@ bool core::UnistylesRegistry::isSuspended(const ShadowNodeFamily* family) const
     return it != this->_shadowRegistry.end() && it->second.isSuspended;
 }
 
-std::shared_ptr<core::StyleSheet> core::UnistylesRegistry::addStyleSheet(jsi::Runtime& rt, core::StyleSheetType type, jsi::Object&& rawValue) {
+std::shared_ptr<core::StyleSheet> core::UnistylesRegistry::addStyleSheet(jsi::Runtime& rt, uint64_t generation, core::StyleSheetType type, jsi::Object&& rawValue) {
+    std::lock_guard<std::mutex> lock(this->_ownershipMutex);
+
+    if (!this->isCurrent(generation)) {
+        throw std::runtime_error(helpers::RUNTIME_REPLACED_ERROR);
+    }
+
     int tag = _nextStyleSheetTag.fetch_add(1);
 
     auto sheet = std::make_shared<core::StyleSheet>(tag, type, std::move(rawValue));
@@ -335,26 +360,85 @@ void core::UnistylesRegistry::setScopedTheme(std::optional<std::string> themeNam
     this->_scopedTheme = std::move(themeName);
 }
 
-void core::UnistylesRegistry::destroy() {
-    // called when module is invalidated, before React Native destroys the runtime
-    // pins must be released now, as families hold JS handles that can't outlive the runtime
-    ReleasedFamilies releasedFamilies;
+uint64_t core::UnistylesRegistry::takeOwnership() {
+    std::lock_guard<std::mutex> lock(this->_ownershipMutex);
+    auto previousGeneration = this->_generation.load();
 
-    this->trafficController.withLock([this, &releasedFamilies](){
-        for (auto& [_, linkedFamily] : this->_shadowRegistry) {
-            releasedFamilies.emplace_back(std::move(linkedFamily.family));
-        }
+    if (previousGeneration != 0) {
+        this->_replacedStates[previousGeneration] = this->takeOwnedState();
+    }
 
-        for (auto& [_, pendingUpdate] : this->trafficController.takeUpdates()) {
-            releasedFamilies.emplace_back(std::move(pendingUpdate.family));
+    this->_generation.store(++this->_lastGeneration);
+
+    return this->_lastGeneration;
+}
+
+void core::UnistylesRegistry::releaseOwnership(uint64_t generation) {
+    // called when module is invalidated, before React Native destroys the runtime
+    // declared before the lock, so jsi values and pins are released after unlocking
+    OwnedState releasedState;
+
+    {
+        std::lock_guard<std::mutex> lock(this->_ownershipMutex);
+
+        if (this->isCurrent(generation)) {
+            releasedState = this->takeOwnedState();
+            this->_generation.store(0);
+        } else if (auto it = this->_replacedStates.find(generation); it != this->_replacedStates.end()) {
+            releasedState = std::move(it->second);
+            this->_replacedStates.erase(it);
         }
+    }
 
-        this->_shadowRegistry.clear();
+    for (auto& [_, styleSheet] : releasedState.styleSheets) {
+        styleSheet->unistyles.clear();
+    }
+}
+
+core::UnistylesRegistry::OwnedState core::UnistylesRegistry::takeOwnedState() {
+    OwnedState ownedState;
+
+    this->trafficController.withLock([this, &ownedState](){
+        ownedState.shadowRegistry = std::exchange(this->_shadowRegistry, {});
+        ownedState.updates = this->trafficController.takeUpdates();
         this->_sweepThreshold = MIN_SWEEP_THRESHOLD;
     });
 
-    this->_state.reset();
-    this->_styleSheetRegistry.clear();
+    ownedState.styleSheets = std::exchange(this->_styleSheetRegistry, {});
+    ownedState.state = std::move(this->_state);
     this->_scopedTheme = std::nullopt;
+    this->_committedTags.clear();
     _nextStyleSheetTag.store(0);
+
+    return ownedState;
+}
+
+std::vector<core::LinkedFamilySnapshot> core::UnistylesRegistry::getLinkedFamiliesSnapshot() {
+    std::vector<LinkedFamilySnapshot> snapshot;
+
+    this->trafficController.withLock([this, &snapshot](){
+        snapshot.reserve(this->_shadowRegistry.size());
+
+        for (const auto& [_, linkedFamily] : this->_shadowRegistry) {
+            const bool isOwnedOnlyByUnistyles = this->isOwnedOnlyByUnistyles(linkedFamily);
+
+            snapshot.push_back({linkedFamily.family, linkedFamily.unistyles, linkedFamily.isSuspended, isOwnedOnlyByUnistyles});
+        }
+    });
+
+    return snapshot;
+}
+
+size_t core::UnistylesRegistry::getPendingUpdatesCount() {
+    return this->trafficController.withLock([this](){
+        return this->trafficController.getUpdatesCount();
+    });
+}
+
+void core::UnistylesRegistry::setCommittedTags(std::vector<Tag>&& tags) {
+    this->_committedTags = std::move(tags);
+}
+
+std::vector<Tag> core::UnistylesRegistry::takeCommittedTags() {
+    return std::exchange(this->_committedTags, {});
 }

package/cxx/core/UnistylesRegistry.h

@@ -2,6 +2,7 @@
 
 #include "set"
 #include <atomic>
+#include <mutex>
 #include <jsi/jsi.h>
 #include <folly/dynamic.h>
 #include <react/renderer/uimanager/UIManager.h>
@@ -29,6 +30,13 @@ struct LinkedFamily {
     bool isSuspended = false;
 };
 
+struct LinkedFamilySnapshot {
+    std::shared_ptr<const ShadowNodeFamily> family;
+    std::vector<std::shared_ptr<UnistyleData>> unistyles;
+    bool isSuspended = false;
+    bool isOwnedOnlyByUnistyles = false;
+};
+
 struct UnistylesRegistry: public StyleSheetRegistry {
     static UnistylesRegistry& get();
 
@@ -37,20 +45,20 @@ struct UnistylesRegistry: public StyleSheetRegistry {
 
     bool shouldUsePointsForBreakpoints = false;
 
-    void registerTheme(jsi::Runtime& rt, std::string name, jsi::Value& theme);
+    void registerTheme(jsi::Runtime& rt, uint64_t generation, std::string name, jsi::Value& theme);
     void registerBreakpoints(std::vector<std::pair<std::string, double>>& sortedBreakpoints);
     void setPrefersAdaptiveThemes(bool prefersAdaptiveThemes);
     void setInitialThemeName(std::string themeName);
-    void updateTheme(jsi::Runtime& rt, std::string& themeName, jsi::Function&& callback);
+    void updateTheme(jsi::Runtime& rt, uint64_t generation, std::string& themeName, jsi::Function&& callback);
 
     UnistylesState& getState();
     void createState();
     std::vector<std::shared_ptr<core::StyleSheet>> getStyleSheetsToRefresh(std::vector<UnistyleDependency>& unistylesDependencies);
-    void linkShadowNodeWithUnistyle(jsi::Runtime& rt, const std::shared_ptr<const ShadowNodeFamily>& shadowNodeFamily, std::vector<std::shared_ptr<UnistyleData>>& unistylesData, std::optional<folly::dynamic> initialScopedUpdate = std::nullopt);
+    void linkShadowNodeWithUnistyle(jsi::Runtime& rt, uint64_t generation, const std::shared_ptr<const ShadowNodeFamily>& shadowNodeFamily, std::vector<std::shared_ptr<UnistyleData>>& unistylesData, std::optional<folly::dynamic> initialScopedUpdate = std::nullopt);
     void unlinkShadowNodeWithUnistyles(const ShadowNodeFamily*);
     void suspendShadowNode(const ShadowNodeFamily*);
     bool isSuspended(const ShadowNodeFamily*) const noexcept;
-    std::shared_ptr<core::StyleSheet> addStyleSheet(jsi::Runtime& rt, core::StyleSheetType type, jsi::Object&& rawValue);
+    std::shared_ptr<core::StyleSheet> addStyleSheet(jsi::Runtime& rt, uint64_t generation, core::StyleSheetType type, jsi::Object&& rawValue);
     DependencyMap buildDependencyMap(std::vector<UnistyleDependency>& deps);
     void shadowLeafUpdateFromUnistyle(jsi::Runtime& rt, Unistyle::Shared unistyle, jsi::Value& maybePressableId);
     // call it only within trafficController.withLock!
@@ -60,13 +68,36 @@ struct UnistylesRegistry: public StyleSheetRegistry {
     void removeDuplicatedUnistyles(const ShadowNodeFamily* shadowNodeFamily, std::vector<core::Unistyle::Shared>& unistyles);
     void setScopedTheme(std::optional<std::string> themeName);
     core::Unistyle::Shared getUnistyleById(std::string unistyleID);
-    void destroy();
+    std::vector<LinkedFamilySnapshot> getLinkedFamiliesSnapshot();
+    size_t getPendingUpdatesCount();
+    void setCommittedTags(std::vector<Tag>&& tags);
+    std::vector<Tag> takeCommittedTags();
+
+    // newest installed runtime owns the registry, generation 0 means no owner
+    // previous runtime's state is kept aside until it releases ownership, as it may still run JS
+    uint64_t takeOwnership();
+    void releaseOwnership(uint64_t generation);
+
+    inline bool isCurrent(uint64_t generation) const noexcept {
+        return generation != 0 && generation == this->_generation.load();
+    }
 
 private:
     using ReleasedFamilies = std::vector<std::shared_ptr<const ShadowNodeFamily>>;
 
+    struct OwnedState {
+        std::unordered_map<const ShadowNodeFamily*, LinkedFamily> shadowRegistry;
+        shadow::PinnedShadowLeafUpdates updates;
+        std::unordered_map<int, std::shared_ptr<core::StyleSheet>> styleSheets;
+        std::unique_ptr<UnistylesState> state;
+    };
+
     UnistylesRegistry() = default;
 
+    // call it only within _ownershipMutex!
+    // destructs nothing, so it can run on the next runtime's thread
+    OwnedState takeOwnedState();
+
     // call it only within trafficController.withLock!
     // pins are moved to releasedFamilies, so they can be released after unlocking
     void forgetFamilyUnsafe(const ShadowNodeFamily* shadowNodeFamily, ReleasedFamilies& releasedFamilies);
@@ -77,12 +108,18 @@ private:
 
     static constexpr size_t MIN_SWEEP_THRESHOLD = 64;
 
+    // lock order is _ownershipMutex -> trafficController, never call JS within
+    std::mutex _ownershipMutex;
+    std::atomic<uint64_t> _generation{0};
+    uint64_t _lastGeneration = 0;
+    std::unordered_map<uint64_t, OwnedState> _replacedStates{};
     static std::atomic<int> _nextStyleSheetTag;
     std::optional<std::string> _scopedTheme{};
     std::unique_ptr<UnistylesState> _state{};
     std::unordered_map<int, std::shared_ptr<core::StyleSheet>> _styleSheetRegistry{};
     std::unordered_map<const ShadowNodeFamily*, LinkedFamily> _shadowRegistry{};
     size_t _sweepThreshold = MIN_SWEEP_THRESHOLD;
+    std::vector<Tag> _committedTags{};
 };
 
 inline UnistylesRegistry& UnistylesRegistry::get() {