@shopify/react-native-skia 2.12.0-next.1 → 2.12.0

package/Package.swift

@@ -0,0 +1,117 @@
+// swift-tools-version: 6.0
+//
+// SwiftPM manifest for @shopify/react-native-skia. iOS, Ganesh.
+// Additive: the CocoaPods podspec remains the supported default.
+//
+// React Native 0.87+ references a library that ships its own Package.swift
+// through a symlink at <app>/ios/build/generated/autolinking/libs/<name>, and
+// resolves the relative paths below against that symlink. They are the same
+// for every standard app, because the symlink location is.
+
+import Foundation
+import PackageDescription
+
+// Skia's xcframeworks are ~200MB and are not carried in this package. They come
+// from the react-native-skia-apple-ios npm package, which @shopify/react-native-skia
+// depends on, so a checkout that has installed its dependencies builds offline.
+// Xcode passes the symlink as the package directory, hence resolvingSymlinks.
+let packageRoot = URL(fileURLWithPath: Context.packageDirectory)
+  .resolvingSymlinksInPath().path
+
+let binariesPath = [
+  "../../react-native-skia-apple-ios", // consumer: sibling in node_modules
+  "../../node_modules/react-native-skia-apple-ios", // this monorepo
+]
+.map { "\(packageRoot)/\($0)" }
+.first { FileManager.default.fileExists(atPath: "\($0)/Package.swift") }
+
+guard let binariesPath else {
+  // Reached when the package was skipped at install time (`--omit=optional`,
+  // or a non-Apple `os` filter), which SwiftPM would otherwise report as an
+  // unresolvable dependency path.
+  fatalError(
+    """
+    react-native-skia-apple-ios was not found next to @shopify/react-native-skia. \
+    It ships the prebuilt Skia binaries this package links against. Reinstall \
+    dependencies without --omit=optional, on macOS.
+    """)
+}
+
+let package = Package(
+  name: "ReactNativeSkia",
+  platforms: [.iOS(.v15)],
+  products: [
+    // Autolinking looks this name up verbatim; react-native.config.js pins it.
+    .library(name: "ReactNativeSkia", targets: ["ReactNativeSkia"])
+  ],
+  dependencies: [
+    .package(name: "React-GeneratedCode", path: "../../../ios"),
+    .package(name: "ReactNative", path: "../../../../xcframeworks"),
+    .package(path: binariesPath),
+  ],
+  targets: [
+    .target(
+      name: "ReactNativeSkia",
+      dependencies: [
+        .product(name: "ReactHeaders", package: "ReactNative"),
+        .product(name: "ReactNativeHeaders", package: "ReactNative"),
+        .product(name: "ReactNativeDependenciesHeaders", package: "ReactNative"),
+        .product(name: "ReactAppHeaders", package: "React-GeneratedCode"),
+        .product(name: "react-native-skia-apple-ios", package: "react-native-skia-apple-ios"),
+      ],
+      // apple/ and cpp/ have no common ancestor below the package root, and
+      // .headerSearchPath cannot escape the target path.
+      path: ".",
+      exclude: [
+        "cpp/rnskia/RNDawnWindowContext.cpp", // Graphite only
+        "cpp/rnskia/RNDawnInterop.cpp", // Graphite only
+      ],
+      // Explicit, so SwiftPM never walks node_modules, lib, android, or the
+      // headers-only cpp/skia — which carries x86 AVX skcms sources that
+      // cannot build for arm64.
+      sources: [
+        "apple",
+        "cpp/api",
+        "cpp/jsi",
+        "cpp/rnskia",
+        "cpp/utils",
+        // libskottie.a needs skjson and Apple builds no libskjson archive.
+        // CocoaPods compiles this via its cpp/**/*.cpp glob.
+        "cpp/skia/modules/jsonreader/SkJSONReader.cpp",
+      ],
+      cxxSettings: [
+        // Replaces the podspec's recursive cpp/** glob, which expands to 90.
+        .headerSearchPath("cpp"), // "api/…", "jsi/…", "utils/…"
+        .headerSearchPath("cpp/skia"), // "include/core/…", "modules/…", "src/…"
+        .headerSearchPath("cpp/rnskia"), // apple/ uses bare "RNSkView.h"
+        .headerSearchPath("cpp/utils"), // apple/ uses bare "RNSkLog.h"
+
+        // CocoaPods forces both project-wide; the SwiftPM path defines neither.
+        // Skia's Apple sources still gate on them: without them RNSkiaModule's
+        // legacy branch fails to compile and -getTurboModule: is dropped, so
+        // the JSI bindings never install.
+        .define("RCT_NEW_ARCH_ENABLED", to: "1"),
+        .define("RCT_REMOVE_LEGACY_ARCH", to: "1"),
+
+        .define("SK_METAL", to: "1"),
+        .define("SK_GANESH", to: "1"),
+        .define("SK_IMAGE_READ_PIXELS_DISABLE_LEGACY_API", to: "1"),
+        .define("SK_DISABLE_LEGACY_SHAPER_FACTORY", to: "1"),
+
+        // React's prebuilt C++ ABI is NDEBUG-gated, and Skia derives
+        // SK_RELEASE from it. Omitting either breaks the Release link.
+        .define("DEBUG", .when(configuration: .debug)),
+        .define("NDEBUG", .when(configuration: .release)),
+      ],
+      linkerSettings: [
+        .linkedFramework("MetalKit"),
+        .linkedFramework("AVFoundation"),
+        .linkedFramework("AVKit"),
+        .linkedFramework("CoreMedia"),
+      ]
+    )
+  ],
+  // React Native's headers need C++20, and so does Skia m152: SkMathPriv.h
+  // calls std::countl_zero, std::countr_zero and std::popcount.
+  cxxLanguageStandard: .cxx20
+)

package/android/CMakeLists.txt

@@ -100,8 +100,7 @@ add_library(
         "${PROJECT_SOURCE_DIR}/cpp/rnskia-android/AHardwareBufferUtils.cpp"
         "${PROJECT_SOURCE_DIR}/cpp/rnskia-android/RNSkAndroidVideo.cpp"
 
-        "${PROJECT_SOURCE_DIR}/../cpp/jsi/RuntimeLifecycleMonitor.cpp"
-        "${PROJECT_SOURCE_DIR}/../cpp/jsi/RuntimeAwareCache.cpp"
+        "${PROJECT_SOURCE_DIR}/../cpp/jsi/JSICache.cpp"
         "${PROJECT_SOURCE_DIR}/../cpp/jsi/JsiPromises.cpp"
         "${PROJECT_SOURCE_DIR}/../cpp/jsi/Promise.cpp"
 

package/android/cpp/rnskia-android/RNSkAndroidPlatformContext.h

@@ -63,16 +63,6 @@ public:
 #endif
   }
 
-  std::shared_ptr<WindowContext>
-  makeContextFromNativeSurface(void *surface, int width, int height) override {
-#if defined(SK_GRAPHITE)
-    return DawnContext::getInstance().MakeWindow(surface, width, height);
-#else
-    auto aWindow = reinterpret_cast<ANativeWindow *>(surface);
-    return OpenGLContext::getInstance().MakeWindow(aWindow);
-#endif
-  }
-
   sk_sp<SkImage> makeImageFromNativeBuffer(void *buffer) override {
 #if defined(SK_GRAPHITE)
     return DawnContext::getInstance().MakeImageFromBuffer(buffer);

package/android/src/main/java/com/shopify/reactnative/skia/ViewScreenshotService.java

@@ -19,10 +19,11 @@ import android.widget.ScrollView;
 import androidx.annotation.NonNull;
 import com.facebook.react.bridge.ReactContext;
 import com.facebook.react.bridge.UIManager;
+import com.facebook.react.uimanager.BackgroundStyleApplicator;
 import com.facebook.react.uimanager.UIManagerHelper;
+import com.facebook.react.uimanager.ViewProps;
 import com.facebook.react.views.view.ReactViewGroup;
 
-import java.lang.reflect.Method;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 
@@ -118,17 +119,13 @@ public class ViewScreenshotService {
     }
 
     private static void drawChildren(Canvas canvas, ViewGroup group, Paint paint, float parentOpacity) {
-        // Handle clipping for ReactViewGroup
-        if (group instanceof ReactViewGroup) {
-            try {
-                Class[] cArg = new Class[1];
-                cArg[0] = Canvas.class;
-                Method method = ReactViewGroup.class.getDeclaredMethod("dispatchOverflowDraw", cArg);
-                method.setAccessible(true);
-                method.invoke(group, canvas);
-            } catch (Exception e) {
-                Log.e(TAG, "couldn't invoke dispatchOverflowDraw() on ReactViewGroup", e);
-            }
+        // ReactViewGroup applies `overflow: hidden` / `overflow: scroll` clipping from its
+        // dispatchDraw() override. We never call dispatchDraw() here because children are
+        // walked manually (TextureView / SurfaceView need special handling), so the clip has
+        // to be replicated explicitly, exactly as ReactViewGroup.dispatchDraw() does it.
+        if (group instanceof ReactViewGroup
+                && !ViewProps.VISIBLE.equals(((ReactViewGroup) group).getOverflow())) {
+            BackgroundStyleApplicator.clipToPaddingBox(group, canvas);
         }
         for (int i = 0; i < group.getChildCount(); i++) {
             View child = group.getChildAt(i);

package/apple/RNSkApplePlatformContext.h

@@ -63,9 +63,6 @@ public:
 
   std::shared_ptr<RNSkVideo> createVideo(const std::string &url) override;
 
-  std::shared_ptr<WindowContext>
-  makeContextFromNativeSurface(void *surface, int width, int height) override;
-
   virtual void performStreamOperation(
       const std::string &sourceUri,
       const std::function<void(std::unique_ptr<SkStreamAsset>)> &op) override;

package/apple/RNSkApplePlatformContext.mm

@@ -307,17 +307,6 @@ RNSkApplePlatformContext::createVideo(const std::string &url) {
   return std::make_shared<RNSkAppleVideo>(url, this);
 }
 
-std::shared_ptr<WindowContext>
-RNSkApplePlatformContext::makeContextFromNativeSurface(void *surface, int width,
-                                                       int height) {
-#if defined(SK_GRAPHITE)
-  return DawnContext::getInstance().MakeWindow(surface, width, height);
-#else
-  return MetalContext::getInstance().MakeWindow((__bridge CALayer *)surface,
-                                                width, height);
-#endif
-}
-
 void RNSkApplePlatformContext::raiseError(const std::exception &err) {
   RCTFatal(RCTErrorWithMessage([NSString stringWithUTF8String:err.what()]));
 }

package/cpp/api/JsiSkApi.h

@@ -56,7 +56,6 @@
 #include "JsiSkTypefaceFactory.h"
 #include "JsiSkTypefaceFontProviderFactory.h"
 #include "JsiSkVertices.h"
-#include "JsiSkiaContext.h"
 #include "JsiSkottieFactory.h"
 #include "JsiVideo.h"
 #include "api/recorder/JsiRecorder.h"
@@ -116,10 +115,6 @@ public:
     return JsiVideo::createCtor(getContext())(runtime, thisValue, arguments,
                                               count);
   }
-  JSI_HOST_FUNCTION(Context) {
-    return JsiSkiaContext::createCtor(getContext())(runtime, thisValue,
-                                                    arguments, count);
-  }
   JSI_HOST_FUNCTION(Font) {
     return JsiSkFont::createCtor(getContext())(runtime, thisValue, arguments,
                                                count);
@@ -256,7 +251,6 @@ public:
 
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
     installHostMethod(runtime, prototype, "Video", &JsiSkApi::Video);
-    installHostMethod(runtime, prototype, "Context", &JsiSkApi::Context);
     installHostMethod(runtime, prototype, "getNativeDevice",
                       &JsiSkApi::getNativeDevice);
     installHostMethod(runtime, prototype, "Font", &JsiSkApi::Font);

package/cpp/api/JsiSkFont.h

@@ -135,8 +135,9 @@ public:
   bool isEmbolden() { return getObject()->isEmbolden(); }
 
   std::shared_ptr<JsiSkTypeface> getTypeface() {
-    return std::make_shared<JsiSkTypeface>(
-        getContext(), sk_sp<SkTypeface>(getObject()->getTypeface()));
+    // refTypeface(), not getTypeface(): the wrapper owns what it is handed.
+    return std::make_shared<JsiSkTypeface>(getContext(),
+                                           getObject()->refTypeface());
   }
 
   void setEdging(double edging) {
@@ -161,15 +162,9 @@ public:
 
   void setSize(double size) { getObject()->setSize(size); }
 
-  // The JS API declares booleans here, but the previous implementation read
-  // the arguments with asNumber() — keep accepting numbers.
-  void setEmbolden(double embolden) {
-    getObject()->setEmbolden(static_cast<bool>(embolden));
-  }
+  void setEmbolden(bool embolden) { getObject()->setEmbolden(embolden); }
 
-  void setSubpixel(double subpixel) {
-    getObject()->setSubpixel(static_cast<bool>(subpixel));
-  }
+  void setSubpixel(bool subpixel) { getObject()->setSubpixel(subpixel); }
 
   void setTypeface(std::variant<std::nullptr_t, sk_sp<SkTypeface>> typeface) {
     getObject()->setTypeface(

package/cpp/api/JsiSkMatrix.h

@@ -69,12 +69,14 @@ public:
 
   void postTranslate(double x, double y) { getObject()->postTranslate(x, y); }
 
+  // A missing y means a uniform scale, matching the CanvasKit backend and the
+  // SkMatrix type, where y is optional rather than defaulted to 1.
   void scale(double x, JsiOptional<double> y) {
-    getObject()->preScale(x, y.has_value() ? *y : 1);
+    getObject()->preScale(x, y.has_value() ? *y : x);
   }
 
   void postScale(double x, JsiOptional<double> y) {
-    getObject()->postScale(x, y.has_value() ? *y : 1);
+    getObject()->postScale(x, y.has_value() ? *y : x);
   }
 
   void skew(double x, double y) { getObject()->preSkew(x, y); }

package/cpp/api/JsiSkSVGFactory.h

@@ -116,6 +116,10 @@ private:
     builder.setResourceProvider(provider);
 
     auto svg_dom = builder.make(*stream);
+    if (!svg_dom) {
+      return jsi::Value::null();
+    }
+
     return makeJsiObject(
         runtime, std::make_shared<JsiSkSVG>(getContext(), std::move(svg_dom)));
   }

package/cpp/api/recorder/Convertor.h

@@ -361,13 +361,16 @@ SkM44 getPropertyValue(jsi::Runtime &runtime, const jsi::Value &value) {
         m4.preScale(1, s);
       } else if (key == "skewX") {
         auto angle = value.getProperty(runtime, key.c_str()).asNumber();
-        SkM44 skewX(1, 0, 0, 0, std::tan(angle), 1, 0, 0, 0, 0, 1, 0, 0, 0, 0,
+        // The SkM44 constructor takes its arguments in row-major reading
+        // order, so the shear factor of a horizontal skew belongs in row 0,
+        // where it scales y into x.
+        SkM44 skewX(1, std::tan(angle), 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0,
                     1);
         m4.preConcat(skewX);
 
       } else if (key == "skewY") {
         auto angle = value.getProperty(runtime, key.c_str()).asNumber();
-        SkM44 skewY(1, std::tan(angle), 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0,
+        SkM44 skewY(1, 0, 0, 0, std::tan(angle), 1, 0, 0, 0, 0, 1, 0, 0, 0, 0,
                     1);
         m4.preConcat(skewY);
       } else if (key == "rotate" || key == "rotateZ") {

package/cpp/api/recorder/Drawings.h

@@ -149,6 +149,9 @@ public:
       if (hasStrokeOptions) {
         const auto &stroke = props.stroke.value();
         SkPaint strokePaint;
+        // A default SkPaint is fill-style, and FillPathWithPaint only
+        // outlines a paint that strokes.
+        strokePaint.setStyle(SkPaint::kStroke_Style);
 
         if (stroke.cap.has_value()) {
           strokePaint.setStrokeCap(stroke.cap.value());
@@ -166,11 +169,18 @@ public:
           strokePaint.setStrokeMiter(stroke.miter_limit.value());
         }
 
+        float precision = stroke.precision.value_or(1.0f);
+
         SkPathBuilder resultBuilder;
-        if (!skpathutils::FillPathWithPaint(*p, strokePaint, &resultBuilder)) {
-          throw std::runtime_error("Failed to apply stroke to path");
+        auto ctm = SkMatrix::Scale(precision, precision);
+        if (skpathutils::FillPathWithPaint(*p, strokePaint, &resultBuilder,
+                                           nullptr, ctm)) {
+          pathToUse = std::make_shared<const SkPath>(resultBuilder.snapshot());
+        } else {
+          // The JS player keeps the unstroked path when Path.Stroke returns
+          // null (e.g. a hairline width of 0).
+          pathToUse = std::const_pointer_cast<const SkPath>(p);
         }
-        pathToUse = std::make_shared<const SkPath>(resultBuilder.snapshot());
       } else {
         pathToUse = std::const_pointer_cast<const SkPath>(p);
       }

package/cpp/api/recorder/ImageFilters.h

@@ -135,8 +135,22 @@ private:
     auto sourceAlpha = SkImageFilters::ColorFilter(
         SkColorFilters::Blend(SK_ColorBLACK, SkBlendMode::kSrcIn), nullptr);
 
+    // The shadow is generated outside the shape and then clipped back into it,
+    // so "outside" has to be the complement of the shape's silhouette. Taking
+    // SrcOut against the source graphic itself makes it the complement of the
+    // source's *alpha*: inside a translucent shape 1 - alpha is non-zero, so
+    // the shadow is generated across the whole interior and tints it, no matter
+    // how small the blur and the offset are (issue #2990). Saturating alpha
+    // first keeps the shadow tied to the shape's outline instead of to its
+    // opacity. 255 is the saturation point of an 8-bit alpha channel, so one
+    // unit of coverage is enough to reach 1.
+    static constexpr float kAlphaSaturate[20] = {
+        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 0};
+    auto coverage = SkImageFilters::ColorFilter(
+        SkColorFilters::Matrix(kAlphaSaturate), nullptr);
+
     auto f1 = SkImageFilters::ColorFilter(
-        SkColorFilters::Blend(color, SkBlendMode::kSrcOut), nullptr);
+        SkColorFilters::Blend(color, SkBlendMode::kSrcOut), coverage);
 
     auto f2 = SkImageFilters::Offset(dx, dy, f1);
     auto f3 = SkImageFilters::Blur(sigmaX, sigmaY, SkTileMode::kDecal, f2);

package/cpp/api/recorder/Paint.h

@@ -154,8 +154,15 @@ public:
     }
     ctx->savePaint();
     if (standalone) {
+      // Reset the paint that savePaint() just pushed instead of pushing a
+      // second one: the matching RestorePaintDeclaration pops a single frame,
+      // so an extra push would leave the enclosing group's opacity on the
+      // stack and leak it onto every sibling drawn afterwards. The fresh
+      // paint is anti-aliased to match the TS player, which resets with
+      // Skia.Paint().
       SkPaint freshPaint;
-      ctx->pushPaint(freshPaint);
+      freshPaint.setAntiAlias(true);
+      ctx->getPaint() = freshPaint;
     }
     auto &paint = ctx->getPaint();
     if (props.opacity.has_value()) {

package/cpp/jsi/JSICache.cpp

@@ -0,0 +1,99 @@
+#include "JSICache.h"
+
+#include <iterator>
+#include <memory>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+#include <utility>
+
+namespace RNJsi {
+
+namespace {
+// Hidden global holding the per-runtime cache object. Named so it is
+// obviously ours if it ever shows up in a debugger or heap snapshot.
+constexpr const char *kGlobalName = "__rnskiaJsiCache";
+} // namespace
+
+std::mutex JSICache::_registryMutex;
+std::unordered_map<jsi::Runtime *, std::weak_ptr<JSICache>> JSICache::_registry;
+
+JSICache &JSICache::get(jsi::Runtime &runtime) {
+  {
+    std::lock_guard<std::mutex> lock(_registryMutex);
+    auto it = _registry.find(&runtime);
+    if (it != _registry.end()) {
+      if (auto cache = it->second.lock()) {
+        // The cache is kept alive by `runtime`'s global, so the raw
+        // reference stays valid for as long as the caller may legally use
+        // `runtime` on this thread.
+        return *cache;
+      }
+      // Expired: the runtime that owned this entry is gone and `&runtime` is
+      // a new runtime reusing the address. Fall through and recreate.
+    }
+  }
+  auto cache = getOrCreateOnGlobal(runtime);
+  {
+    std::lock_guard<std::mutex> lock(_registryMutex);
+    // Drop entries of runtimes that are gone so the map does not grow by one
+    // stale pointer per reload / worklet runtime.
+    for (auto it = _registry.begin(); it != _registry.end();) {
+      it = it->second.expired() ? _registry.erase(it) : std::next(it);
+    }
+    _registry[&runtime] = cache;
+  }
+  return *cache;
+}
+
+std::shared_ptr<JSICache> JSICache::getOrCreateOnGlobal(jsi::Runtime &runtime) {
+  auto global = runtime.global();
+  auto existing = global.getProperty(runtime, kGlobalName);
+  if (existing.isObject()) {
+    auto obj = existing.getObject(runtime);
+    if (obj.hasNativeState<JSICache>(runtime)) {
+      return obj.getNativeState<JSICache>(runtime);
+    }
+  }
+  if (!existing.isUndefined()) {
+    // Something else already claimed our global. The most likely cause is two
+    // copies of react-native-skia loaded in one process (each has its own
+    // JSICache type, so the NativeState check above fails). Say so instead of
+    // letting Object.defineProperty throw a bare TypeError on the
+    // non-configurable property.
+    throw std::runtime_error(
+        std::string("react-native-skia: global.") + kGlobalName +
+        " already exists but is not our JSICache. Is react-native-skia "
+        "linked twice, or is another module using this global?");
+  }
+  auto cache = std::make_shared<JSICache>();
+  jsi::Object holder(runtime);
+  holder.setNativeState(runtime, cache);
+  // Non-enumerable, non-writable, non-configurable: JS code must not be able
+  // to drop the holder (which would finalize the cache under our feet).
+  auto objectCtor = global.getPropertyAsObject(runtime, "Object");
+  auto defineProperty =
+      objectCtor.getPropertyAsFunction(runtime, "defineProperty");
+  jsi::Object descriptor(runtime);
+  descriptor.setProperty(runtime, "value", std::move(holder));
+  descriptor.setProperty(runtime, "writable", false);
+  descriptor.setProperty(runtime, "enumerable", false);
+  descriptor.setProperty(runtime, "configurable", false);
+  defineProperty.call(runtime, global,
+                      jsi::String::createFromAscii(runtime, kGlobalName),
+                      descriptor);
+  return cache;
+}
+
+jsi::Object *JSICache::getPrototype(PrototypeKey key) {
+  auto it = _prototypes.find(key);
+  return it == _prototypes.end() ? nullptr : &it->second;
+}
+
+jsi::Object &JSICache::setPrototype(PrototypeKey key, jsi::Object prototype) {
+  auto [it, inserted] = _prototypes.insert_or_assign(key, std::move(prototype));
+  (void)inserted;
+  return it->second;
+}
+
+} // namespace RNJsi

package/cpp/jsi/JSICache.h

@@ -0,0 +1,90 @@
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <memory>
+#include <mutex>
+#include <typeindex>
+#include <unordered_map>
+
+namespace RNJsi {
+
+namespace jsi = facebook::jsi;
+
+/**
+ * Per-runtime store for JSI values that native code wants to keep across
+ * calls (currently: the prototype object of every NativeObject class).
+ *
+ * Ownership model (borrowed from react-native-nitro-modules' JSICache):
+ *
+ * - One JSICache exists per jsi::Runtime. It is attached as the NativeState
+ *   of a hidden object stored on that runtime's `global`, so the RUNTIME owns
+ *   the cache. When the runtime is destroyed the engine finalizes the object,
+ *   ~JSICache runs while the runtime is still alive, and every cached
+ *   jsi::Object is released correctly. Nothing outlives its runtime and
+ *   nothing has to be leaked.
+ *
+ * - Native code reaches the cache through JSICache::get(runtime). A static
+ *   map of std::weak_ptr, keyed by jsi::Runtime*, makes the lookup cheap; the
+ *   pointer is only a map key, never proof that a runtime is alive. If the
+ *   weak_ptr is expired (the runtime that owned it is gone) the entry is
+ *   recreated on the runtime asking for it. This is what makes an in-process
+ *   runtime recreate (expo-updates OTA apply, DevSettings.reload) safe even
+ *   when the new runtime is allocated at the address of the freed one: the
+ *   old cache was destroyed with the old runtime, so the reused address can
+ *   only ever resolve to a fresh cache.
+ *
+ * - The cache itself is not locked: a jsi::Runtime is single-threaded, and
+ *   the cache is only ever touched from its runtime's thread. Only the static
+ *   runtime -> cache map is guarded.
+ *
+ * The same mechanism works for worklet runtimes (Reanimated UI runtime,
+ * createWorkletRuntime, ...); each gets its own JSICache.
+ */
+class JSICache final : public jsi::NativeState {
+public:
+  /**
+   * Key identifying one cached prototype: the C++ type of the NativeObject
+   * subclass (std::type_index(typeid(Derived))), as in Nitro. It prints as
+   * the class name in a debugger.
+   */
+  using PrototypeKey = std::type_index;
+
+  /**
+   * Returns the cache owned by `runtime`, creating it on first use. Must be
+   * called on the runtime's thread.
+   */
+  static JSICache &get(jsi::Runtime &runtime);
+
+  /**
+   * Returns the cached prototype for `key` or nullptr if none was stored.
+   *
+   * The pointer points into `_prototypes`. std::unordered_map never
+   * invalidates pointers/references to elements on insert or rehash (only on
+   * erase of that element, which we never do), so it stays valid for as long
+   * as the runtime does. Do not swap the container for one without that
+   * guarantee (std::vector, absl::flat_hash_map, ...).
+   */
+  jsi::Object *getPrototype(PrototypeKey key);
+
+  /**
+   * Stores (or replaces) the prototype for `key` and returns it.
+   */
+  jsi::Object &setPrototype(PrototypeKey key, jsi::Object prototype);
+
+  JSICache() = default;
+  ~JSICache() override = default;
+  JSICache(const JSICache &) = delete;
+  JSICache &operator=(const JSICache &) = delete;
+
+private:
+  static std::shared_ptr<JSICache> getOrCreateOnGlobal(jsi::Runtime &runtime);
+
+  std::unordered_map<PrototypeKey, jsi::Object> _prototypes;
+
+  // Runtime -> cache. Weak on purpose: the runtime's global owns the cache.
+  static std::mutex _registryMutex;
+  static std::unordered_map<jsi::Runtime *, std::weak_ptr<JSICache>> _registry;
+};
+
+} // namespace RNJsi