expo-modules-macros 0.35.0 → 0.36.0

package/Package.swift

@@ -30,6 +30,8 @@ let package = Package(
         .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+        // For the value of a string literal (`representedLiteralValue`).
+        .product(name: "SwiftParser", package: "swift-syntax"),
         // For the plugin server, which resolves the macros by type name (see PluginServer.swift).
         .product(name: "_SwiftCompilerPluginMessageHandling", package: "swift-syntax"),
       ],
@@ -47,6 +49,7 @@ let package = Package(
         .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+        .product(name: "SwiftParser", package: "swift-syntax"),
         .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
       ],
       path: "apple/Sources/ExpoModulesMacros"

package/README.md

@@ -25,7 +25,7 @@ This package lists them as optional dependencies, and their `os`, `cpu` and (on
 # Macros
 
 - **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none. It adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet (see [Sendable conformance](#sendable-conformance)).
-- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. The class macro reads only the class body, so `@JS` on a member of an extension, or of a type that is neither a module nor a shared object, is an error. So is `@JS` on an initializer or a `static` member of a module, since JavaScript doesn't construct a module and gets only its instance. `@JS` on any other declaration, such as a subscript, is an error too. A `@JS` function or initializer can't be generic, since the binding converts each value by its static type. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. A name that JavaScript already gives a meaning on the object is an error too: `__proto__` on any object, `constructor` on a shared object's prototype, and `prototype` on its constructor. The macro also checks that every type crossing the boundary is convertible in the direction it travels. For a top-level declaration, a bad type is reported on the author's own declaration. In an `@ExpoModule` or `@SharedObject` class, the class macro makes the check, since only it sees the type aliases in the class body, so the error is reported on the class and names the member and its argument labels, such as `local function 'move(_:by:returning:)' requires that 'Point' conform to 'JavaScriptEncodable'`. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. Because of that, a `.concurrent` function and a function with `.withAsync` can't take a JavaScript value such as `JavaScriptValue` or `JavaScriptObject`, which is valid only on the JavaScript thread; the macro reports such a parameter. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one. A synchronous function or an initializer can take the JavaScript runtime as its last parameter, `in runtime: borrowing JavaScriptRuntime`, for example to create a JavaScript value. The binding passes the runtime of the call, and JavaScript doesn't see the parameter. The runtime can be used only on the JavaScript thread, and an `async` function can resume on another thread after an `await`, so the macro reports the parameter on an `async` function or a function with `.withAsync`, and when it isn't the last parameter, isn't labeled `in`, isn't `borrowing` or is optional. The macro finds the parameter by its type as written, so write it as `JavaScriptRuntime`: a typealias or a subclass is decoded as a JavaScript argument instead.
+- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** and **`@JS(symbol:_:)`** on a member of a module or shared object. Marks a function, property or initializer for export. The class macro reads only the class body, so `@JS` on a member of an extension, or of a type that is neither a module nor a shared object, is an error. So is `@JS` on an initializer or a `static` member of a module, since JavaScript doesn't construct a module and gets only its instance. `@JS` on any other declaration, such as a subscript, is an error too. A `@JS` function or initializer can't be generic, since the binding converts each value by its static type. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. A name that JavaScript already gives a meaning on the object is an error too: `__proto__` on any object, `constructor` on a shared object's prototype, and `prototype` on its constructor. To bind a function or property under a symbol instead of a name, pass `symbol:`: a case of `JavaScriptSymbol.WellKnown`, such as `@JS(symbol: .iterator)` for `Symbol.iterator`, or a string literal, such as `@JS(symbol: "app.id")` for `Symbol.for("app.id")`. A function bound under a symbol is named after it in brackets, such as `[Symbol.iterator]`, as JavaScript names such a method. A function under `Symbol.hasInstance` or `Symbol.toStringTag` is defined as a data property first, since an assignment can't shadow what the prototype chain holds under these keys: a read-only `Symbol.hasInstance` on `Function.prototype`, and a `Symbol.toStringTag` accessor without a setter on the base `SharedObject` prototype. A symbol never collides with a name, and `symbol:` on an initializer is an error. In the `scan-exports` output, such a member has a `symbol` field instead of a `jsName`. The macro also checks that every type crossing the boundary is convertible in the direction it travels. For a top-level declaration, a bad type is reported on the author's own declaration. In an `@ExpoModule` or `@SharedObject` class, the class macro makes the check, since only it sees the type aliases in the class body, so the error is reported on the class and names the member and its argument labels, such as `local function 'move(_:by:returning:)' requires that 'Point' conform to 'JavaScriptEncodable'`. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. Because of that, a `.concurrent` function and a function with `.withAsync` can't take a JavaScript value such as `JavaScriptValue` or `JavaScriptObject`, which is valid only on the JavaScript thread; the macro reports such a parameter. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one. A synchronous function or an initializer can take the JavaScript runtime as its last parameter, `in runtime: borrowing JavaScriptRuntime`, for example to create a JavaScript value. The binding passes the runtime of the call, and JavaScript doesn't see the parameter. The runtime can be used only on the JavaScript thread, and an `async` function can resume on another thread after an `await`, so the macro reports the parameter on an `async` function or a function with `.withAsync`, and when it isn't the last parameter, isn't labeled `in`, isn't `borrowing` or is optional. The macro finds the parameter by its type as written, so write it as `JavaScriptRuntime`: a typealias or a subclass is decoded as a JavaScript argument instead.
 - **`@Event(_ name: String? = nil, _ options: EventOptions...)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `@ExpoModule` and `@SharedObject` warn when two events in the class body have the same JS name. By default the event is scheduled on the JavaScript thread. The `.inline` option runs the listeners before the call returns when it is made on the JavaScript thread, and schedules the event otherwise; it never blocks. The `.blocking` option runs the listeners before the call returns on any thread, so a call from another thread blocks until the JavaScript thread runs them. An event property is callable from any thread with each option.
 - **`@SharedObject(_ name: String? = nil)`** on a subclass of `SharedObject`, direct or not, such as a `SharedRef<T>` subclass. Binds the class's `@JS` members through the `SharedObject` hooks that core calls when it builds the JavaScript class, and emits the JS class name, which defaults to the class name. A class without an inheritance clause is an error, with a Fix-It that adds `: SharedObject`. A module exposes the class through `@ExpoModule(classes:)`, which only accepts `SharedObject` subclasses. A subclass of another `@SharedObject` class also gets the `@JS` members of that class, and its own members replace inherited members with the same JS name. A subclass that isn't `final` can't be constructed from JavaScript through the `@JS init` of its superclass, so give each subclass that JavaScript constructs its own `@JS init`. Like `@ExpoModule`, it adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet.
 - **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. A record converts only from and to JavaScript values: its `from(dictionary:appContext:)` throws `RecordDictionaryConversionException`, so a record can't be created from a native `[String: Any]`. A `@Union` can be a record property. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional. The memberwise initializer sets every field, so a field that is a `let` with a default value is an error. It doesn't set a `private` or `fileprivate` stored property, so such a property needs a default value, unless it's an optional `var` or the type declares its own memberwise initializer.

package/apple/Sources/ExpoModulesCLI/Commands/ScanExports/ExportedSurface.swift

@@ -72,8 +72,12 @@ struct ExportedFunction: Encodable, Equatable {
   let name: String
 
   /// The JS name it binds under: the `@JS("x")` override, else `name`. The second entry of a function
-  /// with `.withAsync("x")` binds under `x`.
-  let jsName: String
+  /// with `.withAsync("x")` binds under `x`. `nil` for a function bound under a symbol (see `symbol`).
+  let jsName: String?
+
+  /// The symbol it binds under with `@JS(symbol: ...)`, or `nil` when it binds under `jsName`.
+  /// Exactly one of `jsName` and `symbol` is set.
+  var symbol: ExportedSymbol? = nil
 
   var parameters: [ExportedParameter]
 
@@ -96,20 +100,41 @@ struct ExportedFunction: Encodable, Equatable {
 
   /// The flags are encoded under their TS-keyword spellings.
   private enum CodingKeys: String, CodingKey {
-    case name, jsName, parameters, returns, accessLevel, platforms
+    case name, jsName, symbol, parameters, returns, accessLevel, platforms
     case isAsync = "async"
     case isThrowing = "throws"
     case isStatic = "static"
   }
 }
 
+/// The symbol that a `@JS(symbol: ...)` member binds under.
+struct ExportedSymbol: Encodable, Hashable {
+  enum Kind: String, Encodable, Hashable {
+    /// A well-known symbol, such as `Symbol.iterator`, from `@JS(symbol: .iterator)`.
+    case wellKnown
+    /// The symbol that the global registry holds for a key, `Symbol.for("app.id")`, from
+    /// `@JS(symbol: "app.id")`.
+    case registered
+  }
+
+  let kind: Kind
+
+  /// The name of the well-known symbol, such as `iterator`, or the registry key.
+  let name: String
+}
+
 /// One `@JS var` on a module or shared object.
 struct ExportedProperty: Encodable, Equatable {
   /// The Swift declaration name.
   let name: String
 
-  /// The JS name it binds under: the `@JS("x")` override, else `name`.
-  let jsName: String
+  /// The JS name it binds under: the `@JS("x")` override, else `name`. `nil` for a property bound
+  /// under a symbol (see `symbol`).
+  let jsName: String?
+
+  /// The symbol it binds under with `@JS(symbol: ...)`, or `nil` when it binds under `jsName`.
+  /// Exactly one of `jsName` and `symbol` is set.
+  var symbol: ExportedSymbol? = nil
 
   /// The value type, or `nil` when undeterminable syntactically (no annotation and no literal
   /// default), the case the macro binds getter-only.
@@ -132,7 +157,7 @@ struct ExportedProperty: Encodable, Equatable {
   let platforms: [ExportedPlatform]
 
   private enum CodingKeys: String, CodingKey {
-    case name, jsName, type, defaultValue, accessLevel, platforms
+    case name, jsName, symbol, type, defaultValue, accessLevel, platforms
     case isReadonly = "readonly"
     case isStatic = "static"
   }
@@ -140,7 +165,8 @@ struct ExportedProperty: Encodable, Equatable {
   func encode(to encoder: Encoder) throws {
     var container = encoder.container(keyedBy: CodingKeys.self)
     try container.encode(name, forKey: .name)
-    try container.encode(jsName, forKey: .jsName)
+    try container.encodeIfPresent(jsName, forKey: .jsName)
+    try container.encodeIfPresent(symbol, forKey: .symbol)
     try container.encodeIfPresent(type, forKey: .type)
     try container.encode(!isSettable, forKey: .isReadonly)
     try container.encode(isStatic, forKey: .isStatic)
@@ -468,7 +494,8 @@ struct ExportedView: Encodable, Equatable {
   /// The Swift class name. Only a view declared at file scope is reported, as in `scan-modules`.
   let name: String
 
-  /// The name the view registers under. `@ExpoView` takes no name, so it is always the class name.
+  /// The name the view registers under: the `@ExpoView<CardProps>("Foo")` override when present,
+  /// otherwise the class name.
   let jsName: String
 
   /// The props type: the generic argument of `@ExpoView<CardProps>`, as written without backticks, or
@@ -606,9 +633,10 @@ enum ExportedEventDispatch: String, Encodable, Equatable {
 /// `defaultValue`, and replaces `constructorParameters` with `initializer`; version 9 adds the
 /// `sharedRef` type kind and the `sharedRef` of a shared object; version 10 adds the `tuple` and `object` type kinds (named after a tuple alias)
 /// and resolves the tuple type aliases declared in `@ExpoModule` and `@SharedObject` classes; version 11
-/// replaces the `sync` flag of an event with `dispatch`. A new field that older consumers can ignore,
-/// such as `views`, doesn't change the version.
-let scanExportsSchemaVersion = 11
+/// replaces the `sync` flag of an event with `dispatch`; version 12 adds the `symbol` of a function or
+/// property bound with `@JS(symbol: ...)`, which then has no `jsName`. A new field that older consumers
+/// can ignore, such as `views`, doesn't change the version.
+let scanExportsSchemaVersion = 12
 
 /// 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/ExpoModulesCLI/Commands/ScanExports/InheritedMembers.swift

@@ -20,7 +20,7 @@ extension ExportedSurface {
   /// `platforms`.
   ///
   /// The members merge the way the macro binds them: the inherited ones first, then the class's own. An
-  /// own member replaces an inherited function or property with the same JS name, separately for static
+  /// own member replaces an inherited function or property with the same JS name or symbol, separately for static
   /// and instance members. Events are kept from both: an event is a stored property that emits under its
   /// JS name, so a subclass can't replace an inherited one, and both are sent. The `@JS init` isn't
   /// inherited: core doesn't construct a subclass through the initializer of its superclass.
@@ -52,17 +52,17 @@ extension ExportedSurface {
       var result = sharedObject
 
       let ownMembers = Set(
-        sharedObject.functions.map { MemberKey(jsName: $0.jsName, isStatic: $0.isStatic) }
-          + sharedObject.properties.map { MemberKey(jsName: $0.jsName, isStatic: $0.isStatic) }
+        sharedObject.functions.map { MemberKey(jsName: $0.jsName, symbol: $0.symbol, isStatic: $0.isStatic) }
+          + sharedObject.properties.map { MemberKey(jsName: $0.jsName, symbol: $0.symbol, isStatic: $0.isStatic) }
       )
       result.functions =
         parents.flatMap(\.functions).filter {
-          !ownMembers.contains(MemberKey(jsName: $0.jsName, isStatic: $0.isStatic))
+          !ownMembers.contains(MemberKey(jsName: $0.jsName, symbol: $0.symbol, isStatic: $0.isStatic))
         }
         + sharedObject.functions
       result.properties =
         parents.flatMap(\.properties).filter {
-          !ownMembers.contains(MemberKey(jsName: $0.jsName, isStatic: $0.isStatic))
+          !ownMembers.contains(MemberKey(jsName: $0.jsName, symbol: $0.symbol, isStatic: $0.isStatic))
         }
         + sharedObject.properties
       result.events = parents.flatMap(\.events) + sharedObject.events
@@ -91,7 +91,9 @@ extension ExportedSurface {
 
 /// A member's slot on the JavaScript side: static members live on the constructor and instance members
 /// on the prototype, so the two don't replace each other.
+/// The key a member binds under: its JS name or its symbol, one of which is set.
 private struct MemberKey: Hashable {
-  let jsName: String
+  let jsName: String?
+  let symbol: ExportedSymbol?
   let isStatic: Bool
 }

package/apple/Sources/ExpoModulesCLI/Commands/ScanExports/SurfaceVisitor.swift

@@ -1,3 +1,4 @@
+import SwiftParser
 import SwiftSyntax
 
 /// Extracts the full JS-exported surface of every `@ExpoModule`, `@SharedObject`, `@Record`,
@@ -222,7 +223,7 @@ final class SurfaceVisitor: SyntaxVisitor {
       views.append(
         ExportedView(
           name: qualified,
-          jsName: name,
+          jsName: stringArgument(of: attribute) ?? name,
           propsType: String(propsType.trimmedDescription.filter { $0 != "`" }),
           propsTypeLookupName: spellingWithoutGenericArguments(of: propsType),
           accessLevel: accessLevel,
@@ -366,10 +367,11 @@ final class SurfaceVisitor: SyntaxVisitor {
     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
+    let makeFunction = { (jsName: String?, symbol: ExportedSymbol?, isAsync: Bool) in
       ExportedFunction(
         name: funcDecl.name.identifierName,
         jsName: jsName,
+        symbol: symbol,
         parameters: exportedParameters,
         returns: returns,
         isAsync: isAsync,
@@ -379,12 +381,15 @@ final class SurfaceVisitor: SyntaxVisitor {
         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.
+    let symbol = symbolArgument(of: attribute)
+    let jsName = symbol == nil ? stringArgument(of: attribute) ?? funcDecl.name.identifierName : nil
+    let function = makeFunction(jsName, symbol, isAsync)
+    // The macro binds no variant for an `async` function: it reports the option there instead. The
+    // variant binds under its own name, also for a function bound under a symbol.
     guard !isAsync, let variantName = asyncVariantName(of: attribute) else {
       return [function]
     }
-    return [function, makeFunction(variantName, true)]
+    return [function, makeFunction(variantName, nil, true)]
   }
 
   /// Builds the `ExportedProperty` entries for a `@JS var`/`let`. One declaration can introduce several
@@ -399,6 +404,7 @@ final class SurfaceVisitor: SyntaxVisitor {
     // 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 symbol = symbolArgument(of: attribute)
     let override = stringArgument(of: attribute)
     var result: [ExportedProperty] = []
 
@@ -411,7 +417,8 @@ final class SurfaceVisitor: SyntaxVisitor {
       result.append(
         ExportedProperty(
           name: name,
-          jsName: override ?? name,
+          jsName: symbol == nil ? override ?? name : nil,
+          symbol: symbol,
           type: type,
           isSettable: !isLazy && isSettable(binding: binding, isLet: isLet),
           isStatic: isStatic,
@@ -895,8 +902,8 @@ private func hasEventOption(_ attribute: AttributeSyntax, named option: String)
 
 /// 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.
+/// argument isn't a string literal without interpolation. The name is the value of the 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
@@ -916,14 +923,11 @@ private func asyncVariantName(of attribute: AttributeSyntax) -> String? {
     }
     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)
+      argument.label == nil
     else {
       return nil
     }
-    return segment.content.text
+    return argument.expression.as(StringLiteralExprSyntax.self)?.representedLiteralValue
   }
   return nil
 }

package/apple/Sources/ExpoModulesCLI/Commands/ScanModules/ScanModules.swift

@@ -44,9 +44,10 @@ struct ScannedClass: Codable, Equatable {
   /// The Swift class name.
   let name: String
 
-  /// The fully-resolved JS name: the `@ExpoModule("Foo")` or `@SharedObject("Foo")` override when
-  /// present, otherwise the class name. `@ExpoView` takes no name, so a view's JS name is its class name. Resolved here (rather than left `nil`) so it matches how the
-  /// macro derives the name and the consumer never has to apply the fallback itself.
+  /// The fully-resolved JS name: the `@ExpoModule("Foo")`, `@SharedObject("Foo")` or
+  /// `@ExpoView<CardProps>("Foo")` override when present, otherwise the class name. Resolved here
+  /// (rather than left `nil`) so it matches how the macro derives the name and the consumer never has
+  /// to apply the fallback itself.
   let jsName: String
 
   /// The class's spelled access modifier (`open`, `public`, `package`, `fileprivate`, `private`),
@@ -155,8 +156,8 @@ func scanModules(paths: [String], defines: Set<String> = []) -> ScanModulesResul
 
     // The macros reject anything but a class, so a struct with one of them is never registered.
     for detection in allModules.detections where detection.declarationKind == "class" {
-      // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` or
-      // `@SharedObject("Foo")` override, else the class name.
+      // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")`,
+      // `@SharedObject("Foo")` or `@ExpoView<CardProps>("Foo")` override, else the class name.
       let scanned = ScannedClass(
         name: detection.name,
         jsName: detection.jsName ?? detection.name,

package/apple/Sources/ExpoModulesCLI/Core/DetectionVisitor.swift

@@ -1,5 +1,6 @@
 import SwiftDiagnostics
 import SwiftIfConfig
+import SwiftParser
 import SwiftSyntax
 
 /// Walks a parsed source file and records top-level declarations carrying `@ExpoModule`, `@JS`,
@@ -206,19 +207,49 @@ private func arguments(of attribute: AttributeSyntax) -> [MacroArgument] {
   }
 }
 
-/// The first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork". Returns
-/// `nil` when there's no argument or it isn't a plain string literal. (Same shape the
-/// `jsNameArgument` helper reads inside the macros.) Shared with the `scan-exports` surface visitor,
-/// which reads the same JS-name override off `@JS`/`@ExpoModule`/`@SharedObject`.
+/// The spellings of the type of the well-known symbols that a `symbol:` argument can name before the
+/// case, as in the macros.
+private let wellKnownSymbolTypeNames: Set<String> = [
+  "JavaScriptSymbol.WellKnown",
+  "ExpoModulesJSI.JavaScriptSymbol.WellKnown",
+  "ExpoModulesCore.JavaScriptSymbol.WellKnown",
+]
+
+/// The `symbol:` argument of `@JS`, the same as the macros read it: a case of
+/// `JavaScriptSymbol.WellKnown` names a well-known symbol (`@JS(symbol: .iterator)`), and a string
+/// literal without interpolation a registry key (`@JS(symbol: "app.id")`), with its escape sequences
+/// decoded. `nil` when the attribute has none, or when the argument has another shape, such as a
+/// constant `Keys.id`, which `@JS` reports.
+func symbolArgument(of attribute: AttributeSyntax) -> ExportedSymbol? {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
+    let argument = args.first(where: { $0.label?.text == "symbol" })
+  else {
+    return nil
+  }
+  if let member = argument.expression.as(MemberAccessExprSyntax.self) {
+    if let base = member.base, !wellKnownSymbolTypeNames.contains(base.trimmedDescription) {
+      return nil
+    }
+    return ExportedSymbol(kind: .wellKnown, name: member.declName.baseName.identifierName)
+  }
+  if let value = argument.expression.as(StringLiteralExprSyntax.self)?.representedLiteralValue {
+    return ExportedSymbol(kind: .registered, name: value)
+  }
+  return nil
+}
+
+/// The value of the first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork",
+/// with its escape sequences decoded, so a raw string and an escape read as JavaScript sees the name.
+/// Returns `nil` when there's no argument or it isn't an unlabeled string literal without
+/// interpolation. (Same shape the `jsNameArgument` helper reads inside the macros.) Shared with the
+/// `scan-exports` surface visitor, which reads the same JS-name override off
+/// `@JS`/`@ExpoModule`/`@SharedObject`.
 func stringArgument(of attribute: AttributeSyntax) -> String? {
   guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
     let first = args.first,
-    first.label == nil,
-    let str = first.expression.as(StringLiteralExprSyntax.self),
-    let segment = str.segments.first?.as(StringSegmentSyntax.self),
-    str.segments.count == 1
+    first.label == nil
   else {
     return nil
   }
-  return segment.content.text
+  return first.expression.as(StringLiteralExprSyntax.self)?.representedLiteralValue
 }

package/apple/Sources/ExpoModulesMacrosCore/Macros/ExpoViewMacro.swift

@@ -26,6 +26,11 @@ import SwiftSyntaxMacros
 ///   public typealias Props = CardProps
 ///   extension CardView: AnyNativeView {}
 ///
+/// The view registers under its class name. Pass `@ExpoView<CardProps>("FancyCard")` to override it,
+/// and the expansion also gets a `_jsName` static that core reads in place of the class name:
+///
+///   public nonisolated static let _jsName = "FancyCard"
+///
 /// There is **no view definition**: no `ViewDefinition`, no `View(…) { }` builder, no `Props(_:)` or
 /// `Events(_:)` element. Core reaches the view through the `AnyNativeView` conformance: it reads the
 /// props type from the `Props` typealias, which satisfies the protocol's associated type, and the
@@ -83,11 +88,18 @@ public struct ExpoViewMacro: MemberMacro, ExtensionMacro {
       )
     }
 
-    return [
+    var emitted: [DeclSyntax] = [
       """
       public typealias Props = \(raw: propsType)
       """
     ]
+
+    // `AnyNativeView` defaults `_jsName` to the class name, so it's emitted only for an override.
+    // `nonisolated`, because the protocol is `@MainActor` and core reads the name off the main actor.
+    if let jsName = jsNameArgument(of: node) {
+      emitted.append("public nonisolated static let _jsName = \"\(raw: jsName)\"")
+    }
+    return emitted
   }
 
   public static func expansion(

package/apple/Sources/ExpoModulesMacrosCore/Macros/JSMacro.swift

@@ -25,6 +25,12 @@ import SwiftSyntaxMacros
 ///
 ///   @JS
 ///   var status: String { "ok" }
+///
+///   @JS(symbol: .iterator)
+///   func makeIterator() -> JavaScriptObject { ... }
+///
+///   @JS(symbol: "app.id")
+///   var id: String { ... }
 public struct JSMacro: PeerMacro {
   public static func expansion(
     of node: AttributeSyntax,
@@ -52,6 +58,7 @@ public struct JSMacro: PeerMacro {
     diagnoseAsyncVariantOption(of: node, on: declaration, in: context)
     diagnoseJavaScriptValuesOffThread(of: node, on: declaration, in: context)
     diagnoseRuntimeParameter(of: node, on: declaration, in: context)
+    diagnoseSymbolArgument(of: node, on: declaration, in: context)
 
     // In an `@ExpoModule` or `@SharedObject` class, the class macro emits the assertion instead: it sees
     // the type aliases declared in the class body, which this macro can't (see `TupleTypeAliases`).
@@ -200,6 +207,44 @@ private func removeAttributeFixIts(_ node: AttributeSyntax, before keyword: Toke
   ]
 }
 
+/// Emits the diagnostics for the `symbol:` argument of `@JS`, which binds the member under a symbol
+/// (see `JSMemberKey`). The argument must be a case of `JavaScriptSymbol.WellKnown` or a string literal
+/// that the macro can read, and an initializer can't take it, since a constructor has no key.
+private func diagnoseSymbolArgument(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  guard let argument = symbolArgument(of: node) else {
+    return
+  }
+  if declaration.is(InitializerDeclSyntax.self) {
+    context.diagnose(
+      Diagnostic(
+        node: argument,
+        message: JSDiagnosticMessage(
+          "'symbol:' applies only to a @JS function or property: JavaScript constructs a shared object with 'new', so an initializer isn't bound under a key.",
+          id: "js-symbol-on-initializer",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if symbolKey(of: node) == nil {
+    context.diagnose(
+      Diagnostic(
+        node: argument.expression,
+        message: JSDiagnosticMessage(
+          "'symbol:' takes a well-known symbol, such as '.iterator', or the registry key of 'Symbol.for' as a string literal, such as \"app.id\". The macro reads the argument from the source, so it can't be a variable, a constant or an interpolated string.",
+          id: "js-symbol-argument",
+          severity: .error
+        )
+      )
+    )
+  }
+}
+
 /// 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

package/apple/Sources/ExpoModulesMacrosCore/Support/DecorateModuleBuilder.swift

@@ -21,9 +21,13 @@ import SwiftSyntax
 /// A synchronous function can take the JavaScript runtime as its last parameter,
 /// `in runtime: borrowing JavaScriptRuntime`. JavaScript doesn't see it: the binding passes the runtime
 /// of the call.
+///
+/// A function marked `@JS(symbol: ...)` binds under a symbol instead of a string name (see
+/// `JSMemberKey`).
 internal struct JSFunction {
   let swiftName: String
-  private(set) var jsName: String
+  /// The key that the function binds under.
+  private(set) var key: JSMemberKey
   /// The parameters that take JavaScript arguments, without the runtime parameter.
   let parameters: [FunctionParameterSyntax]
   /// The label of the parameter that takes the JavaScript runtime, or `nil` when the function has none.
@@ -44,7 +48,7 @@ internal struct JSFunction {
 
   init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
     self.swiftName = funcDecl.name.text
-    self.jsName = jsNameArgument(of: attribute) ?? withoutBackticks(funcDecl.name.text)
+    self.key = JSMemberKey(attribute: attribute, defaultName: withoutBackticks(funcDecl.name.text))
     self.nameToken = funcDecl.name
     let declaredParameters = funcDecl.signature.parameterClause.parameters
     self.parameters = declaredParameters.filter { !isRuntimeParameter($0) }
@@ -68,7 +72,7 @@ internal struct JSFunction {
       return nil
     }
     var variant = self
-    variant.jsName = asyncVariantName.name
+    variant.key = .name(asyncVariantName.name)
     variant.nameToken = asyncVariantName.token
     variant.isAsync = true
     variant.isAsyncVariant = true
@@ -112,7 +116,7 @@ internal struct JSFunction {
       lines.append(
         """
         guard arguments.count == \(maximum) else {
-          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+          throw Exceptions.ArgumentsRangeMismatch((functionName: \(key.functionNameLiteral), received: arguments.count, required: \(required), maximum: \(maximum)))
         }
         """
       )
@@ -120,7 +124,7 @@ internal struct JSFunction {
       lines.append(
         """
         guard arguments.count >= \(required) && arguments.count <= \(maximum) else {
-          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+          throw Exceptions.ArgumentsRangeMismatch((functionName: \(key.functionNameLiteral), received: arguments.count, required: \(required), maximum: \(maximum)))
         }
         """
       )
@@ -337,6 +341,21 @@ internal struct JSFunction {
   /// the host-function closure is what keeps the native callable alive for as long as JS can invoke
   /// it; its lifetime is bounded by the JS VM's garbage collection of the object. A shared object
   /// captures nothing of the instance: it recovers the typed receiver from the JS `this` per call.
+  ///
+  /// A function bound under a symbol gets the symbol from the runtime first, so the statement is
+  /// marked `try`.
+  /// Whether the body of a synchronous binding uses the runtime: to decode an argument, to unwrap a shared
+  /// object from `this`, or to pass it to a function that takes the runtime.
+  private func bodyUsesRuntime(receiver: Receiver) -> Bool {
+    if runtimeLabel != nil || !parameters.isEmpty {
+      return true
+    }
+    if case .sharedObject = receiver {
+      return true
+    }
+    return false
+  }
+
   func decorateStatements(object: String, receiver: Receiver) -> String {
     // Every `@JS` binding hands `this` in as a borrowed `JavaScriptUnownedValue` instead of
     // allocating an owning `JavaScriptValue` and forming its `weak`-runtime reference on every call,
@@ -350,19 +369,21 @@ internal struct JSFunction {
     // returns nothing binds through the `Void` overload (`JavaScriptRuntime.VoidFunctionClosure`)
     // instead, which leaves JS's result as `undefined`. A call through it is faster than through a
     // result-slot closure that writes nothing. The closure declares `-> Void` because a body of several
-    // statements without a `return` is otherwise ambiguous between the overloads. A function that takes
-    // the runtime binds through the result-slot overload even when it returns nothing, so it gets the
-    // runtime as the closure's parameter instead of capturing the decorator's.
+    // statements without a `return` is otherwise ambiguous between the overloads. The `Void` overload
+    // doesn't get the runtime, so it's only for a body that doesn't use it: a function that decodes
+    // arguments, unwraps a shared object or takes the runtime binds through the result-slot overload even
+    // when it returns nothing. Capturing the decorator's runtime instead would make the runtime own a
+    // closure that retains it, so a runtime that owns its engine would never be freed.
     let captures = receiver.captureClause
     let parameters =
       isAsync
       ? "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
-      : returnType == nil && runtimeLabel == nil
+      : returnType == nil && !bodyUsesRuntime(receiver: receiver)
         ? "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) -> Void"
         : resultSlotClosureParameters
 
     return """
-        \(object).setProperty("\(jsName)") { \(captures)\(parameters) in
+        \(key.tryPrefix)\(object).setProperty(\(key.expression)) { \(captures)\(parameters) in
       \(bodyStatements(receiver: receiver, indent: "    "))
         }
       """
@@ -389,9 +410,13 @@ internal struct JSFunction {
 /// so each shared object instance stores its own value. `defineProperty` leaves a frozen object
 /// unchanged, so there the property stays an accessor. A `this` that isn't an object doesn't fail the read
 /// either: the getter still returns the value.
+///
+/// A property marked `@JS(symbol: ...)` binds under a symbol instead of a string name (see
+/// `JSMemberKey`).
 internal struct JSProperty {
   let swiftName: String
-  let jsName: String
+  /// The key that the property binds under.
+  let key: JSMemberKey
   /// The property's value type as written, or `nil` when it couldn't be inferred (no annotation and
   /// no literal default). When `nil` the getter still works (the encode infers from `self.<name>`)
   /// but the setter uses an untyped closure parameter.
@@ -451,7 +476,8 @@ internal struct JSProperty {
         getBody = "result.emplace(\(encode))"
       }
     } else {
-      let define = "this.getObject(in: runtime).defineProperty(\"\(jsName)\", value: value, options: [.enumerable])"
+      let define =
+        "\(key.tryPrefix)this.getObject(in: runtime).defineProperty(\(key.expression), value: value, options: [.enumerable])"
       // A module getter ignores `this` otherwise, so it can be anything, and only an object can hold the
       // value. A shared object's unwrap has already checked that `this` is an object.
       let defineStatement =
@@ -476,7 +502,7 @@ internal struct JSProperty {
       )
     }
 
-    lines.append("\(object).defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
+    lines.append("\(key.tryPrefix)\(object).defineProperty(\(key.expression), descriptor: \(descriptorName))")
 
     return
       lines
@@ -543,7 +569,10 @@ private func encodeIntoSlotStatement(_ type: String, freeForm: FreeFormConversio
 ///
 /// `configurableProperties` makes the property accessors configurable. `replacesInherited` first
 /// redefines the name of each function as a writable data property: the object may already hold an
-/// inherited accessor with that name, which an assignment would call instead of replacing.
+/// inherited accessor with that name, which an assignment would call instead of replacing. A function
+/// bound under a symbol that an object up the prototype chain holds as a read-only property or as an
+/// accessor without a setter is redefined first too, since an assignment can't shadow such a property
+/// (see `JSMemberKey.isInheritedReadOnly`).
 private func decorateBody(
   functions: [JSFunction],
   properties: [JSProperty],
@@ -554,11 +583,11 @@ private func decorateBody(
 ) -> String {
   let functionBody = functions.map { function in
     let binding = function.decorateStatements(object: object, receiver: receiver)
-    guard replacesInherited else {
+    guard replacesInherited || function.key.isInheritedReadOnly else {
       return binding
     }
     let redefine =
-      "  \(object).defineProperty(\"\(function.jsName)\", descriptor: .init(configurable: true, enumerable: true, writable: true))"
+      "  \(function.key.tryPrefix)\(object).defineProperty(\(function.key.expression), descriptor: .init(configurable: true, enumerable: true, writable: true))"
     return redefine + "\n" + binding
   }
   let propertyBody = properties.map {

package/apple/Sources/ExpoModulesMacrosCore/Support/JSMemberKey.swift

@@ -0,0 +1,125 @@
+import SwiftParser
+import SwiftSyntax
+
+/// The JavaScript property key that a `@JS` function or property binds under: a string name, from
+/// `@JS("name")` or the Swift name, or a symbol, from `@JS(symbol: ...)`.
+///
+/// - `@JS(symbol: .iterator)` binds under a well-known symbol, `Symbol.iterator`. The case name is
+///   a case of `JavaScriptSymbol.WellKnown`, which the macro declaration type-checks.
+/// - `@JS(symbol: "app.id")` binds under the symbol that the global registry holds for the key,
+///   `Symbol.for("app.id")`.
+internal enum JSMemberKey: Hashable {
+  /// The name in the form of `literalContent(of:)`, which the generated code puts between quotes.
+  case name(String)
+  /// The name of a case of `JavaScriptSymbol.WellKnown`, such as `iterator`.
+  case wellKnownSymbol(String)
+  /// The registry key, the value of the string literal with its escape sequences decoded.
+  case registeredSymbol(String)
+
+  /// The key of a `@JS` member: the `symbol:` argument of the attribute when it has one, else the
+  /// string name of the attribute, else `defaultName`.
+  init(attribute: AttributeSyntax, defaultName: String) {
+    self = symbolKey(of: attribute) ?? .name(jsNameArgument(of: attribute) ?? defaultName)
+  }
+
+  var isSymbol: Bool {
+    if case .name = self {
+      return false
+    }
+    return true
+  }
+
+  /// True for a well-known symbol that an object up the prototype chain of a binding target holds in a
+  /// way that an assignment can't shadow:
+  /// - `Symbol.hasInstance`, a read-only property of `Function.prototype`, which a shared object
+  ///   constructor inherits;
+  /// - `Symbol.toStringTag`, an accessor without a setter on the prototype of the base `SharedObject`
+  ///   class, which core defines.
+  ///
+  /// A function under such a key is defined with `defineProperty` before it is bound.
+  var isInheritedReadOnly: Bool {
+    guard case .wellKnownSymbol(let name) = self else {
+      return false
+    }
+    return name == "hasInstance" || name == "toStringTag"
+  }
+
+  /// How diagnostics name the key, as JavaScript code would write it: `name`, `Symbol.iterator` or
+  /// `Symbol.for("app.id")`.
+  var description: String {
+    switch self {
+    case .name(let name):
+      return name
+    case .wellKnownSymbol(let name):
+      return "Symbol.\(name)"
+    case .registeredSymbol(let key):
+      return "Symbol.for(\(swiftStringLiteral(key)))"
+    }
+  }
+
+  /// The string literal of the `name` of a function bound under the key, as JavaScript gives it to a
+  /// method: the string name, or the description of the symbol in brackets, such as
+  /// `[Symbol.iterator]` or `[app.id]`. It names the function in an argument count error.
+  var functionNameLiteral: String {
+    switch self {
+    case .name(let name):
+      return "\"\(name)\""
+    case .wellKnownSymbol(let name):
+      return "\"[Symbol.\(name)]\""
+    case .registeredSymbol(let key):
+      return swiftStringLiteral("[\(key)]")
+    }
+  }
+
+  /// The expression that the generated code passes as the key: a string literal, or a throwing call
+  /// that gets the symbol from the runtime in scope (see `tryPrefix`). A well-known symbol is cached
+  /// in the runtime after its first use.
+  var expression: String {
+    switch self {
+    case .name(let name):
+      return "\"\(name)\""
+    case .wellKnownSymbol(let name):
+      return "JavaScriptSymbol.wellKnown(runtime, .\(name))"
+    case .registeredSymbol(let key):
+      return "JavaScriptSymbol.for(runtime, \(swiftStringLiteral(key)))"
+    }
+  }
+
+  /// The `try ` that a statement passing `expression` needs, or an empty string for a string key.
+  var tryPrefix: String {
+    return isSymbol ? "try " : ""
+  }
+}
+
+/// The spellings of the type of the well-known symbols that a `symbol:` argument can name before the
+/// case. Any other base, such as a constant `Keys.iterator` of type `String`, isn't a well-known
+/// symbol.
+private let wellKnownSymbolTypeNames: Set<String> = [
+  "JavaScriptSymbol.WellKnown",
+  "ExpoModulesJSI.JavaScriptSymbol.WellKnown",
+  "ExpoModulesCore.JavaScriptSymbol.WellKnown",
+]
+
+/// The key of a `symbol:` argument, or `nil` when the attribute has none or the argument is neither
+/// a case of `JavaScriptSymbol.WellKnown` (`.iterator`, `JavaScriptSymbol.WellKnown.iterator`) nor a
+/// string literal without interpolation, which `@JS` reports.
+internal func symbolKey(of attribute: AttributeSyntax) -> JSMemberKey? {
+  guard let argument = symbolArgument(of: attribute) else {
+    return nil
+  }
+  if let member = argument.expression.as(MemberAccessExprSyntax.self) {
+    if let base = member.base, !wellKnownSymbolTypeNames.contains(base.trimmedDescription) {
+      return nil
+    }
+    return .wellKnownSymbol(withoutBackticks(member.declName.baseName.text))
+  }
+  if let value = argument.expression.as(StringLiteralExprSyntax.self)?.representedLiteralValue {
+    return .registeredSymbol(value)
+  }
+  return nil
+}
+
+/// The `symbol:` argument of an attribute, or `nil` when it has none.
+internal func symbolArgument(of attribute: AttributeSyntax) -> LabeledExprSyntax? {
+  return attribute.arguments?.as(LabeledExprListSyntax.self)?.first { $0.label?.text == "symbol" }
+}

package/apple/Sources/ExpoModulesMacrosCore/Support/JSNameCollisions.swift

@@ -2,8 +2,8 @@ import SwiftDiagnostics
 import SwiftSyntax
 import SwiftSyntaxMacros
 
-/// Reports each `@JS` member whose JavaScript name an earlier `@JS` member already binds on the same
-/// JavaScript object. Pass the members of one object only: a shared object's static members bind onto
+/// Reports each `@JS` member whose JavaScript name or symbol an earlier `@JS` member already binds on the
+/// same JavaScript object. A symbol never collides with a string name. Pass the members of one object only: a shared object's static members bind onto
 /// the constructor and its instance members onto the prototype, so the two sets are checked separately.
 internal func diagnoseJSNameCollisions(
   functions: [JSFunction],
@@ -14,11 +14,11 @@ internal func diagnoseJSNameCollisions(
   // name, JavaScript would reach only one. Members are compared in source order, so the error lands on
   // every member after the first, whichever kind each one is.
   let members = functions.map(BoundMember.init(function:)) + properties.map(BoundMember.init(property:))
-  var firstMembers: [String: BoundMember] = [:]
+  var firstMembers: [JSMemberKey: BoundMember] = [:]
 
   for member in members.sorted(by: { $0.nameToken.position < $1.nameToken.position }) {
-    guard let first = firstMembers[member.jsName] else {
-      firstMembers[member.jsName] = member
+    guard let first = firstMembers[member.key] else {
+      firstMembers[member.key] = member
       continue
     }
     let renaming =
@@ -27,12 +27,12 @@ internal func diagnoseJSNameCollisions(
       Diagnostic(
         node: member.nameToken,
         message: JSNameCollisionMessage(
-          "The JavaScript name '\(member.jsName)' is already bound by an earlier \(first.kind). A JavaScript object holds one member per name, so JavaScript could reach only one of them. Give one of them another name with \(renaming)."
+          "The JavaScript \(member.keyKind) '\(member.key.description)' is already bound by an earlier \(first.kind). A JavaScript object holds one member per \(member.keyKind), so JavaScript could reach only one of them. Give one of them another \(member.keyKind) with \(renaming)."
         ),
         notes: [
           Note(
             node: Syntax(first.nameToken),
-            message: JSNameCollisionNote("'\(member.jsName)' is first bound here")
+            message: JSNameCollisionNote("'\(member.key.description)' is first bound here")
           )
         ]
       )
@@ -80,14 +80,15 @@ internal func diagnoseReservedJSNames(
 ) {
   let members = functions.map(BoundMember.init(function:)) + properties.map(BoundMember.init(property:))
   for member in members {
-    guard let reason = target.reservedNames[member.jsName] else {
+    // A symbol key never means anything else on the object.
+    guard case .name(let jsName) = member.key, let reason = target.reservedNames[jsName] else {
       continue
     }
     context.diagnose(
       Diagnostic(
         node: member.nameToken,
         message: ReservedJSNameMessage(
-          "The JavaScript name '\(member.jsName)' can't be bound: \(reason). Give the \(member.kind) another name with \(member.renaming)."
+          "The JavaScript name '\(jsName)' can't be bound: \(reason). Give the \(member.kind) another name with \(member.renaming)."
         )
       )
     )
@@ -129,7 +130,7 @@ internal func diagnoseEventNameCollisions(in memberBlock: MemberBlockSyntax, in
 }
 
 private struct BoundMember {
-  let jsName: String
+  let key: JSMemberKey
   /// How the message names the member, such as `@JS function`.
   let kind: String
   /// The spelling that gives the member another JavaScript name.
@@ -138,18 +139,27 @@ private struct BoundMember {
 
   init(function: JSFunction) {
     // A `.withAsync` variant takes its JavaScript name from the option, not from `@JS("...")`.
-    self.jsName = function.jsName
+    self.key = function.key
     self.kind = function.isAsyncVariant ? "'.withAsync' variant" : "@JS function"
-    self.renaming = function.isAsyncVariant ? ".withAsync(\"...\")" : "@JS(\"...\")"
+    self.renaming = function.isAsyncVariant ? ".withAsync(\"...\")" : Self.renaming(of: function.key)
     self.nameToken = function.nameToken
   }
 
   init(property: JSProperty) {
-    self.jsName = property.jsName
+    self.key = property.key
     self.kind = "@JS property"
-    self.renaming = "@JS(\"...\")"
+    self.renaming = Self.renaming(of: property.key)
     self.nameToken = property.nameToken
   }
+
+  /// How the message names the key: `name` or `symbol`.
+  var keyKind: String {
+    return key.isSymbol ? "symbol" : "name"
+  }
+
+  private static func renaming(of key: JSMemberKey) -> String {
+    return key.isSymbol ? "@JS(symbol: ...)" : "@JS(\"...\")"
+  }
 }
 
 private struct JSNameCollisionMessage: DiagnosticMessage {

package/apple/Sources/ExpoModulesMacrosCore/Support/MacroHelpers.swift

@@ -1,28 +1,68 @@
+import SwiftParser
 import SwiftSyntax
 
 /// Reads the first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork".
-/// Returns nil if the attribute has no arguments or the first argument is not a string literal.
+/// Returns nil if the attribute has no arguments or the first argument is not an unlabeled string
+/// literal without interpolation, such as the `symbol:` argument of `@JS(symbol: "app.id")`. The
+/// name is in the form of `literalContent(of:)`.
 internal func jsNameArgument(of attribute: AttributeSyntax) -> String? {
   guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
     let first = args.first,
-    let str = first.expression.as(StringLiteralExprSyntax.self),
-    let segment = str.segments.first?.as(StringSegmentSyntax.self)
+    first.label == nil,
+    let literal = first.expression.as(StringLiteralExprSyntax.self)
   else {
     return nil
   }
-  return segment.content.text
+  return literalContent(of: literal)
+}
+
+/// The value of a string literal as the content of a plain Swift string literal: the value with its
+/// escape sequences decoded, and escaped again by `swiftStringLiteral(_:)` without the quotes. So
+/// the generated code can put it between quotes whatever the literal is: a raw string (`#"a"b"#`)
+/// reads as `a\"b`, and literals with the same value (`"id"`, `"\u{69}d"`) read the same. `nil` for
+/// a literal with interpolation.
+internal func literalContent(of literal: StringLiteralExprSyntax) -> String? {
+  guard let value = literal.representedLiteralValue else {
+    return nil
+  }
+  return String(swiftStringLiteral(value).dropFirst().dropLast())
+}
+
+/// A Swift string literal whose value is `value`. A quote, a backslash and the control characters are
+/// escaped, so any value gives a valid literal.
+internal func swiftStringLiteral(_ value: String) -> String {
+  var literal = "\""
+  for scalar in value.unicodeScalars {
+    switch scalar {
+    case "\"":
+      literal += "\\\""
+    case "\\":
+      literal += "\\\\"
+    case "\n":
+      literal += "\\n"
+    case "\r":
+      literal += "\\r"
+    case "\t":
+      literal += "\\t"
+    case _ where scalar.value < 0x20 || scalar.value == 0x7F:
+      literal += "\\u{\(String(scalar.value, radix: 16))}"
+    default:
+      literal.unicodeScalars.append(scalar)
+    }
+  }
+  return literal + "\""
 }
 
 /// True if the attribute lists the given option member, e.g. `@JS(.concurrent)`, `@Event(.inline)` or
 /// `@Event("name", EventOptions.inline)` -> true for the matching name. Options are written as
 /// member-access expressions, one per variadic argument. Array literals are scanned too, though the
 /// variadic declarations in `expo-modules-core` don't accept them. The leading string literal, when
-/// present, is the JS name and is skipped.
+/// present, is the JS name and is skipped, and so is the `symbol:` argument of `@JS`.
 internal func hasOption(_ attribute: AttributeSyntax, named option: String) -> Bool {
   guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
     return false
   }
-  for arg in args {
+  for arg in args where arg.label == nil {
     if namesOption(arg.expression, option) {
       return true
     }
@@ -88,18 +128,18 @@ private func asyncOptionCall(_ expression: ExprSyntax) -> FunctionCallExprSyntax
 
 /// The JavaScript name a `.withAsync("name")` option gives the promise-returning variant, with the
 /// token of its string literal, where a name collision is reported. `nil` when the argument isn't a
-/// single plain string literal, which `@JS` reports.
+/// string literal without interpolation, which `@JS` reports. The name is in the form of
+/// `literalContent(of:)`.
 internal func asyncVariantName(of option: FunctionCallExprSyntax) -> (name: String, token: TokenSyntax)? {
   guard option.arguments.count == 1,
     let argument = option.arguments.first,
     argument.label == nil,
     let literal = argument.expression.as(StringLiteralExprSyntax.self),
-    literal.segments.count == 1,
-    let segment = literal.segments.first?.as(StringSegmentSyntax.self)
+    let name = literalContent(of: literal)
   else {
     return nil
   }
-  return (segment.content.text, segment.content)
+  return (name, literal.segments.first?.as(StringSegmentSyntax.self)?.content ?? literal.openingQuote)
 }
 
 /// True if the `@JS`-marked declaration lists `.withAsync("name")`. Such a function is left
@@ -563,7 +603,6 @@ internal func collectProperties(
   varDecl: VariableDeclSyntax,
   attribute: AttributeSyntax
 ) -> [JSProperty] {
-  let jsNameOverride = jsNameArgument(of: attribute)
   // A `let` is never settable; only `var` bindings can carry a setter.
   let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
   let isLazy = isLazy(varDecl.modifiers)
@@ -580,7 +619,7 @@ internal func collectProperties(
       ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
     return JSProperty(
       swiftName: swiftName,
-      jsName: jsNameOverride ?? withoutBackticks(swiftName),
+      key: JSMemberKey(attribute: attribute, defaultName: withoutBackticks(swiftName)),
       valueType: valueType,
       // A literal-inferred type never mentions `Any`, so only an explicit annotation can be free-form.
       freeForm: binding.typeAnnotation.flatMap { freeFormConversion(of: $0.type) },

package/build/types.d.ts

@@ -177,6 +177,17 @@ export interface ExportedParameter {
     /** The default value as Swift source text (`1`, `"x"`, `.fast`), absent when none is written. */
     defaultValue?: string;
 }
+/** The symbol that a `@JS(symbol: ...)` member binds under. */
+export interface ExportedSymbol {
+    /**
+     * `wellKnown` for a well-known symbol such as `Symbol.iterator`, from `@JS(symbol: .iterator)`;
+     * `registered` for the symbol that the global registry holds for a key, `Symbol.for("app.id")`, from
+     * `@JS(symbol: "app.id")`.
+     */
+    kind: 'wellKnown' | 'registered';
+    /** The name of the well-known symbol, such as `iterator`, or the registry key. */
+    name: string;
+}
 /** One `@JS func` on a module or shared object. */
 export interface ExportedFunction extends ExportedAccess, ExportedAvailability {
     /**
@@ -185,9 +196,14 @@ export interface ExportedFunction extends ExportedAccess, ExportedAvailability {
     name: string;
     /**
      * The JS name it binds under: the `@JS("x")` override, else `name`. The second entry of a function
-     * with `.withAsync("x")` binds under `x`.
+     * with `.withAsync("x")` binds under `x`. Absent for a function bound under a symbol (see `symbol`).
      */
-    jsName: string;
+    jsName?: string;
+    /**
+     * The symbol it binds under with `@JS(symbol: ...)`, absent when it binds under `jsName`. Exactly one
+     * of `jsName` and `symbol` is present.
+     */
+    symbol?: ExportedSymbol;
     parameters: ExportedParameter[];
     /** Absent for a `Void` return. */
     returns?: TypeNode;
@@ -198,7 +214,16 @@ export interface ExportedFunction extends ExportedAccess, ExportedAvailability {
 /** One `@JS var` on a module or shared object. */
 export interface ExportedProperty extends ExportedAccess, ExportedAvailability {
     name: string;
-    jsName: string;
+    /**
+     * The JS name it binds under: the `@JS("x")` override, else `name`. Absent for a property bound
+     * under a symbol (see `symbol`).
+     */
+    jsName?: string;
+    /**
+     * The symbol it binds under with `@JS(symbol: ...)`, absent when it binds under `jsName`. Exactly one
+     * of `jsName` and `symbol` is present.
+     */
+    symbol?: ExportedSymbol;
     /** Absent when the type isn't determinable syntactically; the macro binds it getter-only. */
     type?: TypeNode;
     readonly: boolean;
@@ -401,7 +426,7 @@ export interface ExportedViewEvent extends ExportedAccess, ExportedAvailability
 export interface ExportedView extends ExportedAccess, ExportedAvailability {
     /** The Swift class name. Only a view declared at file scope is reported. */
     name: string;
-    /** The name the view registers under. `@ExpoView` takes no name, so it is always the class name. */
+    /** The name the view registers under: the `@ExpoView<CardProps>("Foo")` override, else the class name. */
     jsName: string;
     /**
      * The props type: the generic argument of `@ExpoView<CardProps>`, as written without backticks
@@ -451,8 +476,8 @@ export interface ScanStats {
 export interface ScannedClass {
     name: string;
     /**
-     * The resolved JS name: the `@ExpoModule("Foo")` or `@SharedObject("Foo")` override, else the class
-     * name. A view's JS name is its class name.
+     * The resolved JS name: the `@ExpoModule("Foo")`, `@SharedObject("Foo")` or
+     * `@ExpoView<CardProps>("Foo")` override, else the class name.
      */
     jsName: string;
     /**
@@ -535,5 +560,5 @@ export interface ExpandResult {
  * as a clear error instead of silently misread fields.
  */
 export declare const SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
-export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 11;
+export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 12;
 export declare const SUPPORTED_EXPAND_SCHEMA_VERSION = 1;

package/build/types.js

@@ -12,5 +12,5 @@ exports.SUPPORTED_EXPAND_SCHEMA_VERSION = exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_
  * as a clear error instead of silently misread fields.
  */
 exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
-exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 11;
+exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 12;
 exports.SUPPORTED_EXPAND_SCHEMA_VERSION = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-macros",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Swift macro plugin for Expo modules",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -26,9 +26,9 @@
     "typescript": "^5.4.0"
   },
   "optionalDependencies": {
-    "@expo/modules-macros-linux-arm64": "0.35.0",
-    "@expo/modules-macros-linux-x64": "0.35.0",
-    "@expo/modules-macros-win32-arm64": "0.35.0",
-    "@expo/modules-macros-win32-x64": "0.35.0"
+    "@expo/modules-macros-linux-arm64": "0.36.0",
+    "@expo/modules-macros-linux-x64": "0.36.0",
+    "@expo/modules-macros-win32-arm64": "0.36.0",
+    "@expo/modules-macros-win32-x64": "0.36.0"
   }
 }