expo-modules-macros 0.27.1 → 0.29.0

package/.github/workflows/linux.yml

@@ -15,7 +15,6 @@ concurrency:
 
 defaults:
   run:
-    working-directory: apple
     shell: bash
 
 jobs:
@@ -56,8 +55,8 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-
 
@@ -70,14 +69,13 @@ jobs:
       - name: Build release tool
         # Runs `pnpm run build` (scripts/build.js): builds the release plugin binary for this
         # architecture as platforms/linux-<arch>/ExpoModulesMacros.
-        working-directory: ${{ github.workspace }}
         run: pnpm run build
 
       - name: Verify the release tool
         # With no arguments it is the plugin server, which exits when stdin closes; with arguments it
         # is the scanner CLI.
         run: |
-          tool="../platforms/linux-${{ matrix.arch }}/ExpoModulesMacros"
+          tool="platforms/linux-${{ matrix.arch }}/ExpoModulesMacros"
           # The Swift runtime must be linked in statically, so no Swift library may be a dependency.
           needed="$(readelf --dynamic "$tool" | sed -n 's/.*(NEEDED).*\[\(.*\)\]$/\1/p')"
           echo "Needed libraries:" $needed
@@ -98,7 +96,6 @@ jobs:
         # Checks what `npm pack` would publish from `platforms/linux-<arch>`, where the release build
         # put the tool: the executable with its executable bit, the README, the license and the
         # manifest, with the `os`, `cpu` and `libc` fields for this machine.
-        working-directory: ${{ github.workspace }}
         run: |
           # The `./` matters: npm reads `platforms/linux-<arch>` as a GitHub repository.
           npm pack "./platforms/linux-${{ matrix.arch }}" --pack-destination "$RUNNER_TEMP" --json > "$RUNNER_TEMP/pack.json"
@@ -126,7 +123,6 @@ jobs:
       - name: Scan through the TypeScript wrapper
         # Installs the packed platform package. The wrapper must find the executable in
         # `@expo/modules-macros-linux-<arch>`, as it would in a project, not the local build.
-        working-directory: ${{ github.workspace }}
         run: |
           pnpm install
           pnpm add --save-optional "$PLATFORM_PACKAGE_TARBALL"

package/.github/workflows/publish.yml

@@ -284,14 +284,13 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-
 
       - name: Resolve dependencies
         run: swift package resolve
-        working-directory: apple
 
       - name: Install dependencies
         # The wrapper's `prepublishOnly` build needs `tsc`; the tool binary needs none.

package/.github/workflows/swift.yml

@@ -11,10 +11,6 @@ concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-defaults:
-  run:
-    working-directory: apple
-
 jobs:
   build-and-test:
     name: Build & test
@@ -34,8 +30,8 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-
 
@@ -46,26 +42,24 @@ jobs:
         # Runs `pnpm run build` (scripts/build.js): builds the universal
         # (arm64 + x86_64) release plugin binary, copies it to
         # apple/ExpoModulesMacros, and strips it.
-        working-directory: ${{ github.workspace }}
         run: pnpm run build
 
       - name: Verify universal binary
         run: |
-          archs="$(lipo -archs ExpoModulesMacros)"
+          archs="$(lipo -archs apple/ExpoModulesMacros)"
           echo "Architectures: $archs"
           case "$archs" in *arm64*) ;; *) echo "Missing arm64 slice"; exit 1;; esac
           case "$archs" in *x86_64*) ;; *) echo "Missing x86_64 slice"; exit 1;; esac
-          arch -arm64 ./ExpoModulesMacros < /dev/null
-          arch -x86_64 ./ExpoModulesMacros < /dev/null
+          arch -arm64 apple/ExpoModulesMacros < /dev/null
+          arch -x86_64 apple/ExpoModulesMacros < /dev/null
           # With arguments the same binary runs the scanner CLI instead of the plugin server.
-          arch -arm64 ./ExpoModulesMacros --help > /dev/null
-          arch -x86_64 ./ExpoModulesMacros --help > /dev/null
+          arch -arm64 apple/ExpoModulesMacros --help > /dev/null
+          arch -x86_64 apple/ExpoModulesMacros --help > /dev/null
 
       - name: Test
         run: swift test -v
 
       - name: Typecheck the TypeScript wrapper
-        working-directory: ${{ github.workspace }}
         run: |
           pnpm install
           pnpm run typecheck

package/.github/workflows/windows.yml

@@ -13,10 +13,6 @@ concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-defaults:
-  run:
-    working-directory: apple
-
 jobs:
   windows:
     name: Build & test (Windows ${{ matrix.arch }})
@@ -56,8 +52,8 @@ jobs:
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
-          path: apple/.build
-          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('apple/Package.resolved') }}
+          path: .build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('Package.resolved') }}
           restore-keys: |
             spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-
 
@@ -70,7 +66,6 @@ jobs:
       - name: Build release tool
         # Runs `pnpm run build` (scripts/build.js): builds the release plugin binary for this
         # architecture as platforms/win32-<arch>/ExpoModulesMacros.exe.
-        working-directory: ${{ github.workspace }}
         run: pnpm run build
 
       - name: Verify the release tool
@@ -79,7 +74,7 @@ jobs:
         # is the scanner CLI.
         shell: pwsh
         run: |
-          $exe = (Resolve-Path "../platforms/win32-${{ matrix.arch }}/ExpoModulesMacros.exe").Path
+          $exe = (Resolve-Path "platforms/win32-${{ matrix.arch }}/ExpoModulesMacros.exe").Path
           $env:PATH = "$env:SystemRoot\System32;$env:SystemRoot"
           cmd /c "`"$exe`" < NUL"
           if ($LASTEXITCODE -ne 0) { throw "The plugin server exited with $LASTEXITCODE" }
@@ -90,7 +85,6 @@ jobs:
         # Checks what `npm pack` would publish from `platforms/win32-<arch>`, where the release build
         # put the tool: the executable, the README, the license and the manifest, with the `os` and
         # `cpu` fields for this machine.
-        working-directory: ${{ github.workspace }}
         shell: pwsh
         run: |
           # The `./` matters: npm reads `platforms/win32-<arch>` as a GitHub repository.
@@ -109,7 +103,6 @@ jobs:
       - name: Scan through the TypeScript wrapper
         # Installs the packed platform package. The wrapper must find the executable in
         # `@expo/modules-macros-win32-<arch>`, as it would in a project, not the local build.
-        working-directory: ${{ github.workspace }}
         shell: pwsh
         run: |
           pnpm install

package/AGENTS.md

@@ -4,9 +4,11 @@
 
 ## Layout
 
-- `apple/Package.swift`: the SwiftPM package. The test targets are declared only when `apple/Tests` exists, because the published npm package leaves it out.
-- `apple/Sources/ExpoModulesMacros`: the compiler plugin executable. `Plugin.swift` registers the macros of `ProvidedMacro.all` in `providingMacros` and holds the entry point that sends any invocation with arguments to the CLI. `Macros/` holds one file per macro, and `Support/` the code that several macros share. `ProvidedMacros.swift` lists every macro with its attribute name and conformances in `ProvidedMacro.all`, and `Expand/MacroExpander.swift` runs the macros in process for `expand`, because only this executable target can see them.
-- `apple/Sources/ExpoModulesCLI`: the library behind the command-line tool. `CLI.swift` parses the arguments, `Commands/` holds one directory per subcommand (`ScanModules/` for autolinking, `ScanExports/` for type generation, `Expand/` for the report types and the output of `expand`, which gets the expansion from the executable as a `MacroExpander`), and `Core/` holds the shared parsing, `#if` evaluation and output.
+- `Package.swift`: the SwiftPM package, at the root so that its identity is `expo-modules-macros` (an `apple/` manifest would have the identity `apple`, which conflicts with other packages that keep theirs in `apple/`). The targets name their paths under `apple/`. The `ExpoModulesMacrosPlugin` library product vends the macro target to Swift packages, and its name must differ from the target's. The test targets are declared only when `apple/Tests` exists, because the published npm package leaves it out.
+- `apple/Sources/ExpoModulesMacrosCore`: the macro implementations, in a library target so that both executables below can link them. `Macros/` holds one file per macro, and `Support/` the code that several macros share. `ProvidedMacros.swift` lists every macro with its attribute name and conformances in `ProvidedMacro.all`. `PluginServer.swift` runs the compiler plugin protocol with a provider that resolves the macros of `ProvidedMacro.all` by type name, because the default `CompilerPlugin` lookup expects them in a module named `ExpoModulesMacros`. It uses the `@_spi(PluginMessage)` API of swift-syntax.
+- `apple/Sources/ExpoModulesMacros`: the `.macro` target that the `ExpoModulesMacrosPlugin` product vends to Swift packages. It only runs the plugin server, so Swift packages don't compile the CLI.
+- `apple/Sources/ExpoModulesMacrosTool`: the executable that ships as `apple/ExpoModulesMacros` and in the Windows and Linux packages. `main.swift` runs the plugin server without arguments and sends any invocation with arguments to the CLI.
+- `apple/Sources/ExpoModulesCLI`: the library behind the command-line tool. `CLI.swift` parses the arguments, `Commands/` holds one directory per subcommand (`ScanModules/` for autolinking, `ScanExports/` for type generation, `Expand/` for `expand`, with `MacroExpander.swift`, which runs the macros in process), and `Core/` holds the shared parsing, `#if` evaluation and output.
 - `apple/Sources/ExpoModulesOptimized`: declarations for the `@OptimizedFunction` macro.
 - `apple/Tests`: `ExpoModulesMacrosTests` (expansion tests) and `ExpoModulesCLITests`.
 - `platforms/`: the Windows packages `@expo/modules-macros-win32-x64` and `-arm64`, and the Linux packages `@expo/modules-macros-linux-x64` and `-arm64` (a `package.json` with `os` and `cpu`, plus `libc` on Linux, a README and a copy of `LICENSE`). The Publish workflow runs `scripts/set-platform-versions.js` to give them the version of this package. Their `ExpoModulesMacros.exe` (Windows) or `ExpoModulesMacros` (Linux) is written there by `pnpm run build` on that platform and isn't committed.
@@ -20,8 +22,8 @@
 Swift 6.2 is required (Xcode 26 or newer on macOS). The package manager is pnpm, at the version in `packageManager` in `package.json`.
 
 ```sh
-cd apple && swift build      # debug build
-cd apple && swift test       # all Swift tests
+swift build                  # debug build
+swift test                   # all Swift tests
 pnpm install                 # TypeScript dependencies
 pnpm run typecheck           # TypeScript wrapper
 pnpm run build               # release binary (slow; on macOS uses Rosetta for x86_64)
@@ -56,7 +58,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 - 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.
 - 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/ExpoModulesMacros/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`.
+- 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`.
 
 ## Contracts with other packages
 
@@ -64,6 +66,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 - **Generated code calls `expo-modules-core` API.** An expansion that uses a new core symbol only works with a core version that has it.
 - **Scanner output is versioned.** `scanModulesSchemaVersion` (`Commands/ScanModules/ScanModules.swift`), `scanExportsSchemaVersion` (`Commands/ScanExports/ExportedSurface.swift`) and `expandSchemaVersion` (`Commands/Expand/ExpandReport.swift`) change independently. When the output shape of a command changes, bump its version and update the matching `SUPPORTED_*_SCHEMA_VERSION` constant and mirror types in `src/types.ts`. `expo-modules-autolinking` also checks the `scan-modules` version.
 - **The binary path is part of the contract.** `expo-modules-autolinking` resolves this package from `expo-modules-core` and passes `-load-plugin-executable <package>/apple/<binary>#ExpoModulesMacros` to the compiler. The scanner wrapper in autolinking uses the same path, and `expo-modules-cli` uses `getScannerBinaryPath()`. On Windows the binary is `ExpoModulesMacros.exe` in `@expo/modules-macros-win32-<arch>`, and on Linux `ExpoModulesMacros` in `@expo/modules-macros-linux-<arch>`. Renaming or moving a binary needs a matching change in `expo/expo`.
+- **Swift packages depend on the product.** A Swift package that declares or uses the macros depends on the `ExpoModulesMacrosPlugin` product and builds the plugin from source, without the binary. Renaming the product or the macro target, or moving `Package.swift`, needs a matching change in `expo/expo`.
 
 ## Releases
 
@@ -74,4 +77,4 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 ## Installed copies
 
-In `node_modules`, the compiler runs the prebuilt binary `apple/ExpoModulesMacros` (on Windows and Linux, the binary from `@expo/modules-macros-<platform>-<arch>`); editing the Swift sources there has no effect. Macro and scanner fixes belong in this repository and ship in a new release. The TypeScript wrapper ships compiled in `build/`, since `src/` is not published.
+In `node_modules`, a CocoaPods build runs the prebuilt binary `apple/ExpoModulesMacros` (on Windows and Linux, the binary from `@expo/modules-macros-<platform>-<arch>`); editing the Swift sources there has no effect. Macro and scanner fixes belong in this repository and ship in a new release. The TypeScript wrapper ships compiled in `build/`, since `src/` is not published.

package/Package.swift

@@ -0,0 +1,110 @@
+// swift-tools-version: 6.2
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import CompilerPluginSupport
+import Foundation
+import PackageDescription
+
+let package = Package(
+  name: "ExpoModulesMacros",
+  platforms: [.macOS(.v13)],
+  products: [
+    // Lets a SwiftPM package depend on the macros, so the compiler builds and loads the plugin from
+    // source, with no `-load-plugin-executable` flag. A target that declares the macros with
+    // `#externalMacro(module: "ExpoModulesMacros", ...)` depends on this product, and the targets that
+    // depend on it get the plugin too. CocoaPods builds keep loading the prebuilt binary. The name
+    // differs from the macro target's, because SwiftPM already has a product of that name for it.
+    .library(name: "ExpoModulesMacrosPlugin", targets: ["ExpoModulesMacros"]),
+    .executable(name: "ExpoModulesMacrosTool", targets: ["ExpoModulesMacrosTool"]),
+  ],
+  dependencies: [
+    .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "604.0.0-latest")
+  ],
+  targets: [
+    // The macro implementations, shared by the plugin and the tool. The macro target can't be a
+    // dependency of an executable, so they live in a library target.
+    .target(
+      name: "ExpoModulesMacrosCore",
+      dependencies: [
+        .product(name: "SwiftSyntax", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+        .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+        // For the plugin server, which resolves the macros by type name (see PluginServer.swift).
+        .product(name: "_SwiftCompilerPluginMessageHandling", package: "swift-syntax"),
+      ],
+      path: "apple/Sources/ExpoModulesMacrosCore"
+    ),
+    // The plugin that Swift packages build from source. It serves only the macros, so it doesn't
+    // compile the CLI. It lists the swift-syntax products of the implementation again: when SwiftPM
+    // uses its prebuilt swift-syntax, it links the prebuilt library only for the products that the
+    // macro target itself depends on, and the link fails without them.
+    .macro(
+      name: "ExpoModulesMacros",
+      dependencies: [
+        "ExpoModulesMacrosCore",
+        .product(name: "SwiftSyntax", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+        .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+        .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
+      ],
+      path: "apple/Sources/ExpoModulesMacros"
+    ),
+    // The shipped binary, `apple/ExpoModulesMacros` and the Windows and Linux binaries. It is both the
+    // compiler plugin and the scanner CLI: the compiler launches it without arguments and speaks the
+    // plugin protocol over stdin, while an invocation with arguments dispatches into `ScannerCLI`
+    // (see main.swift). CocoaPods builds, `expo-modules-autolinking` and `expo-modules-cli` all
+    // use this one executable.
+    .executableTarget(
+      name: "ExpoModulesMacrosTool",
+      dependencies: [
+        "ExpoModulesCLI",
+        "ExpoModulesMacrosCore",
+      ],
+      path: "apple/Sources/ExpoModulesMacrosTool"
+    ),
+    .target(
+      name: "ExpoModulesCLI",
+      dependencies: [
+        "ExpoModulesMacrosCore",
+        .product(name: "SwiftSyntax", package: "swift-syntax"),
+        .product(name: "SwiftParser", package: "swift-syntax"),
+        .product(name: "SwiftIfConfig", package: "swift-syntax"),
+        // For `expand`, which runs the macros in process.
+        .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxMacroExpansion", package: "swift-syntax"),
+        .product(name: "SwiftParserDiagnostics", package: "swift-syntax"),
+        .product(name: "SwiftBasicFormat", package: "swift-syntax"),
+        .product(name: "SwiftDiagnostics", package: "swift-syntax"),
+      ],
+      path: "apple/Sources/ExpoModulesCLI"
+    ),
+  ]
+)
+
+// The Tests directory is excluded from the published npm package,
+// so only declare the test target when building from the repository.
+if FileManager.default.fileExists(atPath: Context.packageDirectory + "/apple/Tests") {
+  package.targets.append(
+    .testTarget(
+      name: "ExpoModulesMacrosTests",
+      dependencies: [
+        "ExpoModulesMacrosCore",
+        "ExpoModulesCLI",
+        .product(name: "SwiftSyntaxMacrosGenericTestSupport", package: "swift-syntax"),
+      ],
+      path: "apple/Tests/ExpoModulesMacrosTests"
+    )
+  )
+  package.targets.append(
+    .testTarget(
+      name: "ExpoModulesCLITests",
+      dependencies: [
+        "ExpoModulesCLI",
+        .product(name: "SwiftParser", package: "swift-syntax"),
+      ],
+      path: "apple/Tests/ExpoModulesCLITests"
+    )
+  )
+}

package/README.md

@@ -13,7 +13,7 @@ The same executable doubles as a source scanner CLI.
 
 # Installation
 
-This package is not meant to be installed directly. It is a dependency of `expo-modules-core`, so every Expo project already has it. The published package contains a prebuilt universal (arm64 + x86_64) macOS binary at `apple/ExpoModulesMacros`, so consumers never build the plugin themselves.
+This package is not meant to be installed directly. It is a dependency of `expo-modules-core`, so every Expo project already has it. The published package contains a prebuilt universal (arm64 + x86_64) macOS binary at `apple/ExpoModulesMacros`, so CocoaPods builds never build the plugin themselves. A Swift package can build it from source instead (see [Swift packages](#swift-packages)).
 
 The Windows and Linux binaries ship in their own packages, one per platform and architecture:
 
@@ -24,13 +24,15 @@ 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.
-- **`@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. 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 or the module's default isolation, 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.
+- **`@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. 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, sync: Bool = false)`** 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. `sync: true` dispatches inline instead of asynchronously.
-- **`@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.
-- **`@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. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
+- **`@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.
 
+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`.
+
 A tuple can cross the boundary as a `@JS` argument, result or property, a `@Record` property, a `@Union` payload, an `@Event` payload, or a parameter or result of a closure argument that isn't `async`. An unlabeled tuple such as `(Int, String)` maps to an array with one value per element, and a labeled tuple such as `(x: Double, y: Double)` to an object with one property per label. A tuple must have two or more elements, all labeled or none, and each element must be convertible. Tuples nest in other tuples, optionals, arrays and `String`-keyed dictionaries. `@ExpoModule` and `@SharedObject` also resolve a type alias of a tuple, such as `typealias Span = (start: Int, end: Int)`, when the class body declares it. A macro sees only the declaration it is attached to, so an alias declared anywhere else doesn't resolve.
 
 How that looks in a module:
@@ -64,6 +66,10 @@ final class Cache: SharedObject {
 
 The author-facing documentation for each macro lives next to its declaration in `expo-modules-core`, in `ios/Core/ExpoModulesMacros.swift`. This repository holds the implementations.
 
+## Sendable conformance
+
+Native code calls a module or shared object from more than one thread: a `.withAsync` variant runs on the concurrent thread pool, and events and closure arguments can be called from any thread. So the generated code needs the class to be `Sendable`. A subclass of `Module` or `SharedObject` can't be checked `Sendable`, because those base classes aren't, so `@ExpoModule` and `@SharedObject` add `extension MyModule: @unchecked Sendable {}`. The compiler doesn't check the class's mutable state then: keep state that more than one thread uses behind a lock or an actor. The macros add nothing when the class already declares `Sendable` or `@unchecked Sendable`, or inherits it. Swift warns on a subclass of a module or shared object until the subclass restates `@unchecked Sendable`.
+
 # Scanner
 
 The Swift compiler launches a plugin executable with no arguments and speaks the plugin protocol over stdin, so the binary treats any argument as a scanner invocation instead:
@@ -139,16 +145,33 @@ The binary is a compiled executable, so each call still spawns a process. What t
 
 to `OTHER_SWIFT_FLAGS` for `ExpoModulesCore`, every pod that depends on it, and their test specs. Expo's SPM prebuilds pass the same flag when they generate `Package.swift`, so both build systems load the same binary.
 
+## Swift packages
+
+The package manifest is `Package.swift` at the root of this package, so a Swift package can depend on it by its path in `node_modules` or by the URL of this repository. Its identity is then `expo-modules-macros`. The `ExpoModulesMacrosPlugin` library product holds the `ExpoModulesMacros` macro target:
+
+```swift
+dependencies: [
+  .package(path: "../node_modules/expo-modules-macros")
+],
+targets: [
+  .target(
+    name: "ExpoModulesCore",
+    dependencies: [.product(name: "ExpoModulesMacrosPlugin", package: "expo-modules-macros")]
+  )
+]
+```
+
+SwiftPM then builds the plugin from source for the host (the macros, without the scanner CLI) and loads it into every target that depends on that target, with no `-load-plugin-executable` flag and no unsafe flags. When the resolved swift-syntax version is a release, SwiftPM and Xcode can use their prebuilt swift-syntax for it, so only the sources of this package compile.
+
 On Windows and Linux, the compiler loads `ExpoModulesMacros.exe` from `@expo/modules-macros-win32-<arch>` or `ExpoModulesMacros` from `@expo/modules-macros-linux-<arch>` with the same flag. `getScannerBinaryPath()` in the TypeScript wrapper returns the binary for the current platform and architecture. On Windows and Linux it falls back to the local `pnpm run build` output in `platforms/<platform>-<arch>` when the platform package isn't installed, for example in this repository.
 
-The module and type names in `#externalMacro` must stay in sync with `apple/Sources/ExpoModulesMacros/Plugin.swift`.
+The module and type names in `#externalMacro` must stay in sync with `ProvidedMacro.all` in `apple/Sources/ExpoModulesMacrosCore/ProvidedMacros.swift`.
 
 # Development
 
 Requires a toolchain with Swift 6.2 or newer: on macOS 13 or newer that means Xcode 26 or newer, and on Windows and Linux the Swift toolchain from swift.org (CI uses 6.4).
 
 ```sh
-cd apple
 swift build
 swift test
 ```
@@ -168,7 +191,7 @@ cp "$(cd /tmp/swift-format && swift build -c release --show-bin-path)/swift-form
 
 Then add `~/.local/bin` to `PATH`.
 
-`pnpm run build` runs `scripts/build.js`, which builds the release binary with SwiftPM's native build system (Swift Build, the default since Swift 6.4, doesn't build a macro tool that no target in the package uses).
+`pnpm run build` runs `scripts/build.js`, which builds the release binary, the `ExpoModulesMacrosTool` executable, with SwiftPM's native build system.
 
 - On macOS, it builds for arm64 and x86_64, merges the slices into `apple/ExpoModulesMacros` with `lipo`, strips it, and verifies both slices are present. SwiftPM only builds macro tools for the host architecture, so the x86_64 slice is produced by running the toolchain under Rosetta; the script installs Rosetta if it is missing.
 - On Windows, it builds for the host architecture only, with the Swift runtime linked in statically and without debug info, and writes `platforms/win32-<arch>/ExpoModulesMacros.exe` (`x64` or `arm64`, as Node's `process.arch` names them), the file that the package for that architecture publishes. It strips the executable with `llvm-strip` from the Swift toolchain and checks the architecture in its header.

package/apple/Sources/ExpoModulesCLI/CLI.swift

@@ -110,7 +110,7 @@ public enum ScannerCLI {
 }
 
 /// The invoked executable's basename, so the usage text matches however the tool was launched
-/// (the `ExpoModulesMacros` shipped in the package, or a locally built `ExpoModulesMacros-tool`).
+/// (the `ExpoModulesMacros` shipped in the package, or a locally built `ExpoModulesMacrosTool`).
 private var toolName: String {
   guard let path = CommandLine.arguments.first else {
     return "ExpoModulesMacros"

package/apple/Sources/{ExpoModulesMacros → ExpoModulesCLI/Commands}/Expand/MacroExpander.swift

@@ -1,4 +1,4 @@
-import ExpoModulesCLI
+import ExpoModulesMacrosCore
 import SwiftBasicFormat
 import SwiftDiagnostics
 import SwiftParser

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

@@ -293,9 +293,12 @@ struct ExportedSharedObject: Encodable, Equatable {
   /// if a malformed source has more. Not named `constructor`, which every JS object inherits.
   var initializer: ExportedInitializer?
 
-  /// What the class inherits from `SharedRef<T>`, or `nil` when its superclass isn't `SharedRef`.
-  let sharedRef: ExportedSharedRef?
+  /// What the class inherits from `SharedRef<T>`, directly or through another scanned `@SharedObject`
+  /// class, or `nil` when it doesn't inherit `SharedRef`.
+  var sharedRef: ExportedSharedRef?
 
+  /// The class's `@JS` members, followed by the ones it inherits from scanned `@SharedObject`
+  /// superclasses (see `ExportedSurface.mergingInheritedMembers()`).
   var functions: [ExportedFunction]
   var properties: [ExportedProperty]
   var events: [ExportedEvent]
@@ -306,10 +309,24 @@ struct ExportedSharedObject: Encodable, Equatable {
   let platforms: [ExportedPlatform]
 
   let file: String
+
+  /// The superclass as written, without generic arguments, or `nil` when there is none or it is
+  /// `SharedObject` or `SharedRef`. Not encoded: it is only read to find the inherited members.
+  var superclass: String? = nil
+
+  /// The value of the class's own `nativeRefType` override (see `ExportedSharedRef.nativeRefType`), or
+  /// `.none` when it declares none. Not encoded: a subclass of a `SharedRef` subclass reports its own
+  /// override in the inherited `sharedRef`.
+  var ownNativeRefType: String?? = .none
+
+  private enum CodingKeys: String, CodingKey {
+    case name, jsName, initializer, sharedRef, functions, properties, events, accessLevel, platforms, file
+  }
 }
 
-/// The `SharedRef<T>` superclass of a shared object. Only the superclass written on the class is read,
-/// so a class that inherits `SharedRef` through another subclass has none.
+/// The `SharedRef<T>` superclass of a shared object. A class that inherits `SharedRef` through another
+/// `@SharedObject` class reports the `T` of that class. A class that inherits it through a class the
+/// scan doesn't report has none.
 struct ExportedSharedRef: Encodable, Equatable {
   /// The `T` in `SharedRef<T>`: the native type the object holds, which JS never sees.
   let native: TypeNode

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

@@ -0,0 +1,96 @@
+/// Adds to each `@SharedObject` class the `@JS` members it inherits from scanned `@SharedObject`
+/// superclasses.
+///
+/// The `@SharedObject` macro binds the members of the superclass on the JavaScript objects of the
+/// subclass too, since core builds each JavaScript class on the base `SharedObject` class and not on the
+/// JavaScript class of the superclass. So the reported surface of a subclass lists the inherited members
+/// as its own, and a consumer generates the same type as for any other class.
+
+extension ExportedSurface {
+  /// This surface with the inherited members added to each shared object. Runs after
+  /// `resolvingRefs()`, so the refs in an inherited member are resolved from the superclass that
+  /// declares it, as Swift resolves them.
+  ///
+  /// The superclass is looked up from the scope that encloses the class, the way `RefIndex` looks up a
+  /// ref. A superclass the scan doesn't report as a shared object (a protocol, a class without
+  /// `@SharedObject`, or a class from another module) ends the chain, so nothing is inherited through it.
+  ///
+  /// A superclass declared more than once, in `#if` branches, contributes the members of each
+  /// declaration whose platforms overlap the platforms of the class. Each member keeps its own
+  /// `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
+  /// 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.
+  ///
+  /// A class that inherits `SharedRef` through its superclass gets the `sharedRef` of the superclass,
+  /// with the class's own `nativeRefType` override when it has one.
+  func mergingInheritedMembers() -> ExportedSurface {
+    let index = RefIndex(surface: self)
+    let declarations = Dictionary(grouping: sharedObjects, by: \.name)
+
+    // `chain` holds the classes being merged, so a malformed cycle in the inheritance ends instead of
+    // recursing forever.
+    func merged(_ sharedObject: ExportedSharedObject, chain: Set<String>) -> ExportedSharedObject {
+      let scope = sharedObject.name.split(separator: ".").dropLast().joined(separator: ".")
+      guard let superclass = sharedObject.superclass,
+        let entry = index.lookup(superclass, in: scope),
+        entry.kind == .sharedObject,
+        !chain.contains(entry.name)
+      else {
+        return sharedObject
+      }
+      let platforms = Set(sharedObject.platforms.map(\.name))
+      let parents = (declarations[entry.name] ?? [])
+        .filter { declaration in declaration.platforms.contains { platforms.contains($0.name) } }
+        .map { merged($0, chain: chain.union([sharedObject.name])) }
+      guard !parents.isEmpty else {
+        return sharedObject
+      }
+      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) }
+      )
+      result.functions =
+        parents.flatMap(\.functions).filter {
+          !ownMembers.contains(MemberKey(jsName: $0.jsName, isStatic: $0.isStatic))
+        }
+        + sharedObject.functions
+      result.properties =
+        parents.flatMap(\.properties).filter {
+          !ownMembers.contains(MemberKey(jsName: $0.jsName, isStatic: $0.isStatic))
+        }
+        + sharedObject.properties
+      result.events = parents.flatMap(\.events) + sharedObject.events
+
+      // Every declaration of a superclass names the same superclass in practice, so the first one that
+      // inherits `SharedRef` stands for all of them.
+      if result.sharedRef == nil, let inherited = parents.lazy.compactMap(\.sharedRef).first {
+        result.sharedRef = ExportedSharedRef(
+          native: inherited.native,
+          nativeRefType: sharedObject.ownNativeRefType ?? inherited.nativeRefType
+        )
+      }
+      return result
+    }
+
+    return ExportedSurface(
+      modules: modules,
+      sharedObjects: sharedObjects.map { merged($0, chain: []) },
+      records: records,
+      enums: enums,
+      unions: unions
+    )
+  }
+}
+
+/// 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.
+private struct MemberKey: Hashable {
+  let jsName: String
+  let isStatic: Bool
+}

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

@@ -57,14 +57,15 @@ func scanExports(paths: [String]) -> ScanExportsResult {
   }
 
   // Refs resolve only once every file has been walked: a type parsed in one file may name a type
-  // declared in another, so the full set of declarations has to exist before any lookup is valid.
+  // declared in another, so the full set of declarations has to exist before any lookup is valid. The
+  // same holds for a superclass, so the inherited members are merged after that.
   let surface = ExportedSurface(
     modules: modules,
     sharedObjects: sharedObjects,
     records: records,
     enums: enums,
     unions: unions
-  ).resolvingRefs()
+  ).resolvingRefs().mergingInheritedMembers()
 
   return ScanExportsResult(
     schemaVersion: scanExportsSchemaVersion,