expo-modules-macros 0.31.0 → 0.32.0

package/.github/workflows/{swift.yml → macos.yml}

@@ -1,4 +1,6 @@
-name: Swift
+name: macOS
+
+# Builds and tests the package on macOS, and checks the universal release tool there.
 
 on:
   push:
@@ -12,8 +14,8 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build-and-test:
-    name: Build & test
+  macos:
+    name: Build & test (macOS)
     # The package declares swift-tools-version 6.2, which requires Xcode 26+.
     runs-on: macos-26
     steps:
@@ -63,3 +65,10 @@ jobs:
         run: |
           pnpm install
           pnpm run typecheck
+
+      - name: Scan through the TypeScript wrapper
+        # The wrapper must find the release tool in `apple/`, and `scanExports` must report the
+        # surface in `scripts/check-scan-exports.json`, which the Windows and Linux workflows also check.
+        run: |
+          pnpm run build:ts
+          node scripts/check-scan.js .

package/AGENTS.md

@@ -31,7 +31,7 @@ pnpm run swift:format        # format the Swift sources in place
 pnpm run swift:lint          # check the formatting, as CI does
 ```
 
-CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `pnpm run typecheck`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `pnpm run swift:lint`. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
+CI runs on macOS (`.github/workflows/macos.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, runs `swift test` and `pnpm run typecheck`, then scans through the TypeScript wrapper with `scripts/check-scan.js`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. On every platform, `check-scan.js` also requires `scanExports` to report the surface in `scripts/check-scan-exports.json` for its fixture, so the generated types are the same on each OS. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `pnpm run swift:lint`. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
 
 ## Windows
 
@@ -57,6 +57,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 ## Changing macros
 
 - The scanner re-implements the macros' naming and member rules on the syntax tree; it does not call the macro code. When a macro changes which members it binds or how it names them (the `@JS` name override, the `on` prefix `@Event` strips, which properties `@Record` treats as fields), change `scan-exports` to match, or generated TypeScript types drift from the runtime.
+- When the `scan-exports` output changes on purpose, update `scripts/check-scan-exports.json`: run `swift build`, then `node scripts/check-scan.js . --update .build/debug/ExpoModulesMacrosTool`, and review the diff. CI compares it with the output on macOS, Windows and Linux.
 - The scanner only parses files that pass the pre-filter, `MacroPrefilter` in `ExpoModulesCLI/Core/SourceScan.swift`. Each command builds it from the `macros` and `conformances` arguments of its `scanFiles` call. A new attribute or conformance the scanner must detect has to be added to those arguments (an attribute also needs a `DetectedMacro` case), or files that use it are skipped without an error.
 - A new macro needs: the implementation in `apple/Sources/ExpoModulesMacrosCore/Macros`, an entry in `ProvidedMacro.all` in `ProvidedMacros.swift` (with the attribute name and the extension conformances of its declaration), an expansion test file, the `#externalMacro` declaration in `expo-modules-core`, and an entry in the macro list in `README.md`.
 

package/README.md

@@ -25,11 +25,11 @@ 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. `@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. The macro also checks that every type crossing the boundary is convertible in the direction it travels. Outside a module or shared object, 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.
-- **`@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. 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 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.
-- **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first.
+- **`@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.
+- **`@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.
+- **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first. The macro warns about a case that an earlier case always decodes first: any case after a `JavaScriptValue` case, and a case with a payload that decodes only numbers, such as `Float` or `Int32`, after a `Double`, `Float` or `CGFloat` case.
 
 The members and conformances that `@Record` and `@Union` generate are `nonisolated`, so they also work in a module that builds with a default isolation, such as `-default-isolation MainActor`. The stored properties of a record still take that isolation. A class record, or a struct record with a property whose type isn't `Sendable`, then needs `nonisolated` on its declaration, for example `@Record nonisolated final class Options`.
 

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

@@ -29,8 +29,8 @@ import SwiftSyntaxMacros
 /// The synthesized property is deliberately **not** isolated to `@JavaScriptActor`, unlike `@JS`
 /// members: `emit` is itself non-isolated and schedules the dispatch onto the JS thread internally,
 /// so the event is callable from any thread or isolation with no actor hop at the call site. It is
-/// also self-contained: `@ExpoModule`/`@SharedObject` neither collect `@Event` members nor register
-/// their names anywhere.
+/// also self-contained: `@ExpoModule`/`@SharedObject` don't register `@Event` members anywhere. They
+/// read the event names only to warn when two events share one (see `diagnoseEventNameCollisions`).
 ///
 /// Two options change how the event is dispatched, and each one calls its own `EventEmitter` method,
 /// which is callable from any thread as well:
@@ -293,6 +293,16 @@ private func isDispatchOption(_ expression: ExprSyntax) -> Bool {
   return name == "inline" || name == "blocking"
 }
 
+/// The JS name of an `@Event` property: the `@Event("…")` override, or the default name derived from
+/// the property name. `nil` when the declaration isn't a single named property, which the macro reports.
+internal func eventJSName(of varDecl: VariableDeclSyntax, attribute: AttributeSyntax) -> String? {
+  guard varDecl.bindings.count == 1, let identifier = varDecl.bindings.first?.pattern.as(IdentifierPatternSyntax.self)
+  else {
+    return nil
+  }
+  return jsNameArgument(of: attribute) ?? defaultEventName(for: withoutBackticks(identifier.identifier.text))
+}
+
 // MARK: - Default event name
 
 /// The default JS event name for a property: the Swift name with the conventional `on` prefix

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

@@ -63,6 +63,16 @@ public struct ExpoModuleMacro: MemberMacro {
     for member in classDecl.memberBlock.members {
       // The types of a `@JS` member are read with the class's tuple aliases resolved.
       let decl = aliases.resolving(member.decl)
+      // A generic member is reported by `@JS` and left out, so the build has no errors in its binding.
+      if memberHasJSAttribute(decl) && jsGenericParameterClause(of: decl) != nil {
+        continue
+      }
+      // So is a `static` or `class` member: the module object binds only instance members.
+      if memberHasJSAttribute(decl),
+        let modifiers = decl.asProtocol(WithModifiersSyntax.self)?.modifiers, isTypeLevel(modifiers)
+      {
+        continue
+      }
       if memberHasJSAttribute(decl), let assertion = jsConformanceAssertionBody(for: decl) {
         assertions.append(assertion)
       }
@@ -86,6 +96,8 @@ public struct ExpoModuleMacro: MemberMacro {
     }
 
     diagnoseJSNameCollisions(functions: functions, properties: properties, in: context)
+    diagnoseReservedJSNames(functions: functions, properties: properties, on: .module, in: context)
+    diagnoseEventNameCollisions(in: classDecl.memberBlock, in: context)
 
     var emitted: [DeclSyntax] = []
 

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

@@ -31,6 +31,20 @@ public struct JSMacro: PeerMacro {
     providingPeersOf declaration: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
+    diagnosePlacement(of: node, on: declaration, in: context)
+    if let genericParameterClause = jsGenericParameterClause(of: declaration) {
+      context.diagnose(
+        Diagnostic(
+          node: genericParameterClause,
+          message: JSDiagnosticMessage(
+            "A @JS function or initializer can't be generic: the binding decodes each argument and encodes the result by its static type, which a generic parameter doesn't have. Use a concrete type, a @Union of the types, or 'JavaScriptValue'.",
+            id: "js-generic-member",
+            severity: .error
+          )
+        )
+      )
+      return []
+    }
     diagnoseParameterSpecifiers(in: declaration, in: context)
     diagnoseFreeFormTypes(in: declaration, in: context)
     diagnoseClosureTypes(in: declaration, in: context)
@@ -75,6 +89,116 @@ private func isInBindingClass(_ context: some MacroExpansionContext) -> Bool {
     || classDecl.attributes.firstAttribute(named: "SharedObject") != nil
 }
 
+/// Reports a `@JS` attribute that no macro binds, so the member would be missing in JavaScript without
+/// an error:
+/// - on a declaration other than a function, property or initializer, such as a subscript;
+/// - on a member of an extension, since `@ExpoModule` and `@SharedObject` read only the class body;
+/// - on a member of a type that isn't an `@ExpoModule` or `@SharedObject` class;
+/// - on a `static` or `class` member of an `@ExpoModule` class, since JavaScript gets only the instance;
+/// - on an initializer of an `@ExpoModule` class, since JavaScript doesn't construct a module.
+private func diagnosePlacement(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  guard
+    declaration.is(FunctionDeclSyntax.self) || declaration.is(VariableDeclSyntax.self)
+      || declaration.is(InitializerDeclSyntax.self)
+  else {
+    let kind = declaration.is(SubscriptDeclSyntax.self) ? "a subscript" : "this declaration"
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "@JS applies to a function, property or initializer, so \(kind) isn't bound to JavaScript. Expose a @JS function instead.",
+          id: "js-unsupported-declaration",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let extensionDecl = context.lexicalContext.first?.as(ExtensionDeclSyntax.self) {
+    let typeName = extensionDecl.extendedType.trimmedDescription
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "A @JS member of an extension isn't bound to JavaScript: @ExpoModule and @SharedObject bind only the @JS members declared in the class body. Move the member into the declaration of '\(typeName)'.",
+          id: "js-in-extension",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let enclosingType = context.lexicalContext.first, enclosingType.isProtocol(DeclGroupSyntax.self),
+    !isInBindingClass(context)
+  {
+    let typeName = enclosingType.asProtocol(NamedDeclSyntax.self).map { "'\($0.name.text)'" } ?? "this type"
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "A @JS member of \(typeName) isn't bound to JavaScript: only an @ExpoModule or @SharedObject class binds its @JS members. Add one of these macros to \(typeName), or move the member into such a class.",
+          id: "js-outside-binding-class",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let modifiers = declaration.asProtocol(WithModifiersSyntax.self)?.modifiers, isTypeLevel(modifiers),
+    let classDecl = context.lexicalContext.first?.as(ClassDeclSyntax.self),
+    classDecl.attributes.firstAttribute(named: "ExpoModule") != nil
+  {
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "A @JS member of an @ExpoModule class can't be 'static' or 'class': JavaScript gets one module object, and @ExpoModule binds the members of the instance to it. Make the member an instance member.",
+          id: "js-module-static-member",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if let initDecl = declaration.as(InitializerDeclSyntax.self),
+    let classDecl = context.lexicalContext.first?.as(ClassDeclSyntax.self),
+    classDecl.attributes.firstAttribute(named: "ExpoModule") != nil
+  {
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "@JS on an initializer of an @ExpoModule class isn't bound to JavaScript: JavaScript doesn't construct a module, it gets the instance that the app context creates. Remove @JS, or construct a @SharedObject class from JavaScript instead.",
+          id: "js-module-initializer",
+          severity: .error
+        ),
+        fixIts: removeAttributeFixIts(node, before: initDecl.initKeyword)
+      )
+    )
+  }
+}
+
+/// The fix-it that removes a `@JS` attribute written on its own line, with the line break and
+/// indentation before it. The macro gets the attribute without the trivia after it, so when the
+/// declaration starts on the line of the attribute (`@JS init()`), the fix-it can't tell how much
+/// space to remove, and there is none. It edits only the text of the attribute, since the declaration
+/// that a peer macro gets can carry attributes that other macros added.
+private func removeAttributeFixIts(_ node: AttributeSyntax, before keyword: TokenSyntax) -> [FixIt] {
+  guard keyword.leadingTrivia.contains(where: \.isNewline) else {
+    return []
+  }
+  return [
+    FixIt(
+      message: JSFixItMessage("Remove '@JS'", id: "js-remove-attribute"),
+      changes: [.replaceText(range: node.position..<node.endPosition, with: "", in: Syntax(node))]
+    )
+  ]
+}
+
 /// 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/Macros/RecordMacro.swift

@@ -81,6 +81,12 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     // the author's version stand — the factories only need *an* `init(<properties>)` and `Record` only
     // needs *an* `init()`, regardless of who wrote them.
     let existingInitLabels = initializerParameterLabels(of: declaration)
+    if !existingInitLabels.contains(properties.map { $0.key }) {
+      let diagnostics = unsetPrivatePropertyDiagnostics(of: declaration)
+      guard diagnostics.isEmpty else {
+        throw DiagnosticsError(diagnostics: diagnostics)
+      }
+    }
 
     var members: [DeclSyntax] = []
 
@@ -227,6 +233,10 @@ private func recordProperties(
       guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
         continue
       }
+      // The memberwise init sets every property, and a `let` with a default value can't be set again.
+      if varDecl.bindingSpecifier.tokenKind == .keyword(.let), binding.initializer != nil {
+        throw DiagnosticsError(diagnostics: [letWithDefaultDiagnostic(for: varDecl, name: ident.identifier.text)])
+      }
       // Prefer the explicit annotation. When it's omitted, recover the type from a literal default
       // (Swift's own default-literal type) — covers the common `var name = "foo"` case. Anything
       // whose type a syntactic macro can't determine (calls, collections, member access) still needs
@@ -637,6 +647,64 @@ private func unsupportedClassDiagnostics(of declaration: some DeclGroupSyntax) -
   return diagnostics
 }
 
+/// The errors for the `private` and `fileprivate` stored properties that the synthesized memberwise
+/// initializer would leave without a value. Such a property isn't a record property, so the initializer
+/// doesn't set it, and it needs a default value. An optional `var` starts as `nil`, so it needs none.
+private func unsetPrivatePropertyDiagnostics(of declaration: some DeclGroupSyntax) -> [Diagnostic] {
+  var diagnostics: [Diagnostic] = []
+  for member in declaration.memberBlock.members {
+    guard let varDecl = member.decl.as(VariableDeclSyntax.self),
+      let access = varDecl.modifiers.first(where: {
+        $0.name.tokenKind == .keyword(.private) || $0.name.tokenKind == .keyword(.fileprivate)
+      }),
+      !varDecl.modifiers.contains(where: {
+        $0.name.tokenKind == .keyword(.static) || $0.name.tokenKind == .keyword(.class)
+          || $0.name.tokenKind == .keyword(.lazy)
+      })
+    else {
+      continue
+    }
+    let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
+    for binding in varDecl.bindings where binding.accessorBlock == nil && binding.initializer == nil {
+      guard let ident = binding.pattern.as(IdentifierPatternSyntax.self),
+        !(isVar && binding.typeAnnotation.map { isOptionalType($0.type) } == true)
+      else {
+        continue
+      }
+      diagnostics.append(
+        Diagnostic(
+          node: ident,
+          message: RecordDiagnosticMessage(
+            "@Record leaves out the \(access.name.text) property '\(ident.identifier.text)', so the synthesized initializer doesn't set it. Give it a default value, or remove '\(access.name.text)' to make it a record property",
+            id: "record-unset-private-property"
+          )
+        )
+      )
+    }
+  }
+  return diagnostics
+}
+
+/// The error for a `let` property with a default value, attached to the `let` keyword and carrying a
+/// fix-it that replaces it with `var`. The default still applies when JavaScript omits the property.
+private func letWithDefaultDiagnostic(for varDecl: VariableDeclSyntax, name: String) -> Diagnostic {
+  let specifier = varDecl.bindingSpecifier
+  let fixIt = FixIt(
+    message: RecordFixItMessage("Replace 'let' with 'var'", id: "record-let-to-var"),
+    changes: [
+      .replace(oldNode: Syntax(specifier), newNode: Syntax(specifier.with(\.tokenKind, .keyword(.var))))
+    ]
+  )
+  return Diagnostic(
+    node: specifier,
+    message: RecordDiagnosticMessage(
+      "@Record property '\(name)' is a 'let' with a default value, so the synthesized initializer can't set it from JavaScript. Make it a 'var', and the default applies when JavaScript omits the property, or make it 'static' or 'private' to leave it out of the record",
+      id: "record-let-with-default"
+    ),
+    fixIts: [fixIt]
+  )
+}
+
 /// The fix-it for a record class that isn't `final`: add the modifier right before `class`.
 private func markFinalFixIt(for classDecl: ClassDeclSyntax) -> FixIt {
   // The new modifier takes over the leading trivia of `class` (the line break after the attribute

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

@@ -1,3 +1,4 @@
+import SwiftDiagnostics
 import SwiftSyntax
 import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
@@ -42,9 +43,13 @@ public struct SharedObjectMacro: MemberMacro {
       in: context
     )
 
-    // The superclass isn't checked here: the macro sees only this declaration, so it can't tell an
+    // A class without an inheritance clause has no superclass, so it can't be a `SharedObject`. Any
+    // other superclass isn't checked: 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.
+    if classDecl.inheritanceClause == nil {
+      throw DiagnosticsError(diagnostics: [missingBaseClassDiagnostic(for: classDecl)])
+    }
     let typeName = classDecl.name.text
     let jsName = jsNameArgument(of: node) ?? withoutBackticks(typeName)
 
@@ -71,6 +76,10 @@ public struct SharedObjectMacro: MemberMacro {
     for member in classDecl.memberBlock.members {
       // The types of a `@JS` member are read with the class's tuple aliases resolved.
       let decl = aliases.resolving(member.decl)
+      // A generic member is reported by `@JS` and left out, so the build has no errors in its binding.
+      if memberHasJSAttribute(decl) && jsGenericParameterClause(of: decl) != nil {
+        continue
+      }
       if memberHasJSAttribute(decl), let assertion = jsConformanceAssertionBody(for: decl) {
         assertions.append(assertion)
       }
@@ -114,6 +123,19 @@ public struct SharedObjectMacro: MemberMacro {
 
     diagnoseJSNameCollisions(functions: instanceFunctions, properties: instanceProperties, in: context)
     diagnoseJSNameCollisions(functions: staticFunctions, properties: staticProperties, in: context)
+    diagnoseReservedJSNames(
+      functions: instanceFunctions,
+      properties: instanceProperties,
+      on: .prototype,
+      in: context
+    )
+    diagnoseReservedJSNames(
+      functions: staticFunctions,
+      properties: staticProperties,
+      on: .constructor,
+      in: context
+    )
+    diagnoseEventNameCollisions(in: classDecl.memberBlock, in: context)
 
     // 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.
@@ -199,3 +221,59 @@ extension SharedObjectMacro: ExtensionMacro {
     return [sendable]
   }
 }
+
+/// The error for a `@SharedObject` class without an inheritance clause, with a fix-it that makes it
+/// inherit from `SharedObject`: `class Cache {` becomes `class Cache: SharedObject {`.
+private func missingBaseClassDiagnostic(for classDecl: ClassDeclSyntax) -> Diagnostic {
+  // The name carries the space before `{` as trailing trivia, so move it onto the clause to keep the
+  // spacing.
+  let name = classDecl.name
+  let clause = InheritanceClauseSyntax(
+    colon: .colonToken(trailingTrivia: .space),
+    inheritedTypes: InheritedTypeListSyntax([
+      InheritedTypeSyntax(type: TypeSyntax(IdentifierTypeSyntax(name: .identifier("SharedObject"))))
+    ])
+  )
+  let fixIt = FixIt(
+    message: SharedObjectFixItMessage("Inherit from 'SharedObject'", id: "sharedobject-add-base-class"),
+    changes: [
+      .replace(
+        oldNode: Syntax(classDecl),
+        newNode: Syntax(
+          classDecl
+            .with(\.name, name.with(\.trailingTrivia, []))
+            .with(\.inheritanceClause, clause.with(\.trailingTrivia, name.trailingTrivia))
+        )
+      )
+    ]
+  )
+  return Diagnostic(
+    node: name,
+    message: SharedObjectDiagnosticMessage(
+      "@SharedObject class '\(name.text)' must inherit from 'SharedObject', directly or through another class such as 'SharedRef'. Add ': SharedObject' to the class declaration.",
+      id: "sharedobject-missing-base-class"
+    ),
+    fixIts: [fixIt]
+  )
+}
+
+private struct SharedObjectDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+private struct SharedObjectFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}

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

@@ -35,7 +35,9 @@ import SwiftSyntaxMacros
 /// Discrimination is structural and order-dependent: the first case whose payload decodes wins. When
 /// two payload shapes overlap (two records with compatible fields, `Int` and `Double`), the earlier
 /// case matches; the author orders the more specific case first. A case may not repeat another case's
-/// payload type, since it could never be chosen.
+/// payload type, since it could never be chosen. A case after a `JavaScriptValue` case, or with a
+/// number-only payload after a `Double`, `Float` or `CGFloat` case, can't be chosen either, so the macro
+/// warns about it.
 ///
 /// The named-union counterpart of core's `Either`: any number of named cases instead of two anonymous
 /// slots, no `Any?` box, and an exhaustive `switch` as the primary way to read it (`as(_:)` covers the
@@ -48,6 +50,7 @@ public struct UnionMacro: MemberMacro, ExtensionMacro {
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
     let union = try validatedUnion(of: declaration)
+    diagnoseUnreachableCases(of: declaration, in: context)
 
     var members: [DeclSyntax] = []
 
@@ -223,8 +226,8 @@ private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> Unio
       let payloadType = parameter.type.trimmedDescription
       // Alternatives decode in declaration order and the first success wins, so a case whose payload
       // type repeats an earlier case's is unreachable: an exact-spelling duplicate is an error. (An
-      // overlap between *different* types, like `Int` and `Double`, is the author's ordering call and
-      // isn't checked here.)
+      // overlap between *different* types, like `Int` and `Double`, is the author's ordering call;
+      // `diagnoseUnreachableCases` warns about the overlaps that make a case unreachable.)
       let normalizedType = payloadType.filter { !$0.isWhitespace }
       if let earlierCase = seenPayloadTypes[normalizedType] {
         diagnostics.append(
@@ -256,6 +259,88 @@ private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> Unio
   return UnionType(name: enumDecl.name.text, cases: cases)
 }
 
+/// The payload types whose decode accepts every JavaScript number: they convert the number with
+/// `asDouble()`, so they never fail on one.
+private let anyNumberPayloadTypes: Set<String> = ["Double", "Float", "CGFloat"]
+
+/// The payload types that decode only a JavaScript number, so a case before them with a type of
+/// `anyNumberPayloadTypes` decodes every value they could. `Int`, `Int64`, `UInt` and `UInt64` aren't
+/// listed, since they also decode a `bigint`.
+private let numberOnlyPayloadTypes: Set<String> = [
+  "Double", "Float", "CGFloat", "Int8", "Int16", "Int32", "UInt8", "UInt16", "UInt32",
+]
+
+/// Warns about each case that an earlier case always decodes first, so it is never chosen. Cases are
+/// tried in declaration order and the first that decodes wins. The macro knows that only for some
+/// payload types: a `JavaScriptValue` payload decodes every value, and a floating-point payload every
+/// number, so a later case that decodes only numbers can't be reached. Types with the same spelling
+/// are reported as an error by `validatedUnion`, which runs first.
+private func diagnoseUnreachableCases(of declaration: some DeclGroupSyntax, in context: some MacroExpansionContext) {
+  var catchAllCase: (name: TokenSyntax, type: String)?
+  var anyNumberCase: (name: TokenSyntax, type: String)?
+
+  for member in declaration.memberBlock.members {
+    guard let caseDecl = member.decl.as(EnumCaseDeclSyntax.self) else {
+      continue
+    }
+    for element in caseDecl.elements {
+      guard let parameter = element.parameterClause?.parameters.first else {
+        continue
+      }
+      let type = unqualifiedPayloadTypeName(parameter.type)
+      let reason: String?
+      let earlier: (name: TokenSyntax, type: String)?
+      if let catchAllCase {
+        earlier = catchAllCase
+        reason = "'\(catchAllCase.type)' decodes every JavaScript value"
+      } else if let anyNumberCase, numberOnlyPayloadTypes.contains(type) {
+        earlier = anyNumberCase
+        reason = "'\(anyNumberCase.type)' decodes every JavaScript number, and '\(type)' decodes only numbers"
+      } else {
+        earlier = nil
+        reason = nil
+      }
+      if let earlier, let reason {
+        let name = element.name.text
+        context.diagnose(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' is never decoded: case '\(earlier.name.text)' is tried first, and \(reason). Move case '\(name)' before case '\(earlier.name.text)'.",
+              id: "union-unreachable-case",
+              severity: .warning
+            ),
+            notes: [
+              Note(
+                node: Syntax(earlier.name),
+                message: UnionNoteMessage(
+                  "case '\(earlier.name.text)' is declared here",
+                  id: "union-unreachable-case-earlier"
+                )
+              )
+            ]
+          )
+        )
+        continue
+      }
+      if type == "JavaScriptValue" {
+        catchAllCase = (element.name, type)
+      } else if anyNumberCase == nil, anyNumberPayloadTypes.contains(type) {
+        anyNumberCase = (element.name, type)
+      }
+    }
+  }
+}
+
+/// The name of a payload type without the module that it may be qualified with, such as `Swift.Double`.
+private func unqualifiedPayloadTypeName(_ type: TypeSyntax) -> String {
+  let modules = ["Swift", "CoreGraphics", "CoreFoundation", "Foundation", "ExpoModulesCore", "ExpoModulesJSI"]
+  if let memberType = type.as(MemberTypeSyntax.self), modules.contains(memberType.baseType.trimmedDescription) {
+    return memberType.name.text
+  }
+  return type.trimmedDescription
+}
+
 // MARK: - Synthesized members
 
 /// `decode(_:in:)`: tries each case's payload converter in declaration order and returns the first
@@ -429,11 +514,22 @@ private func defaultValueDiagnostic(
 private struct UnionDiagnosticMessage: DiagnosticMessage {
   let message: String
   let diagnosticID: MessageID
-  let severity: DiagnosticSeverity = .error
+  let severity: DiagnosticSeverity
 
-  init(_ message: String, id: String) {
+  init(_ message: String, id: String, severity: DiagnosticSeverity = .error) {
     self.message = message
     self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+    self.severity = severity
+  }
+}
+
+private struct UnionNoteMessage: NoteMessage {
+  let message: String
+  let noteID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.noteID = MessageID(domain: "ExpoModulesMacros", id: id)
   }
 }