expo-modules-macros 0.22.0 → 0.23.0

package/.github/workflows/linux.yml

@@ -50,6 +50,9 @@ jobs:
         with:
           node-version: 24
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
@@ -65,10 +68,10 @@ jobs:
         run: swift test
 
       - name: Build release tool
-        # Runs `npm run build` (scripts/build.js): builds the release plugin binary for this
+        # 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: npm run build
+        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
@@ -125,8 +128,8 @@ jobs:
         # `@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
+          pnpm install
+          pnpm add --save-optional "$PLATFORM_PACKAGE_TARBALL"
+          pnpm run build:ts
           node scripts/check-scan.js .
 

package/.github/workflows/publish.yml

@@ -56,10 +56,13 @@ jobs:
         with:
           node-version: 24
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Build release tool
         # Runs scripts/build.js: builds the release plugin binary for this architecture as
         # platforms/win32-<arch>/ExpoModulesMacros.exe.
-        run: npm run build
+        run: pnpm run build
 
       - name: Upload tool
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
@@ -94,10 +97,13 @@ jobs:
         with:
           node-version: 24
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - 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
+        run: pnpm run build
 
       - name: Upload tool
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
@@ -130,6 +136,9 @@ jobs:
         with:
           node-version: 24
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Download tool
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
@@ -142,11 +151,11 @@ jobs:
           # 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
+          pnpm install
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          npm install --no-save (Join-Path $env:RUNNER_TEMP $pack[0].filename)
+          pnpm add --save-optional (Join-Path $env:RUNNER_TEMP $pack[0].filename)
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          npm run build:ts
+          pnpm run build:ts
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           node scripts/check-scan.js .
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
@@ -178,6 +187,9 @@ jobs:
         with:
           node-version: 24
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Download tool
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
@@ -191,9 +203,9 @@ jobs:
           # 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
+          pnpm install
+          pnpm add --save-optional "$RUNNER_TEMP/$tarball"
+          pnpm run build:ts
 
       - name: Scan on each distribution
         run: |
@@ -233,6 +245,9 @@ jobs:
           node-version: 24
           registry-url: https://registry.npmjs.org
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Update npm
         # Trusted publishing requires npm >= 11.5.1.
         run: npm install -g npm@latest
@@ -280,18 +295,18 @@ jobs:
 
       - name: Install dependencies
         # The wrapper's `prepublishOnly` build needs `tsc`; the tool binary needs none.
-        run: npm install
+        run: pnpm install
 
       - name: Build release tool
         # Runs scripts/build.js: builds the release plugin binary,
         # copies it to apple/ExpoModulesMacros, and strips it.
-        run: npm run build
+        run: pnpm run build
 
       - 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
+          pnpm run build:ts
           node scripts/check-scan.js .
 
       - name: Download Windows and Linux tools

package/.github/workflows/swift-format.yml

@@ -37,6 +37,9 @@ jobs:
         with:
           node-version: 24
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Restore swift-format
         id: swift-format-cache
         uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
@@ -73,4 +76,4 @@ jobs:
           # The script lists the files with `git ls-files`. The checkout belongs to another user than
           # the container's root user, so Git needs it marked as safe.
           git config --global --add safe.directory "$GITHUB_WORKSPACE"
-          npm run swift:lint
+          pnpm run swift:lint

package/.github/workflows/swift.yml

@@ -24,6 +24,9 @@ jobs:
       - name: Checkout
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Select Xcode
         # Pin to an Xcode that ships Swift 6.2 (required by Package.swift).
         run: sudo xcode-select -switch /Applications/Xcode_26.4.1.app
@@ -40,11 +43,11 @@ jobs:
         run: swift package resolve
 
       - name: Build release tool
-        # Runs `npm run build` (scripts/build.js): builds the universal
+        # 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: npm run build
+        run: pnpm run build
 
       - name: Verify universal binary
         run: |
@@ -64,5 +67,5 @@ jobs:
       - name: Typecheck the TypeScript wrapper
         working-directory: ${{ github.workspace }}
         run: |
-          npm install
-          npm run typecheck
+          pnpm install
+          pnpm run typecheck

package/.github/workflows/windows.yml

@@ -50,6 +50,9 @@ jobs:
         with:
           node-version: 24
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
       - name: Cache SwiftPM build
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
@@ -65,10 +68,10 @@ jobs:
         run: swift test
 
       - name: Build release tool
-        # Runs `npm run build` (scripts/build.js): builds the release plugin binary for this
+        # 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: npm run build
+        run: pnpm run build
 
       - name: Verify the release tool
         # Runs it with only the Windows directories on PATH, so it must not need the Swift runtime DLLs.
@@ -109,11 +112,11 @@ jobs:
         working-directory: ${{ github.workspace }}
         shell: pwsh
         run: |
-          npm install
+          pnpm install
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          npm install --no-save $env:PLATFORM_PACKAGE_TARBALL
+          pnpm add --save-optional $env:PLATFORM_PACKAGE_TARBALL
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          npm run build:ts
+          pnpm run build:ts
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           node scripts/check-scan.js .
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

package/AGENTS.md

@@ -9,26 +9,27 @@
 - `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`, 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.
+- `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.
 - `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 and Linux `platforms/win32-<arch>/ExpoModulesMacros.exe` or `platforms/linux-<arch>/ExpoModulesMacros` for the host architecture (not committed; published in that package).
-- `scripts/swift-format.js` (`npm run swift:format`, `npm run swift:lint`): runs swift-format on the `.swift` files that Git tracks or doesn't ignore, with the configuration in `.swift-format`.
+- `scripts/build.js` (`pnpm 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).
+- `scripts/swift-format.js` (`pnpm run swift:format`, `pnpm run swift:lint`): runs swift-format on the `.swift` files that Git tracks or doesn't ignore, with the configuration in `.swift-format`.
 
 ## Commands
 
-Swift 6.2 is required (Xcode 26 or newer on macOS).
+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
-npm run typecheck            # TypeScript wrapper
-npm run build                # release binary (slow; on macOS uses Rosetta for x86_64)
-npm run swift:format         # format the Swift sources in place
-npm run swift:lint           # check the formatting, as CI does
+pnpm install                 # TypeScript dependencies
+pnpm run typecheck           # TypeScript wrapper
+pnpm run build               # release binary (slow; on macOS uses Rosetta for x86_64)
+pnpm run swift:format        # format the Swift sources in place
+pnpm run swift:lint          # check the formatting, as CI does
 ```
 
-CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `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. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `npm run swift:lint`. 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 `pnpm run typecheck`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `pnpm run swift:lint`. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
 
 ## Windows
 
@@ -42,7 +43,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 ## Conventions
 
-- swift-format formats the Swift sources. After you change Swift code, run `npm run swift:format` and then `npm run swift:lint`, which also reports the rules that the formatter doesn't fix. `.swift-format` is a copy of the configuration in `expo/expo`, so keep the two the same. Each repository pins its own swift-format version.
+- swift-format formats the Swift sources. After you change Swift code, run `pnpm run swift:format` and then `pnpm run swift:lint`, which also reports the rules that the formatter doesn't fix. `.swift-format` is a copy of the configuration in `expo/expo`, so keep the two the same. Each repository pins its own swift-format version.
 - The scripts run the swift-format on `PATH`, or on macOS the one in Xcode when there is none. CI builds the version in `SWIFT_FORMAT_VERSION` (`.github/workflows/swift-format.yml`, also named in the README), which can format differently from the one in Xcode. When CI reports a finding that the local lint doesn't, fix it as CI reports it.
 - Write new doc comments as `///` line comments, not `/** */` blocks.
 - Tests use Swift Testing (`import Testing`, `@Test`) with backtick-quoted descriptive names, for example ``func `Prunes .build, Pods, .git, and node_modules directories`()``.
@@ -68,6 +69,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 - 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.
+- The workflows install dependencies and run scripts with pnpm, but they pack, version and publish with npm (`npm pack`, `npm version`, `npm publish`), because the packages use npm trusted publishing (OIDC). Keep those commands on npm.
 - Commit and PR titles are short and imperative, with code identifiers in backticks, for example ``Report `@Union` types in `scan-exports` ``.
 
 ## Installed copies

package/README.md

@@ -25,9 +25,9 @@ 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, 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. 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.
+- **`@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. 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.
 - **`@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:)`.
+- **`@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.
 - **`@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.
 
@@ -102,7 +102,7 @@ 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 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.
+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`.
 
@@ -116,7 +116,9 @@ swift build
 swift test
 ```
 
-The Swift sources are formatted with [swift-format](https://github.com/swiftlang/swift-format), using the same configuration (`.swift-format`) as the `expo/expo` repository. `npm run swift:format` formats the `.swift` files that Git tracks or doesn't ignore in place, and `npm run swift:lint` checks them without changes, as CI does.
+The scripts and the TypeScript wrapper use [pnpm](https://pnpm.io), at the version in `packageManager` in `package.json`. Run `pnpm install` to install the TypeScript dependencies, and `pnpm run typecheck` to check the wrapper.
+
+The Swift sources are formatted with [swift-format](https://github.com/swiftlang/swift-format), using the same configuration (`.swift-format`) as the `expo/expo` repository. `pnpm run swift:format` formats the `.swift` files that Git tracks or doesn't ignore in place, and `pnpm run swift:lint` checks them without changes, as CI does.
 
 The scripts run the `swift-format` on `PATH`, or on macOS the one in the selected Xcode when there is none on `PATH`. CI uses swift-format `604.0.0`, which can format differently from the one in Xcode. To get the version that CI uses, build it from source:
 
@@ -129,7 +131,7 @@ cp "$(cd /tmp/swift-format && swift build -c release --show-bin-path)/swift-form
 
 Then add `~/.local/bin` to `PATH`.
 
-`npm 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 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).
 
 - 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/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -363,6 +363,13 @@ internal struct JSFunction {
 /// writes `<callee>.<name> = …`. Decode/encode of the value go through `JavaScriptDecodable.decode` /
 /// `JavaScriptEncodable.encode` (or the free-form methods for a type that mentions `Any`), the same
 /// path as functions.
+///
+/// A `lazy var` binds a getter only, on a configurable accessor. On the first read the getter defines
+/// the encoded value as a data property on the JS `this` with `defineProperty`, so later reads don't
+/// call into native code. The data property goes on `this`, not on the object that holds the accessor,
+/// so each shared object instance stores its own value. `defineProperty` leaves a frozen object
+/// unchanged, so there the property stays an accessor. A `this` that isn't an object doesn't fail the read
+/// either: the getter still returns the value.
 internal struct JSProperty {
   let swiftName: String
   let jsName: String
@@ -373,8 +380,10 @@ internal struct JSProperty {
   /// How the value converts when its type mentions `Any`, or `nil` for any other type.
   let freeForm: FreeFormConversion?
   /// 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`.
+  /// explicit `set` accessor; `false` for a getter-only computed `var`, a `lazy var` or a `let`.
   let isSettable: Bool
+  /// Whether the property is a `lazy var`, whose getter replaces the accessor with the first value.
+  let isLazy: Bool
   /// The property's name in the source, where a JavaScript name collision is reported.
   let nameToken: TokenSyntax
 
@@ -395,18 +404,36 @@ internal struct JSProperty {
 
     lines.append("let \(descriptorName) = runtime.createObject()")
     lines.append("\(descriptorName).setProperty(\"enumerable\", value: true)")
+    if isLazy {
+      // The getter redefines the property on `this`, which needs a configurable accessor when `this`
+      // is the object that holds it (a module).
+      lines.append("\(descriptorName).setProperty(\"configurable\", value: true)")
+    }
 
     // Getter: read `<callee>.<name>` and encode the result back to JS through `encode`. When the value
     // type couldn't be inferred (no annotation and no literal default, rare for a stored var) there's
     // no static type to call `encode` on, so the value's own `toJavaScriptValue(in:)` is the fallback.
-    let getEncode: String
+    let encode: String
     if let valueType {
-      getEncode = "return try \(encodeCall(valueType, freeForm: freeForm, of: "\(callee).\(swiftName)"))"
+      encode = "try \(encodeCall(valueType, freeForm: freeForm, of: "\(callee).\(swiftName)"))"
+    } else {
+      encode = "\(callee).\(swiftName).toJavaScriptValue(in: runtime)"
+    }
+    let getBody: String
+    if isLazy {
+      let define = "this.getObject(in: runtime).defineProperty(\"\(jsName)\", value: value, options: [.enumerable])"
+      // A module getter ignores `this` otherwise, so it can be anything, and only an object can hold the
+      // value. A shared object's unwrap has already checked that `this` is an object.
+      let defineStatement =
+        receiver.unwrapStatement == nil
+        ? "if this.isObject() {\n  \(define)\n}"
+        : define
+      getBody = "let value = \(encode)\n\(defineStatement)\nreturn value"
     } else {
-      getEncode = "return \(callee).\(swiftName).toJavaScriptValue(in: runtime)"
+      getBody = "return \(encode)"
     }
     lines.append(
-      accessorClosure(descriptorName, "get", receiver: receiver, body: "\(unwrap)\(getEncode)")
+      accessorClosure(descriptorName, "get", receiver: receiver, body: "\(unwrap)\(getBody)")
     )
 
     // Setter: decode argument 0 by the static type through `decode` and write `<callee>.<name>`. A

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -7,10 +7,9 @@ import SwiftSyntaxMacros
 ///
 /// - `MemberMacro`: binds `@JS`-marked members directly into the module's JS object via the
 ///   synthesized `_decorateModule`, and emits the resolved module name as a non-optional
-///   `_jsName` static (no `Name(…)` DSL element). It also synthesizes a
-///   framework-internal `_synthesizedDefinition()` returning `[AnyDefinition]` (now carrying
-///   only nested `classes` entries) that `expo-modules-core` merges into the module's
-///   definition. When the class doesn't already inherit `Module`/`BaseModule`, it also
+///   `_jsName` static (no `Name(…)` DSL element). The `classes:` and `views:` arguments become
+///   `_classTypes` and `_viewTypes` statics that `expo-modules-core` registers by type.
+///   When the class doesn't already inherit `Module`/`BaseModule`, it also
 ///   synthesizes the `appContext` storage and `init(appContext:)` those base classes provide.
 /// - `MemberAttributeMacro`: stamps `@JavaScriptActor` on `@JS` sync members and
 ///   `@ModuleDefinitionBuilder` on a `definition()` method.
@@ -44,18 +43,13 @@ public struct ExpoModuleMacro: MemberMacro {
     // macro no longer emits a `Name(…)` DSL entry. Core reads the static for the module name,
     // ahead of its type-name fallback (which then only applies to non-macro DSL modules).
     let moduleName = jsNameArgument(of: node) ?? withoutBackticks(classDecl.name.text)
-    var entries: [String] = []
 
     // `@JS func`s (sync and async) and `@JS var`s are bound directly into the JS object by the
     // synthesized `_decorateModule` rather than described with a `Function(...)` / `Property(...)`
-    // DSL entry, so they're collected here instead of appended to `entries`.
+    // DSL entry.
     var functions: [JSFunction] = []
     var properties: [JSProperty] = []
 
-    for typeName in classListArgument(of: node, label: "classes") {
-      entries.append("\(typeName)._synthesizedClassDefinition()")
-    }
-
     for member in classDecl.memberBlock.members {
       let decl = member.decl
 
@@ -79,14 +73,6 @@ public struct ExpoModuleMacro: MemberMacro {
 
     diagnoseJSNameCollisions(functions: functions, properties: properties, in: context)
 
-    let body: String
-    if entries.isEmpty {
-      body = "  return []"
-    } else {
-      let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
-      body = "  return [\n\(lines)\n  ]"
-    }
-
     var emitted: [DeclSyntax] = []
 
     // The fully-resolved module name as a non-optional stored constant. Core reads this
@@ -94,6 +80,16 @@ public struct ExpoModuleMacro: MemberMacro {
     // JS object name, so they can't diverge.
     emitted.append("public static let _jsName = \"\(raw: moduleName)\"")
 
+    // Shared object classes are registered by type: core builds each JavaScript class from the
+    // `@SharedObject` hooks, with the name from the class's `_jsName`. The element type makes the
+    // compiler reject a class that isn't a `SharedObject` subclass. Emitted only when the argument is
+    // present, so a module without classes gains nothing.
+    let classTypes = classListArgument(of: node, label: "classes")
+    if !classTypes.isEmpty {
+      let entries = classTypes.map { "\($0).self" }.joined(separator: ", ")
+      emitted.append("public static let _classTypes: [SharedObject.Type] = [\(raw: entries)]")
+    }
+
     // View classes are registered by type, not spliced as definitions: an `@ExpoView` emits no
     // definition function, so there is nothing to call on each entry. Core reads a view's props
     // type from its `Props` typealias and its event names from that type's `_eventNames`, both
@@ -123,15 +119,6 @@ public struct ExpoModuleMacro: MemberMacro {
       }
     }
 
-    // Always emitted: the definition is derived from the class name and `@JS` members,
-    // independent of any `definition()` the user wrote.
-    let method: DeclSyntax = """
-      public func _synthesizedDefinition() -> [AnyDefinition] {
-      \(raw: body)
-      }
-      """
-    emitted.append(method)
-
     // Direct JSI binding: one `_decorateModule` that binds each `@JS func` (inlined `setProperty`
     // closure) and each `@JS var` (a `defineProperty` get/set accessor) into the module's JS object.
     // Only emitted when there's at least one member to bind.

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -386,15 +386,15 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
     let type = binding.typeAnnotation?.type,
     !containsFunctionType(type)
   {
-    // A `let`, or a `var` with no setter, is read-only (encodable only). A settable `var` is also
-    // decoded on write, so its value type is asserted in both directions. A type that mentions `Any`
-    // converts through the free-form methods instead, so it isn't asserted at all.
+    // A `let`, a `lazy var`, or a `var` with no setter is read-only (encodable only). A settable `var`
+    // is also decoded on write, so its value type is asserted in both directions. A type that mentions
+    // `Any` converts through the free-form methods instead, so it isn't asserted at all.
     guard !mentionsFreeFormAny(type) else {
       return nil
     }
     let typeText = type.trimmedDescription
     let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
-    let isSettable = isVar && bindingIsSettable(binding)
+    let isSettable = isVar && !isLazy(varDecl.modifiers) && bindingIsSettable(binding)
     return BoundaryMember(
       name: identifier.identifier.text,
       decodableTypes: isSettable ? [typeText] : [],

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -270,6 +270,12 @@ internal func isTypeLevel(_ modifiers: DeclModifierListSyntax) -> Bool {
   }
 }
 
+/// True for a `lazy` property. A lazy `@JS` property is read-only from JS: its getter stores the
+/// first value as a data property on the JS object, which a setter couldn't write through.
+internal func isLazy(_ modifiers: DeclModifierListSyntax) -> Bool {
+  return modifiers.contains { $0.name.tokenKind == .keyword(.lazy) }
+}
+
 /// True if a trailing occurrence of this parameter may be omitted by the JS caller: it either has a
 /// default value (Swift applies it) or is an optional type (an absent slot becomes `nil`). The arity
 /// range and the per-arity call branches are derived from this.
@@ -545,6 +551,7 @@ internal func collectProperties(
   let jsNameOverride = jsNameArgument(of: attribute)
   // A `let` is never settable; only `var` bindings can carry a setter.
   let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
+  let isLazy = isLazy(varDecl.modifiers)
 
   return varDecl.bindings.compactMap { binding in
     guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
@@ -562,7 +569,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 && !isLazy && bindingIsSettable(binding),
+      isLazy: isLazy,
       nameToken: ident.identifier
     )
   }

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -499,7 +499,7 @@ private func javaScriptCodableWitnesses(
     ["  let object = runtime.createObject()"]
     + lookupLines
     + objectWriteLines(properties: properties, of: "value", cachesPropNames: cachesPropNames)
-    + ["  return object.asValue()"]
+    + ["  return object.takeValue()"]
   return [
     """
     @JavaScriptActor

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

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

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

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

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

@@ -112,6 +112,9 @@ extension TypeNode {
     switch self {
     case .primitive, .unknown:
       return self
+    case .sharedRef:
+      // The native type never reaches JS, so it isn't looked up among the scanned declarations.
+      return self
     case .ref(let name, _, _):
       guard let entry = index.lookup(name, in: scope) else {
         return self

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

@@ -170,6 +170,7 @@ final class SurfaceVisitor: SyntaxVisitor {
           name: qualified,
           jsName: stringArgument(of: attribute) ?? name,
           initializer: initializer,
+          sharedRef: sharedRefSuperclass(of: node),
           functions: functions,
           properties: properties,
           events: events,
@@ -348,6 +349,8 @@ final class SurfaceVisitor: SyntaxVisitor {
     platforms: [ExportedPlatform]
   ) -> [ExportedProperty] {
     let isLet = varDecl.bindingSpecifier.tokenKind == .keyword(.let)
+    // A `lazy var` is read-only from JS, like a `let`: the macro binds it getter-only.
+    let isLazy = varDecl.modifiers.contains { $0.name.tokenKind == .keyword(.lazy) }
     let isStatic = isTypeLevel(varDecl.modifiers)
     let override = stringArgument(of: attribute)
     var result: [ExportedProperty] = []
@@ -363,7 +366,7 @@ final class SurfaceVisitor: SyntaxVisitor {
           name: name,
           jsName: override ?? name,
           type: type,
-          isSettable: isSettable(binding: binding, isLet: isLet),
+          isSettable: !isLazy && isSettable(binding: binding, isLet: isLet),
           isStatic: isStatic,
           // Only a stored property has an initializer; a computed one has none to report.
           defaultValue: binding.initializer?.value.trimmedDescription,
@@ -741,6 +744,54 @@ private func asyncVariantName(of attribute: AttributeSyntax) -> String? {
   return nil
 }
 
+/// The `SharedRef<T>` a class names as its superclass, or `nil` when it names another one or none.
+/// Swift requires the superclass to come first in the inheritance clause, so only that entry is read.
+private func sharedRefSuperclass(of node: some DeclGroupSyntax) -> ExportedSharedRef? {
+  guard let superclass = node.inheritanceClause?.inheritedTypes.first?.type,
+    case .sharedRef(let native) = typeNode(from: superclass)
+  else {
+    return nil
+  }
+  return ExportedSharedRef(native: native, nativeRefType: nativeRefType(in: node.memberBlock.members))
+}
+
+/// The value of a `nativeRefType` override that returns a plain string literal: `"image"` in
+/// `override var nativeRefType: String { "image" }`, also with `return` or inside a `get` block.
+/// `unknown`, core's default, when the class declares no `nativeRefType`, and `nil` when its getter is
+/// anything else.
+private func nativeRefType(in members: MemberBlockItemListSyntax) -> String? {
+  let binding = members.lazy
+    .compactMap { $0.decl.as(VariableDeclSyntax.self) }
+    .filter { !isTypeLevel($0.modifiers) }
+    .flatMap { $0.bindings }
+    .first { $0.pattern.as(IdentifierPatternSyntax.self)?.identifier.text == "nativeRefType" }
+  guard let binding else {
+    return "unknown"
+  }
+  let statements: CodeBlockItemListSyntax?
+  switch binding.accessorBlock?.accessors {
+  case .getter(let body):
+    statements = body
+  case .accessors(let accessors):
+    statements = accessors.first { $0.accessorSpecifier.tokenKind == .keyword(.get) }?.body?.statements
+  case nil:
+    statements = nil
+  }
+  guard let statements, statements.count == 1, let item = statements.first?.item else {
+    return nil
+  }
+  let expression = item.as(ReturnStmtSyntax.self)?.expression ?? item.as(ExprSyntax.self)
+  guard let literal = expression?.as(StringLiteralExprSyntax.self),
+    literal.segments.count == 1,
+    let segment = literal.segments.first?.as(StringSegmentSyntax.self)
+  else {
+    return nil
+  }
+  // An escape would need real unescaping, so it's treated as unreadable, as in `writtenRawValue(of:)`.
+  let content = segment.content.text
+  return content.contains("\\") ? nil : content
+}
+
 private func isTypeLevel(_ modifiers: DeclModifierListSyntax) -> Bool {
   modifiers.contains {
     $0.name.tokenKind == .keyword(.static) || $0.name.tokenKind == .keyword(.class)

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

@@ -8,8 +8,8 @@ import SwiftSyntax
 /// never silently dropped.
 
 /// The runtime category mirroring JavaScript's `typeof`. A coarse companion to `TypeNode.kind`: every
-/// structured object kind (array, dictionary, promise, ref) reports `object`. `symbol` is included for
-/// completeness; the scanner doesn't produce it.
+/// structured object kind (array, dictionary, promise, ref, sharedRef) reports `object`. `symbol` is
+/// included for completeness; the scanner doesn't produce it.
 enum JSType: String, Encodable {
   case undefined
   case object
@@ -72,6 +72,11 @@ indirect enum TypeNode: Equatable {
   /// node parsed at a use site has never seen.
   case ref(name: String, refKind: RefKind? = nil, jsTypeOverride: JSType? = nil)
 
+  /// `SharedRef<T>` (or `ExpoModulesCore.SharedRef<T>`): a shared object holding a native `T`, which
+  /// JS sees as an instance of `expo.SharedRef`. `native` is `T` parsed like any other type, but it
+  /// never crosses the boundary itself, so refs in it are not resolved.
+  case sharedRef(native: TypeNode)
+
   /// A spelling the parser doesn't model (generic parameter, tuple, metatype, …), kept verbatim so
   /// nothing is lost. Has no `typeof`.
   case unknown(text: String)
@@ -82,7 +87,7 @@ indirect enum TypeNode: Equatable {
     switch self {
     case .primitive(_, let jsType):
       return jsType
-    case .array, .dictionary, .promise:
+    case .array, .dictionary, .promise, .sharedRef:
       return .object
     case .ref(_, _, let jsTypeOverride):
       // An unresolved ref, and every resolved one but an enum, is an object.
@@ -105,7 +110,7 @@ extension TypeNode: Encodable {
     // The `typeof` category. Spelled `typeof` in JSON (what the consumer reads); the Swift property is
     // `jsType` since it's the cleaner Swift name.
     case jsType = "typeof"
-    case wrapped, element, key, value, parameters, returns, text
+    case wrapped, element, key, value, parameters, returns, text, native
     // A closure type's effects, matching `ExportedFunction`'s TS-keyword spellings.
     case isAsync = "async"
     case isThrowing = "throws"
@@ -143,6 +148,9 @@ extension TypeNode: Encodable {
       try container.encode("ref", forKey: .kind)
       try container.encode(name, forKey: .name)
       try container.encodeIfPresent(refKind, forKey: .refKind)
+    case .sharedRef(let native):
+      try container.encode("sharedRef", forKey: .kind)
+      try container.encode(native, forKey: .native)
     case .unknown(let text):
       try container.encode("unknown", forKey: .kind)
       try container.encode(text, forKey: .text)
@@ -209,8 +217,15 @@ func typeNode(from type: TypeSyntax) -> TypeNode {
   if let identifier = type.as(IdentifierTypeSyntax.self) {
     return nominalNode(name: identifier.name.identifierName, generics: identifier.genericArgumentClause)
   }
-  // A qualified nominal type: `Foo.Bar`. Kept as a ref under its full spelling.
+  // A qualified nominal type: `Foo.Bar`. Kept as a ref under its full spelling, except core's own
+  // `ExpoModulesCore.SharedRef<T>`, which is the same type as a bare `SharedRef<T>`.
   if let member = type.as(MemberTypeSyntax.self) {
+    if member.baseType.as(IdentifierTypeSyntax.self)?.name.text == "ExpoModulesCore",
+      member.name.text == "SharedRef",
+      let generics = member.genericArgumentClause
+    {
+      return nominalNode(name: "SharedRef", generics: generics)
+    }
     return .ref(name: member.trimmedDescription)
   }
   // Tuples, metatypes, some/any types, etc.: not modeled, preserve the verbatim spelling.
@@ -218,8 +233,8 @@ func typeNode(from type: TypeSyntax) -> TypeNode {
 }
 
 /// A nominal type's node. The standard generic wrappers normalize to their sugared node
-/// (`Optional<T>`/`Array<T>`/`Dictionary<K,V>`/`Promise<T>`); a bare name is a primitive when known,
-/// else a ref; any other generic is a ref under its full spelling.
+/// (`Optional<T>`/`Array<T>`/`Dictionary<K,V>`/`Promise<T>`) and `SharedRef<T>` to its own node; a
+/// bare name is a primitive when known, else a ref; any other generic is a ref under its full spelling.
 private func nominalNode(name: String, generics: GenericArgumentClauseSyntax?) -> TypeNode {
   guard let generics else {
     if let jsType = primitiveJSTypes[name] {
@@ -238,6 +253,8 @@ private func nominalNode(name: String, generics: GenericArgumentClauseSyntax?) -
     return .dictionary(key: arguments[0], value: arguments[1])
   case ("Promise", 1):
     return .promise(value: arguments[0])
+  case ("SharedRef", 1):
+    return .sharedRef(native: arguments[0])
   default:
     // An unmodeled generic (`Set<Int>`, `Either<A, B>`, …). Keep the whole spelling as a ref so the
     // name and its arguments survive for the generator to interpret or flag.
@@ -297,6 +314,8 @@ extension TypeNode {
       return "[\(key.spelling): \(value.spelling)]"
     case .promise(let value):
       return "Promise<\(value.spelling)>"
+    case .sharedRef(let native):
+      return "SharedRef<\(native.spelling)>"
     case .function(let parameters, let returns, _, _):
       return "(\(parameters.map { $0.spelling }.joined(separator: ", "))) -> \(returns?.spelling ?? "Void")"
     case .unknown(let text):

package/build/index.d.ts

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

package/build/index.js

@@ -75,7 +75,7 @@ function platformBinaryPackageName() {
  *   `bin` directory.
  * - Windows and Linux: `ExpoModulesMacros.exe` or `ExpoModulesMacros` from the package for the
  *   current platform and architecture (see `platformBinaryPackageName`). When that package isn't
- *   installed, for example in this repository, it falls back to the executable that `npm run build`
+ *   installed, for example in this repository, it falls back to the executable that `pnpm run build`
  *   writes to `platforms/<platform>-<arch>`.
  *
  * The path isn't checked here; running a missing binary fails with a `ScannerError` that says how to
@@ -97,7 +97,7 @@ function getScannerBinaryPath() {
 /** The message for a scanner binary that doesn't exist at `binaryPath`. */
 function missingBinaryMessage(binaryPath) {
     if (process.platform === 'darwin') {
-        return `The scanner binary is missing at ${binaryPath}. Run \`npm run build\` in this package to build it.`;
+        return `The scanner binary is missing at ${binaryPath}. Run \`pnpm run build\` in this package to build it.`;
     }
     const machines = platformPackageMachines[process.platform];
     if (machines === undefined) {
@@ -106,7 +106,7 @@ function missingBinaryMessage(binaryPath) {
     return (`The scanner binary is missing at ${binaryPath}. It comes from the optional package ` +
         `${platformBinaryPackageName()}, which your package manager installs only on ${machines}. ` +
         'Reinstall dependencies without skipping optional ones (for example without `--omit=optional`), ' +
-        'or run `npm run build` in this package to build it locally.');
+        'or run `pnpm run build` in this package to build it locally.');
 }
 /**
  * Runs a scanner subcommand and parses its JSON report.

package/build/types.d.ts

@@ -61,6 +61,15 @@ export type TypeNode = {
     name: string;
     refKind?: 'record' | 'sharedObject' | 'enum' | 'union';
 }
+/**
+ * `SharedRef<T>`: a shared object that JS sees as an instance of `expo.SharedRef`. `native` is the
+ * `T` it holds on the native side. It never reaches JS, so refs in it are not resolved.
+ */
+ | {
+    kind: 'sharedRef';
+    typeof: JSType;
+    native: TypeNode;
+}
 /** A type the scanner couldn't interpret; `text` is its source spelling. */
  | {
     kind: 'unknown';
@@ -241,11 +250,26 @@ export interface ExportedSharedObject extends ExportedAccess, ExportedAvailabili
      * which every JS object inherits.
      */
     initializer?: ExportedInitializer;
+    /** What the class inherits from `SharedRef<T>`, or absent when its superclass isn't `SharedRef`. */
+    sharedRef?: ExportedSharedRef;
     functions: ExportedFunction[];
     properties: ExportedProperty[];
     events: ExportedEvent[];
     file: string;
 }
+/**
+ * The `SharedRef<T>` superclass of a shared object. Only the superclass written on the class is read,
+ * so a class that inherits `SharedRef` through another subclass has none.
+ */
+export interface ExportedSharedRef {
+    /** The `T` in `SharedRef<T>`: the native type the object holds, which JS never sees. */
+    native: TypeNode;
+    /**
+     * The `nativeRefType` JS reads to tell refs apart, for example `image`. `unknown` (core's default)
+     * when the class doesn't override it, and absent when the override isn't a plain string literal.
+     */
+    nativeRefType?: string;
+}
 /** A `@Record` type and its properties. */
 export interface ExportedRecord extends ExportedAccess, ExportedAvailability {
     /** The Swift type name, qualified with the types it is nested in (`Outer.Options`). */
@@ -365,4 +389,4 @@ export interface ScanExportsResult {
  * as a clear error instead of silently misread fields.
  */
 export declare const SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
-export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 8;
+export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 9;

package/build/types.js

@@ -12,4 +12,4 @@ exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = exports.SUPPORTED_SCAN_MODULES_S
  * as a clear error instead of silently misread fields.
  */
 exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
-exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 8;
+exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 9;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-macros",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Swift macro plugin for Expo modules",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -11,6 +11,7 @@
     "type": "git",
     "url": "git+https://github.com/expo/expo-modules-macros.git"
   },
+  "packageManager": "pnpm@12.14.0",
   "scripts": {
     "build": "node scripts/build.js",
     "build:ts": "tsc -p tsconfig.json",
@@ -25,9 +26,9 @@
     "typescript": "^5.4.0"
   },
   "optionalDependencies": {
-    "@expo/modules-macros-linux-arm64": "0.22.0",
-    "@expo/modules-macros-linux-x64": "0.22.0",
-    "@expo/modules-macros-win32-arm64": "0.22.0",
-    "@expo/modules-macros-win32-x64": "0.22.0"
+    "@expo/modules-macros-linux-arm64": "0.23.0",
+    "@expo/modules-macros-linux-x64": "0.23.0",
+    "@expo/modules-macros-win32-arm64": "0.23.0",
+    "@expo/modules-macros-win32-x64": "0.23.0"
   }
 }