feat!: run on react-native-worklets instead of react-native-worklets-core

[eduardoborges]

Continues #327 by @hannojg: drops react-native-worklets-core and runs on react-native-worklets, the worklet runtime that ships with Reanimated 4. Opened as a draft because everything below was verified on simulators and emulators only.

What changes for users

• Peer dependencies are react-native-worklets >= 0.12 and react-native-reanimated >= 4. The react-native-worklets-core patch and its Babel plugin go away; apps use the react-native-worklets/plugin they already have for Reanimated.
• Reanimated shared values are accepted directly by useApplyTransformations, lights, Camera and the rest. useSyncSharedValue and useDerivedValue are removed, since Reanimated's own useSharedValue and useDerivedValue work as they are.
• useWorkletCallback returns a JS function that schedules the worklet on the Filament runtime and resolves with the result. It cannot be captured inside another worklet or handed to native callbacks; pass a plain 'worklet' function there. The PhysicsCoin example was doing exactly that with its collision callback.
• RenderableManager.destroyEntity() is new. Entities from createPlane, createImageBackgroundShape and createDebugCubeWireframe were never destroyed, and releasing their material hit a Filament precondition abort. BackgroundImage and DebugBox clean up after themselves now, and the material deleters detach any renderable that still uses an instance.
• Android compiles with the app's ndkVersion (AGP 9 defaults to NDK 28, whose libc++ fails to dlopen next to React Native's NDK 27 build) and as C++20.
• The getting started, Reanimated and transformation docs are rewritten for the new setup.

How it works

The Filament runtime is a regular react-native-worklets runtime created from JS with createWorkletRuntime, backed by an AsyncQueueUI whose scheduler forwards jobs to the render thread. Its __globalDispatcher runs jobs under the runtime lock. Every native entry into that runtime (frame callbacks, promise resolution, shared value listeners) takes the react-native-worklets runtime mutex first. Hot reload, serializables and shared value reads touch the runtime from other threads, and Hermes' reentrancy check traps otherwise.

Reanimated only allows shared value listeners on the UI runtime, so useSharedValueListener registers there and forwards changes to the Filament runtime by listener id. State shared across runtimes (surface liveness, animator crossfade, last applied transform) lives in createSynchronizable values.

Two Android details worth knowing while reviewing:

• libc++ on Android compares type_info by pointer, and typeinfo for worklets::AsyncQueue is a weak symbol with one copy per .so. A dynamic_pointer_cast across libraries then fails depending on dlopen order, so instead of subclassing AsyncQueue we hand react-native-worklets an AsyncQueueUI with a custom UIScheduler.
• Hermes finalizes HybridObjects on its GC thread. A wrapper holding the last reference to a Filament resource then calls JDispatcher from a thread that is not attached to the JVM. JDispatcher now wraps its JNI calls in jni::ThreadScope::WithClassLoader, like the other native finalizers already did.

withCleanupScope used to wait on InteractionManager, which React Native 0.87 removed from core. It now defers by one tick. The shorter delay exposed three teardown races that were already in the code base: a material destroyed while a renderable still used it, the recorder surface freed before Filament ran createSwapChain, and the GC thread JNI call above. All three are fixed here.

Testing

• Example app on React Native 0.83.1, iPhone 17 Pro simulator and an arm64 Android emulator with host GPU. A throwaway React Native 0.87.1 app with the New Architecture, Reanimated 4.6.0 and react-native-worklets 0.12.1 on both platforms, including both library load orders on Android.
• The example has a new Stress screen that pushes and pops all 17 example scenes. Both platforms pass 3 rounds at 1.5 s per screen and 5 rounds at 250 ms per screen (scenes unmount while their assets are still loading) without a crash. On iOS the fast run created and destroyed 160 engines.
• Checked by hand: GLB with IBL, shared value rotation, animator crossfade, and in the 0.87 app drag with inertia plus device tilt through useAnimatedSensor.

Not done: no physical device yet. Under the 250 ms loop the Android emulator logs Java OutOfMemoryError while loading assets, without crashing; model buffers are only freed once Hermes collects the wrapper, so having useModel release its buffer after loadResources would help. The offscreen recording example double starts under StrictMode and logs a rejected promise, which predates this branch.

Since rc.5

A night of looping every example screen (3 rounds at 1.5 s, 5 rounds at 250 ms, a 20 round soak with memory sampling), JS reloads, Fast Refresh, backgrounding and rotation on both platforms, plus a React Native 0.87.1 app, turned up a few more things, all in this branch:

• Buffers that finish loading after their effect cleaned up are released even with releaseOnUnmount: false; they piled up on Android until asset loads hit OutOfMemoryError. Skybox releases its texture buffer on unmount.
• useLightEntity destroys its light on unmount.
• FilamentView no longer rejects when the native view is gone before findFilamentView resolves.
• The recording example stops the recorder only when one runs, the test hybrid object initialises its enum, enableTransparentRendering={false} documents that a Skybox is required, and there is a TwoScenes example with two engines on one screen.

Memory over the soak stayed flat (Android PSS 688 MB from the first to the last sample, iOS RSS falling from 180 MB to 108 MB), thread counts stable, and Filament engines are created and destroyed in equal numbers once Hermes collects the wrappers.

CI

The workflows were already red before this branch touched them. Two commits at the tip fix that and can be cherry-picked on their own:

• macos-latest now means macos-26 with Xcode 26, whose clang refuses the two virtual methods declared inside the final PlatformMetal class while the Metal backend compiles with -Werror. filament_clang21.patch applies the two-line change from Fix macOS build with clang 21 google/filament#9928 until the submodule is bumped past it.
• android-actions/setup-android@v3 runs sdkmanager tools, a package that no longer exists, so both Android jobs died before compiling anything. v4 installs only the packages it is asked for.
• The docs workflows ran yarn classic inside package/, which finds the root bun workspace and refuses it because the root is not private. They now install the workspace with bun the way validate-js does, and the root is marked private.

Prereleases with the Filament and Bullet binaries are on the fork: https://github.com/eduardoborges/react-native-filament/releases (latest v2.0.0-rc.6).