expo-modules-core 56.0.15 → 56.0.16

package/CHANGELOG.md

@@ -10,6 +10,22 @@
 
 ### 💡 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

package/android/build.gradle

@@ -27,7 +27,7 @@ if (shouldIncludeCompose) {
 }
 
 group = 'host.exp.exponent'
-version = '56.0.15'
+version = '56.0.16'
 
 def isExpoModulesCoreTests = {
   Gradle gradle = getGradle()
@@ -94,7 +94,7 @@ android {
   defaultConfig {
     consumerProguardFiles 'proguard-rules.pro'
     versionCode 1
-    versionName "56.0.15"
+    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

@@ -511,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/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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-core",
-  "version": "56.0.15",
+  "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.8",
+    "@expo/expo-modules-macros-plugin": "0.2.2",
+    "expo-modules-jsi": "~56.0.9",
     "invariant": "^2.2.4"
   },
   "peerDependencies": {
@@ -66,7 +66,7 @@
     "@types/invariant": "^2.2.33",
     "expo-module-scripts": "56.0.3"
   },
-  "gitHead": "175f1e78e3444ca99ddea473faea6777a0656668",
+  "gitHead": "b1e94a5c1c5b19472a42ca25752a3533699bc46a",
   "scripts": {
     "build": "expo-module build",
     "clean": "expo-module clean",