expo-modules-macros 0.21.0 → 0.23.0

package/apple/Sources/ExpoModulesScanner/Exports/ResolveRefs.swift

@@ -44,7 +44,11 @@ struct RefIndex {
     }
     for sharedObject in surface.sharedObjects {
       entries[sharedObject.name] = Entry(
-        name: sharedObject.name, kind: .sharedObject, jsType: .object, jsName: sharedObject.jsName)
+        name: sharedObject.name,
+        kind: .sharedObject,
+        jsType: .object,
+        jsName: sharedObject.jsName
+      )
     }
     for union in surface.unions {
       // A union crosses as whichever alternative matched, so its category is only meaningful per
@@ -53,7 +57,10 @@ struct RefIndex {
     }
     for enumeration in surface.enums {
       entries[enumeration.name] = Entry(
-        name: enumeration.name, kind: .enum, jsType: jsType(ofRawType: enumeration.rawType))
+        name: enumeration.name,
+        kind: .enum,
+        jsType: jsType(ofRawType: enumeration.rawType)
+      )
     }
   }
 
@@ -105,6 +112,9 @@ extension TypeNode {
     switch self {
     case .primitive, .unknown:
       return self
+    case .sharedRef:
+      // The native type never reaches JS, so it isn't looked up among the scanned declarations.
+      return self
     case .ref(let name, _, _):
       guard let entry = index.lookup(name, in: scope) else {
         return self
@@ -113,7 +123,8 @@ extension TypeNode {
       return .ref(
         name: entry.name,
         refKind: entry.kind,
-        jsTypeOverride: entry.jsType == .object ? nil : entry.jsType)
+        jsTypeOverride: entry.jsType == .object ? nil : entry.jsType
+      )
     case .optional(let wrapped):
       return .optional(wrapped: wrapped.resolvingRefs(using: index, in: scope))
     case .array(let element):
@@ -121,7 +132,8 @@ extension TypeNode {
     case .dictionary(let key, let value):
       return .dictionary(
         key: key.resolvingRefs(using: index, in: scope),
-        value: value.resolvingRefs(using: index, in: scope))
+        value: value.resolvingRefs(using: index, in: scope)
+      )
     case .promise(let value):
       return .promise(value: value.resolvingRefs(using: index, in: scope))
     case .function(let parameters, let returns, let isAsync, let isThrowing):
@@ -153,7 +165,8 @@ extension ExportedSurface {
         resolved.events = module.events.map { $0.resolvingRefs(using: index, in: module.name) }
         resolved.classes = module.classes.map { exportedClass in
           guard let entry = index.lookup(exportedClass.name, in: module.name),
-            entry.kind == .sharedObject else {
+            entry.kind == .sharedObject
+          else {
             return exportedClass
           }
           return ExportedClass(name: entry.name, jsName: entry.jsName)

package/apple/Sources/ExpoModulesScanner/Exports/ScanExports.swift

@@ -1,10 +1,11 @@
+import SwiftParser
+import SwiftSyntax
+
 #if canImport(FoundationEssentials)
 import FoundationEssentials
 #else
 import Foundation
 #endif
-import SwiftParser
-import SwiftSyntax
 
 extension Scanner {
   /// Runs `scan-exports` over `paths`, prints the JSON report to stdout, and returns the exit code
@@ -58,7 +59,11 @@ func scanExports(paths: [String]) -> ScanExportsResult {
   // Refs resolve only once every file has been walked: a type parsed in one file may name a type
   // declared in another, so the full set of declarations has to exist before any lookup is valid.
   let surface = ExportedSurface(
-    modules: modules, sharedObjects: sharedObjects, records: records, enums: enums, unions: unions
+    modules: modules,
+    sharedObjects: sharedObjects,
+    records: records,
+    enums: enums,
+    unions: unions
   ).resolvingRefs()
 
   return ScanExportsResult(

package/apple/Sources/ExpoModulesScanner/Exports/SurfaceVisitor.swift

@@ -100,7 +100,8 @@ final class SurfaceVisitor: SyntaxVisitor {
           accessLevel: spelledAccessLevel(of: node.modifiers),
           platforms: platforms,
           file: file
-        ))
+        )
+      )
     } else if inherits(from: enumerableConformanceName, in: node.inheritanceClause) {
       let rawType = rawValueType(of: node.inheritanceClause)
       enums.append(
@@ -111,7 +112,8 @@ final class SurfaceVisitor: SyntaxVisitor {
           accessLevel: spelledAccessLevel(of: node.modifiers),
           platforms: platforms,
           file: file
-        ))
+        )
+      )
     }
     // An enum is often a namespace for other types, so its body is searched too.
     return .visitChildren
@@ -156,7 +158,8 @@ final class SurfaceVisitor: SyntaxVisitor {
           accessLevel: accessLevel,
           platforms: platforms,
           file: file
-        ))
+        )
+      )
       return
     }
 
@@ -167,13 +170,15 @@ final class SurfaceVisitor: SyntaxVisitor {
           name: qualified,
           jsName: stringArgument(of: attribute) ?? name,
           initializer: initializer,
+          sharedRef: sharedRefSuperclass(of: node),
           functions: functions,
           properties: properties,
           events: events,
           accessLevel: accessLevel,
           platforms: platforms,
           file: file
-        ))
+        )
+      )
       return
     }
 
@@ -185,7 +190,8 @@ final class SurfaceVisitor: SyntaxVisitor {
           accessLevel: accessLevel,
           platforms: platforms,
           file: file
-        ))
+        )
+      )
     }
   }
 
@@ -214,7 +220,8 @@ final class SurfaceVisitor: SyntaxVisitor {
 
       if let varDecl = decl.as(VariableDeclSyntax.self),
         varDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue) == nil,
-        let attribute = varDecl.attributes.firstAttribute(named: DetectedMacro.event.rawValue) {
+        let attribute = varDecl.attributes.firstAttribute(named: DetectedMacro.event.rawValue)
+      {
         events.append(contentsOf: makeEvents(varDecl: varDecl, attribute: attribute, platforms: platforms))
         continue
       }
@@ -224,7 +231,8 @@ final class SurfaceVisitor: SyntaxVisitor {
       }
 
       if let initDecl = decl.as(InitializerDeclSyntax.self),
-        initDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue) != nil {
+        initDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue) != nil
+      {
         // At most one `@JS init`; keep the first if a malformed source has more (the macro errors).
         if initializer == nil {
           initializer = ExportedInitializer(
@@ -237,13 +245,15 @@ final class SurfaceVisitor: SyntaxVisitor {
       }
 
       if let funcDecl = decl.as(FunctionDeclSyntax.self),
-        let attribute = funcDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue) {
-        functions.append(makeFunction(funcDecl: funcDecl, attribute: attribute, platforms: platforms))
+        let attribute = funcDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue)
+      {
+        functions.append(contentsOf: makeFunctions(funcDecl: funcDecl, attribute: attribute, platforms: platforms))
         continue
       }
 
       if let varDecl = decl.as(VariableDeclSyntax.self),
-        let attribute = varDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue) {
+        let attribute = varDecl.attributes.firstAttribute(named: DetectedMacro.js.rawValue)
+      {
         properties.append(contentsOf: makeProperties(varDecl: varDecl, attribute: attribute, platforms: platforms))
       }
     }
@@ -256,10 +266,13 @@ final class SurfaceVisitor: SyntaxVisitor {
   /// reporting one would describe a surface that does not exist. `@JS` on the same property is
   /// caught by the caller, which reaches the `@JS` branch first.
   private func makeEvents(
-    varDecl: VariableDeclSyntax, attribute: AttributeSyntax, platforms: [ExportedPlatform]
+    varDecl: VariableDeclSyntax,
+    attribute: AttributeSyntax,
+    platforms: [ExportedPlatform]
   ) -> [ExportedEvent] {
     guard varDecl.bindingSpecifier.tokenKind != .keyword(.let),
-      !isTypeLevel(varDecl.modifiers) else {
+      !isTypeLevel(varDecl.modifiers)
+    else {
       return []
     }
     let override = stringArgument(of: attribute)
@@ -274,7 +287,8 @@ final class SurfaceVisitor: SyntaxVisitor {
         binding.accessorBlock == nil,
         let functionType = underlyingFunctionType(of: binding.typeAnnotation?.type),
         isVoidEventReturn(functionType.returnClause.type),
-        functionType.parameters.count <= 1 else {
+        functionType.parameters.count <= 1
+      else {
         continue
       }
       let name = ident.identifier.identifierName
@@ -286,38 +300,57 @@ final class SurfaceVisitor: SyntaxVisitor {
           isSync: isSync,
           accessLevel: spelledAccessLevel(of: varDecl.modifiers),
           platforms: platforms
-        ))
+        )
+      )
     }
     return result
   }
 
-  /// Builds an `ExportedFunction` from a `@JS func`: JS-name fallback, parameters, a `Void` return as
-  /// `nil`, and the effect/static flags.
-  private func makeFunction(
-    funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax, platforms: [ExportedPlatform]
-  ) -> ExportedFunction {
+  /// Builds the `ExportedFunction` entries for a `@JS func`: JS-name fallback, parameters, a `Void`
+  /// return as `nil`, and the effect/static flags. A synchronous function with `.withAsync("name")`
+  /// gets a second, `async` entry under that name, for the promise-returning variant the macro binds.
+  private func makeFunctions(
+    funcDecl: FunctionDeclSyntax,
+    attribute: AttributeSyntax,
+    platforms: [ExportedPlatform]
+  ) -> [ExportedFunction] {
     let effects = funcDecl.signature.effectSpecifiers
     let returnType = funcDecl.signature.returnClause?.type
-    return ExportedFunction(
-      name: funcDecl.name.identifierName,
-      jsName: stringArgument(of: attribute) ?? funcDecl.name.identifierName,
-      parameters: parameters(of: funcDecl.signature.parameterClause),
-      returns: isVoidType(returnType) ? nil : returnType.map { typeNode(from: $0) },
-      isAsync: effects?.asyncSpecifier != nil,
-      isThrowing: effects?.throwsClause?.throwsSpecifier != nil,
-      isStatic: isTypeLevel(funcDecl.modifiers),
-      accessLevel: spelledAccessLevel(of: funcDecl.modifiers),
-      platforms: platforms
-    )
+    let isAsync = effects?.asyncSpecifier != nil
+    let exportedParameters = parameters(of: funcDecl.signature.parameterClause)
+    let returns = isVoidType(returnType) ? nil : returnType.map { typeNode(from: $0) }
+    let makeFunction = { (jsName: String, isAsync: Bool) in
+      ExportedFunction(
+        name: funcDecl.name.identifierName,
+        jsName: jsName,
+        parameters: exportedParameters,
+        returns: returns,
+        isAsync: isAsync,
+        isThrowing: effects?.throwsClause?.throwsSpecifier != nil,
+        isStatic: isTypeLevel(funcDecl.modifiers),
+        accessLevel: spelledAccessLevel(of: funcDecl.modifiers),
+        platforms: platforms
+      )
+    }
+    let function = makeFunction(stringArgument(of: attribute) ?? funcDecl.name.identifierName, isAsync)
+    // The macro binds no variant for an `async` function: it reports the option there instead.
+    guard !isAsync, let variantName = asyncVariantName(of: attribute) else {
+      return [function]
+    }
+    return [function, makeFunction(variantName, true)]
   }
 
   /// Builds the `ExportedProperty` entries for a `@JS var`/`let`. One declaration can introduce several
   /// bindings (`var a, b: Int`), so this returns an array. The value type is the annotation, else the
   /// literal default's inferred type, else `nil`.
   private func makeProperties(
-    varDecl: VariableDeclSyntax, attribute: AttributeSyntax, platforms: [ExportedPlatform]
+    varDecl: VariableDeclSyntax,
+    attribute: AttributeSyntax,
+    platforms: [ExportedPlatform]
   ) -> [ExportedProperty] {
     let isLet = varDecl.bindingSpecifier.tokenKind == .keyword(.let)
+    // A `lazy var` is read-only from JS, like a `let`: the macro binds it getter-only.
+    let isLazy = varDecl.modifiers.contains { $0.name.tokenKind == .keyword(.lazy) }
     let isStatic = isTypeLevel(varDecl.modifiers)
     let override = stringArgument(of: attribute)
     var result: [ExportedProperty] = []
@@ -333,13 +366,14 @@ final class SurfaceVisitor: SyntaxVisitor {
           name: name,
           jsName: override ?? name,
           type: type,
-          isSettable: isSettable(binding: binding, isLet: isLet),
+          isSettable: !isLazy && isSettable(binding: binding, isLet: isLet),
           isStatic: isStatic,
           // Only a stored property has an initializer; a computed one has none to report.
           defaultValue: binding.initializer?.value.trimmedDescription,
           accessLevel: spelledAccessLevel(of: varDecl.modifiers),
           platforms: platforms
-        ))
+        )
+      )
     }
     return result
   }
@@ -380,7 +414,8 @@ final class SurfaceVisitor: SyntaxVisitor {
     // `@Record` reads only the properties written directly in the body, so `#if` is not looked into.
     for member in members {
       guard let varDecl = member.decl.as(VariableDeclSyntax.self),
-        !isExcludedRecordModifier(varDecl.modifiers) else {
+        !isExcludedRecordModifier(varDecl.modifiers)
+      else {
         continue
       }
       let platforms = platformResolver.platforms(of: varDecl)
@@ -406,7 +441,8 @@ final class SurfaceVisitor: SyntaxVisitor {
             defaultValue: binding.initializer?.value.trimmedDescription,
             accessLevel: spelledAccessLevel(of: varDecl.modifiers),
             platforms: platforms
-          ))
+          )
+        )
       }
     }
     return properties
@@ -440,7 +476,8 @@ final class SurfaceVisitor: SyntaxVisitor {
             name: name,
             rawValue: writtenRawValue(of: element) ?? derivedStringRawValue(for: name, rawType: rawType),
             platforms: platforms
-          ))
+          )
+        )
       }
     }
     return cases
@@ -467,12 +504,17 @@ final class SurfaceVisitor: SyntaxVisitor {
       for element in caseDecl.elements {
         guard let parameters = element.parameterClause?.parameters,
           parameters.count == 1, let parameter = parameters.first,
-          parameter.defaultValue == nil else {
+          parameter.defaultValue == nil
+        else {
           continue
         }
         result.append(
           ExportedUnionMember(
-            name: element.name.identifierName, type: typeNode(from: parameter.type), platforms: platforms))
+            name: element.name.identifierName,
+            type: typeNode(from: parameter.type),
+            platforms: platforms
+          )
+        )
       }
     }
     return result
@@ -508,7 +550,8 @@ final class SurfaceVisitor: SyntaxVisitor {
     }
     guard let item = node.parent?.as(MemberBlockItemSyntax.self),
       let parent = declaration(owning: item),
-      let scope = enclosingTypes(of: parent) else {
+      let scope = enclosingTypes(of: parent)
+    else {
       return nil
     }
     if let decl = parent.as(ExtensionDeclSyntax.self) {
@@ -633,7 +676,8 @@ private func underlyingFunctionType(of type: TypeSyntax?) -> FunctionTypeSyntax?
     return underlyingFunctionType(of: attributed.baseType)
   }
   if let tuple = type.as(TupleTypeSyntax.self),
-    tuple.elements.count == 1, let element = tuple.elements.first, element.firstName == nil {
+    tuple.elements.count == 1, let element = tuple.elements.first, element.firstName == nil
+  {
     return underlyingFunctionType(of: element.type)
   }
   return type.as(FunctionTypeSyntax.self)
@@ -643,7 +687,8 @@ private func underlyingFunctionType(of type: TypeSyntax?) -> FunctionTypeSyntax?
 /// accepts neither `Swift.Void` nor a parenthesized `(Void)`, so it would drop valid events.
 private func isVoidEventReturn(_ type: TypeSyntax) -> Bool {
   if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
-    let element = tuple.elements.first, element.firstName == nil {
+    let element = tuple.elements.first, element.firstName == nil
+  {
     return isVoidEventReturn(element.type)
   }
   let text = type.trimmedDescription
@@ -664,6 +709,89 @@ private func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool?
   return nil
 }
 
+/// The name in a `@JS` attribute's `.withAsync("name")` option, in the arguments or inside an array
+/// literal (`@JS("load", [.withAsync("loadAsync")])`), or `nil` when the option is absent or its
+/// argument isn't a plain string literal. Mirrors `asyncVariantOption` and `asyncVariantName` in the
+/// macros.
+private func asyncVariantName(of attribute: AttributeSyntax) -> String? {
+  guard let arguments = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return nil
+  }
+  let expressions = arguments.flatMap { argument -> [ExprSyntax] in
+    if let array = argument.expression.as(ArrayExprSyntax.self) {
+      return array.elements.map(\.expression)
+    }
+    return [argument.expression]
+  }
+  for expression in expressions {
+    guard let call = expression.as(FunctionCallExprSyntax.self),
+      let member = call.calledExpression.as(MemberAccessExprSyntax.self),
+      member.declName.baseName.text == "withAsync"
+    else {
+      continue
+    }
+    guard call.arguments.count == 1,
+      let argument = call.arguments.first,
+      argument.label == nil,
+      let literal = argument.expression.as(StringLiteralExprSyntax.self),
+      literal.segments.count == 1,
+      let segment = literal.segments.first?.as(StringSegmentSyntax.self)
+    else {
+      return nil
+    }
+    return segment.content.text
+  }
+  return nil
+}
+
+/// The `SharedRef<T>` a class names as its superclass, or `nil` when it names another one or none.
+/// Swift requires the superclass to come first in the inheritance clause, so only that entry is read.
+private func sharedRefSuperclass(of node: some DeclGroupSyntax) -> ExportedSharedRef? {
+  guard let superclass = node.inheritanceClause?.inheritedTypes.first?.type,
+    case .sharedRef(let native) = typeNode(from: superclass)
+  else {
+    return nil
+  }
+  return ExportedSharedRef(native: native, nativeRefType: nativeRefType(in: node.memberBlock.members))
+}
+
+/// The value of a `nativeRefType` override that returns a plain string literal: `"image"` in
+/// `override var nativeRefType: String { "image" }`, also with `return` or inside a `get` block.
+/// `unknown`, core's default, when the class declares no `nativeRefType`, and `nil` when its getter is
+/// anything else.
+private func nativeRefType(in members: MemberBlockItemListSyntax) -> String? {
+  let binding = members.lazy
+    .compactMap { $0.decl.as(VariableDeclSyntax.self) }
+    .filter { !isTypeLevel($0.modifiers) }
+    .flatMap { $0.bindings }
+    .first { $0.pattern.as(IdentifierPatternSyntax.self)?.identifier.text == "nativeRefType" }
+  guard let binding else {
+    return "unknown"
+  }
+  let statements: CodeBlockItemListSyntax?
+  switch binding.accessorBlock?.accessors {
+  case .getter(let body):
+    statements = body
+  case .accessors(let accessors):
+    statements = accessors.first { $0.accessorSpecifier.tokenKind == .keyword(.get) }?.body?.statements
+  case nil:
+    statements = nil
+  }
+  guard let statements, statements.count == 1, let item = statements.first?.item else {
+    return nil
+  }
+  let expression = item.as(ReturnStmtSyntax.self)?.expression ?? item.as(ExprSyntax.self)
+  guard let literal = expression?.as(StringLiteralExprSyntax.self),
+    literal.segments.count == 1,
+    let segment = literal.segments.first?.as(StringSegmentSyntax.self)
+  else {
+    return nil
+  }
+  // An escape would need real unescaping, so it's treated as unreadable, as in `writtenRawValue(of:)`.
+  let content = segment.content.text
+  return content.contains("\\") ? nil : content
+}
+
 private func isTypeLevel(_ modifiers: DeclModifierListSyntax) -> Bool {
   modifiers.contains {
     $0.name.tokenKind == .keyword(.static) || $0.name.tokenKind == .keyword(.class)
@@ -721,7 +849,8 @@ private func writtenRawValue(of element: EnumCaseElementSyntax) -> String? {
     return value.trimmedDescription
   }
   guard literal.segments.count == 1,
-    let segment = literal.segments.first?.as(StringSegmentSyntax.self) else {
+    let segment = literal.segments.first?.as(StringSegmentSyntax.self)
+  else {
     return nil
   }
   // The segment's text is the literal's content with its delimiters already stripped, so a plain
@@ -777,7 +906,8 @@ private let knownNonRawValueProtocols: Set<String> = [
 func rawValueType(of clause: InheritanceClauseSyntax?) -> TypeNode? {
   guard let first = clause?.inheritedTypes.first?.type,
     let trailing = first.trimmedDescription.split(separator: ".").last.map(String.init),
-    !knownNonRawValueProtocols.contains(trailing) else {
+    !knownNonRawValueProtocols.contains(trailing)
+  else {
     return nil
   }
   return typeNode(from: first)
@@ -801,7 +931,8 @@ extension AttributeListSyntax {
   fileprivate func firstAttribute(named name: String) -> AttributeSyntax? {
     for element in self {
       if let attribute = element.as(AttributeSyntax.self),
-        attribute.attributeName.trimmedDescription == name {
+        attribute.attributeName.trimmedDescription == name
+      {
         return attribute
       }
     }
@@ -814,14 +945,16 @@ extension AttributeListSyntax {
 /// an array literal. A local copy of the macros' helper (the macro target can't be imported here).
 private func classListArgument(of attribute: AttributeSyntax, label: String) -> [String] {
   guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
-    let array = args.first(where: { $0.label?.text == label })?.expression.as(ArrayExprSyntax.self) else {
+    let array = args.first(where: { $0.label?.text == label })?.expression.as(ArrayExprSyntax.self)
+  else {
     return []
   }
   return array.elements.compactMap { element in
     guard let memberAccess = element.expression.as(MemberAccessExprSyntax.self),
       memberAccess.declName.baseName.text == "self",
       let base = memberAccess.base,
-      base.is(DeclReferenceExprSyntax.self) || base.is(MemberAccessExprSyntax.self) else {
+      base.is(DeclReferenceExprSyntax.self) || base.is(MemberAccessExprSyntax.self)
+    else {
       return nil
     }
     return base.trimmedDescription

package/apple/Sources/ExpoModulesScanner/Exports/TypeNode.swift

@@ -8,8 +8,8 @@ import SwiftSyntax
 /// never silently dropped.
 
 /// The runtime category mirroring JavaScript's `typeof`. A coarse companion to `TypeNode.kind`: every
-/// structured object kind (array, dictionary, promise, ref) reports `object`. `symbol` is included for
-/// completeness; the scanner doesn't produce it.
+/// structured object kind (array, dictionary, promise, ref, sharedRef) reports `object`. `symbol` is
+/// included for completeness; the scanner doesn't produce it.
 enum JSType: String, Encodable {
   case undefined
   case object
@@ -72,6 +72,11 @@ indirect enum TypeNode: Equatable {
   /// node parsed at a use site has never seen.
   case ref(name: String, refKind: RefKind? = nil, jsTypeOverride: JSType? = nil)
 
+  /// `SharedRef<T>` (or `ExpoModulesCore.SharedRef<T>`): a shared object holding a native `T`, which
+  /// JS sees as an instance of `expo.SharedRef`. `native` is `T` parsed like any other type, but it
+  /// never crosses the boundary itself, so refs in it are not resolved.
+  case sharedRef(native: TypeNode)
+
   /// A spelling the parser doesn't model (generic parameter, tuple, metatype, …), kept verbatim so
   /// nothing is lost. Has no `typeof`.
   case unknown(text: String)
@@ -82,7 +87,7 @@ indirect enum TypeNode: Equatable {
     switch self {
     case .primitive(_, let jsType):
       return jsType
-    case .array, .dictionary, .promise:
+    case .array, .dictionary, .promise, .sharedRef:
       return .object
     case .ref(_, _, let jsTypeOverride):
       // An unresolved ref, and every resolved one but an enum, is an object.
@@ -105,7 +110,7 @@ extension TypeNode: Encodable {
     // The `typeof` category. Spelled `typeof` in JSON (what the consumer reads); the Swift property is
     // `jsType` since it's the cleaner Swift name.
     case jsType = "typeof"
-    case wrapped, element, key, value, parameters, returns, text
+    case wrapped, element, key, value, parameters, returns, text, native
     // A closure type's effects, matching `ExportedFunction`'s TS-keyword spellings.
     case isAsync = "async"
     case isThrowing = "throws"
@@ -143,6 +148,9 @@ extension TypeNode: Encodable {
       try container.encode("ref", forKey: .kind)
       try container.encode(name, forKey: .name)
       try container.encodeIfPresent(refKind, forKey: .refKind)
+    case .sharedRef(let native):
+      try container.encode("sharedRef", forKey: .kind)
+      try container.encode(native, forKey: .native)
     case .unknown(let text):
       try container.encode("unknown", forKey: .kind)
       try container.encode(text, forKey: .text)
@@ -201,15 +209,23 @@ func typeNode(from type: TypeSyntax) -> TypeNode {
   }
   // `(T)`: one unlabeled element in parentheses is the same type as `T`, as in `((Int) -> Void)?`.
   if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
-    let element = tuple.elements.first, element.firstName == nil {
+    let element = tuple.elements.first, element.firstName == nil
+  {
     return typeNode(from: element.type)
   }
   // A nominal type, possibly generic: `Int`, `Point`, `Optional<T>`, `Array<T>`, `Promise<T>`.
   if let identifier = type.as(IdentifierTypeSyntax.self) {
     return nominalNode(name: identifier.name.identifierName, generics: identifier.genericArgumentClause)
   }
-  // A qualified nominal type: `Foo.Bar`. Kept as a ref under its full spelling.
+  // A qualified nominal type: `Foo.Bar`. Kept as a ref under its full spelling, except core's own
+  // `ExpoModulesCore.SharedRef<T>`, which is the same type as a bare `SharedRef<T>`.
   if let member = type.as(MemberTypeSyntax.self) {
+    if member.baseType.as(IdentifierTypeSyntax.self)?.name.text == "ExpoModulesCore",
+      member.name.text == "SharedRef",
+      let generics = member.genericArgumentClause
+    {
+      return nominalNode(name: "SharedRef", generics: generics)
+    }
     return .ref(name: member.trimmedDescription)
   }
   // Tuples, metatypes, some/any types, etc.: not modeled, preserve the verbatim spelling.
@@ -217,8 +233,8 @@ func typeNode(from type: TypeSyntax) -> TypeNode {
 }
 
 /// A nominal type's node. The standard generic wrappers normalize to their sugared node
-/// (`Optional<T>`/`Array<T>`/`Dictionary<K,V>`/`Promise<T>`); a bare name is a primitive when known,
-/// else a ref; any other generic is a ref under its full spelling.
+/// (`Optional<T>`/`Array<T>`/`Dictionary<K,V>`/`Promise<T>`) and `SharedRef<T>` to its own node; a
+/// bare name is a primitive when known, else a ref; any other generic is a ref under its full spelling.
 private func nominalNode(name: String, generics: GenericArgumentClauseSyntax?) -> TypeNode {
   guard let generics else {
     if let jsType = primitiveJSTypes[name] {
@@ -237,6 +253,8 @@ private func nominalNode(name: String, generics: GenericArgumentClauseSyntax?) -
     return .dictionary(key: arguments[0], value: arguments[1])
   case ("Promise", 1):
     return .promise(value: arguments[0])
+  case ("SharedRef", 1):
+    return .sharedRef(native: arguments[0])
   default:
     // An unmodeled generic (`Set<Int>`, `Either<A, B>`, …). Keep the whole spelling as a ref so the
     // name and its arguments survive for the generator to interpret or flag.
@@ -296,6 +314,8 @@ extension TypeNode {
       return "[\(key.spelling): \(value.spelling)]"
     case .promise(let value):
       return "Promise<\(value.spelling)>"
+    case .sharedRef(let native):
+      return "SharedRef<\(native.spelling)>"
     case .function(let parameters, let returns, _, _):
       return "(\(parameters.map { $0.spelling }.joined(separator: ", "))) -> \(returns?.spelling ?? "Void")"
     case .unknown(let text):

package/apple/Sources/ExpoModulesScanner/Modules/ScanModules.swift

@@ -1,9 +1,10 @@
+import SwiftParser
+
 #if canImport(FoundationEssentials)
 import FoundationEssentials
 #else
 import Foundation
 #endif
-import SwiftParser
 
 /// The scanner's public entry point. Argument parsing, subcommand dispatch, and usage text live in
 /// the CLI target; this just runs a command and writes its JSON report to stdout.
@@ -122,7 +123,12 @@ func scanModules(paths: [String], defines: Set<String> = []) -> ScanModulesResul
     var platformsByDetection: [String: [String]] = [:]
     for platform in platformUniverse {
       let configuration = ScanBuildConfiguration(platform: platform.condition, defines: defines)
-      let visitor = DetectionVisitor(file: file, tree: tree, detectedMacros: [.expoModule], configuration: configuration)
+      let visitor = DetectionVisitor(
+        file: file,
+        tree: tree,
+        detectedMacros: [.expoModule],
+        configuration: configuration
+      )
       visitor.walk(tree)
       for detection in visitor.detections {
         platformsByDetection[detectionKey(detection), default: []].append(platform.reported)

package/build/index.d.ts

@@ -43,7 +43,7 @@ export declare class ScannerSchemaVersionError extends Error {
  *   `bin` directory.
  * - Windows and Linux: `ExpoModulesMacros.exe` or `ExpoModulesMacros` from the package for the
  *   current platform and architecture (see `platformBinaryPackageName`). When that package isn't
- *   installed, for example in this repository, it falls back to the executable that `npm run build`
+ *   installed, for example in this repository, it falls back to the executable that `pnpm run build`
  *   writes to `platforms/<platform>-<arch>`.
  *
  * The path isn't checked here; running a missing binary fails with a `ScannerError` that says how to