expo-modules-core 56.0.14 → 56.0.16

package/CHANGELOG.md

@@ -10,6 +10,35 @@
 
 ### 💡 Others
 
+## 56.0.16 — 2026-06-10
+
+### 🎉 New features
+
+- [iOS] Added the `@Record` macro that synthesizes a record from a type's stored properties, with no `@Field` wrappers needed. ([#46547](https://github.com/expo/expo/pull/46547) by [@tsapeta](https://github.com/tsapeta))
+
+### 🐛 Bug fixes
+
+- [android] Add a synchronous shadow node size update path, fixing a layout shift for `Host` `matchContents` views. ([#46604](https://github.com/expo/expo/pull/46604) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Accept JS `Double` timestamps in `Date` Convertible. JS numbers arrive across the JSI bridge as Swift `Double`; the prior `as? Int` branch never matched, throwing `ConvertingException<Date>` whenever a JS caller passed `someDate.getTime()` to a `Date` / `Date?` argument. ([#46340](https://github.com/expo/expo/pull/46340) by [@kyleasaff](https://github.com/kyleasaff))
+- [Android] Fix events being silently dropped for Compose views in custom modules. ([#46623](https://github.com/expo/expo/issues/46623) by [@benjaminkomen](https://github.com/benjaminkomen)) ([#46624](https://github.com/expo/expo/pull/46624) by [@nishan](https://github.com/intergalacticspacehighway))
+
+### 💡 Others
+
+- [iOS] `@ExpoModule` now synthesizes a `_decorateModule` that binds the module's `@JS` functions directly onto the JS object, letting the module holder skip the dynamic definition path for synthesized modules. ([#46612](https://github.com/expo/expo/pull/46612) by [@tsapeta](https://github.com/tsapeta))
+
+## 56.0.15 — 2026-06-05
+
+### 🐛 Bug fixes
+
+- [iOS] Propagate async-function promise construction failures instead of trapping the app. ([#46106](https://github.com/expo/expo/issues/46106) by [@qutrek](https://github.com/qutrek)) ([#46145](https://github.com/expo/expo/pull/46145) by [@mvincentong](https://github.com/mvincentong))
+- [iOS] Read iPad-specific supported orientations from `UISupportedInterfaceOrientations~ipad`. ([#46281](https://github.com/expo/expo/issues/46281) by [@bryandent](https://github.com/bryandent)) ([#46306](https://github.com/expo/expo/pull/46306) by [@mvincentong](https://github.com/mvincentong))
+- [android] Fix nested `Host` double-composing children. ([#46304](https://github.com/expo/expo/pull/46304) by [@nishan](https://github.com/intergalacticspacehighway))
+- [iOS] Throw an actionable error when a worklet is used but `react-native-worklets`'s native adapter isn't linked, instead of a misleading "not an instance of Worklet" failure. ([#46571](https://github.com/expo/expo/pull/46571) by [@chrfalch](https://github.com/chrfalch))
+
+### 💡 Others
+
+- Native view config attributes now carry a `process` function that unwraps shared objects to their registry id, so callers can pass shared objects directly as view props instead of unwrapping them manually. ([#46212](https://github.com/expo/expo/pull/46212) by [@tsapeta](https://github.com/tsapeta))
+
 ## 56.0.14 — 2026-05-29
 
 _This version does not introduce any user-facing changes._
@@ -20,10 +49,6 @@ _This version does not introduce any user-facing changes._
 
 - [Android] Create Compose props without View. ([#46256](https://github.com/expo/expo/pull/46256) by [@jakex7](https://github.com/jakex7))
 
-### 💡 Others
-
-- Native view config attributes now carry a `process` function that unwraps shared objects to their registry id, so callers can pass shared objects directly as view props instead of unwrapping them manually. ([#46212](https://github.com/expo/expo/pull/46212) by [@tsapeta](https://github.com/tsapeta))
-
 ## 56.0.12 — 2026-05-21
 
 ### 🐛 Bug fixes

package/ExpoModulesCore.podspec

@@ -119,7 +119,7 @@ Pod::Spec.new do |s|
     s.static_framework = true
     s.header_dir     = 'ExpoModulesCore'
     s.source_files = 'ios/**/*.{h,m,mm,swift,cpp}', 'common/cpp/**/*.{h,cpp}'
-    s.exclude_files = ['ios/Tests', 'ios/Worklets', 'ios/WorkletsAdapter']
+    s.exclude_files = ['ios/Tests', 'ios/Worklets', 'ios/WorkletsTests', 'ios/WorkletsAdapter']
     s.compiler_flags = compiler_flags
     s.private_header_files = ['ios/**/*+Private.h', 'ios/**/Swift.h']
   end

package/ExpoModulesWorklets.podspec

@@ -31,4 +31,11 @@ Pod::Spec.new do |s|
 
   s.source_files = 'ios/Worklets/**/*.{h,m,mm,swift,cpp}'
   s.private_header_files = 'ios/Worklets/**/*+Private.h'
+
+  s.test_spec 'Tests' do |test_spec|
+    # ExpoModulesCore requires React-hermes or React-jsc in tests, add ExpoModulesTestCore for the underlying dependencies
+    test_spec.dependency 'ExpoModulesTestCore'
+
+    test_spec.source_files = 'ios/WorkletsTests/**/*.{m,swift}'
+  end
 end

package/android/build.gradle

@@ -27,7 +27,7 @@ if (shouldIncludeCompose) {
 }
 
 group = 'host.exp.exponent'
-version = '56.0.14'
+version = '56.0.16'
 
 def isExpoModulesCoreTests = {
   Gradle gradle = getGradle()
@@ -94,7 +94,7 @@ android {
   defaultConfig {
     consumerProguardFiles 'proguard-rules.pro'
     versionCode 1
-    versionName "56.0.14"
+    versionName "56.0.16"
     buildConfigField "String", "EXPO_MODULES_CORE_VERSION", "\"${versionName}\""
     buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", "true"
 

package/android/src/compose/expo/modules/kotlin/views/ExpoComposeView.kt

@@ -128,6 +128,8 @@ abstract class ExpoComposeView<T : ComposeProps>(
     recomposeScope = currentRecomposeScope
     for (index in 0..<this.size) {
       val child = getChildAt(index) as? ExpoComposeView<*> ?: continue
+      // Hosting children render themselves via their own ComposeView; skip to avoid double-rendering.
+      if (child.shouldUseAndroidLayout) continue
       key(child) {
         with(composableScope ?: ComposableScope()) {
           with(child) {
@@ -143,6 +145,7 @@ abstract class ExpoComposeView<T : ComposeProps>(
     recomposeScope = currentRecomposeScope
     for (index in 0..<this.size) {
       val child = getChildAt(index) as? ExpoComposeView<*> ?: continue
+      if (child.shouldUseAndroidLayout) continue
       if (!filter(child)) {
         continue
       }
@@ -160,6 +163,7 @@ abstract class ExpoComposeView<T : ComposeProps>(
   fun Child(composableScope: ComposableScope, index: Int) {
     recomposeScope = currentRecomposeScope
     val child = getChildAt(index) as? ExpoComposeView<*> ?: return
+    if (child.shouldUseAndroidLayout) return
     key(child) {
       with(composableScope) {
         with(child) {
@@ -507,7 +511,8 @@ class ComposeFunctionHolder<Props : ComposeProps>(
   appContext: AppContext,
   override val name: String,
   private val composableContent: @Composable FunctionalComposableScope.(props: Props) -> Unit,
-  override val props: Props
+  override val props: Props,
+  override val callbacksDefinition: CallbacksDefinition?
 ) : ExpoComposeView<Props>(context, appContext), ViewFunctionHolder {
   val propsMutableState = mutableStateOf(props)
 

package/android/src/compose/expo/modules/kotlin/views/ModuleDefinitionBuilderComposeExtension.kt

@@ -143,7 +143,7 @@ class ComposeViewFunctionDefinitionBuilder<Props : ComposeProps> @PublishedApi i
         } catch (e: Exception) {
           throw IllegalStateException("Could not instantiate props instance of $name compose component.", e)
         }
-        ComposeFunctionHolder(context, appContext, name, viewFunction, instance)
+        ComposeFunctionHolder(context, appContext, name, viewFunction, instance, eventBuilder.callbacksDefinition)
       },
       callbacksDefinition = eventBuilder.callbacksDefinition,
       viewType = ComposeFunctionHolder::class.java,

package/android/src/main/cpp/fabric/NativeStatePropsGetter.cpp

@@ -9,9 +9,54 @@ namespace expo {
 void NativeStatePropsGetter::registerNatives() {
   javaClassLocal()->registerNatives({
                                       makeNativeMethod("getStateProps", NativeStatePropsGetter::getStateProps),
+                                      makeNativeMethod("updateStyleSizeImmediate", NativeStatePropsGetter::updateStyleSizeImmediate),
+                                      makeNativeMethod("updateViewSizeImmediate", NativeStatePropsGetter::updateViewSizeImmediate),
                                     });
 }
 
+static std::shared_ptr<const react::ConcreteState<AndroidExpoViewState>> concreteStateFrom(
+  jni::alias_ref<jobject> stateWrapper
+) {
+  auto stateWrapperImpl = jni::alias_ref<react::StateWrapperImpl::javaobject>{
+    static_cast<react::StateWrapperImpl::javaobject>(stateWrapper.get())
+  };
+  return std::dynamic_pointer_cast<const react::ConcreteState<AndroidExpoViewState>>(
+    stateWrapperImpl->cthis()->getState()
+  );
+}
+
+void NativeStatePropsGetter::updateStyleSizeImmediate(
+  jni::alias_ref<NativeStatePropsGetter::javaobject> self,
+  jni::alias_ref<jobject> stateWrapper,
+  jdouble styleWidth,
+  jdouble styleHeight
+) {
+  const auto state = concreteStateFrom(stateWrapper);
+  if (state == nullptr) {
+    return;
+  }
+  AndroidExpoViewState newState;
+  newState._styleWidth = static_cast<float>(styleWidth);
+  newState._styleHeight = static_cast<float>(styleHeight);
+  state->updateState(std::move(newState), react::EventQueue::UpdateMode::unstable_Immediate);
+}
+
+void NativeStatePropsGetter::updateViewSizeImmediate(
+  jni::alias_ref<NativeStatePropsGetter::javaobject> self,
+  jni::alias_ref<jobject> stateWrapper,
+  jdouble width,
+  jdouble height
+) {
+  const auto state = concreteStateFrom(stateWrapper);
+  if (state == nullptr) {
+    return;
+  }
+  AndroidExpoViewState newState;
+  newState._width = static_cast<float>(width);
+  newState._height = static_cast<float>(height);
+  state->updateState(std::move(newState), react::EventQueue::UpdateMode::unstable_Immediate);
+}
+
 jni::local_ref<jni::JMap<jstring, jobject>> NativeStatePropsGetter::getStateProps(
   jni::alias_ref<NativeStatePropsGetter::javaobject> self,
   jni::alias_ref<jobject> stateWrapper

package/android/src/main/cpp/fabric/NativeStatePropsGetter.h

@@ -18,6 +18,23 @@ public:
     jni::alias_ref<NativeStatePropsGetter::javaobject> self,
     jni::alias_ref<jobject> stateWrapper
   );
+
+  // Synchronously flushes a shadow-node size state update in the current frame
+  // (`UpdateMode::unstable_Immediate`) — the same path iOS uses. This avoids the layout shift an
+  // asynchronous `StateWrapper.updateState` causes for matchContents Hosts in Expo UI Compose views
+  static void updateStyleSizeImmediate(
+    jni::alias_ref<NativeStatePropsGetter::javaobject> self,
+    jni::alias_ref<jobject> stateWrapper,
+    jdouble styleWidth,
+    jdouble styleHeight
+  );
+
+  static void updateViewSizeImmediate(
+    jni::alias_ref<NativeStatePropsGetter::javaobject> self,
+    jni::alias_ref<jobject> stateWrapper,
+    jdouble width,
+    jdouble height
+  );
 };
 
 } // namespace expo

package/android/src/main/java/expo/modules/kotlin/jni/fabric/NativeStatePropsGetter.kt

@@ -6,4 +6,10 @@ import com.facebook.yoga.annotations.DoNotStrip
 class NativeStatePropsGetter {
   // We can't use StateWrapper directly, as this class is not exposed
   external fun getStateProps(stateWrapper: Any): Map<String, Any?>?
+
+  // Synchronously flush a style property size update in the current frame (pass NaN for "unset").
+  external fun updateStyleSizeImmediate(stateWrapper: Any, styleWidth: Double, styleHeight: Double)
+
+  // Synchronously flush a size update in the current frame.
+  external fun updateViewSizeImmediate(stateWrapper: Any, width: Double, height: Double)
 }

package/android/src/main/java/expo/modules/kotlin/viewevent/ViewEvent.kt

@@ -4,10 +4,12 @@ import android.view.View
 import com.facebook.react.bridge.ReactContext
 import com.facebook.react.bridge.WritableMap
 import expo.modules.core.utilities.ifNull
+import expo.modules.kotlin.ModuleRegistry
 import expo.modules.kotlin.getUnimoduleProxy
 import expo.modules.kotlin.logger
 import expo.modules.kotlin.types.JSTypeConverterProvider
 import expo.modules.kotlin.types.putGeneric
+import expo.modules.kotlin.views.CallbacksDefinition
 import expo.modules.kotlin.views.ViewFunctionHolder
 
 fun interface ViewEventCallback<T> {
@@ -27,24 +29,13 @@ open class ViewEvent<T>(
     val appContext = nativeModulesProxy.kotlinInteropModuleRegistry.appContext
 
     if (!isValidated) {
-      val holder = appContext.registry.getModuleHolder(view::class.java).ifNull {
-        logger.warn("⚠️ Cannot get module holder for ${view::class.java}")
-        return
-      }
-
-      val callbacksDefinition = if (view is ViewFunctionHolder) {
-        appContext.registry.getViewDefinition(holder, view.name)?.callbacksDefinition
-      } else {
-        appContext.registry.getViewDefinition(holder, view::class.java)?.callbacksDefinition
-      }
-
-      val callbacks = callbacksDefinition.ifNull {
-        logger.warn("⚠️ Cannot get callbacks for ${holder.module::class.java}")
+      val callbacks = resolveCallbacksDefinition(view, appContext.registry).ifNull {
+        logger.warn("⚠️ Cannot get callbacks for ${view::class.java}")
         return
       }
 
       if (!callbacks.names.any { it == name }) {
-        logger.warn("⚠️ Event $name wasn't exported from ${holder.module::class.java}")
+        logger.warn("⚠️ Event $name wasn't exported from ${view::class.java}")
         return
       }
 
@@ -71,3 +62,17 @@ open class ViewEvent<T>(
     }
   }
 }
+
+/**
+ * Resolves the callbacks declared for [view]. Views that reuse a single class
+ * (e.g. ComposeFunctionHolder) carry their own [CallbacksDefinition] because they
+ * can't be matched by class; everything else is looked up by class in the registry.
+ * See https://github.com/expo/expo/issues/46623.
+ */
+internal fun resolveCallbacksDefinition(view: View, registry: ModuleRegistry): CallbacksDefinition? {
+  if (view is ViewFunctionHolder) {
+    return view.callbacksDefinition
+  }
+  val holder = registry.getModuleHolder(view::class.java) ?: return null
+  return registry.getViewDefinition(holder, view::class.java)?.callbacksDefinition
+}

package/android/src/main/java/expo/modules/kotlin/views/ShadowNodeProxy.kt

@@ -1,23 +1,53 @@
 package expo.modules.kotlin.views
 
-import com.facebook.react.bridge.Arguments
+import android.view.ViewTreeObserver
+import expo.modules.kotlin.jni.fabric.NativeStatePropsGetter
 import java.lang.ref.WeakReference
 
 class ShadowNodeProxy(expoView: ExpoView) {
   val weakExpoView = WeakReference(expoView)
+  private val stateUpdater = NativeStatePropsGetter()
 
+  private var pendingFlush: ((stateWrapper: Any) -> Unit)? = null
+  private var preDrawListener: ViewTreeObserver.OnPreDrawListener? = null
+
+  // Schedule in predraw listener to avoid early return in re-entrancy
+  // We have a proper fix [here](https://github.com/facebook/react-native/pull/56311)
+  // but it needs to be merged in RN
+  // TODO: Remove the workaround when RN PR gets merged.
   fun setViewSize(width: Double, height: Double) {
-    weakExpoView.get()?.stateWrapper?.updateState(Arguments.makeNativeMap(mapOf("width" to width, "height" to height)))
+    scheduleFlush { stateWrapper ->
+      stateUpdater.updateViewSizeImmediate(stateWrapper, width, height)
+    }
   }
 
   fun setStyleSize(width: Double?, height: Double?) {
-    weakExpoView.get()?.stateWrapper?.updateState(
-      Arguments.makeNativeMap(
-        mapOf(
-          "styleWidth" to width,
-          "styleHeight" to height
-        )
-      )
-    )
+    scheduleFlush { stateWrapper ->
+      stateUpdater.updateStyleSizeImmediate(stateWrapper, width ?: Double.NaN, height ?: Double.NaN)
+    }
+  }
+
+  private fun scheduleFlush(flush: (stateWrapper: Any) -> Unit) {
+    pendingFlush = flush
+    val observer = weakExpoView.get()?.viewTreeObserver?.takeIf { it.isAlive } ?: return
+
+    // Remove the previous attached listener
+    preDrawListener?.let(observer::removeOnPreDrawListener)
+
+    val listener = object : ViewTreeObserver.OnPreDrawListener {
+      override fun onPreDraw(): Boolean {
+        preDrawListener = null
+        // The view is attached while drawing, so this re-fetch returns the same
+        // observer that is dispatching us. removeOnPreDrawListener throws on a dead
+        // observer, hence the isAlive guard.
+        weakExpoView.get()?.viewTreeObserver?.takeIf { it.isAlive }?.removeOnPreDrawListener(this)
+        val flushNow = pendingFlush
+        pendingFlush = null
+        weakExpoView.get()?.stateWrapper?.let { flushNow?.invoke(it) }
+        return true
+      }
+    }
+    preDrawListener = listener
+    observer.addOnPreDrawListener(listener)
   }
 }

package/android/src/main/java/expo/modules/kotlin/views/ViewFunctionHolder.kt

@@ -1,9 +1,12 @@
 package expo.modules.kotlin.views
 
 /*
- * A marker interface identifying views reusing a single class (like ComposeFunctionHolder)
- * that should be identified by name for things like event validation.
+ * A marker interface for views that reuse a single class (like ComposeFunctionHolder) and so
+ * can't be resolved by class. They're identified by [name] and carry their
+ * own [callbacksDefinition], which event invocation reads directly instead of looking it up in the
+ * registry. See https://github.com/expo/expo/issues/46623.
  */
 interface ViewFunctionHolder {
   val name: String
+  val callbacksDefinition: CallbacksDefinition?
 }

package/ios/AppDelegates/ExpoAppDelegateSubscriberManager.swift

@@ -462,9 +462,7 @@ public class ExpoAppDelegateSubscriberManager: NSObject {
    */
   @objc
   public static func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
-    let deviceOrientationMask = allowedOrientations(for: UIDevice.current.userInterfaceIdiom)
-    let universalOrientationMask = allowedOrientations(for: .unspecified)
-    let infoPlistOrientations = deviceOrientationMask.isEmpty ? universalOrientationMask : deviceOrientationMask
+    let infoPlistOrientations = allowedOrientations(for: UIDevice.current.userInterfaceIdiom)
 
     let parsedSubscribers = ExpoAppDelegateSubscriberRepository.subscribers.filter {
       $0.responds(to: #selector(UIApplicationDelegate.application(_:supportedInterfaceOrientationsFor:)))
@@ -483,14 +481,28 @@ public class ExpoAppDelegateSubscriberManager: NSObject {
 }
 
 #if os(iOS)
-private func allowedOrientations(for userInterfaceIdiom: UIUserInterfaceIdiom) -> UIInterfaceOrientationMask {
-  // For now only iPad-specific orientations are supported
-  let deviceString = userInterfaceIdiom == .pad ? "~pad" : ""
-  var mask: UIInterfaceOrientationMask = []
-  guard let orientations = Bundle.main.infoDictionary?["UISupportedInterfaceOrientations\(deviceString)"] as? [String] else {
+func allowedOrientations(
+  for userInterfaceIdiom: UIUserInterfaceIdiom,
+  infoDictionary: [String: Any]? = Bundle.main.infoDictionary
+) -> UIInterfaceOrientationMask {
+  // For now only iPad-specific orientations are supported. When the `~ipad` key is absent,
+  // fall back to the universal `UISupportedInterfaceOrientations` key, matching how UIKit
+  // resolves device-specific keys. We additionally fall back when `~ipad` is present but
+  // resolves to no orientations, treating a malformed entry as if it were absent.
+  if userInterfaceIdiom == .pad,
+    let mask = orientationMask(forKey: "UISupportedInterfaceOrientations~ipad", in: infoDictionary),
+    !mask.isEmpty {
     return mask
   }
+  return orientationMask(forKey: "UISupportedInterfaceOrientations", in: infoDictionary) ?? []
+}
 
+private func orientationMask(forKey key: String, in infoDictionary: [String: Any]?) -> UIInterfaceOrientationMask? {
+  guard let orientations = infoDictionary?[key] as? [String] else {
+    return nil
+  }
+
+  var mask: UIInterfaceOrientationMask = []
   for orientation in orientations {
     switch orientation {
     case "UIInterfaceOrientationPortrait":

package/ios/Core/AppContext.swift

@@ -529,8 +529,8 @@ public final class AppContext: NSObject, EXAppContextProtocol, @unchecked Sendab
    */
   @JavaScriptActor
   private func installModuleClasses(in runtime: JavaScriptRuntime) throws {
-    let coreObject = runtime.global().getPropertyAsObject(EXGlobalCoreObjectPropertyName)
-    let sharedObjectClass = coreObject.getPropertyAsObject("SharedObject")
+    let coreObject = try runtime.global().getPropertyAsObject(EXGlobalCoreObjectPropertyName)
+    let sharedObjectClass = try coreObject.getPropertyAsObject("SharedObject")
     let sharedObjectBaseProto = sharedObjectClass.getProperty("prototype")
 
     // Stored as JavaScriptValue (a class) because JavaScriptObject is ~Copyable

package/ios/Core/Arguments/Convertibles.swift

@@ -153,7 +153,14 @@ extension Date: Convertible {
       }
       return date
     }
-    // For converting the value from `Date.now()`
+    // JS numbers arrive across the JSI bridge as Swift Double (all JS numbers
+    // are doubles). `as? Int` does NOT downcast a Double, so without this
+    // branch any JS caller passing `someDate.getTime()` to a `Date` / `Date?`
+    // argument throws ConvertingException<Date>.
+    if let value = value as? Double {
+      return Date(timeIntervalSince1970: value / 1000.0)
+    }
+    // Kept for parity with explicit Int values (rare but possible from native callers).
     if let value = value as? Int {
       return Date(timeIntervalSince1970: Double(value) / 1000.0)
     }

package/ios/Core/Conversions.swift

@@ -218,7 +218,7 @@ public struct Conversions {
         memcpy(arrayBuffer.data(), baseAddress, data.count)
       }
     }
-    let uint8ArrayCtor = runtime.global().getPropertyAsFunction("Uint8Array")
+    let uint8ArrayCtor = try runtime.global().getPropertyAsFunction("Uint8Array")
     return try uint8ArrayCtor.callAsConstructor(arrayBuffer.asValue())
   }
 

package/ios/Core/DynamicTypes/DynamicConvertibleType.swift

@@ -21,10 +21,10 @@ internal struct DynamicConvertibleType: AnyDynamicType {
 
   @JavaScriptActor
   func cast(jsValue: JavaScriptValue, appContext: AppContext) throws -> Any {
+    // `from(object:)` dispatches dynamically: reflection-based hydration for `@Field` records,
+    // a direct statically-typed factory for `@Record`-synthesized ones.
     if let recordType = innerType as? any Record.Type {
-      let record = recordType.init()
-      try record.update(withObject: try jsValue.asObject(), appContext: appContext)
-      return record
+      return try recordType.from(object: jsValue.asObject(), appContext: appContext)
     }
     return try innerType.convert(from: jsValue.getAny(), appContext: appContext)
   }
@@ -53,6 +53,19 @@ internal struct DynamicConvertibleType: AnyDynamicType {
     return try convertOriginalValueToJS(value, appContext: appContext)
   }
 
+  // The protocol default for the `in: runtime` variant pre-converts the value via
+  // `convertFunctionResult` (which calls `convertResult` → `Record.toDictionary` for records) before
+  // reaching `castToJS`, defeating the direct object path. Override it to try the direct path first —
+  // the same short-circuit as the no-runtime `convertToJS` above — so records (including
+  // `@Record`-synthesized ones) convert straight through `toObject` on the return side too.
+  func convertToJS<ValueType>(_ value: ValueType, appContext: AppContext, in runtime: JavaScriptRuntime) throws -> JavaScriptValue {
+    if let directJSValue = try directJSValueIfPossible(value, appContext: appContext) {
+      return directJSValue
+    }
+    let result = Conversions.convertFunctionResult(value, appContext: appContext, dynamicType: self)
+    return try castToJS(result, appContext: appContext, in: runtime)
+  }
+
   func convertResult<ResultType>(_ result: ResultType, appContext: AppContext) throws -> Any {
     return try innerType.convertResult(result, appContext: appContext)
   }
@@ -62,15 +75,17 @@ internal struct DynamicConvertibleType: AnyDynamicType {
   }
 
   private func directJSValueIfPossible<ValueType>(_ value: ValueType, appContext: AppContext) throws -> JavaScriptValue? {
+    // `toObject` is a `Record` requirement, so the synthesized override dispatches dynamically;
+    // `@Field` records fall through to the reflection-based default.
     if let value = value as? any Record {
       return try JavaScriptActor.assumeIsolated {
-        try value.toJSValue(appContext: appContext)
+        try value.toObject(appContext: appContext).asValue()
       }
     }
     // `FormattedRecord` isn't a `Record`, so it needs this separate branch to preserve the direct path.
-    if let value = value as? any RecordJavaScriptValueConvertible {
+    if let value = value as? any RecordObjectConvertible {
       return try JavaScriptActor.assumeIsolated {
-        try value.toJSValue(appContext: appContext)
+        try value.toObject(appContext: appContext).asValue()
       }
     }
     return nil

package/ios/Core/DynamicTypes/DynamicSharedObjectType.swift

@@ -95,7 +95,7 @@ private func getBaseSharedType(_ appContext: AppContext, nativeType: AnySharedOb
 
 private func newBaseSharedObject(_ appContext: AppContext, nativeType: AnySharedObject.Type) throws -> JavaScriptObject? {
   let jsClass = try getBaseSharedType(appContext, nativeType: nativeType)
-  let prototype = jsClass.asObject().getPropertyAsObject("prototype")
+  let prototype = try jsClass.asObject().getPropertyAsObject("prototype")
   return try appContext.runtime.createObject(prototype: prototype)
 }
 

package/ios/Core/ExpoModulesMacros.swift

@@ -38,14 +38,21 @@ public macro OptimizedFunction() =
 ///
 ///     @JS
 ///     var status: String { "ok" }
-@attached(peer)
+///
+/// Also emits a never-called `_assertTypesConformance_<member>` peer that statically asserts every
+/// type crossing the JS boundary conforms to the JS-convertible protocol, so a non-conforming type
+/// fails to compile on the user's declaration. The peer name embeds the member name, hence
+/// `names: arbitrary`.
+@attached(peer, names: arbitrary)
 public macro JS(_ jsName: String? = nil) =
   #externalMacro(module: "ExpoModulesMacros", type: "JSMacro")
 
 /// Member macro applied to a `Module` subclass. Scans the class body for declarations
-/// marked with `@JS` and synthesizes a framework-internal `_exposedDefinition()` method.
+/// marked with `@JS` and synthesizes a framework-internal `_synthesizedDefinition()` method.
 /// `expo-modules-core` calls it automatically and merges the result into the module's
-/// definition, so the user doesn't have to reference it from `definition()`.
+/// definition, so the user doesn't have to reference it from `definition()`. `@JS` functions are
+/// additionally bound directly into the module's JS object by a synthesized
+/// `_decorateModule(object:in:appContext:)`.
 ///
 /// Usage:
 ///
@@ -58,13 +65,15 @@ public macro JS(_ jsName: String? = nil) =
 ///       @JS
 ///       func greet(name: String) -> String { "Hi, \(name)" }
 ///     }
-@attached(member, names: named(_exposedDefinition), named(appContext), named(init))
+@attached(
+  member,
+  names: named(_synthesizedDefinition), named(appContext), named(init), named(_decorateModule))
 public macro ExpoModule(_ name: String? = nil, classes: [Any.Type] = []) =
   #externalMacro(module: "ExpoModulesMacros", type: "ExpoModuleMacro")
 
 /// Member macro applied to a `SharedObject` subclass. Scans the class body for declarations
 /// marked with `@JS` (including a single `@JS init(...)` for the JS constructor) and
-/// synthesizes a `_exposedClassDefinition()` static method returning a `ClassDefinition`.
+/// synthesizes a `_synthesizedClassDefinition()` static method returning a `ClassDefinition`.
 /// The companion `@ExpoModule(classes: [Foo.self])` wires the class into the module's
 /// exposed surface.
 ///
@@ -81,6 +90,35 @@ public macro ExpoModule(_ name: String? = nil, classes: [Any.Type] = []) =
 ///       @JS
 ///       var size: Int { 42 }
 ///     }
-@attached(member, names: named(_exposedClassDefinition))
+@attached(member, names: named(_synthesizedClassDefinition))
 public macro SharedObject(_ name: String? = nil) =
   #externalMacro(module: "ExpoModulesMacros", type: "SharedObjectMacro")
+
+/// Member + extension macro applied to a record `struct` or `class`. Every non-`static`,
+/// non-`private`/`fileprivate`, non-`lazy`, non-computed stored property is part of the record — no
+/// `@Field` wrapper needed — and the macro synthesizes the whole conversion surface from each
+/// property's static type: a memberwise `init`, the `from(object:appContext:)` /
+/// `from(dictionary:appContext:)` factories, and the `toDictionary(appContext:)` /
+/// `toObject(appContext:)` write side. The type is auto-conformed to `Record`; the synthesized
+/// methods override `Record`'s reflection-based defaults, so it stays usable anywhere a `Record`
+/// argument is expected.
+///
+/// Requiredness is inferred from each property: a default value makes it optional, an optional type
+/// makes it nullable and optional, and a non-optional property without a default is required (the
+/// factories throw `RecordPropertyRequiredException` when the source omits it).
+///
+/// Usage:
+///
+///     @Record
+///     struct Options {
+///       var name: String          // required
+///       var count: Int = 0        // optional (has default)
+///       var note: String?         // nullable + optional
+///     }
+@attached(
+  member,
+  names: named(init), named(from), named(toDictionary), named(toObject),
+  named(_assertTypesConformance))
+@attached(extension, conformances: Record)
+public macro Record() =
+  #externalMacro(module: "ExpoModulesMacros", type: "RecordMacro")

package/ios/Core/Functions/AsyncFunctionDefinition.swift

@@ -186,7 +186,7 @@ public class AsyncFunctionDefinition<Args, FirstArgType, ReturnType>: AnyAsyncFu
       guard let appContext else {
         throw Exceptions.AppContextLost()
       }
-      let promise = JavaScriptPromise(try appContext.runtime)
+      let promise = try JavaScriptPromise(appContext.runtime)
       let promiseValue = promise.asValue()
 
       self.call(appContext, this: this, arguments: arguments) { [promise] result in
@@ -209,5 +209,3 @@ public class AsyncFunctionDefinition<Args, FirstArgType, ReturnType>: AnyAsyncFu
     return self
   }
 }
-
-

package/ios/Core/ModuleHolder.swift

@@ -52,20 +52,20 @@ public final class ModuleHolder {
 
   /// Combines the user-authored definition with the entries synthesized by the
   /// `@ExpoModule` macro on this module's class (if any). The macro emits a
-  /// `_exposedDefinition()` method returning an `[AnyDefinition]` array of the
+  /// `_synthesizedDefinition()` method returning an `[AnyDefinition]` array of the
   /// `Function` / `Property` / `Constructor` entries it generated from `@JS`
   /// members. Those entries are prepended to the user's definitions and the
   /// whole list is fed back through `ModuleDefinition.init` so the merged
   /// result is rebucketed (into `functions`, `properties`, etc.) just like a
   /// hand-written definition. Modules that don't use the macro fall through
-  /// the empty-exposed fast path and return the user's definition unchanged.
+  /// the empty-synthesized fast path and return the user's definition unchanged.
   private static func buildDefinition(for module: AnyModule) -> ModuleDefinition {
     let userDefinition = module.definition()
-    let exposed = module._exposedDefinition()
-    if exposed.isEmpty {
+    let synthesized = module._synthesizedDefinition()
+    if synthesized.isEmpty {
       return userDefinition
     }
-    return ModuleDefinition(definitions: exposed + userDefinition.rawDefinitions)
+    return ModuleDefinition(definitions: synthesized + userDefinition.rawDefinitions)
   }
 
   // MARK: Constants
@@ -106,7 +106,13 @@ public final class ModuleHolder {
     }
     do {
       log.info("Creating JS object for module '\(name)'")
-      return try definition.build(appContext: appContext)
+      let object = try definition.build(appContext: appContext)
+
+      // Install the `@JS` members the `@ExpoModule` macro binds directly into the JS object
+      // (the direct-JSI path). A no-op for modules that don't use the macro.
+      try module._decorateModule(object: object, in: appContext.runtime, appContext: appContext)
+
+      return object
     } catch {
       log.error("Building the module object failed: \(error)")
       return nil

package/ios/Core/Protocols/AnyModule.swift

@@ -1,3 +1,5 @@
+import ExpoModulesJSI
+
 /**
  A protocol for any type-erased module that provides functions used by the core.
  */
@@ -19,11 +21,23 @@ public protocol AnyModule: AnyObject, AnyArgument {
   /// Framework-internal: the leading underscore signals this is not part of the public API and
   /// should only be called by `expo-modules-core` itself. Modules that don't use the macro fall
   /// back to the default empty implementation.
-  func _exposedDefinition() -> [AnyDefinition]
+  func _synthesizedDefinition() -> [AnyDefinition]
+
+  /// Binds the module's `@JS` members directly into its JavaScript object, generated by the
+  /// `@ExpoModule` macro. Core calls this after building the module object so the synthesized
+  /// host functions are installed alongside the DSL-described surface. Framework-internal
+  /// (leading underscore). Modules that don't use the macro fall back to the default no-op.
+  @JavaScriptActor
+  func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws
 }
 
 public extension AnyModule {
-  func _exposedDefinition() -> [AnyDefinition] {
+  func _synthesizedDefinition() -> [AnyDefinition] {
     return []
   }
+
+  @JavaScriptActor
+  func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws {
+    // No-op by default — only `@ExpoModule`-macro modules synthesize a real implementation.
+  }
 }

package/ios/Core/Records/FormattedRecord.swift

@@ -2,7 +2,7 @@
  Class that binds a formatter with a record.
  It can be converted to JS, but it can't be converted from a JS value.
  */
-public struct FormattedRecord<RecordType: Record>: Convertible, RecordJavaScriptValueConvertible {
+public struct FormattedRecord<RecordType: Record>: Convertible, RecordObjectConvertible {
   internal final class FormattedRecordCannotBeUsedAsParameterException: Exception, @unchecked Sendable {
     override var reason: String {
       "FormattedRecord cannot be used as a parameter"
@@ -39,7 +39,7 @@ public struct FormattedRecord<RecordType: Record>: Convertible, RecordJavaScript
   }
 
   @JavaScriptActor
-  func toJSValue(appContext: AppContext) throws -> JavaScriptValue {
+  func toObject(appContext: AppContext) throws -> JavaScriptObject {
     let object = try appContext.runtime.createObject()
 
     for field in fieldsOf(record) {
@@ -58,6 +58,6 @@ public struct FormattedRecord<RecordType: Record>: Convertible, RecordJavaScript
       let jsValue = try recordFieldValueToJSValue(value, appContext: appContext)
       object.setProperty(key, value: jsValue)
     }
-    return object.asValue()
+    return object
   }
 }

package/ios/Core/Records/Record.swift

@@ -20,15 +20,53 @@ public protocol Record: Convertible {
    */
   init(from: Dict, appContext: AppContext) throws
 
+  /**
+   Reads the record's members off a `JavaScriptObject`. The `@Field`-based default goes through
+   reflection (`init()` + `update(withObject:)`); the `@Record` macro overrides it with a direct,
+   factory that reads each stored property by its declared type.
+   */
+  @JavaScriptActor
+  static func from(object: borrowing JavaScriptObject, appContext: AppContext) throws -> Self
+
+  /**
+   Reads the record's members from a `[String: Any]` dictionary. The `@Field`-based default goes
+   through reflection (`init()` + `update(withDict:)`); the `@Record` macro overrides it with a
+   direct, statically-typed factory.
+   */
+  static func from(dictionary: Dict, appContext: AppContext) throws -> Self
+
   /**
    Converts the record back to the dictionary. Only members wrapped by `@Field` will be set in the dictionary.
    */
   func toDictionary(appContext: AppContext?) -> Dict
+
+  /**
+   Converts the record to a `JavaScriptObject`. The `@Field`-based default builds the object via
+   reflection; the `@Record` macro overrides it with a direct, statically-typed conversion.
+   */
+  @JavaScriptActor
+  func toObject(appContext: AppContext) throws -> JavaScriptObject
 }
 
-internal protocol RecordJavaScriptValueConvertible {
+/**
+ Adopted by record-like types that produce a `JavaScriptObject` directly but aren't themselves a
+ `Record` — currently just `FormattedRecord`. Lets `DynamicConvertibleType` take the direct
+ object-building path for them, same as for records.
+ */
+internal protocol RecordObjectConvertible {
   @JavaScriptActor
-  func toJSValue(appContext: AppContext) throws -> JavaScriptValue
+  func toObject(appContext: AppContext) throws -> JavaScriptObject
+}
+
+/**
+ Thrown by a synthesized record's factories when a required property is missing from the source.
+ Public because the `@Record`-generated code lives in user modules and references it directly.
+ The `@Field`-based path has its own internal `FieldRequiredException`.
+ */
+public final class RecordPropertyRequiredException: GenericException<String>, @unchecked Sendable {
+  override public var reason: String {
+    return "Value for property '\(param)' is required, got nil"
+  }
 }
 
 /**
@@ -37,7 +75,9 @@ internal protocol RecordJavaScriptValueConvertible {
 public extension Record {
   static func convert(from value: Any?, appContext: AppContext) throws -> Self {
     if let value = value as? Dict {
-      return try Self(from: value, appContext: appContext)
+      // `from(dictionary:)` dispatches dynamically — reflection for `@Field` records, the
+      // synthesized factory for `@Record` ones — so both read correctly off a dictionary.
+      return try Self.from(dictionary: value, appContext: appContext)
     }
     // It's possible that the current implementation tries to convert a value that is already of the desired type.
     // Handle that gracefully instead of throwing an exception.
@@ -52,6 +92,22 @@ public extension Record {
     try update(withDict: dict, appContext: appContext)
   }
 
+  @JavaScriptActor
+  static func from(object: borrowing JavaScriptObject, appContext: AppContext) throws -> Self {
+    // Reflection-based default for `@Field` records. The `@Record` macro synthesizes a direct,
+    // statically-typed override that takes precedence over this.
+    let record = Self()
+    try record.update(withObject: object, appContext: appContext)
+    return record
+  }
+
+  static func from(dictionary: Dict, appContext: AppContext) throws -> Self {
+    // Reflection-based default for `@Field` records. The `@Record` macro synthesizes a direct,
+    // statically-typed override that takes precedence over this. Delegates to `init(from:appContext:)`
+    // so any custom dictionary initializer a record provides still runs.
+    return try Self(from: dictionary, appContext: appContext)
+  }
+
   func update(withDict dict: Dict, appContext: AppContext) throws {
     let dictKeys = dict.keys
 
@@ -107,7 +163,7 @@ public extension Record {
   }
 
   @JavaScriptActor
-  func toJSValue(appContext: AppContext) throws -> JavaScriptValue {
+  func toObject(appContext: AppContext) throws -> JavaScriptObject {
     let object = try appContext.runtime.createObject()
 
     for field in fieldsOf(self) {
@@ -117,7 +173,7 @@ public extension Record {
       let value = try recordFieldValueToJSValue(field.get(), dynamicType: field.fieldType, appContext: appContext)
       object.setProperty(key, value: value)
     }
-    return object.asValue()
+    return object
   }
 }
 

package/ios/JS/ExpoRuntimeInstaller.swift

@@ -30,7 +30,7 @@ internal class ExpoRuntimeInstaller: EXJavaScriptRuntimeManager {
    */
   @JavaScriptActor
   internal func installExpoModulesHostObject() throws {
-    let coreObject = runtime.global().getPropertyAsObject(EXGlobalCoreObjectPropertyName)
+    let coreObject = try runtime.global().getPropertyAsObject(EXGlobalCoreObjectPropertyName)
 
     if coreObject.hasProperty("modules") {
       // Host object already installed

package/ios/Platform/Platform.h

@@ -16,6 +16,7 @@
 @compatibility_alias UIWindow NSWindow;
 @compatibility_alias UIHostingController NSHostingController;
 @compatibility_alias UIImage NSImage;
+@compatibility_alias UIImageView NSImageView;
 
 #ifndef UIApplication
 @compatibility_alias UIApplication NSApplication;

package/ios/Platform/Platform.swift

@@ -14,6 +14,7 @@ public typealias UIHostingController = NSHostingController
 public typealias UIViewRepresentable = NSViewRepresentable
 public typealias UILabel = NSLabel
 public typealias UIImage = NSImage
+public typealias UIImageView = NSImageView
 public typealias UIPasteboard = NSPasteboard
 
 extension UIApplication {

package/ios/Worklets/Core/DynamicSerializableType.swift

@@ -28,6 +28,10 @@ internal struct DynamicSerializableType: AnyDynamicType {
       }
     }
     guard let jsSerializable else {
+      // Adapter not linked → the extractor returns nil for every value; give an actionable error.
+      if WorkletsProviderRegistry.shared == nil {
+        throw WorkletsNotInstalledException()
+      }
       throw NotSerializableException(innerType)
     }
     return Serializable(jsSerializable)

package/ios/Worklets/Core/Worklet.swift

@@ -46,3 +46,13 @@ internal final class NotWorkletException: GenericException<SerializableValueType
     "Expected Serializable of type Worklet but got \(param)"
   }
 }
+
+/// Thrown when a worklet operation is attempted but the `react-native-worklets` native
+/// adapter isn't linked (its provider is `nil`). Replaces misleading lower-level errors.
+internal final class WorkletsNotInstalledException: Exception, @unchecked Sendable {
+  override var reason: String {
+    "This feature requires `react-native-worklets`, but its native adapter isn't linked — usually " +
+    "because the package isn't installed (it's an optional peer dependency of libraries like Expo UI " +
+    "and Reanimated). Install it with `npx expo install react-native-worklets`, then rebuild the app."
+  }
+}

package/ios/WorkletsTests/WorkletRuntimeIntegrationTests.swift

@@ -0,0 +1,27 @@
+// Copyright 2025-present 650 Industries. All rights reserved.
+
+import Testing
+
+import ExpoModulesCore
+import ExpoModulesWorklets
+
+/**
+ Runtime-level checks for the worklets integration wiring.
+
+ Note: these run under `use_expo_modules_tests!`, which does not link companion pods, so the
+ worklets adapter — and therefore `WorkletsProviderRegistry.shared` — is intentionally absent
+ here (the same state as an app without `react-native-worklets`). Whether the adapter is
+ correctly autolinked is guarded by the JS test `WorkletsAdapterAutolinking-test.ts`; the
+ consumer-side behaviour when it's missing is covered by `WorkletsNotInstalledTests`.
+ */
+@Suite("WorkletRuntimeIntegration", .serialized)
+struct WorkletRuntimeIntegrationTests {
+  @Test
+  func `UI worklet runtime factory registers on the app context`() {
+    // `WorkletIntegration.register()` installs the core-side hook (normally invoked via +load)
+    // that turns a worklet runtime pointer into a usable runtime. Guards the factory wiring onto
+    // AppContext; it does not require the adapter to be linked.
+    WorkletIntegration.register()
+    #expect(AppContext.uiRuntimeFactory != nil)
+  }
+}

package/ios/WorkletsTests/WorkletsNotInstalledTests.swift

@@ -0,0 +1,33 @@
+// Copyright 2025-present 650 Industries. All rights reserved.
+
+import Testing
+
+@testable import ExpoModulesCore
+@testable import ExpoModulesWorklets
+
+/**
+ The `use_expo_modules_tests!` harness does not link companion pods, so the worklets adapter
+ never registers `WorkletsProviderRegistry.shared`. That nil-provider state is exactly an app
+ where `react-native-worklets` isn't installed — so this is the right place to assert that a
+ worklet operation fails with the actionable `WorkletsNotInstalledException` rather than a
+ misleading lower-level error (e.g. "not an instance of Worklet").
+ */
+@Suite("WorkletsNotInstalled", .serialized)
+@JavaScriptActor
+struct WorkletsNotInstalledTests {
+  @Test
+  func `converting a worklet argument reports that worklets are not installed`() throws {
+    // Only meaningful while the adapter is unlinked (the default in this test harness).
+    try #require(WorkletsProviderRegistry.shared == nil)
+
+    let appContext = AppContext.create()
+    let runtime = try appContext.runtime
+    // Any JS value works — with the adapter unlinked, extraction returns nil for everything.
+    let jsValue = try runtime.eval("42")
+    let dynamicType = DynamicSerializableType(innerType: Worklet.self)
+
+    #expect(throws: WorkletsNotInstalledException.self) {
+      _ = try dynamicType.cast(jsValue: jsValue, appContext: appContext)
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-core",
-  "version": "56.0.14",
+  "version": "56.0.16",
   "description": "The core of Expo Modules architecture",
   "main": "src/index.ts",
   "types": "build/index.d.ts",
@@ -46,8 +46,8 @@
     "preset": "expo-module-scripts"
   },
   "dependencies": {
-    "@expo/expo-modules-macros-plugin": "~0.0.9",
-    "expo-modules-jsi": "~56.0.7",
+    "@expo/expo-modules-macros-plugin": "0.2.2",
+    "expo-modules-jsi": "~56.0.9",
     "invariant": "^2.2.4"
   },
   "peerDependencies": {
@@ -64,9 +64,9 @@
     "@testing-library/react-native": "^13.3.0",
     "@types/react": "~19.2.0",
     "@types/invariant": "^2.2.33",
-    "expo-module-scripts": "56.0.2"
+    "expo-module-scripts": "56.0.3"
   },
-  "gitHead": "a7adc95c1747db1e92655feba56d0e62660098db",
+  "gitHead": "b1e94a5c1c5b19472a42ca25752a3533699bc46a",
   "scripts": {
     "build": "expo-module build",
     "clean": "expo-module clean",

package/spm.config.json

@@ -46,6 +46,7 @@
           "headerPattern": "**/*.h",
           "exclude": [
             "Tests/**",
+            "WorkletsTests/**",
             "Worklets/**",
             "WorkletsAdapter/**"
           ],
@@ -87,6 +88,7 @@
           "exclude": [
             "JSI/**",
             "Tests/**",
+            "WorkletsTests/**",
             "BridgeModule/**",
             "Views/**",
             "Worklets/**",