expo-modules-macros 0.22.0 → 0.23.1

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -43,14 +43,17 @@ import SwiftSyntaxMacros
 /// (`from(dictionary:)` / `toDictionary(appContext:)`), since `JavaScriptCodable` only converts JS
 /// values, not native `Any`. Both spell types as `public` symbols so the synthesized code compiles inside
 /// user modules without any internal core symbols. Every property type must therefore conform to both
-/// `AnyArgument` and `JavaScriptDecodable & JavaScriptEncodable`.
+/// `AnyArgument` and `JavaScriptDecodable & JavaScriptEncodable`. The conformance assertion checks only
+/// the JS codable protocols; the compiler reports a missing `AnyArgument` at the `getDynamicType()`
+/// call.
 ///
 /// A property whose type mentions `Any` (`Any?`, `[String: Any]?`, `[String: [Any]]`, …) can't conform to
-/// the JS codable protocols. On the JS-value paths it converts through the `JavaScriptValue` free-form
-/// methods instead: `decodeAny`/`decodeAnyArray`/`decodeAnyDictionary` and the matching `encodeAny…`
-/// for `Any`, `[Any]` and `[String: Any]` (optional or not), and the generic `decodeAny(_:as:in:)` /
-/// `encodeAny(_:in:)` for any other type. Such a property only needs `AnyArgument` for the dictionary
-/// paths, and a bare `Any` needs nothing, since the dictionary paths pass it through unchanged.
+/// the JS codable protocols, so it isn't asserted. On the JS-value paths it converts through the
+/// `JavaScriptValue` free-form methods instead: `decodeAny`/`decodeAnyArray`/`decodeAnyDictionary` and
+/// the matching `encodeAny…` for `Any`, `[Any]` and `[String: Any]` (optional or not), and the generic
+/// `decodeAny(_:as:in:)` / `encodeAny(_:in:)` for any other type. Such a property only needs
+/// `AnyArgument` for the dictionary paths, and a bare `Any` needs nothing, since the dictionary paths
+/// pass it through unchanged.
 ///
 /// A record class must be `final` and have no inheritance clause. The synthesized factories construct
 /// `Self` through the memberwise init, which only a final class can do without a `required` init, and
@@ -87,23 +90,16 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
 
     var members: [DeclSyntax] = []
 
-    // A single never-called member that makes the compiler verify each property type is convertible
-    // both ways (the JS-value paths call `decode`/`encode`; the native-`Any` dictionary paths call
-    // the dynamic-type API). Each property keeps its own named assertion inside, so the compiler's
-    // conformance diagnostic names the offending property (see `typeConformanceAssertions`). Emitted
-    // first so that, for a non-conforming type, this clear "requires that '…' conform to '…'" error
-    // is reported ahead of the noisier "no member 'decode'"/"getDynamicType" errors from the
-    // conversion code below.
+    // A single never-called member that makes the compiler verify each property type converts both
+    // ways (the JS-value paths call `decode`/`encode`). Each property keeps its own named assertion
+    // inside, so the compiler's conformance diagnostic names the offending property (see
+    // `typeConformanceAssertions`). Emitted first so that, for a non-conforming type, this clear
+    // "requires that '…' conform to '…'" error is reported ahead of the noisier "no member 'decode'"
+    // errors from the conversion code below.
     let assertions = properties.map { property in
-      // A bare `Any` can't conform to anything and needs no conformance, since every path converts it
-      // without one.
-      ConformanceAssertion(
-        name: property.name,
-        types: property.freeForm?.isBareAny == true ? [] : [property.type],
-        constraint: property.freeForm != nil ? jsConvertibleProtocolName : nil
-      )
+      ConformanceAssertion(name: property.name, types: property.freeForm == nil ? [property.type] : [])
     }
-    if let assertionMember = typeConformanceAssertions(for: assertions, constraint: recordFieldProtocolName) {
+    if let assertionMember = typeConformanceAssertions(for: assertions, constraint: javaScriptCodableProtocolName) {
       members.append(assertionMember)
     }
 
@@ -499,7 +495,7 @@ private func javaScriptCodableWitnesses(
     ["  let object = runtime.createObject()"]
     + lookupLines
     + objectWriteLines(properties: properties, of: "value", cachesPropNames: cachesPropNames)
-    + ["  return object.asValue()"]
+    + ["  return object.takeValue()"]
   return [
     """
     @JavaScriptActor

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -2,9 +2,10 @@ import SwiftSyntax
 import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
 
-/// Member macro applied to a `SharedObject` subclass. Scans the class body for
-/// declarations marked with `@JS` and synthesizes `_synthesizedClassDefinition()`,
-/// returning a `ClassDefinition` ready to drop into a module's `Class { ... }` slot.
+/// Member macro applied to a `SharedObject` subclass, direct or not (a `SharedRef<T>` subclass too).
+/// Scans the class body for declarations marked with `@JS` and binds them directly through overrides of
+/// the `SharedObject` hooks core calls when it builds the JavaScript class. The class's JavaScript name
+/// is emitted as a `_jsName` override.
 ///
 ///   @SharedObject
 ///   final class Cache: SharedObject {
@@ -18,8 +19,8 @@ import SwiftSyntaxMacros
 ///     var size: Int { 42 }
 ///   }
 ///
-/// The companion `@ExpoModule(classes: [Cache.self])` wires the resulting
-/// definition into the module's exposed surface.
+/// The companion `@ExpoModule(classes: [Cache.self])` registers the class with the module, which
+/// exposes it in its JavaScript object.
 public struct SharedObjectMacro: MemberMacro {
   public static func expansion(
     of node: AttributeSyntax,
@@ -31,26 +32,19 @@ public struct SharedObjectMacro: MemberMacro {
       throw MacroExpansionErrorMessage("@SharedObject can only be applied to a class")
     }
 
-    guard inheritsFromSharedObject(classDecl) else {
-      throw MacroExpansionErrorMessage(
-        "@SharedObject class must inherit from SharedObject. Add `: SharedObject` to the class declaration."
-      )
-    }
-
+    // The superclass isn't checked here: the macro sees only this declaration, so it can't tell an
+    // indirect subclass (`class Thumbnail: ImageRef`) from an unrelated class. The compiler reports a
+    // class that isn't a `SharedObject` subclass on the `_jsName` override, which is always emitted.
     let typeName = classDecl.name.text
     let jsName = jsNameArgument(of: node) ?? withoutBackticks(typeName)
 
     // `@JS func`s/`var`s and the `@JS init` are bound directly into the shared object's JS object by
-    // the synthesized `_decorateSharedObject(prototype:)` / `_decorateSharedObject(constructor:)` / `_constructSharedObject`
-    // rather than described with a `Function(...)` / `Property(...)` / `Constructor { … }` DSL entry, so
-    // they're collected here instead of appended to the `Class` block. The block keeps only non-`@JS`
-    // definitions (none are collected today), so it's empty when every member is `@JS`.
+    // the synthesized `_decorateSharedObject(prototype:)` / `_decorateSharedObject(constructor:)` / `_constructSharedObject`.
     //
     // Members split by the `static`/`class` modifier onto two different JS objects: instance members
     // decorate the prototype (receiver recovered from JS `this`), static members decorate the
     // constructor (called on the metatype). A JS instance and static member may share a name without
     // colliding: they live on different objects.
-    let entries: [String] = []
     var instanceFunctions: [JSFunction] = []
     var instanceProperties: [JSProperty] = []
     var staticFunctions: [JSFunction] = []
@@ -100,18 +94,10 @@ public struct SharedObjectMacro: MemberMacro {
     diagnoseJSNameCollisions(functions: instanceFunctions, properties: instanceProperties, in: context)
     diagnoseJSNameCollisions(functions: staticFunctions, properties: staticProperties, in: context)
 
-    let lines = entries.map { "    \($0)" }.joined(separator: "\n")
-    let body =
-      entries.isEmpty
-      ? "  return Class(\"\(jsName)\", \(typeName).self) {\n  }"
-      : "  return Class(\"\(jsName)\", \(typeName).self) {\n\(lines)\n  }"
-
+    // The resolved JS class name, read by core when it builds the class. An `override` of the
+    // `SharedObject` class property, so core reads it through the concrete type's metatype.
     var emitted: [DeclSyntax] = [
-      """
-      public static func _synthesizedClassDefinition() -> ClassDefinition {
-      \(raw: body)
-      }
-      """
+      "public override class var _jsName: String { \"\(raw: jsName)\" }"
     ]
 
     // Direct JSI binding, split by which JS object each member decorates:
@@ -170,9 +156,3 @@ extension SharedObjectMacro: MemberAttributeMacro {
     return ["@JavaScriptActor"]
   }
 }
-
-// MARK: - Inheritance check
-
-private func inheritsFromSharedObject(_ classDecl: ClassDeclSyntax) -> Bool {
-  return inheritsFromAny(classDecl, names: ["SharedObject"])
-}

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -1,9 +1,8 @@
 import SwiftSyntax
 import SwiftSyntaxBuilder
 
-/// The protocol that every type crossing the JS boundary must conform to. Centralized here so the
-/// eventual rename (this is a placeholder name) is a single edit, and shared by the macros whose
-/// generated conversions go through the dynamic-type API (`@Record`, `@Event`).
+/// The protocol of the 1.0 dynamic-type API (`getDynamicType()`). `@Event` asserts payload types
+/// against it.
 internal let jsConvertibleProtocolName = "AnyArgument"
 
 /// The constraint a `@JS` boundary type must satisfy, by direction: an argument (and a settable
@@ -15,23 +14,10 @@ internal let jsConvertibleProtocolName = "AnyArgument"
 internal let javaScriptDecodableProtocolName = "JavaScriptDecodable"
 internal let javaScriptEncodableProtocolName = "JavaScriptEncodable"
 
-/// The constraint a `@Record` property type must satisfy: it must be both `AnyArgument` (the
-/// `from(dictionary:)` / `toDictionary(appContext:)` paths still convert native `Any` through the
-/// dynamic-type API) and `JavaScriptDecodable & JavaScriptEncodable` (the `from(object:)` /
-/// `toObject(appContext:)` paths convert JS values through `decode`/`encode`). A record field has to
-/// support both directions, so the assertion requires the intersection.
-///
-/// The exception is a property whose type mentions `Any` (`[String: Any]?`, `[Any]`, …): it can't
-/// conform to the JS codable protocols, so the JS-value paths convert it through the `JavaScriptValue`
-/// free-form methods, and it's asserted against `jsConvertibleProtocolName` alone for the dictionary
-/// paths.
-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 constraint a `@Record` property type and a `@Union` case payload type must satisfy. A record
+/// decodes and encodes each property, and a union decodes by trying each payload's `decode` and
+/// encodes through the matching payload's `encode`, so both convert in both directions.
+internal let javaScriptCodableProtocolName = "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
@@ -52,20 +38,15 @@ internal struct ConformanceAssertion {
   /// Declared types as written. Composed types (`[Int]`, `String?`, …) are kept verbatim — their
   /// conditional conformances transitively constrain the elements.
   let types: [String]
-  /// The constraint for this member's types, overriding the one passed to `typeConformanceAssertions`.
-  /// `@Record` uses it to assert only `AnyArgument` for a property that mentions `Any`, which can't be
-  /// `JavaScriptDecodable & JavaScriptEncodable`.
-  var constraint: String? = nil
 }
 
 /// A directional conformance-assertion peer for a `@JS` member: a never-called `private func` whose
 /// body asserts each argument type is `JavaScriptDecodable` and the return/getter type is
 /// `JavaScriptEncodable`, matching how the generated binding converts each (decode on the way in,
-/// encode on the way out). The check is a single member-named nested helper with one `A0…` generic
-/// parameter per asserted argument and a single `Return` parameter for the value, called once with
-/// every type's metatype; naming the helper after the member puts the member in the compiler's
-/// diagnostic, and the per-slot constraint reports the offending type against the protocol for *its*
-/// direction.
+/// encode on the way out). The check is a single member-named nested helper with one opaque metatype
+/// parameter per asserted type, called once with every type's metatype; naming the helper after the
+/// member puts the member in the compiler's diagnostic, and the per-parameter constraint reports the
+/// offending type against the protocol for *its* direction.
 ///
 /// `decodableTypes` are the argument types (and a settable property's value type); `encodableType` is
 /// the single return type (or a property's value type on read), or `nil` when there's none.
@@ -87,31 +68,18 @@ internal func directionalConformanceAssertion(
     return nil
   }
 
-  // Build the generic parameter list and the matching call arguments in lockstep: one `A0…` slot
-  // constrained `JavaScriptDecodable` per argument, one `E0…` slot constrained `JavaScriptEncodable`
-  // per closure-argument parameter, and a single `Return` slot constrained `JavaScriptEncodable` for
-  // the return/getter value (there's only ever one, so it isn't indexed). Every slot suppresses
-  // `Copyable`, so a non-copyable boundary type such as `JavaScriptValue` can fill it.
-  var parameters: [String] = []
-  var typeParameters: [String] = []
-  var arguments: [String] = []
-  for (index, type) in decodables.enumerated() {
-    parameters.append("A\(index): \(javaScriptDecodableProtocolName) & ~Copyable")
-    typeParameters.append("_: A\(index).Type")
-    arguments.append("\(type).self")
-  }
-  for (index, type) in callbackArguments.enumerated() {
-    parameters.append("E\(index): \(javaScriptEncodableProtocolName) & ~Copyable")
-    typeParameters.append("_: E\(index).Type")
-    arguments.append("\(type).self")
-  }
-  if let encodable {
-    parameters.append("Return: \(javaScriptEncodableProtocolName) & ~Copyable")
-    typeParameters.append("_: Return.Type")
-    arguments.append("\(encodable).self")
-  }
-
-  let helper = "func \(name)<\(parameters.joined(separator: ", "))>(\(typeParameters.joined(separator: ", "))) {}"
+  // Arguments are constrained `JavaScriptDecodable`, and closure-argument parameters and the
+  // return/getter value `JavaScriptEncodable`. Every parameter suppresses `Copyable`, so a
+  // non-copyable boundary type such as `JavaScriptValue` can fill it.
+  let encodables = callbackArguments + [encodable].compactMap { $0 }
+  let decodableParameter = opaqueMetatypeParameter(constraint: "\(javaScriptDecodableProtocolName) & ~Copyable")
+  let encodableParameter = opaqueMetatypeParameter(constraint: "\(javaScriptEncodableProtocolName) & ~Copyable")
+  let parameters =
+    Array(repeating: decodableParameter, count: decodables.count)
+    + Array(repeating: encodableParameter, count: encodables.count)
+  let arguments = (decodables + encodables).map { "\($0).self" }
+
+  let helper = "func \(name)(\(parameters.joined(separator: ", "))) {}"
   let call = "\(name)(\(arguments.joined(separator: ", ")))"
   let staticKeyword = isStatic ? "static " : ""
   let peerName = derivedIdentifier(from: name, prefix: "_assertTypesConformance_")
@@ -132,9 +100,9 @@ internal func directionalConformanceAssertion(
 /// caller emits nothing.
 internal func typeConformanceAssertions(
   for assertions: [ConformanceAssertion],
-  constraint: String = jsConvertibleProtocolName
+  constraint: String
 ) -> DeclSyntax? {
-  let bodies = assertions.compactMap { conformanceAssertionBody($0, constraint: $0.constraint ?? constraint) }
+  let bodies = assertions.compactMap { conformanceAssertionBody($0, constraint: constraint) }
   guard !bodies.isEmpty else {
     return nil
   }
@@ -186,25 +154,33 @@ private func setsConform(to constraint: String) -> Bool {
   }
 }
 
-/// The assertion's body fragment: a nested generic helper named after the member, plus one call per
-/// distinct type that needs an assertion. Nesting the helper keeps the constraint entirely local — no
-/// shared symbol, nothing to collide, nothing left in the type's namespace — and naming it after the
-/// member puts the member's name in the compiler's conformance diagnostic. Returns `nil` when every
-/// type was known to conform or the list was empty.
+/// The assertion's body fragment: a nested helper named after the member, plus one call per distinct
+/// type that needs an assertion. Nesting the helper keeps the constraint entirely local — no shared
+/// symbol, nothing to collide, nothing left in the type's namespace — and naming it after the member
+/// puts the member's name in the compiler's conformance diagnostic. Returns `nil` when every type was
+/// known to conform or the list was empty.
 private func conformanceAssertionBody(
   _ assertion: ConformanceAssertion,
-  constraint: String = jsConvertibleProtocolName
+  constraint: String
 ) -> String? {
   let distinct = distinctAssertableTypes(assertion.types, constraint: constraint)
   guard !distinct.isEmpty else {
     return nil
   }
 
-  var lines = ["func \(assertion.name)<T: \(constraint)>(_: T.Type) {}"]
+  var lines = ["func \(assertion.name)(\(opaqueMetatypeParameter(constraint: constraint))) {}"]
   lines.append(contentsOf: distinct.map { "\(assertion.name)(\($0).self)" })
   return lines.joined(separator: "\n")
 }
 
+/// An unlabeled parameter that takes the metatype of any type satisfying `constraint`, for an
+/// assertion helper.
+internal func opaqueMetatypeParameter(constraint: String) -> String {
+  // A named generic parameter would shadow a generic parameter of the same name on an enclosing
+  // type, which is an error. An opaque parameter declares no name.
+  return "_: (some \(constraint)).Type"
+}
+
 /// The distinct types to assert against `constraint` from a list, mapping each through
 /// `assertableBoundaryType` (which drops what needs no assertion) and deduping in first-seen order.
 private func distinctAssertableTypes(_ types: [String], constraint: String) -> [String] {

package/apple/Sources/ExpoModulesMacros/UnionMacro.swift

@@ -57,7 +57,7 @@ public struct UnionMacro: MemberMacro, ExtensionMacro {
     // reports the clear "requires that '…' conform to …" error ahead of the noisier "no member
     // 'decode'"/"'encode'" errors from the conversion code below.
     let assertions = union.cases.map { ConformanceAssertion(name: $0.name, types: [$0.payloadType]) }
-    if let assertionMember = typeConformanceAssertions(for: assertions, constraint: unionPayloadProtocolName) {
+    if let assertionMember = typeConformanceAssertions(for: assertions, constraint: javaScriptCodableProtocolName) {
       members.append(assertionMember)
     }
 

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

@@ -293,6 +293,9 @@ struct ExportedSharedObject: Encodable, Equatable {
   /// if a malformed source has more. Not named `constructor`, which every JS object inherits.
   var initializer: ExportedInitializer?
 
+  /// What the class inherits from `SharedRef<T>`, or `nil` when its superclass isn't `SharedRef`.
+  let sharedRef: ExportedSharedRef?
+
   var functions: [ExportedFunction]
   var properties: [ExportedProperty]
   var events: [ExportedEvent]
@@ -305,6 +308,17 @@ struct ExportedSharedObject: Encodable, Equatable {
   let file: String
 }
 
+/// The `SharedRef<T>` superclass of a shared object. Only the superclass written on the class is read,
+/// so a class that inherits `SharedRef` through another subclass has none.
+struct ExportedSharedRef: Encodable, Equatable {
+  /// The `T` in `SharedRef<T>`: the native type the object holds, which JS never sees.
+  let native: TypeNode
+
+  /// The `nativeRefType` JS reads to tell refs apart, for example `image`. `unknown` (core's default)
+  /// when the class doesn't override it, and `nil` when the override isn't a plain string literal.
+  let nativeRefType: String?
+}
+
 /// A `@Record` type and its properties (data only: no functions, accessors, or constructor).
 struct ExportedRecord: Encodable, Equatable {
   /// The Swift type name (struct or class), qualified with the types it is nested in
@@ -448,8 +462,9 @@ struct ExportedSurface: Encodable, Equatable {
 /// an enum ref's `typeof`; version 6 added `classes` to modules; version 7 reports nested types under
 /// qualified names and gives a resolved ref the name of its declaration; version 8 reports
 /// declarations in `#if` blocks, adds `platforms` (with deprecations), `accessLevel`, and
-/// `defaultValue`, and replaces `constructorParameters` with `initializer`.
-let scanExportsSchemaVersion = 8
+/// `defaultValue`, and replaces `constructorParameters` with `initializer`; version 9 adds the
+/// `sharedRef` type kind and the `sharedRef` of a shared object.
+let scanExportsSchemaVersion = 9
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).

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

@@ -112,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

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

@@ -170,6 +170,7 @@ final class SurfaceVisitor: SyntaxVisitor {
           name: qualified,
           jsName: stringArgument(of: attribute) ?? name,
           initializer: initializer,
+          sharedRef: sharedRefSuperclass(of: node),
           functions: functions,
           properties: properties,
           events: events,
@@ -348,6 +349,8 @@ final class SurfaceVisitor: SyntaxVisitor {
     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] = []
@@ -363,7 +366,7 @@ 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,
@@ -741,6 +744,54 @@ private func asyncVariantName(of attribute: AttributeSyntax) -> String? {
   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)

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)
@@ -209,8 +217,15 @@ func typeNode(from type: TypeSyntax) -> TypeNode {
   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.
@@ -218,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] {
@@ -238,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.
@@ -297,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/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

package/build/index.js

@@ -75,7 +75,7 @@ function platformBinaryPackageName() {
  *   `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
@@ -97,7 +97,7 @@ function getScannerBinaryPath() {
 /** The message for a scanner binary that doesn't exist at `binaryPath`. */
 function missingBinaryMessage(binaryPath) {
     if (process.platform === 'darwin') {
-        return `The scanner binary is missing at ${binaryPath}. Run \`npm run build\` in this package to build it.`;
+        return `The scanner binary is missing at ${binaryPath}. Run \`pnpm run build\` in this package to build it.`;
     }
     const machines = platformPackageMachines[process.platform];
     if (machines === undefined) {
@@ -106,7 +106,7 @@ function missingBinaryMessage(binaryPath) {
     return (`The scanner binary is missing at ${binaryPath}. It comes from the optional package ` +
         `${platformBinaryPackageName()}, which your package manager installs only on ${machines}. ` +
         'Reinstall dependencies without skipping optional ones (for example without `--omit=optional`), ' +
-        'or run `npm run build` in this package to build it locally.');
+        'or run `pnpm run build` in this package to build it locally.');
 }
 /**
  * Runs a scanner subcommand and parses its JSON report.