expo-modules-macros 0.20.0 → 0.21.0

package/.github/workflows/linux.yml

@@ -0,0 +1,132 @@
+name: Linux
+
+# Builds and tests the package on Linux, and checks the release tool and its package there.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: apple
+    shell: bash
+
+jobs:
+  linux:
+    name: Build & test (Linux ${{ matrix.arch }})
+    runs-on: ${{ matrix.runner }}
+    # The release tool needs the glibc version that it's built against or a newer one. Red Hat UBI 9
+    # has glibc 2.34, the oldest version that the package supports. The Publish workflow builds the
+    # tool in the same image.
+    container: swift:6.4.0-rhel-ubi9@sha256:802a003f1eacbca9c20664a8ba79621d13f4538c3d329e745b7f8d53c70604a3
+    # The limit stops a hang, for example in the plugin server, from holding a runner for the default
+    # 6 hours.
+    timeout-minutes: 30
+    env:
+      # The newest glibc symbol version that the release tool may need. The READMEs of the Linux
+      # packages name it.
+      MAX_GLIBC_VERSION: '2.34'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - 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') }}
+          restore-keys: |
+            spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-
+
+      - name: Build
+        run: swift build
+
+      - name: Test
+        run: swift test
+
+      - name: Build release tool
+        # Runs `npm run build` (scripts/build.js): builds the release plugin binary for this
+        # architecture as platforms/linux-<arch>/ExpoModulesMacros.
+        working-directory: ${{ github.workspace }}
+        run: npm 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"
+          # 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
+          if echo "$needed" | grep -E 'swift|Foundation|dispatch|BlocksRuntime'; then
+            echo "The release tool links a Swift library dynamically"
+            exit 1
+          fi
+          glibc="$(objdump -T "$tool" | grep -o 'GLIBC_[0-9][0-9.]*' | sed 's/^GLIBC_//' | sort -uV | tail -n 1)"
+          echo "Newest glibc symbol version: $glibc"
+          if [ "$(printf '%s\n' "$glibc" "$MAX_GLIBC_VERSION" | sort -V | tail -n 1)" != "$MAX_GLIBC_VERSION" ]; then
+            echo "The release tool needs glibc $glibc, newer than $MAX_GLIBC_VERSION"
+            exit 1
+          fi
+          "$tool" < /dev/null
+          "$tool" --help > /dev/null
+
+      - name: Pack the platform package
+        # 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"
+          node - "$RUNNER_TEMP/pack.json" "${{ matrix.arch }}" <<'EOF'
+          const fs = require('node:fs');
+          const [packPath, arch] = process.argv.slice(2);
+          const [pack] = JSON.parse(fs.readFileSync(packPath, 'utf8'));
+          const files = pack.files.map((file) => file.path).sort().join(',');
+          console.log(`${pack.filename}: ${files} (${pack.size} bytes packed)`);
+          if (files !== 'ExpoModulesMacros,LICENSE,README.md,package.json') {
+            throw new Error(`Unexpected files: ${files}`);
+          }
+          const tool = pack.files.find((file) => file.path === 'ExpoModulesMacros');
+          if ((tool.mode & 0o111) === 0) {
+            throw new Error(`ExpoModulesMacros is packed without the executable bit (mode ${tool.mode.toString(8)})`);
+          }
+          const manifest = JSON.parse(fs.readFileSync(`platforms/linux-${arch}/package.json`, 'utf8'));
+          const fields = [manifest.os, manifest.cpu, manifest.libc].join(' / ');
+          if (fields !== `linux / ${arch} / glibc`) {
+            throw new Error(`Unexpected os / cpu / libc: ${fields}`);
+          }
+          fs.appendFileSync(process.env.GITHUB_ENV, `PLATFORM_PACKAGE_TARBALL=${process.env.RUNNER_TEMP}/${pack.filename}\n`);
+          EOF
+
+      - 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: |
+          npm install
+          npm install --no-save "$PLATFORM_PACKAGE_TARBALL"
+          npm run build:ts
+          node scripts/check-scan.js .
+

package/.github/workflows/publish.yml

@@ -70,11 +70,147 @@ jobs:
           path: platforms/win32-${{ matrix.arch }}/ExpoModulesMacros.exe
           if-no-files-found: error
 
+  build-linux:
+    name: Build Linux tool (${{ matrix.arch }})
+    # SwiftPM builds macro tools only for the host, so each architecture builds on a runner of its own.
+    runs-on: ${{ matrix.runner }}
+    # The tool needs the glibc version that it's built against or a newer one. Red Hat UBI 9 has
+    # glibc 2.34, the oldest version that the package supports. The Linux workflow uses the same image.
+    container: swift:6.4.0-rhel-ubi9@sha256:802a003f1eacbca9c20664a8ba79621d13f4538c3d329e745b7f8d53c70604a3
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Build release tool
+        # Runs scripts/build.js: builds the release plugin binary for this architecture as
+        # platforms/linux-<arch>/ExpoModulesMacros.
+        run: npm run build
+
+      - name: Upload tool
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          # Named after the package directory, like the Windows artifacts.
+          name: linux-${{ matrix.arch }}
+          path: platforms/linux-${{ matrix.arch }}/ExpoModulesMacros
+          if-no-files-found: error
+
+  verify-windows:
+    name: Verify Windows tool (${{ matrix.arch }})
+    needs: build-windows
+    # Installs the release tool from its packed package and scans through the TypeScript wrapper,
+    # before anything is published. The runner has no Swift toolchain.
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            runner: windows-latest
+          - arch: arm64
+            runner: windows-11-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Download tool
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: win32-${{ matrix.arch }}
+          path: platforms/win32-${{ matrix.arch }}
+
+      - name: Install the packed tool and scan
+        shell: pwsh
+        run: |
+          # The `./` matters: npm reads `platforms/win32-<arch>` as a GitHub repository.
+          $pack = npm pack "./platforms/win32-${{ matrix.arch }}" --pack-destination $env:RUNNER_TEMP --json | ConvertFrom-Json
+          if ($LASTEXITCODE -ne 0) { throw "npm pack failed" }
+          npm install
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          npm install --no-save (Join-Path $env:RUNNER_TEMP $pack[0].filename)
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          npm run build:ts
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          node scripts/check-scan.js .
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+  verify-linux:
+    name: Verify Linux tool (${{ matrix.arch }})
+    needs: build-linux
+    # Installs the release tool from its packed package, then scans through the TypeScript wrapper in
+    # images of the oldest distribution releases that the package supports, before anything is
+    # published. The images have no Swift toolchain, and the runner's Node runs in them.
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 15
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Download tool
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: linux-${{ matrix.arch }}
+          path: platforms/linux-${{ matrix.arch }}
+
+      - name: Install the packed tool
+        run: |
+          # Artifacts don't keep file modes, so the executable gets its executable bit back first.
+          chmod +x platforms/linux-${{ matrix.arch }}/ExpoModulesMacros
+          # 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"
+          tarball="$(node -p 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"))[0].filename' "$RUNNER_TEMP/pack.json")"
+          npm install
+          npm install --no-save "$RUNNER_TEMP/$tarball"
+          npm run build:ts
+
+      - name: Scan on each distribution
+        run: |
+          node_dir="$(dirname "$(dirname "$(command -v node)")")"
+          for image in ubuntu:22.04 debian:12 amazonlinux:2023; do
+            echo "::group::$image"
+            run=(docker run --rm -v "$PWD:/work:ro" -v "$node_dir:/node:ro" -w /work "$image")
+            "${run[@]}" getconf GNU_LIBC_VERSION
+            "${run[@]}" /node/bin/node scripts/check-scan.js .
+            echo "::endgroup::"
+          done
+
   publish:
     name: Build and publish to npm
-    needs: build-windows
-    # Builds the native macOS tool binary, so it must run on macOS. The Windows binaries come from the
-    # build-windows jobs.
+    needs: [build-windows, build-linux, verify-windows, verify-linux]
+    # Builds the native macOS tool binary, so it must run on macOS. The Windows and Linux binaries come
+    # from the build-windows and build-linux jobs.
     # The package declares swift-tools-version 6.2, which requires Xcode 26+.
     runs-on: macos-26
     permissions:
@@ -151,25 +287,38 @@ jobs:
         # copies it to apple/ExpoModulesMacros, and strips it.
         run: npm run build
 
-      - name: Download Windows tools
-        # Each artifact goes into the directory of its name: `platforms/win32-<arch>`.
+      - name: Verify the macOS tool
+        # Scans through the TypeScript wrapper, which must find the binary in `apple/`, before
+        # anything is published. The verify-windows and verify-linux jobs check the other binaries.
+        run: |
+          npm run build:ts
+          node scripts/check-scan.js .
+
+      - name: Download Windows and Linux tools
+        # Each artifact goes into the directory of its name: `platforms/<platform>-<arch>`.
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
-          pattern: win32-*
+          pattern: '{win32,linux}-*'
           path: platforms
 
-      - name: Verify Windows tools
-        run: ls -l platforms/win32-x64/ExpoModulesMacros.exe platforms/win32-arm64/ExpoModulesMacros.exe
+      - name: Verify Windows and Linux tools
+        # Artifacts don't keep file modes, so the Linux executables get their executable bit back
+        # here. `npm publish` keeps it in the package.
+        run: |
+          chmod +x platforms/linux-x64/ExpoModulesMacros platforms/linux-arm64/ExpoModulesMacros
+          ls -l \
+            platforms/win32-x64/ExpoModulesMacros.exe platforms/win32-arm64/ExpoModulesMacros.exe \
+            platforms/linux-x64/ExpoModulesMacros platforms/linux-arm64/ExpoModulesMacros
 
-      - name: Publish the Windows packages
+      - name: Publish the Windows and Linux packages
         # Published before `expo-modules-macros`, whose optional dependencies point at them, so that
         # package is never on npm without them. Each package needs trusted publishing (OIDC)
         # configured on npmjs.com for this workflow.
         env:
           DRY_RUN: ${{ inputs.dry_run && '--dry-run' || '' }}
         run: |
-          for arch in x64 arm64; do
-            npm publish --access public --tag "${{ steps.bump.outputs.tag }}" $DRY_RUN "./platforms/win32-$arch"
+          for package in win32-x64 win32-arm64 linux-x64 linux-arm64; do
+            npm publish --access public --tag "${{ steps.bump.outputs.tag }}" $DRY_RUN "./platforms/$package"
           done
 
       - name: Publish

package/.github/workflows/windows.yml

@@ -1,7 +1,6 @@
 name: Windows
 
-# Builds and tests the package on Windows, and checks the release tool there. The Windows binaries
-# aren't published yet, so this runs apart from the macOS workflow.
+# Builds and tests the package on Windows, and checks the release tool and its package there.
 
 on:
   push:
@@ -116,29 +115,5 @@ jobs:
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           npm run build:ts
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          $fixture = Join-Path $env:RUNNER_TEMP "scan-fixture"
-          New-Item -ItemType Directory -Force $fixture | Out-Null
-          Set-Content (Join-Path $fixture "Module.swift") "@ExpoModule`npublic final class WindowsModule {}"
-          @'
-          const path = require('node:path');
-          const { getScannerBinaryPath, scanModules } = require(path.resolve('build'));
-          const binaryPath = getScannerBinaryPath();
-          const expected = path.join('node_modules', '@expo', `modules-macros-win32-${process.arch}`, 'ExpoModulesMacros.exe');
-          if (!binaryPath.endsWith(expected)) {
-            console.error(`getScannerBinaryPath() returned ${binaryPath}, not a path ending in ${expected}`);
-            process.exit(1);
-          }
-          console.log(`getScannerBinaryPath() returned ${binaryPath}`);
-          scanModules([process.argv[2]]).then((result) => {
-            const module = result.modules.find((candidate) => candidate.name === 'WindowsModule');
-            if (!module) {
-              console.error(JSON.stringify(result, null, 2));
-              process.exit(1);
-            }
-            console.log(`scanModules reported ${module.name} in ${module.file}`);
-          }, (error) => {
-            console.error(error);
-            process.exit(1);
-          });
-          '@ | Set-Content (Join-Path $env:RUNNER_TEMP "scan-check.js")
-          node (Join-Path $env:RUNNER_TEMP "scan-check.js") $fixture
+          node scripts/check-scan.js .
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

package/AGENTS.md

@@ -9,10 +9,10 @@
 - `apple/Sources/ExpoModulesScanner`: the scanner library. `Modules/` implements `scan-modules` (autolinking), `Exports/` implements `scan-exports` (type generation), `Core/` holds the shared parsing and `#if` evaluation, and `CLI.swift` is the command-line front end.
 - `apple/Sources/ExpoModulesOptimized`: declarations for the `@OptimizedFunction` macro.
 - `apple/Tests`: `ExpoModulesMacrosTests` (expansion tests) and `ExpoModulesScannerTests`.
-- `platforms/`: the Windows packages `@expo/modules-macros-win32-x64` and `-arm64` (a `package.json` with `os` and `cpu`, 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` is written there by `npm run build` on Windows and isn't committed.
+- `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 `npm run build` on that platform and isn't committed.
 - `apple/PodTests`: a stub test so that `expo/expo` native tests can install this package as a pod. Do not add real tests here.
 - `src/`: the TypeScript wrapper around the scanner CLI. `types.ts` mirrors the Swift `Codable` output types by hand.
-- `scripts/build.js` (`npm run build`): builds the release binaries: the universal macOS `apple/ExpoModulesMacros` (committed and published), and on Windows `platforms/win32-<arch>/ExpoModulesMacros.exe` for the host architecture (not committed; published in that package).
+- `scripts/build.js` (`npm run build`): builds the release binaries: the universal macOS `apple/ExpoModulesMacros` (committed and published), and on Windows and Linux `platforms/win32-<arch>/ExpoModulesMacros.exe` or `platforms/linux-<arch>/ExpoModulesMacros` for the host architecture (not committed; published in that package).
 
 ## Commands
 
@@ -25,13 +25,18 @@ npm run typecheck            # TypeScript wrapper
 npm run build                # release binary (slow; on macOS uses Rosetta for x86_64)
 ```
 
-CI runs on macOS (`.github/workflows/swift.yml`) and on Windows x64 and arm64 (`.github/workflows/windows.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `npm 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, which must find the executable there. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
+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 `npm 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. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
 
 ## Windows
 
 - Outside Apple platforms, `Sources` import `FoundationEssentials` instead of `Foundation` (`#if canImport(FoundationEssentials)`). Full Foundation brings in ICU, which would add tens of megabytes to the statically linked Windows binary. Don't use APIs that only `Foundation` has (`FileHandle`, `NSRegularExpression`, `CharacterSet`, `FileManager.enumerator`, `NSString` path methods); `Core/StandardStreams.swift` writes to stdout and stderr.
 - The Windows binaries link the Swift runtime statically (`-static-stdlib`), because Swift has no stable ABI on Windows and the scanner must also run without a Swift toolchain. SwiftPM's `--static-swift-stdlib` has no effect there.
 
+## Linux
+
+- The `FoundationEssentials` rule above applies on Linux too.
+- The Linux binaries link the Swift runtime statically (`-static-stdlib`; SwiftPM's `--static-swift-stdlib` doesn't apply to the macro tool here either) but link glibc and the GNU C++ runtime dynamically, so they need the glibc version they were built against or a newer one. CI and the Publish workflow build them in `swift:6.4.0-rhel-ubi9` (glibc 2.34), and the Linux workflow fails when the binary needs a newer glibc symbol than `MAX_GLIBC_VERSION`. A change to the build image must keep these and the glibc version in the READMEs in sync.
+
 ## Conventions
 
 - Swift uses 2-space indentation. Write new doc comments as `///` line comments, not `/** */` blocks.
@@ -52,14 +57,14 @@ CI runs on macOS (`.github/workflows/swift.yml`) and on Windows x64 and arm64 (`
 - **Macro declarations live in `expo-modules-core`** (`ios/Core/ExpoModulesMacros.swift` in `expo/expo`), as `#externalMacro(module: "ExpoModulesMacros", type: ...)`. Adding a macro, renaming a macro type or changing a macro's signature needs a matching edit there, and the type must be listed in `providingMacros` in `Plugin.swift`.
 - **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` (`Modules/ScanModules.swift`) and `scanExportsSchemaVersion` (`Exports/ExportedSurface.swift`) change independently. When the output shape of a command changes, bump its version and update the matching `SUPPORTED_SCAN_*_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>`. Renaming or moving a binary needs a matching change in `expo/expo`.
+- **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`.
 
 ## Releases
 
-- Do not rebuild or commit the binary under `apple/` in a feature change. Only the **Publish** workflow (`.github/workflows/publish.yml`, manual) rebuilds it, and it commits the result as `Release vX.Y.Z` after the npm publish succeeds. It also builds the Windows binaries and publishes them in the `platforms/` packages, with the same version.
+- Do not rebuild or commit the binary under `apple/` in a feature change. Only the **Publish** workflow (`.github/workflows/publish.yml`, manual) rebuilds it, and it commits the result as `Release vX.Y.Z` after the npm publish succeeds. It also builds the Windows and Linux binaries and publishes them in the `platforms/` packages, with the same version. Before it publishes anything, it installs each binary from its packed package and scans through the TypeScript wrapper with `scripts/check-scan.js`.
 - Do not edit the `version` in `package.json` by hand. The Publish workflow bumps it.
 - Commit and PR titles are short and imperative, with code identifiers in backticks, for example ``Report `@Union` types in `scan-exports` ``.
 
 ## Installed copies
 
-In `node_modules`, the compiler runs the prebuilt binary `apple/ExpoModulesMacros` (on Windows, `ExpoModulesMacros.exe` from `@expo/modules-macros-win32-<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`, 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.

package/README.md

@@ -15,12 +15,17 @@ The same executable doubles as a source scanner CLI.
 
 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.
 
-The Windows binaries ship in their own packages, `@expo/modules-macros-win32-x64` and `@expo/modules-macros-win32-arm64`, each with an `ExpoModulesMacros.exe`. This package lists them as optional dependencies, and their `os` and `cpu` fields make npm, pnpm and Yarn install only the one that matches a Windows machine, so other machines don't download them. The Swift runtime is linked in statically, so the executables run without a Swift toolchain; they need only Windows system libraries and the Microsoft Visual C++ runtime.
+The Windows and Linux binaries ship in their own packages, one per platform and architecture:
+
+- `@expo/modules-macros-win32-x64` and `@expo/modules-macros-win32-arm64`, each with an `ExpoModulesMacros.exe`. They need only Windows system libraries and the Microsoft Visual C++ runtime.
+- `@expo/modules-macros-linux-x64` and `@expo/modules-macros-linux-arm64`, each with an `ExpoModulesMacros`. They need glibc 2.34 or newer and the GNU C++ runtime (`libstdc++` and `libgcc_s`), for example on Ubuntu 22.04, Debian 12, Red Hat Enterprise Linux 9 or Amazon Linux 2023. They don't run on musl distributions such as Alpine Linux.
+
+This package lists them as optional dependencies, and their `os`, `cpu` and (on Linux) `libc` fields make npm, pnpm and Yarn install only the one that matches the machine, so other machines don't download them. The Swift runtime is linked in statically, so the executables run without a Swift toolchain.
 
 # 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. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. 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.
+- **`@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, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. 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 `SharedObject` subclass. Collects the class's `@JS` members into a class definition that a module exposes through `@ExpoModule(classes:)`.
 - **`@Record()`** on a record type. 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.
@@ -97,13 +102,13 @@ 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.
 
-On Windows, the compiler loads `ExpoModulesMacros.exe` from `@expo/modules-macros-win32-<arch>` with the same flag. `getScannerBinaryPath()` in the TypeScript wrapper returns the binary for the current platform and architecture. On Windows it falls back to the local `npm run build` output in `platforms/win32-<arch>` when the platform package isn't installed, for example in this repository.
+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 `npm 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`.
 
 # Development
 
-Requires a toolchain with Swift 6.2 or newer: on macOS 13 or newer that means Xcode 26 or newer, and on Windows the Swift toolchain from swift.org (CI uses 6.4).
+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
@@ -115,16 +120,17 @@ swift test
 
 - 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.
+- On Linux, it also builds for the host architecture only, with the Swift runtime linked in statically, and writes `platforms/linux-<arch>/ExpoModulesMacros`. It strips the executable with `strip` and checks the architecture in its ELF header. The executable needs the glibc version of the machine it's built on or a newer one, so CI and the Publish workflow build it in the `swift:6.4.0-rhel-ubi9` image (Red Hat UBI 9, glibc 2.34).
 
-The macOS binary is committed to the repository. The Windows binaries aren't: the Publish workflow builds them and puts them into the packages in `platforms/`.
+The macOS binary is committed to the repository. The Windows and Linux binaries aren't: the Publish workflow builds them and puts them into the packages in `platforms/`.
 
 # Releasing
 
 The **Publish** workflow is manual (`workflow_dispatch`) and takes a release type. It bumps the version, builds the universal binary, and publishes to npm through OIDC trusted publishing. The commit, tag and GitHub release are created only after the publish succeeds, so a failed build leaves the branch untouched.
 
-Windows jobs (x64 and arm64) build the `.exe` files first. After the version bump, `scripts/set-platform-versions.js` gives the packages in `platforms/` the same version and lists them in this package's `optionalDependencies` with that exact version. The workflow publishes the two Windows packages before `expo-modules-macros`, so this package is never on npm without them. Each package needs trusted publishing configured on npmjs.com for the Publish workflow.
+Windows and Linux jobs (x64 and arm64 for each) build their binaries first. Verify jobs then install each binary from its packed package and scan through the TypeScript wrapper with `scripts/check-scan.js`, on Windows runners without Swift and, for Linux, in the Ubuntu 22.04, Debian 12 and Amazon Linux 2023 images. The publish job does the same for the macOS binary, so a failed check stops the release before anything is published. After the version bump, `scripts/set-platform-versions.js` gives the packages in `platforms/` the same version and lists them in this package's `optionalDependencies` with that exact version. The workflow publishes the four platform packages before `expo-modules-macros`, so this package is never on npm without them. Each package needs trusted publishing configured on npmjs.com for the Publish workflow.
 
-Prerelease versions (`prepatch`, `preminor`, `premajor`, `prerelease`) are published with the `next` dist-tag, and the others with `latest`. With **Dry run** checked, the workflow builds everything and runs `npm publish --dry-run` for the three packages, but doesn't publish, commit, tag or create a release. Use it to check a change to the workflow.
+Prerelease versions (`prepatch`, `preminor`, `premajor`, `prerelease`) are published with the `next` dist-tag, and the others with `latest`. With **Dry run** checked, the workflow builds everything and runs `npm publish --dry-run` for the five packages, but doesn't publish, commit, tag or create a release. Use it to check a change to the workflow.
 
 # Contributing
 

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -23,10 +23,13 @@ internal struct JSFunction {
   let returnFreeForm: FreeFormConversion?
   let isThrowing: Bool
   let isAsync: Bool
+  /// The function's name in the source, where a JavaScript name collision is reported.
+  let nameToken: TokenSyntax
 
   init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
     self.swiftName = funcDecl.name.text
     self.jsName = jsNameArgument(of: attribute) ?? withoutBackticks(funcDecl.name.text)
+    self.nameToken = funcDecl.name
     self.parameters = Array(funcDecl.signature.parameterClause.parameters)
 
     let declaredReturnType = funcDecl.signature.returnClause?.type
@@ -313,6 +316,8 @@ internal struct JSProperty {
   /// Whether the property is settable from JS: `true` for a stored `var` or a computed `var` with an
   /// explicit `set` accessor; `false` for a getter-only computed `var` or a `let`.
   let isSettable: Bool
+  /// The property's name in the source, where a JavaScript name collision is reported.
+  let nameToken: TokenSyntax
 
   /// The statements that install this property's accessor on the JS object, indented for the
   /// decorator body. Builds a descriptor object (`enumerable` + `get`, and `set` when settable) via

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -73,6 +73,8 @@ public struct ExpoModuleMacro: MemberMacro {
       }
     }
 
+    diagnoseJSNameCollisions(functions: functions, properties: properties, in: context)
+
     let body: String
     if entries.isEmpty {
       body = "  return []"

package/apple/Sources/ExpoModulesMacros/JSNameCollisions.swift

@@ -0,0 +1,64 @@
+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
+/// the constructor and its instance members onto the prototype, so the two sets are checked separately.
+internal func diagnoseJSNameCollisions(
+  functions: [JSFunction],
+  properties: [JSProperty],
+  in context: some MacroExpansionContext
+) {
+  // Each member binds with its own `setProperty` or `defineProperty` call, so of two members with one
+  // 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(jsName: $0.jsName, kind: "function", nameToken: $0.nameToken) }
+    + properties.map { BoundMember(jsName: $0.jsName, kind: "property", nameToken: $0.nameToken) }
+  var firstMembers: [String: BoundMember] = [:]
+
+  for member in members.sorted(by: { $0.nameToken.position < $1.nameToken.position }) {
+    guard let first = firstMembers[member.jsName] else {
+      firstMembers[member.jsName] = member
+      continue
+    }
+    context.diagnose(
+      Diagnostic(
+        node: member.nameToken,
+        message: JSNameCollisionMessage(
+          "The JavaScript name '\(member.jsName)' is already bound by an earlier @JS \(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 @JS(\"...\")."
+        ),
+        notes: [
+          Note(
+            node: Syntax(first.nameToken),
+            message: JSNameCollisionNote("'\(member.jsName)' is first bound here"))
+        ]
+      ))
+  }
+}
+
+private struct BoundMember {
+  let jsName: String
+  let kind: String
+  let nameToken: TokenSyntax
+}
+
+private struct JSNameCollisionMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID = MessageID(domain: "ExpoModulesMacros", id: "js-name-collision")
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String) {
+    self.message = message
+  }
+}
+
+private struct JSNameCollisionNote: NoteMessage {
+  let message: String
+  let noteID = MessageID(domain: "ExpoModulesMacros", id: "js-name-collision-first")
+
+  init(_ message: String) {
+    self.message = message
+  }
+}

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -441,7 +441,8 @@ internal func collectProperties(
       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) },
-      isSettable: isVar && bindingIsSettable(binding)
+      isSettable: isVar && bindingIsSettable(binding),
+      nameToken: ident.identifier
     )
   }
 }

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -9,14 +9,16 @@ import SwiftSyntaxMacros
  needed — and synthesizes the conversion surface from the property's static type:
 
  - an explicit memberwise `init` (so the static factories have a single construction point),
- - `from(object:appContext:)` — the fast path, reading each property straight off a
-   `JavaScriptObject`,
- - `from(dictionary:appContext:)` — reading each property from a `[String: Any]` dictionary,
- - `toDictionary(appContext:)` and `toObject(appContext:)` for the write side.
+ - `decode(_:in:)` and `encode(_:in:)` — the fast paths, reading each property straight off a JS
+   object and writing it straight into one,
+ - `from(object:appContext:)` and `toObject(appContext:)`, which forward to `decode` and `encode`,
+ - `from(dictionary:appContext:)` and `toDictionary(appContext:)` — converting each property from and
+   to a `[String: Any]` dictionary.
 
- The type is auto-conformed to `Record` (a core protocol whose requirements are exactly this
- surface); the synthesized methods override `Record`'s reflection-based defaults. Author-facing
- shape — no conformance to spell out:
+ The type is auto-conformed to `Record` (a core protocol whose requirements are this surface); the
+ synthesized methods override `Record`'s reflection-based defaults, and the synthesized `decode` and
+ `encode` replace its default `JavaScriptCodable` witnesses. Author-facing shape — no conformance to
+ spell out:
 
    @Record
    struct Options {
@@ -31,7 +33,7 @@ import SwiftSyntaxMacros
  default is required (the factories throw when the source omits it).
 
  The JS-value paths convert through `JavaScriptDecodable.decode` / `JavaScriptEncodable.encode`
- (`from(object:)` / `toObject(appContext:)`); the native-`Any` dictionary paths still go through the
+ (`decode(_:in:)` / `encode(_:in:)`); the native-`Any` dictionary paths still go through the
  public dynamic-type API — `T.getDynamicType()` plus `cast(_:appContext:)` / `convertToJS(_:appContext:)`
  (`from(dictionary:)` / `toDictionary(appContext:)`), since `JavaScriptCodable` only converts JS
  values, not native `Any`. Both spell types as `public` symbols so the synthesized code compiles inside
@@ -55,10 +57,15 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     conformingTo protocols: [TypeSyntax],
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
-    let isClass = declaration.is(ClassDeclSyntax.self)
-    guard declaration.is(StructDeclSyntax.self) || isClass else {
+    let typeName: String
+    if let structDecl = declaration.as(StructDeclSyntax.self) {
+      typeName = structDecl.name.text
+    } else if let classDecl = declaration.as(ClassDeclSyntax.self) {
+      typeName = classDecl.name.text
+    } else {
       throw MacroExpansionErrorMessage("@Record can only be applied to a struct or class")
     }
+    let isClass = declaration.is(ClassDeclSyntax.self)
 
     let properties = try recordProperties(of: declaration)
     let inheritsRecord = isClass && classHasInheritance(declaration)
@@ -99,10 +106,13 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     if !existingInitLabels.contains(properties.map { $0.key }) {
       members.append(memberwiseInit(properties: properties))
     }
-    members.append(fromJSObjectFactory(properties: properties))
+    members.append(fromJSObjectFactory(properties: properties, inheritsRecord: inheritsRecord))
     members.append(fromDictionaryFactory(properties: properties))
     members.append(toDictionaryMethod(properties: properties, inheritsRecord: inheritsRecord))
     members.append(toObjectMethod(properties: properties, inheritsRecord: inheritsRecord))
+    if !inheritsRecord {
+      members.append(contentsOf: javaScriptCodableWitnesses(properties: properties, typeName: typeName))
+    }
     return members
   }
 
@@ -326,15 +336,24 @@ private func memberwiseInit(properties: [RecordProperty]) -> DeclSyntax {
 }
 
 /**
- `from(object:appContext:)` — reads each property off the `JavaScriptObject` into a local,
- then constructs the record through the memberwise init. Required properties throw when
- undefined; defaulted properties fall back to the property's declared default (inlined) when
- undefined; optional properties become `nil` when undefined/null. Each property is decoded with
- `JavaScriptDecodable.decode`, so the factory binds the `runtime` from the app context once and
- threads it to every read. A free-form property decodes through the `JavaScriptValue` free-form
- methods, which take the runtime too.
+ `from(object:appContext:)`. A record forwards to its own unowned `decode(_:in:)` witness (see
+ `javaScriptCodableWitnesses`), which holds the property reads. A subclass, which gets no witnesses,
+ reads the properties here, in the app context's runtime.
  */
-private func fromJSObjectFactory(properties: [RecordProperty]) -> DeclSyntax {
+private func fromJSObjectFactory(properties: [RecordProperty], inheritsRecord: Bool) -> DeclSyntax {
+  guard inheritsRecord else {
+    // The record declares only the unowned `decode`, so the call lends the value unowned. With an owning
+    // value it would reach an owning `decode` default, and `Record`'s converts through this factory.
+    return """
+      @JavaScriptActor
+      public static func from(object: borrowing JavaScriptObject, appContext: AppContext) throws -> Self {
+        let runtime = try appContext.runtime
+        return try object.asValue().withUnownedValue(in: runtime) { unownedValue in
+          return try decode(unownedValue, in: runtime)
+        }
+      }
+      """
+  }
   var lines: [String] = []
   // Only bind the runtime when there's a property to decode — an empty record's factory would
   // otherwise leave it unused.
@@ -342,11 +361,10 @@ private func fromJSObjectFactory(properties: [RecordProperty]) -> DeclSyntax {
     lines.append("  let runtime = try appContext.runtime")
   }
   lines.append(factoryBody(properties: properties, readLines: jsObjectReadLines(properties: properties)))
-  let body = lines.joined(separator: "\n")
   return """
     @JavaScriptActor
     public static func from(object: borrowing JavaScriptObject, appContext: AppContext) throws -> Self {
-    \(raw: body)
+    \(raw: lines.joined(separator: "\n"))
     }
     """
 }
@@ -373,69 +391,68 @@ private func fromDictionaryFactory(properties: [RecordProperty]) -> DeclSyntax {
 private func factoryBody(properties: [RecordProperty], readLines: [String]) -> String {
   var lines: [String] = []
   lines.append(contentsOf: readLines)
-  let initArgs = properties.map { "\($0.name): \($0.name)" }.joined(separator: ", ")
+  let initArgs = properties.enumerated().map { "\($1.name): \(fieldLocal($0))" }.joined(separator: ", ")
   lines.append("  return Self(\(initArgs))")
   return lines.joined(separator: "\n")
 }
 
-/// Per-property read statements for the JS-object factory, each producing a `let <name>` by decoding
-/// the JS value with `JavaScriptDecodable.decode` (recovering the app context from `runtime` itself).
-/// A free-form property decodes through the `JavaScriptValue` free-form methods instead; for an optional
-/// free-form shape, `undefined`/`null` map to `nil` around the call, just like `Optional.decode`.
+/// The local that holds the value of the property at `index` in a factory. It's numbered rather than
+/// named after the property, so no property can collide with it or with the factory's other parameters
+/// and locals (`object`, `runtime`, `dictionary`, `appContext`).
+private func fieldLocal(_ index: Int) -> String {
+  return "field\(index)"
+}
+
+/// Per-property read statements, each producing a `let field<index>` from the property of the JS object
+/// named `object`. The property is lent to a closure as a `JavaScriptUnownedValue` and decoded there the
+/// same way as a `@JS` argument (see `decodeCall`), so the read doesn't allocate a `JavaScriptValue`.
+/// Only the generic free-form decode copies the value into one.
 private func jsObjectReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
-  for property in properties {
+  for (index, property) in properties.enumerated() {
     let valueVar = derivedIdentifier(from: property.name, suffix: "JSValue")
-    let exprType = expressionType(property.type)
-    let decode: String
-    switch property.freeForm {
-    case .shape(let decodeMethod, _, let isOptional, _):
-      let call = "try JavaScriptValue.\(decodeMethod)(\(valueVar), in: runtime)"
-      decode = isOptional ? "\(valueVar).isUndefined() || \(valueVar).isNull() ? nil : \(call)" : call
-    case .generic:
-      decode = "try JavaScriptValue.decodeAny(\(valueVar), as: \(exprType).self, in: runtime)"
-    case nil:
-      decode = "try \(exprType).decode(\(valueVar), in: runtime)"
-    }
-    lines.append("  let \(valueVar) = object.getProperty(\"\(property.key)\")")
+    let decode = "try \(decodeCall(property.type, freeForm: property.freeForm, from: valueVar))"
+    lines.append("  let \(fieldLocal(index)) = try object.withUnownedProperty(\"\(property.key)\") { \(valueVar) in")
     if property.isRequired {
-      lines.append("  guard !\(valueVar).isUndefined() else {")
-      lines.append("    throw RecordPropertyRequiredException(\"\(property.key)\")")
-      lines.append("  }")
-      lines.append("  let \(property.name) = \(decode)")
+      lines.append("    guard !\(valueVar).isUndefined() else {")
+      lines.append("      throw RecordPropertyRequiredException(\"\(property.key)\")")
+      lines.append("    }")
+      lines.append("    return \(decode)")
     } else if property.isOptional {
-      // `Optional.decode` (and the free-form reads above) already map `undefined`/`null` to `nil`, so
-      // the read is a plain decode.
-      lines.append("  let \(property.name) = \(decode)")
+      // `Optional.decode` (and the free-form decodes of optional shapes) already map `undefined` and
+      // `null` to `nil`, so the read is a plain decode.
+      lines.append("    return \(decode)")
     } else {
-      lines.append("  let \(property.name) = \(valueVar).isUndefined() ? \(property.defaultValue!) : \(decode)")
+      lines.append("    return \(valueVar).isUndefined() ? \(property.defaultValue!) : \(decode)")
     }
+    lines.append("  }")
   }
   return lines
 }
 
-/// Per-property read statements for the dictionary factory, each producing a `let <name>`. A bare `Any`
-/// property has no dynamic type to cast through, and the dictionary value already is an `Any`, so it's
-/// read unchanged.
+/// Per-property read statements for the dictionary factory, each producing a `let field<index>` from the
+/// raw dictionary value in `entry<index>`. A bare `Any` property has no dynamic type to cast through, and
+/// the dictionary value already is an `Any`, so it's read unchanged.
 private func dictionaryReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
-  for property in properties {
-    let valueVar = derivedIdentifier(from: property.name, suffix: "Value")
+  for (index, property) in properties.enumerated() {
+    let field = fieldLocal(index)
+    let entry = "entry\(index)"
     let exprType = expressionType(property.type)
     let isBareAny = property.freeForm?.isBareAny == true
     let cast = isBareAny
-      ? valueVar
-      : "try \(exprType).getDynamicType().cast(\(valueVar), appContext: appContext) as! \(exprType)"
-    lines.append("  let \(valueVar) = dictionary[\"\(property.key)\"]")
+      ? entry
+      : "try \(exprType).getDynamicType().cast(\(entry), appContext: appContext) as! \(exprType)"
+    lines.append("  let \(entry) = dictionary[\"\(property.key)\"]")
     if property.isRequired {
-      lines.append("  guard let \(valueVar) else {")
+      lines.append("  guard let \(entry) else {")
       lines.append("    throw RecordPropertyRequiredException(\"\(property.key)\")")
       lines.append("  }")
-      lines.append("  let \(property.name) = \(cast)")
+      lines.append("  let \(field) = \(cast)")
     } else if property.isOptional {
-      lines.append("  let \(property.name): \(property.type) = (\(valueVar) == nil || \(valueVar)! is NSNull) ? nil : \(cast)")
+      lines.append("  let \(field): \(property.type) = (\(entry) == nil || \(entry)! is NSNull) ? nil : \(cast)")
     } else {
-      lines.append("  let \(property.name) = \(valueVar) == nil ? \(property.defaultValue!) : \(isBareAny ? valueVar + "!" : cast)")
+      lines.append("  let \(field) = \(entry) == nil ? \(property.defaultValue!) : \(isBareAny ? entry + "!" : cast)")
     }
   }
   return lines
@@ -474,51 +491,94 @@ private func toDictionaryMethod(properties: [RecordProperty], inheritsRecord: Bo
 }
 
 /**
- `toObject(appContext:)` — builds a `JavaScriptObject` directly, encoding each property with
- `JavaScriptEncodable.encode` (or, for a free-form property, the matching `JavaScriptValue` free-form
- method). The fast write path mirroring `from(object:)`. The `runtime` is bound
- from the app context once and threaded to every write. Subclasses chain to `super` so inherited
- properties are written first.
+ `toObject(appContext:)`. A record forwards to its own `encode(_:in:)` witness (see
+ `javaScriptCodableWitnesses`), which holds the property writes. A subclass, which gets no witnesses,
+ overrides it to chain to `super`, so inherited properties are written first, and writes its own
+ properties in the app context's runtime.
  */
 private func toObjectMethod(properties: [RecordProperty], inheritsRecord: Bool) -> DeclSyntax {
-  let overrideKeyword = inheritsRecord ? "override " : ""
+  guard inheritsRecord else {
+    return """
+      @JavaScriptActor
+      public func toObject(appContext: AppContext) throws -> JavaScriptObject {
+        return try Self.encode(self, in: appContext.runtime).asObject()
+      }
+      """
+  }
   var lines: [String] = []
-  // The base case needs the runtime to create the object; the inheriting case only needs it when
-  // there's a property to encode (it chains to `super` for the object itself). Binding it when unused
-  // would warn.
-  if !inheritsRecord || !properties.isEmpty {
+  // The runtime is only needed when there's a property to encode (the object itself comes from
+  // `super`). Binding it when unused would warn.
+  if !properties.isEmpty {
     lines.append("  let runtime = try appContext.runtime")
   }
-  if inheritsRecord {
-    lines.append("  let object = try super.toObject(appContext: appContext)")
-  } else {
-    lines.append("  let object = runtime.createObject()")
-  }
-  for property in properties {
-    let exprType = expressionType(property.type)
+  lines.append("  let object = try super.toObject(appContext: appContext)")
+  lines.append(contentsOf: objectWriteLines(properties: properties, of: "self"))
+  lines.append("  return object")
+  return """
+    @JavaScriptActor
+    public override func toObject(appContext: AppContext) throws -> JavaScriptObject {
+    \(raw: lines.joined(separator: "\n"))
+    }
+    """
+}
+
+/**
+ The record's own `JavaScriptDecodable` and `JavaScriptEncodable` witnesses, which convert in the
+ runtime they're given. Without them the record would convert through `Record`'s default witnesses,
+ which recover the app context from the runtime and convert in the app context's runtime.
+
+ `decode` reads each property off the JS object into a local, then constructs the record through the
+ memberwise init. Required properties throw when undefined; defaulted properties fall back to the
+ property's declared default (inlined) when undefined; optional properties become `nil` when
+ undefined/null. It's the unowned overload: an owning value decodes through `JavaScriptDecodable`'s
+ default, which forwards to it. `encode` builds the JS object, writing each property. Its parameter
+ names the type, because a class can't take `Self` as a parameter type.
+ */
+private func javaScriptCodableWitnesses(properties: [RecordProperty], typeName: String) -> [DeclSyntax] {
+  // An empty record still decodes only from an object, but has no property to read off it.
+  let objectLine = properties.isEmpty
+    ? "  _ = try value.asObject(in: runtime)"
+    : "  let object = try value.asObject(in: runtime)"
+  let decodeBody = objectLine + "\n" + factoryBody(properties: properties, readLines: jsObjectReadLines(properties: properties))
+  let encodeLines = ["  let object = runtime.createObject()"]
+    + objectWriteLines(properties: properties, of: "value")
+    + ["  return object.asValue()"]
+  return [
+    """
+    @JavaScriptActor
+    public static func decode(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime) throws -> Self {
+    \(raw: decodeBody)
+    }
+    """,
+    """
+    @JavaScriptActor
+    public static func encode(_ value: \(raw: typeName), in runtime: borrowing JavaScriptRuntime) throws -> JavaScriptValue {
+    \(raw: encodeLines.joined(separator: "\n"))
+    }
+    """,
+  ]
+}
+
+/// The statements that write each property of `record` (`self` or the `encode` parameter) into the
+/// `object` local, encoding it with `JavaScriptEncodable.encode` or, for a free-form property, the
+/// matching `JavaScriptValue` free-form method.
+private func objectWriteLines(properties: [RecordProperty], of record: String) -> [String] {
+  return properties.map { property in
+    let value = "\(record).\(property.name)"
     let encode: String
     switch property.freeForm {
     case .shape(_, let encodeMethod, let isOptional, _):
       encode = isOptional
-        ? "self.\(property.name) == nil ? .null() : try JavaScriptValue.\(encodeMethod)(self.\(property.name)!, in: runtime)"
-        : "try JavaScriptValue.\(encodeMethod)(self.\(property.name), in: runtime)"
+        ? "\(value) == nil ? .null() : try JavaScriptValue.\(encodeMethod)(\(value)!, in: runtime)"
+        : "try JavaScriptValue.\(encodeMethod)(\(value), in: runtime)"
     case .generic:
       // The explicit `as Any` keeps an optional property from warning about its implicit coercion.
-      encode = "try JavaScriptValue.encodeAny(self.\(property.name) as Any, in: runtime)"
+      encode = "try JavaScriptValue.encodeAny(\(value) as Any, in: runtime)"
     case nil:
-      encode = "try \(exprType).encode(self.\(property.name), in: runtime)"
+      encode = "try \(expressionType(property.type)).encode(\(value), in: runtime)"
     }
-    lines.append("  object.setProperty(\"\(property.key)\", value: \(encode))")
+    return "  object.setProperty(\"\(property.key)\", value: \(encode))"
   }
-  lines.append("  return object")
-  let body = lines.joined(separator: "\n")
-
-  return """
-    @JavaScriptActor
-    public \(raw: overrideKeyword)func toObject(appContext: AppContext) throws -> JavaScriptObject {
-    \(raw: body)
-    }
-    """
 }
 
 // MARK: - Helpers

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -93,6 +93,9 @@ public struct SharedObjectMacro: MemberMacro {
       }
     }
 
+    diagnoseJSNameCollisions(functions: instanceFunctions, properties: instanceProperties, in: context)
+    diagnoseJSNameCollisions(functions: staticFunctions, properties: staticProperties, in: context)
+
     let lines = entries.map { "    \($0)" }.joined(separator: "\n")
     let body = entries.isEmpty
       ? "  return Class(\"\(jsName)\", \(typeName).self) {\n  }"

package/build/index.d.ts

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

package/build/index.js

@@ -51,12 +51,21 @@ class ScannerSchemaVersionError extends Error {
 }
 exports.ScannerSchemaVersionError = ScannerSchemaVersionError;
 /**
- * The package with the Windows binary for the current architecture, for example
- * `@expo/modules-macros-win32-x64`. It is an optional dependency of this package, and its `os` and
- * `cpu` fields make package managers install it only on a matching Windows machine.
+ * The platforms whose binaries ship in packages of their own, one per architecture, with the
+ * machines that those packages install on.
  */
-function windowsBinaryPackageName() {
-    return `@expo/modules-macros-win32-${process.arch}`;
+const platformPackageMachines = {
+    win32: 'Windows x64 and arm64',
+    linux: 'Linux x64 and arm64 with glibc',
+};
+/**
+ * The package with the binary for the current platform and architecture, for example
+ * `@expo/modules-macros-win32-x64` or `@expo/modules-macros-linux-arm64`. It is an optional
+ * dependency of this package, and its `os`, `cpu` and (on Linux) `libc` fields make package managers
+ * install it only on a matching machine.
+ */
+function platformBinaryPackageName() {
+    return `@expo/modules-macros-${process.platform}-${process.arch}`;
 }
 /**
  * Absolute path to the scanner binary for the current platform. It doubles as the macro plugin
@@ -64,34 +73,40 @@ function windowsBinaryPackageName() {
  *
  * - macOS: the universal binary shipped in this package, next to the Swift package rather than in a
  *   `bin` directory.
- * - Windows: `ExpoModulesMacros.exe` from the package for the current architecture (see
- *   `windowsBinaryPackageName`). When that package isn't installed, for example in this repository,
- *   it falls back to the executable that `npm run build` writes to `platforms/win32-<arch>`.
+ * - Windows and Linux: `ExpoModulesMacros.exe` or `ExpoModulesMacros` from the package for the
+ *   current platform and architecture (see `platformBinaryPackageName`). When that package isn't
+ *   installed, for example in this repository, it falls back to the executable that `npm run build`
+ *   writes to `platforms/<platform>-<arch>`.
  *
  * The path isn't checked here; running a missing binary fails with a `ScannerError` that says how to
  * get it.
  */
 function getScannerBinaryPath() {
-    if (process.platform !== 'win32') {
+    if (process.platform === 'darwin') {
         return node_path_1.default.join(__dirname, '..', 'apple', 'ExpoModulesMacros');
     }
+    const fileName = process.platform === 'win32' ? 'ExpoModulesMacros.exe' : 'ExpoModulesMacros';
     try {
-        const packageJson = require.resolve(`${windowsBinaryPackageName()}/package.json`);
-        return node_path_1.default.join(node_path_1.default.dirname(packageJson), 'ExpoModulesMacros.exe');
+        const packageJson = require.resolve(`${platformBinaryPackageName()}/package.json`);
+        return node_path_1.default.join(node_path_1.default.dirname(packageJson), fileName);
     }
     catch {
-        return node_path_1.default.join(__dirname, '..', 'platforms', `win32-${process.arch}`, 'ExpoModulesMacros.exe');
+        return node_path_1.default.join(__dirname, '..', 'platforms', `${process.platform}-${process.arch}`, fileName);
     }
 }
 /** The message for a scanner binary that doesn't exist at `binaryPath`. */
 function missingBinaryMessage(binaryPath) {
-    if (process.platform === 'win32') {
-        return (`The scanner binary is missing at ${binaryPath}. On Windows it comes from the optional package ` +
-            `${windowsBinaryPackageName()}, which your package manager installs only on Windows x64 and arm64. ` +
-            'Reinstall dependencies without skipping optional ones (for example without `--omit=optional`), ' +
-            'or run `npm run build` in this package to build it locally.');
+    if (process.platform === 'darwin') {
+        return `The scanner binary is missing at ${binaryPath}. Run \`npm run build\` in this package to build it.`;
+    }
+    const machines = platformPackageMachines[process.platform];
+    if (machines === undefined) {
+        return `The scanner binary is missing at ${binaryPath}. No binary is built for ${process.platform}.`;
     }
-    return `The scanner binary is missing at ${binaryPath}. Run \`npm run build\` in this package to build it.`;
+    return (`The scanner binary is missing at ${binaryPath}. It comes from the optional package ` +
+        `${platformBinaryPackageName()}, which your package manager installs only on ${machines}. ` +
+        'Reinstall dependencies without skipping optional ones (for example without `--omit=optional`), ' +
+        'or run `npm run build` in this package to build it locally.');
 }
 /**
  * Runs a scanner subcommand and parses its JSON report.

package/package.json

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