@expo/expo-modules-macros-plugin 0.8.0 → 0.10.0

package/.github/workflows/swift.yml

@@ -54,6 +54,9 @@ jobs:
           case "$archs" in *x86_64*) ;; *) echo "Missing x86_64 slice"; exit 1;; esac
           arch -arm64 ./ExpoModulesMacros-tool < /dev/null
           arch -x86_64 ./ExpoModulesMacros-tool < /dev/null
+          # With arguments the same binary runs the scanner CLI instead of the plugin server.
+          arch -arm64 ./ExpoModulesMacros-tool --help > /dev/null
+          arch -x86_64 ./ExpoModulesMacros-tool --help > /dev/null
 
       - name: Test
         run: swift test -v

package/apple/Package.swift

@@ -8,19 +8,19 @@ import PackageDescription
 let package = Package(
   name: "ExpoModulesMacros",
   platforms: [.macOS(.v13)],
-  products: [
-    // The scanner CLI. Named `ExpoModulesScanner` (the user-facing tool name) while its target is
-    // `ExpoModulesScannerCLI`; the detection logic lives in the importable `ExpoModulesScanner`
-    // library that both the CLI and the tests depend on.
-    .executable(name: "ExpoModulesScanner", targets: ["ExpoModulesScannerCLI"]),
-  ],
   dependencies: [
     .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "602.0.0-latest")
   ],
   targets: [
+    // The plugin executable doubles as the scanner CLI: the compiler launches it without arguments
+    // and speaks the plugin protocol over stdin, while an invocation with arguments dispatches into
+    // `ScannerCLI` (see the entry point in Plugin.swift). Sharing the binary keeps the package to a
+    // single shipped executable; the scanner adds little on top of the SwiftSyntax the macros
+    // already link.
     .macro(
       name: "ExpoModulesMacros",
       dependencies: [
+        "ExpoModulesScanner",
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
       ]
@@ -30,12 +30,9 @@ let package = Package(
       dependencies: [
         .product(name: "SwiftSyntax", package: "swift-syntax"),
         .product(name: "SwiftParser", package: "swift-syntax"),
+        .product(name: "SwiftIfConfig", package: "swift-syntax"),
       ]
     ),
-    .executableTarget(
-      name: "ExpoModulesScannerCLI",
-      dependencies: ["ExpoModulesScanner"]
-    ),
   ]
 )
 

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -166,8 +166,8 @@ internal struct JSFunction {
   /// primitive's `decode` is `@inlinable` and lowers to the same direct accessor a hand-rolled fast
   /// path would use.
   private func decodeStatement(at index: Int) -> String {
-    let exprType = expressionType(parameters[index].type.trimmedDescription)
-    return "let arg\(index) = try \(exprType).decode(arguments.unownedValue(at: \(index)), in: runtime)"
+    let type = parameters[index].type.trimmedDescription
+    return "let arg\(index) = try \(decodeCall(type, from: "arguments.unownedValue(at: \(index))"))"
   }
 
   /// The `<callee>.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
@@ -332,8 +332,7 @@ internal struct JSProperty {
     // getter-only (a settable var with neither an annotation nor a literal default is rare and can't
     // be decoded).
     if isSettable, let valueType {
-      let exprType = expressionType(valueType)
-      let setDecode = "\(callee).\(swiftName) = try \(exprType).decode(arguments.unownedValue(at: 0), in: runtime)"
+      let setDecode = "\(callee).\(swiftName) = try \(decodeCall(valueType, from: "arguments.unownedValue(at: 0)"))"
       lines.append(
         accessorClosure(
           descriptorName, "set", receiver: receiver, body: "\(unwrap)\(setDecode)\nreturn .undefined"))

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -151,6 +151,13 @@ extension ExpoModuleMacro: MemberAttributeMacro {
       attributes.append("@JavaScriptActor")
     }
 
+    // `@JS(.concurrent)` is the inverse: instead of the JS-thread stamp the member gets
+    // `@concurrent`, so its body runs on the concurrent pool. `shouldStampJavaScriptActor` already
+    // skipped the stamp above, leaving the two mutually exclusive.
+    if isConcurrentJSMember(member) {
+      attributes.append("@concurrent")
+    }
+
     // Apply the result builder to `definition()` so the user doesn't have to. Skipped if
     // they already wrote `@ModuleDefinitionBuilder` themselves, which would otherwise be
     // a duplicate attribute.

package/apple/Sources/ExpoModulesMacros/FreeFormTypes.swift

@@ -0,0 +1,59 @@
+/// Recognition of the free-form (`Any`-bearing) boundary types and the spellings the macros emit or
+/// suggest for them. None of these types can conform to the JS codable protocols (`Any` can't conform
+/// to a protocol, and the container conditional conformances require the element/value to conform), so
+/// they can't cross the boundary through the usual `T.decode` / `T.encode` path. Instead they're
+/// accepted **only** in decode position (function/constructor arguments), decoded through a dedicated
+/// `JavaScriptValue.decodeAny…` entry point; a free-form return or getter is rejected, since there's
+/// no free-form encode.
+///
+/// Shared across the macro pipeline: `TypeConformanceAssertion` skips them, `MacroHelpers.decodeCall`
+/// reroutes their decode, and `JSMacro` uses them for the steering diagnostics.
+
+/// The free-form boundary types: an untyped value (`Any`), an untyped array (`[Any]`), and an untyped
+/// string-keyed dictionary (`[String: Any]`). Matched by whitespace-normalized spelling so
+/// `[String: Any]` and `[String : Any]` both count.
+private let freeFormBoundaryTypes: Set<String> = ["Any", "[Any]", "[String:Any]"]
+
+/// The `JavaScriptValue.decodeAny…` method the binding calls to decode a free-form argument, keyed by
+/// the free-form type's normalized spelling. `nil` for any non-free-form type.
+private let freeFormDecodeMethods: [String: String] = [
+  "Any": "decodeAny",
+  "[Any]": "decodeAnyArray",
+  "[String:Any]": "decodeAnyDictionary",
+]
+
+/// The type-safe alternative a free-form type's diagnostic steers to: the same shape with the `Any`
+/// element replaced by `JavaScriptValue`, which conforms to the codable protocols. Keyed by the
+/// free-form type's normalized spelling; spelled with conventional spacing for the message.
+private let typedFreeFormReplacements: [String: String] = [
+  "Any": "JavaScriptValue",
+  "[Any]": "[JavaScriptValue]",
+  "[String:Any]": "[String: JavaScriptValue]",
+]
+
+/// True when a boundary type (as written) is one of the free-form spellings, ignoring internal
+/// whitespace so `[String: Any]` and `[String :Any]` both match. Optionals are not free-form here: a
+/// trailing `?` would route through `Optional.decode`, which free-form can't satisfy, so an optional
+/// free-form type isn't recognized and stays a normal (failing) assertion.
+internal func isFreeFormBoundaryType(_ type: String) -> Bool {
+  return freeFormBoundaryTypes.contains(normalizedTypeSpelling(type))
+}
+
+/// The `JavaScriptValue.decodeAny…` method name for a free-form boundary type, or `nil` when the type
+/// isn't free-form. The binding emits `JavaScriptValue.<method>(arguments.unownedValue(at:), in:)` in
+/// place of the type's own `.decode`.
+internal func freeFormDecodeMethod(for type: String) -> String? {
+  return freeFormDecodeMethods[normalizedTypeSpelling(type)]
+}
+
+/// The type-safe alternative to suggest in place of a free-form type (its `Any` element replaced by
+/// `JavaScriptValue`), or `nil` when the type isn't free-form.
+internal func typedFreeFormReplacement(for type: String) -> String? {
+  return typedFreeFormReplacements[normalizedTypeSpelling(type)]
+}
+
+/// A type spelling with all whitespace removed, so spelling variations of the same type
+/// (`[String: Any]` vs `[String :Any]`) compare equal.
+private func normalizedTypeSpelling(_ type: String) -> String {
+  return type.filter { !$0.isWhitespace }
+}

package/apple/Sources/ExpoModulesMacros/JSConstructor.swift

@@ -27,8 +27,8 @@ internal struct JSConstructor {
 
     var callArguments: [String] = []
     for (index, parameter) in parameters.enumerated() {
-      let exprType = expressionType(parameter.type.trimmedDescription)
-      lines.append("let arg\(index) = try \(exprType).decode(arguments.unownedValue(at: \(index)), in: runtime)")
+      let type = parameter.type.trimmedDescription
+      lines.append("let arg\(index) = try \(decodeCall(type, from: "arguments.unownedValue(at: \(index))"))")
 
       let label = parameter.firstName.text
       callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -1,3 +1,4 @@
+import SwiftDiagnostics
 import SwiftSyntax
 import SwiftSyntaxMacros
 
@@ -30,6 +31,9 @@ public struct JSMacro: PeerMacro {
     providingPeersOf declaration: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
+    diagnoseFreeFormTypes(in: declaration, in: context)
+    diagnoseConcurrentOption(of: node, on: declaration, in: context)
+
     guard let member = boundaryMember(of: declaration),
       let assertion = directionalConformanceAssertion(
         name: member.name,
@@ -43,6 +47,190 @@ public struct JSMacro: PeerMacro {
   }
 }
 
+/// Emits the diagnostic for `@JS(.concurrent)` on a member that can't take it. The option maps to
+/// Swift's `@concurrent`, which requires an `async` function: a synchronous member has nowhere to
+/// suspend, and a property or initializer can't be async at all. Diagnosing here points at the
+/// user's own `@JS` attribute rather than at the `@concurrent` the module macro would attach.
+private func diagnoseConcurrentOption(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  guard hasJSOption(node, named: "concurrent") else {
+    return
+  }
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    guard funcDecl.signature.effectSpecifiers?.asyncSpecifier == nil else {
+      return
+    }
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "'.concurrent' needs an 'async' function: a synchronous @JS member runs on the JavaScript thread by definition. Mark the function 'async' to run its body off that thread.",
+          id: "js-concurrent-requires-async",
+          severity: .error
+        ),
+        fixIts: [insertAsyncFixIt(for: funcDecl)]))
+    return
+  }
+  context.diagnose(
+    Diagnostic(
+      node: node,
+      message: JSDiagnosticMessage(
+        "'.concurrent' applies only to an 'async' @JS function, not to a property or initializer.",
+        id: "js-concurrent-requires-function",
+        severity: .error
+      )))
+}
+
+/// The fix-it offered alongside the synchronous-function diagnostic: insert `async` into the
+/// signature so `@JS(.concurrent)` becomes valid. The macro can't add the keyword itself (no macro
+/// role rewrites the declaration it's attached to), but Xcode can apply this in one click.
+///
+/// `async` goes at the front of the effect specifiers, ahead of any `throws`, which is the only
+/// order Swift accepts. When the signature has no effect specifiers yet, the new clause inherits
+/// what the parameter clause had trailing it and the parameter clause is left with a single space,
+/// so `() -> Int` becomes `() async -> Int` rather than `() async-> Int`.
+private func insertAsyncFixIt(for funcDecl: FunctionDeclSyntax) -> FixIt {
+  let signature = funcDecl.signature
+  var newSignature = signature
+
+  if var effectSpecifiers = signature.effectSpecifiers {
+    effectSpecifiers.asyncSpecifier = .keyword(.async, trailingTrivia: .space)
+    newSignature.effectSpecifiers = effectSpecifiers
+  } else {
+    newSignature.effectSpecifiers = FunctionEffectSpecifiersSyntax(
+      asyncSpecifier: .keyword(.async, trailingTrivia: signature.parameterClause.trailingTrivia)
+    )
+    newSignature.parameterClause.trailingTrivia = .space
+  }
+
+  return FixIt(
+    message: JSFixItMessage("Mark the function 'async'", id: "js-concurrent-insert-async"),
+    changes: [.replace(oldNode: Syntax(signature), newNode: Syntax(newSignature))]
+  )
+}
+
+/// Emits the free-form (`Any` / `[Any]` / `[String: Any]`) diagnostics for a `@JS` declaration.
+///
+/// A free-form type is only supported crossing the boundary as an **argument**, decoded through
+/// `JavaScriptValue.decodeAny…`; there is no free-form encode, so any position that encodes is a hard
+/// error. That means:
+/// - a function/constructor **parameter** typed free-form gets a warning steering to
+///   `[String: JavaScriptValue]` (the type-safe alternative), but compiles;
+/// - a function **return** typed free-form is an error (it would need to encode);
+/// - a **property** typed free-form is an error regardless of settability, because its getter always
+///   encodes.
+///
+/// Types are matched by their written spelling on the type node, so the diagnostic points at the
+/// offending type in the user's source.
+private func diagnoseFreeFormTypes(
+  in declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    warnFreeFormArguments(funcDecl.signature.parameterClause.parameters, in: context)
+    if let returnType = funcDecl.signature.returnClause?.type,
+      isFreeFormBoundaryType(returnType.trimmedDescription) {
+      context.diagnose(
+        Diagnostic(node: returnType, message: freeFormReturnError(for: returnType.trimmedDescription)))
+    }
+    return
+  }
+
+  // A constructor decodes its arguments exactly like a function; it has no return value to encode, so
+  // only the argument warning applies.
+  if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    warnFreeFormArguments(initDecl.signature.parameterClause.parameters, in: context)
+    return
+  }
+
+  if let varDecl = declaration.as(VariableDeclSyntax.self),
+    let type = varDecl.bindings.first?.typeAnnotation?.type,
+    isFreeFormBoundaryType(type.trimmedDescription) {
+    context.diagnose(
+      Diagnostic(node: type, message: freeFormPropertyError(for: type.trimmedDescription)))
+  }
+}
+
+/// The tail of a free-form encode error: the reshaped `JavaScriptValue` alternative when the type is a
+/// container (`[String: Any]` -> `[String: JavaScriptValue]`), otherwise the passthrough suggestion
+/// for a bare `Any`. Both conform to the codable protocols, so either is a valid fix.
+private func suggestedAlternative(for freeFormType: String) -> String {
+  if let reshaped = typedFreeFormReplacement(for: freeFormType), reshaped != "JavaScriptValue" {
+    return "Use '\(reshaped)', or 'JavaScriptValue' to pass a JS value through unchanged."
+  }
+  return "Use a concrete type, or 'JavaScriptValue' to pass a JS value through unchanged."
+}
+
+/// Emits the steering warning for each free-form parameter in a list. Shared by the function and
+/// constructor cases, which both decode their arguments through the same path.
+private func warnFreeFormArguments(
+  _ parameters: FunctionParameterListSyntax,
+  in context: some MacroExpansionContext
+) {
+  for parameter in parameters {
+    let type = parameter.type.trimmedDescription
+    guard let suggested = typedFreeFormReplacement(for: type) else {
+      continue
+    }
+    context.diagnose(
+      Diagnostic(
+        node: parameter.type,
+        message: freeFormArgumentWarning(for: type, suggesting: suggested)))
+  }
+}
+
+private func freeFormArgumentWarning(
+  for freeFormType: String,
+  suggesting suggestedType: String
+) -> JSDiagnosticMessage {
+  return JSDiagnosticMessage(
+    "Prefer '\(suggestedType)' over the free-form '\(freeFormType)' for a @JS argument. Free-form decoding boxes every value as 'Any' (slower, no static typing); the 'JavaScriptValue' element keeps each value inspectable without erasing it.",
+    id: "js-free-form-argument",
+    severity: .warning
+  )
+}
+
+private func freeFormReturnError(for freeFormType: String) -> JSDiagnosticMessage {
+  return JSDiagnosticMessage(
+    "A @JS function can't return the free-form '\(freeFormType)': there's no way to encode an untyped value back to JavaScript. \(suggestedAlternative(for: freeFormType))",
+    id: "js-free-form-return",
+    severity: .error
+  )
+}
+
+private func freeFormPropertyError(for freeFormType: String) -> JSDiagnosticMessage {
+  return JSDiagnosticMessage(
+    "A @JS property can't have the free-form '\(freeFormType)': its getter would have to encode an untyped value back to JavaScript, which isn't supported. \(suggestedAlternative(for: freeFormType))",
+    id: "js-free-form-property",
+    severity: .error
+  )
+}
+
+private struct JSDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity
+
+  init(_ message: String, id: String, severity: DiagnosticSeverity) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+    self.severity = severity
+  }
+}
+
+private struct JSFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
 /// What an assertion peer needs about the `@JS` member it sits beside: a name (to keep the peer unique
 /// among siblings), the boundary types split by conversion direction, and whether the member is
 /// type-level. Arguments (and a settable property's incoming value) are decoded; return values (and a

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -31,6 +31,44 @@ internal func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool
   return nil
 }
 
+/// True if the attribute lists the given `JSOptions` member, e.g. `@JS(.concurrent)` or
+/// `@JS("name", [.concurrent])` -> true for "concurrent". Options are written as member-access
+/// expressions (`.concurrent`), optionally inside an array literal when more than one is combined, so
+/// both spellings are scanned. The leading string literal, when present, is the JS name and is skipped.
+internal func hasJSOption(_ attribute: AttributeSyntax, named option: String) -> Bool {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return false
+  }
+  for arg in args {
+    if namesOption(arg.expression, option) {
+      return true
+    }
+    if let array = arg.expression.as(ArrayExprSyntax.self),
+      array.elements.contains(where: { namesOption($0.expression, option) }) {
+      return true
+    }
+  }
+  return false
+}
+
+/// True when the expression is the member access `.<option>` (or `JSOptions.<option>`).
+private func namesOption(_ expression: ExprSyntax, _ option: String) -> Bool {
+  guard let member = expression.as(MemberAccessExprSyntax.self) else {
+    return false
+  }
+  return member.declName.baseName.text == option
+}
+
+/// True if the `@JS`-marked declaration opted into running off the JavaScript thread with
+/// `@JS(.concurrent)`. Such a member is left unstamped and gets `@concurrent` instead, so its body
+/// runs on the concurrent pool rather than inheriting the JS thread.
+internal func isConcurrentJSMember(_ decl: DeclSyntaxProtocol) -> Bool {
+  guard let attribute = memberAttributes(of: decl).firstAttribute(named: "JS") else {
+    return false
+  }
+  return hasJSOption(attribute, named: "concurrent")
+}
+
 /// True if the type is written as an optional: `T?`, `T!`, or the explicit `Optional<T>`. Used to
 /// decide argument requiredness (an optional parameter may be omitted) and record-field nullability.
 internal func isOptionalType(_ type: TypeSyntax) -> Bool {
@@ -156,6 +194,7 @@ internal func memberHasJSAttribute(_ decl: DeclSyntaxProtocol) -> Bool {
 
 /// Decides whether the macro should stamp `@JavaScriptActor` on a `@JS`-marked member.
 /// The macro defers to the user when they've already chosen an isolation:
+/// - the member opted out with `@JS(.concurrent)`
 /// - the `nonisolated` modifier is present on the member
 /// - any attribute whose name matches a known global actor (`@MainActor`, `@JavaScriptActor`)
 ///   or follows the `*Actor` naming convention is present on the member or its enclosing type
@@ -165,6 +204,10 @@ internal func shouldStampJavaScriptActor(
   on member: DeclSyntaxProtocol,
   enclosedBy enclosing: some DeclGroupSyntax
 ) -> Bool {
+  if isConcurrentJSMember(member) {
+    return false
+  }
+
   let modifiers = memberModifiers(of: member)
   if modifiers.contains(where: { $0.name.text == "nonisolated" }) {
     return false
@@ -261,6 +304,18 @@ internal func expressionType(_ type: String) -> String {
   return type.dropLast() + "?"
 }
 
+/// The decode expression for a boundary type read from `valueExpression` (a `JavaScriptUnownedValue`),
+/// as it appears after `try`. A free-form type (`Any`, `[Any]`, `[String: Any]`) can't conform to
+/// `JavaScriptDecodable`, so it decodes through the dedicated `JavaScriptValue.decodeAny…` entry point
+/// keyed to its shape; every other type decodes through its own static `decode`, spelled in expression
+/// position (`T!` rewritten to `T?`).
+internal func decodeCall(_ type: String, from valueExpression: String) -> String {
+  if let method = freeFormDecodeMethod(for: type) {
+    return "JavaScriptValue.\(method)(\(valueExpression), in: runtime)"
+  }
+  return "\(expressionType(type)).decode(\(valueExpression), in: runtime)"
+}
+
 // MARK: - @JS property collection
 
 /// Collects the `@JS var` bindings of a declaration into `JSProperty` values for direct JSI binding.
@@ -314,3 +369,25 @@ internal func bindingIsSettable(_ binding: PatternBindingSyntax) -> Bool {
     return false
   }
 }
+
+/// True if the type's inheritance clause already lists a protocol with the given name. Matches
+/// either the bare identifier (`Record`) or a qualified member access ending in the name
+/// (`ExpoModulesCore.Record`). Used by the extension macros to skip a conformance the author already
+/// spelled out. Works for `struct`, `class`, and `enum` declarations; any other declaration kind has no
+/// inheritance clause to read and reports `false`.
+internal func inheritsProtocol(named name: String, in declaration: some DeclGroupSyntax) -> Bool {
+  let inheritanceClause: InheritanceClauseSyntax?
+  if let structDecl = declaration.as(StructDeclSyntax.self) {
+    inheritanceClause = structDecl.inheritanceClause
+  } else if let classDecl = declaration.as(ClassDeclSyntax.self) {
+    inheritanceClause = classDecl.inheritanceClause
+  } else if let enumDecl = declaration.as(EnumDeclSyntax.self) {
+    inheritanceClause = enumDecl.inheritanceClause
+  } else {
+    return false
+  }
+  guard let inherited = inheritanceClause?.inheritedTypes else {
+    return false
+  }
+  return inherited.contains { baseIdentifier(of: $0.type) == name }
+}

package/apple/Sources/ExpoModulesMacros/Plugin.swift

@@ -1,7 +1,8 @@
+import ExpoModulesScanner
+import Foundation
 import SwiftCompilerPlugin
 import SwiftSyntaxMacros
 
-@main
 struct ExpoModulesMacrosPlugin: CompilerPlugin {
   let providingMacros: [Macro.Type] = [
     OptimizedFunctionAttachedMacro.self,
@@ -10,5 +11,22 @@ struct ExpoModulesMacrosPlugin: CompilerPlugin {
     ExpoModuleMacro.self,
     SharedObjectMacro.self,
     RecordMacro.self,
+    UnionMacro.self,
   ]
 }
+
+/// The executable doubles as the scanner CLI. The compiler always launches a plugin executable
+/// without arguments and speaks the plugin protocol over stdin, so any argument means a scanner
+/// invocation (`ExpoModulesMacros-tool scan-modules <path>...`); with none, this starts the plugin
+/// server exactly as `@main` on the `CompilerPlugin` type would.
+@main
+enum EntryPoint {
+  static func main() throws {
+    let arguments = Array(CommandLine.arguments.dropFirst())
+    if arguments.isEmpty {
+      try ExpoModulesMacrosPlugin.main()
+    } else {
+      exit(ScannerCLI.run(arguments: arguments))
+    }
+  }
+}

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -478,37 +478,6 @@ private func isExcludedByModifier(_ modifiers: DeclModifierListSyntax) -> Bool {
   return false
 }
 
-/**
- True if the type's inheritance clause already lists a protocol with the given name.
- Matches either the bare identifier (`Record`) or a qualified member access ending in
- the name (`ExpoModulesCore.Record`).
- */
-private func inheritsProtocol(named name: String, in declaration: some DeclGroupSyntax) -> Bool {
-  let inheritanceClause: InheritanceClauseSyntax?
-  if let structDecl = declaration.as(StructDeclSyntax.self) {
-    inheritanceClause = structDecl.inheritanceClause
-  } else if let classDecl = declaration.as(ClassDeclSyntax.self) {
-    inheritanceClause = classDecl.inheritanceClause
-  } else {
-    return false
-  }
-  guard let inherited = inheritanceClause?.inheritedTypes else {
-    return false
-  }
-  for entry in inherited {
-    let typeSyntax = entry.type
-    if let identifier = typeSyntax.as(IdentifierTypeSyntax.self),
-      identifier.name.text == name {
-      return true
-    }
-    if let member = typeSyntax.as(MemberTypeSyntax.self),
-      member.name.text == name {
-      return true
-    }
-  }
-  return false
-}
-
 /**
  True if the class declaration has any inheritance clause. Used as a heuristic for
  whether the superclass also conforms to `Record` and provides the synthesized methods;

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -141,8 +141,14 @@ extension SharedObjectMacro: MemberAttributeMacro {
     // `@Event(sync: true)` members are stamped alongside `@JS` ones: a sync event dispatches
     // inline, so the isolation forces its call site onto the JS thread. Async events (the
     // default) stay unstamped — their `emit` schedules onto the JS thread itself.
-    guard memberHasJSAttribute(member) || isSyncEventMember(member),
-      shouldStampJavaScriptActor(on: member, enclosedBy: declaration) else {
+    guard memberHasJSAttribute(member) || isSyncEventMember(member) else {
+      return []
+    }
+    // `@JS(.concurrent)` opts the member out of the JS-thread stamp and onto the concurrent pool.
+    if isConcurrentJSMember(member) {
+      return ["@concurrent"]
+    }
+    guard shouldStampJavaScriptActor(on: member, enclosedBy: declaration) else {
       return []
     }
     return ["@JavaScriptActor"]

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -21,6 +21,12 @@ internal let javaScriptEncodableProtocolName = "JavaScriptEncodable"
 /// support both directions, so the assertion requires the intersection.
 internal let recordFieldProtocolName = "AnyArgument & JavaScriptDecodable & JavaScriptEncodable"
 
+/// The constraint a `@Union` case payload type must satisfy: the union decodes by trying each payload's
+/// `decode` and encodes through the matching payload's `encode`, so every alternative must convert in
+/// both directions. Unlike a `@Record` field, a union never crosses the native-`Any` dictionary path, so
+/// `AnyArgument` is not required.
+internal let unionPayloadProtocolName = "JavaScriptDecodable & JavaScriptEncodable"
+
 /// The protocol a type must conform to for `self.emit(event:…)` to resolve; core conforms
 /// `BaseModule` and `SharedObject` to it. Asserted by `@Event` so attaching it to a type that can't
 /// emit fails with a conformance diagnostic instead of an opaque "no member 'emit'" error.
@@ -116,11 +122,15 @@ internal func typeConformanceAssertions(
     """
 }
 
-/// The type to assert for a boundary type as written: trailing optional markers are unwrapped to the
-/// core type, and a known-conforming primitive returns `nil` (nothing to assert). Shared with
-/// `@Event`, which folds its single payload type into a combined assertion of its own shape rather
-/// than reusing the whole body fragment below.
+/// The type to assert for a boundary type as written, or `nil` when nothing needs asserting: an
+/// exactly-free-form type (handled by the binding's `decodeAny…` reroute) and a known-conforming
+/// primitive both return `nil`; everything else is unwrapped of trailing optionals and asserted. An
+/// *optional* free-form (`[String: Any]?`) isn't rerouted and doesn't conform, so it's kept and
+/// asserted for a clean diagnostic. Shared with `@Event`.
 internal func assertableBoundaryType(_ type: String) -> String? {
+  guard !isFreeFormBoundaryType(type) else {
+    return nil
+  }
   let unwrapped = unwrappedOptional(type)
   return knownConformingPrimitives.contains(unwrapped) ? nil : unwrapped
 }
@@ -144,14 +154,12 @@ private func conformanceAssertionBody(
   return lines.joined(separator: "\n")
 }
 
-/// Normalizes a list of boundary types for assertion: unwraps each to its core type (trailing
-/// optionals stripped), drops the known-conforming primitives that never need asserting, and dedups
-/// while preserving first-seen order so a type is asserted once even when it appears more than once.
+/// The distinct types to assert from a list, mapping each through `assertableBoundaryType` (which
+/// drops what needs no assertion) and deduping in first-seen order.
 private func distinctAssertableTypes(_ types: [String]) -> [String] {
   var seen: Set<String> = []
   var distinct: [String] = []
-  for type in types.map(unwrappedOptional)
-  where !knownConformingPrimitives.contains(type) && seen.insert(type).inserted {
+  for type in types.compactMap(assertableBoundaryType) where seen.insert(type).inserted {
     distinct.append(type)
   }
   return distinct