expo-modules-macros 0.30.0 → 0.32.0

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

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

package/AGENTS.md

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

package/README.md

@@ -25,11 +25,11 @@ This package lists them as optional dependencies, and their `os`, `cpu` and (on
 # Macros
 
 - **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none. It adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet (see [Sendable conformance](#sendable-conformance)).
-- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. The macro also checks that every type crossing the boundary is convertible in the direction it travels. Outside a module or shared object, a bad type is reported on the author's own declaration. In an `@ExpoModule` or `@SharedObject` class, the class macro makes the check, since only it sees the type aliases in the class body, so the error is reported on the class and names the member and its argument labels, such as `local function 'move(_:by:returning:)' requires that 'Point' conform to 'JavaScriptEncodable'`. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. Because of that, a `.concurrent` function and a function with `.withAsync` can't take a JavaScript value such as `JavaScriptValue` or `JavaScriptObject`, which is valid only on the JavaScript thread; the macro reports such a parameter. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
-- **`@Event(_ name: String? = nil, _ options: EventOptions...)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. The `.sync` option dispatches inline on the JavaScript thread instead of asynchronously, and `@ExpoModule` and `@SharedObject` isolate the property to `@JavaScriptActor`.
-- **`@SharedObject(_ name: String? = nil)`** on a subclass of `SharedObject`, direct or not, such as a `SharedRef<T>` subclass. Binds the class's `@JS` members through the `SharedObject` hooks that core calls when it builds the JavaScript class, and emits the JS class name, which defaults to the class name. A module exposes the class through `@ExpoModule(classes:)`, which only accepts `SharedObject` subclasses. A subclass of another `@SharedObject` class also gets the `@JS` members of that class, and its own members replace inherited members with the same JS name. A subclass that isn't `final` can't be constructed from JavaScript through the `@JS init` of its superclass, so give each subclass that JavaScript constructs its own `@JS init`. Like `@ExpoModule`, it adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet.
-- **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. A record converts only from and to JavaScript values: its `from(dictionary:appContext:)` throws `RecordDictionaryConversionException`, so a record can't be created from a native `[String: Any]`. A `@Union` can be a record property. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
-- **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first.
+- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. The class macro reads only the class body, so `@JS` on a member of an extension, or of a type that is neither a module nor a shared object, is an error. So is `@JS` on an initializer or a `static` member of a module, since JavaScript doesn't construct a module and gets only its instance. `@JS` on any other declaration, such as a subscript, is an error too. A `@JS` function or initializer can't be generic, since the binding converts each value by its static type. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. A name that JavaScript already gives a meaning on the object is an error too: `__proto__` on any object, `constructor` on a shared object's prototype, and `prototype` on its constructor. The macro also checks that every type crossing the boundary is convertible in the direction it travels. For a top-level declaration, a bad type is reported on the author's own declaration. In an `@ExpoModule` or `@SharedObject` class, the class macro makes the check, since only it sees the type aliases in the class body, so the error is reported on the class and names the member and its argument labels, such as `local function 'move(_:by:returning:)' requires that 'Point' conform to 'JavaScriptEncodable'`. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. Because of that, a `.concurrent` function and a function with `.withAsync` can't take a JavaScript value such as `JavaScriptValue` or `JavaScriptObject`, which is valid only on the JavaScript thread; the macro reports such a parameter. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
+- **`@Event(_ name: String? = nil, _ options: EventOptions...)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `@ExpoModule` and `@SharedObject` warn when two events in the class body have the same JS name. By default the event is scheduled on the JavaScript thread. The `.inline` option runs the listeners before the call returns when it is made on the JavaScript thread, and schedules the event otherwise; it never blocks. The `.blocking` option runs the listeners before the call returns on any thread, so a call from another thread blocks until the JavaScript thread runs them. An event property is callable from any thread with each option.
+- **`@SharedObject(_ name: String? = nil)`** on a subclass of `SharedObject`, direct or not, such as a `SharedRef<T>` subclass. Binds the class's `@JS` members through the `SharedObject` hooks that core calls when it builds the JavaScript class, and emits the JS class name, which defaults to the class name. A class without an inheritance clause is an error, with a Fix-It that adds `: SharedObject`. A module exposes the class through `@ExpoModule(classes:)`, which only accepts `SharedObject` subclasses. A subclass of another `@SharedObject` class also gets the `@JS` members of that class, and its own members replace inherited members with the same JS name. A subclass that isn't `final` can't be constructed from JavaScript through the `@JS init` of its superclass, so give each subclass that JavaScript constructs its own `@JS init`. Like `@ExpoModule`, it adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet.
+- **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. A record converts only from and to JavaScript values: its `from(dictionary:appContext:)` throws `RecordDictionaryConversionException`, so a record can't be created from a native `[String: Any]`. A `@Union` can be a record property. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional. The memberwise initializer sets every field, so a field that is a `let` with a default value is an error. It doesn't set a `private` or `fileprivate` stored property, so such a property needs a default value, unless it's an optional `var` or the type declares its own memberwise initializer.
+- **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first. The macro warns about a case that an earlier case always decodes first: any case after a `JavaScriptValue` case, and a case with a payload that decodes only numbers, such as `Float` or `Int32`, after a `Double`, `Float` or `CGFloat` case.
 
 The members and conformances that `@Record` and `@Union` generate are `nonisolated`, so they also work in a module that builds with a default isolation, such as `-default-isolation MainActor`. The stored properties of a record still take that isolation. A class record, or a struct record with a property whose type isn't `Sendable`, then needs `nonisolated` on its declaration, for example `@Record nonisolated final class Options`.
 
@@ -145,11 +145,13 @@ Each applied Fix-It is printed to stdout as `<file>:<line>:<column>: fix-it: <me
 
 `fix` applies the Fix-Its of errors and of warnings, such as "Make the class 'public'" for a module class that isn't `public`. With `--only-errors`, it applies only those of errors.
 
-- A macro can stop at its first error, so after applying the Fix-Its of a file, `fix` expands it again and applies the new ones, until none applies (at most 10 passes). The location of a Fix-It is in the file as it was when the Fix-It was applied.
-- A diagnostic with more than one Fix-It is skipped, because they are alternatives. So is a Fix-It whose edits overlap the edits of another one, or whose text isn't in the file where the edit expects it. Each skipped Fix-It is printed to stderr as a warning.
+- A macro can stop at its first error, so after applying the Fix-Its of a file, `fix` expands it again and applies the new ones, until none applies (at most 10 passes, with a warning when Fix-Its are left after them). The location of a Fix-It is in the file as it was when the Fix-It was applied.
+- A diagnostic with more than one Fix-It is skipped, because they are alternatives. So is a Fix-It whose edits overlap the edits of another one, or whose text isn't in the file where the edit expects it; an insertion is checked against the few bytes after it. Each skipped Fix-It is printed to stderr as a warning.
 - It applies only the Fix-Its of the macros, not those of syntax errors.
 - It changes only the text that a Fix-It changes and doesn't format the file. An inserted keyword can make a line longer than your formatter allows, so run your formatter after `fix` if you use one.
 
+`fix` writes a file only when it still has the contents that `fix` read, so it doesn't overwrite a change saved meanwhile. It writes the file in place, so on macOS and Linux, symbolic and hard links, permissions, the owner, extended attributes and ACLs stay, and a read-only file isn't written. When a write fails, `fix` writes the original contents back and reports whether the file is unchanged; when that fails too, it saves them to a file in the temporary directory and names it. A file that can't be written is reported, and the other files are still fixed. A UTF-8 byte order mark is kept.
+
 The exit code is `0` also when a Fix-It is skipped or errors remain, `1` when a file can't be written, and `2` for an input that `expand` doesn't take.
 
 # TypeScript wrapper

package/apple/Sources/ExpoModulesCLI/Commands/Expand/ExpandReport.swift

@@ -107,8 +107,9 @@ public struct ExpansionEdit: Equatable, Sendable {
   /// The UTF-8 offset in the original file.
   public let offset: Int
 
-  /// The text that the edit replaces, so `fix` can check that the file still has it there. Empty
-  /// for an insertion.
+  /// The text that the edit replaces, so `fix` can check that the file still has it there. An
+  /// insertion also replaces a few bytes after it with themselves, so it has text to check too, and
+  /// is empty only at the end of a declaration.
   public let original: String
 
   public let replacement: String

package/apple/Sources/ExpoModulesCLI/Commands/Expand/MacroExpander.swift

@@ -35,8 +35,10 @@ public func expandMacros(source: String, file: String, symbols: [String]) -> Exp
   let originalDeclarations = OriginalDeclarations(tree)
   diagnostics += context.diagnostics.map { diagnostic in
     let location = { (position: AbsolutePosition, node: Syntax) -> SourceLocation in
-      let declarationStart = context.location(for: node.root.position, anchoredAt: node, fileName: file).offset
-      if let original = originalDeclarations.position(of: position, in: node, declarationStart: declarationStart) {
+      let original = originalDeclarations.position(of: position, in: node) {
+        context.location(for: node.root.position, anchoredAt: node, fileName: file).offset
+      }
+      if let original {
         return converter.location(for: original)
       }
       return context.location(for: position, anchoredAt: node, fileName: file)
@@ -221,13 +223,21 @@ private func originalEdits(
   of fixIt: FixIt,
   offset: (AbsolutePosition, Syntax) -> Int
 ) -> [ExpansionEdit]? {
-  var edits: [ExpansionEdit] = []
+  // The edit of each change in the tree of its node. `FixIt.edits` drops an edit that overlaps an
+  // earlier one; this applies the same rule.
+  var changes: [(edit: SourceEdit, node: Syntax)] = []
   for change in fixIt.changes {
-    // `FixIt.edits` drops an edit that overlaps an earlier one; this applies the same rule.
     guard let edit = FixIt(message: fixIt.message, changes: [change]).edits.first else {
       continue
     }
     let node = changedNode(change)
+    if !changes.contains(where: { $0.node.root.id == node.root.id && $0.edit.range.overlaps(edit.range) }) {
+      changes.append((edit, node))
+    }
+  }
+
+  var edits: [ExpansionEdit] = []
+  for (index, (edit, node)) in changes.enumerated() {
     let root = node.root
     let text = Array(root.description.utf8)
     let start = edit.range.lowerBound.utf8Offset - root.position.utf8Offset
@@ -241,19 +251,36 @@ private func originalEdits(
     guard prefix + suffix < max(old.count, new.count) else {
       continue
     }
-    let changedStart = edit.range.lowerBound.advanced(by: prefix)
-    let originalEdit = ExpansionEdit(
-      offset: offset(changedStart, node),
-      original: String(decoding: old.dropFirst(prefix).dropLast(suffix), as: UTF8.self),
-      replacement: String(decoding: new.dropFirst(prefix).dropLast(suffix), as: UTF8.self)
-    )
-    if !edits.contains(where: { overlaps($0, originalEdit) }) {
-      edits.append(originalEdit)
+    var original = Array(old.dropFirst(prefix).dropLast(suffix))
+    var replacement = Array(new.dropFirst(prefix).dropLast(suffix))
+    if original.isEmpty {
+      // An insertion has no text that `fix` can check in the file, so it also replaces the bytes after
+      // it with themselves, up to a character boundary and not into another change of the Fix-It.
+      let insertion = start + prefix
+      let nextChange = changes.enumerated().filter { $0.offset != index && $0.element.node.root.id == root.id }
+        .map { $0.element.edit.range.lowerBound.utf8Offset - root.position.utf8Offset }
+        .filter { $0 >= insertion }.min()
+      var contextEnd = min(insertion + insertionContextLength, text.count, nextChange ?? text.count)
+      while contextEnd > insertion && contextEnd < text.count && text[contextEnd] & 0xC0 == 0x80 {
+        contextEnd -= 1
+      }
+      original = Array(text[insertion..<contextEnd])
+      replacement += original
     }
+    edits.append(
+      ExpansionEdit(
+        offset: offset(edit.range.lowerBound.advanced(by: prefix), node),
+        original: String(decoding: original, as: UTF8.self),
+        replacement: String(decoding: replacement, as: UTF8.self)
+      )
+    )
   }
   return edits
 }
 
+/// The number of bytes after an insertion that its edit also replaces with themselves.
+private let insertionContextLength = 8
+
 /// The node in the tree that `change` edits.
 private func changedNode(_ change: FixIt.Change) -> Syntax {
   switch change {
@@ -268,11 +295,6 @@ private func changedNode(_ change: FixIt.Change) -> Syntax {
   }
 }
 
-/// Whether two edits change the same bytes of the original file.
-private func overlaps(_ a: ExpansionEdit, _ b: ExpansionEdit) -> Bool {
-  a.offset < b.offset + b.original.utf8.count && b.offset < a.offset + a.original.utf8.count
-}
-
 /// The lengths of the longest common prefix and suffix of `old` and `new` that don't overlap, at
 /// character boundaries, so the bytes between them are valid UTF-8 on both sides.
 private func commonAffixLengths(_ old: [UInt8], _ new: [UInt8]) -> (prefix: Int, suffix: Int) {
@@ -320,45 +342,72 @@ private func severity(_ severity: DiagnosticSeverity) -> ExpansionDiagnostic.Sev
 /// `init`) to its end is the same in both, so this moves the position by the offset of the keyword
 /// in the original declaration. A position before the keyword, in the attributes or the modifiers,
 /// isn't mapped.
-private struct OriginalDeclarations {
+///
+/// An accessor macro can get a declaration that swift-syntax rewrote rather than detached, for
+/// example an `@Event` property with a closure in its initializer, and its start doesn't map to the
+/// file. Such a declaration is found by its text when no other declaration in the file has it.
+private final class OriginalDeclarations {
   /// The declarations in the original file by the UTF-8 offset of their start, with their leading
   /// trivia: the text from the keyword to the end of each, and the position of its keyword.
-  private let declarations: [Int: [(text: String, keyword: AbsolutePosition)]]
+  private let declarationsByStart: [Int: [(text: String, keyword: AbsolutePosition)]]
+
+  /// The positions of the keywords of the declarations in the original file, by the text from the
+  /// keyword to the end of the declaration.
+  private let keywordsByText: [String: [AbsolutePosition]]
+
+  /// The positions of the keyword of each declaration that a macro got and of its original
+  /// declaration, or `nil` when it has no original declaration.
+  private var keywords: [SyntaxIdentifier: (keyword: AbsolutePosition, original: AbsolutePosition)?] = [:]
 
   init(_ tree: SourceFileSyntax) {
     let collector = DeclarationCollector(viewMode: .sourceAccurate)
     collector.walk(tree)
-    var declarations: [Int: [(text: String, keyword: AbsolutePosition)]] = [:]
+    var declarationsByStart: [Int: [(text: String, keyword: AbsolutePosition)]] = [:]
+    var keywordsByText: [String: [AbsolutePosition]] = [:]
     for declaration in collector.declarations {
       guard let keyword = keywordToken(of: declaration) else {
         continue
       }
-      declarations[declaration.position.utf8Offset, default: []].append(
-        (textFromKeyword(keyword, of: declaration), keyword.positionAfterSkippingLeadingTrivia)
+      let text = textFromKeyword(keyword, of: declaration)
+      declarationsByStart[declaration.position.utf8Offset, default: []].append(
+        (text, keyword.positionAfterSkippingLeadingTrivia)
       )
+      keywordsByText[text, default: []].append(keyword.positionAfterSkippingLeadingTrivia)
     }
-    self.declarations = declarations
+    self.declarationsByStart = declarationsByStart
+    self.keywordsByText = keywordsByText
   }
 
   /// The position in the original file of `position` in `node`, or `nil` when `node` is in the
-  /// original file, isn't in a detached declaration, is before its keyword, or no declaration with its
-  /// text starts at `declarationStart`.
+  /// original file, isn't in a declaration that a macro got, is before its keyword, or its original
+  /// declaration isn't found.
   ///
-  /// `declarationStart` is the offset that the macro system maps the start of the detached
-  /// declaration to.
-  func position(of position: AbsolutePosition, in node: Syntax, declarationStart: Int) -> AbsolutePosition? {
-    guard !node.root.is(SourceFileSyntax.self),
-      let declaration = node.root.as(DeclSyntax.self),
-      let keyword = keywordToken(of: declaration),
-      position >= keyword.positionAfterSkippingLeadingTrivia,
-      let original = declarations[declarationStart]?.first(where: {
-        $0.text == textFromKeyword(keyword, of: declaration)
-      })
-    else {
+  /// `declarationStart` returns the offset that the macro system maps the start of the declaration
+  /// to. It is called once for each declaration.
+  func position(
+    of position: AbsolutePosition,
+    in node: Syntax,
+    declarationStart: () -> Int
+  ) -> AbsolutePosition? {
+    guard !node.root.is(SourceFileSyntax.self), let declaration = node.root.as(DeclSyntax.self) else {
+      return nil
+    }
+    let found: (keyword: AbsolutePosition, original: AbsolutePosition)?
+    if let cached = keywords[declaration.id] {
+      found = cached
+    } else {
+      found = keywordToken(of: declaration).flatMap { keyword in
+        let text = textFromKeyword(keyword, of: declaration)
+        let byStart = declarationsByStart[declarationStart()]?.first { $0.text == text }?.keyword
+        let byText = keywordsByText[text].flatMap { $0.count == 1 ? $0.first : nil }
+        return (byStart ?? byText).map { (keyword.positionAfterSkippingLeadingTrivia, $0) }
+      }
+      keywords[declaration.id] = found
+    }
+    guard let found, position >= found.keyword else {
       return nil
     }
-    let offset = position.utf8Offset - keyword.positionAfterSkippingLeadingTrivia.utf8Offset
-    return AbsolutePosition(utf8Offset: original.keyword.utf8Offset + offset)
+    return AbsolutePosition(utf8Offset: found.original.utf8Offset + position.utf8Offset - found.keyword.utf8Offset)
   }
 }
 

package/apple/Sources/ExpoModulesCLI/Commands/Expand/RunExpand.swift

@@ -86,14 +86,14 @@ func expandFiles(options: ExpandOptions, expander: MacroExpander) -> Result<Expa
   }
 }
 
-/// The files of `options` with their sources, expanded with `expander`, as `expandFiles` describes.
-/// `fix` uses it too, because it edits the sources.
+/// The files of `options` with their sources and the bytes that were read, expanded with `expander`,
+/// as `expandFiles` describes. `fix` uses it too, because it edits the sources.
 func expandSources(
   options: ExpandOptions,
   expander: MacroExpander
-) -> Result<[(source: String, expanded: ExpandedFile)], ExpandInputError> {
+) -> Result<[(source: String, contents: Data, expanded: ExpandedFile)], ExpandInputError> {
   let prefilter = MacroPrefilter(attributeNames: expander.attributeNames)
-  var sources: [(file: String, source: String)] = []
+  var sources: [(file: String, source: String, contents: Data)] = []
   var seen: Set<String> = []
   for path in options.paths {
     switch isDirectory(atPath: path) {
@@ -101,12 +101,12 @@ func expandSources(
       return .failure(ExpandInputError(message: "no such file or directory '\(path)'"))
     case .some(true):
       for file in swiftFiles(in: [path]) where !seen.contains(fileIdentity(file)) {
-        guard let source = try? String(contentsOfFile: file, encoding: .utf8) else {
+        guard let (source, contents) = readSource(atPath: file) else {
           return .failure(ExpandInputError(message: "could not read '\(file)'"))
         }
         seen.insert(fileIdentity(file))
         if mightContainMacro(in: source, prefilter: prefilter) {
-          sources.append((file, source))
+          sources.append((file, source, contents))
         }
       }
     case .some(false):
@@ -116,15 +116,17 @@ func expandSources(
       guard !seen.contains(fileIdentity(path)) else {
         continue
       }
-      guard let source = try? String(contentsOfFile: path, encoding: .utf8) else {
+      guard let (source, contents) = readSource(atPath: path) else {
         return .failure(ExpandInputError(message: "could not read '\(path)'"))
       }
       seen.insert(fileIdentity(path))
-      sources.append((path, source))
+      sources.append((path, source, contents))
     }
   }
 
-  let files = sources.map { (source: $0.source, expanded: expander.expand($0.source, $0.file, options.symbols)) }
+  let files = sources.map {
+    (source: $0.source, contents: $0.contents, expanded: expander.expand($0.source, $0.file, options.symbols))
+  }
 
   let found = Set(files.flatMap { $0.expanded.expansions.compactMap(\.symbol) })
   if let missing = options.symbols.first(where: { !found.contains($0) }) {
@@ -139,6 +141,22 @@ func expandSources(
   return .success(files)
 }
 
+/// The bytes of a UTF-8 byte order mark.
+let utf8ByteOrderMark: [UInt8] = [0xEF, 0xBB, 0xBF]
+
+/// The contents of the file at `path` as text, without a UTF-8 byte order mark, and the bytes that
+/// were read. `nil` when the file can't be read or isn't UTF-8.
+func readSource(atPath path: String) -> (source: String, contents: Data)? {
+  guard let contents = try? Data(contentsOf: URL(fileURLWithPath: path)) else {
+    return nil
+  }
+  let text = contents.starts(with: utf8ByteOrderMark) ? contents.dropFirst(utf8ByteOrderMark.count) : contents[...]
+  guard let source = String(bytes: text, encoding: .utf8) else {
+    return nil
+  }
+  return (source, contents)
+}
+
 /// The expanded sources as text. A single expansion is printed as it is; more than one each get a
 /// `// <file>` or `// <file>: <symbol>` header and are separated by an empty line.
 func renderExpansions(_ files: [ExpandedFile]) -> String {

package/apple/Sources/ExpoModulesCLI/Commands/Fix/RunFix.swift

@@ -28,8 +28,7 @@ struct FixedSource: Equatable {
   let source: String
   let fixIts: [FixItReport]
 
-  /// Whether `fixSource` stopped after `maxFixPasses` passes while the last pass still applied a
-  /// Fix-It, so the source can have more.
+  /// Whether `fixSource` stopped after `maxFixPasses` passes while Fix-Its were left to apply.
   var reachedPassLimit = false
 
   var applied: [FixItReport] {
@@ -46,8 +45,16 @@ extension Scanner {
   /// `--dry-run`, the files aren't written. A file that can't be written is reported and the others are
   /// still fixed. The exit code is `0` also when a Fix-It is skipped, `1` when a file can't be written,
   /// and `2` for an input that `expand` doesn't take.
-  static func runFix(options: FixOptions, expander: MacroExpander) -> Int32 {
-    let sources: [(source: String, expanded: ExpandedFile)]
+  ///
+  /// `write` writes a fixed file and returns whether it changed it (see `writeFixedSource`); tests
+  /// replace it. A file that another path already fixed, through a hard link, isn't printed or counted
+  /// again.
+  static func runFix(
+    options: FixOptions,
+    expander: MacroExpander,
+    write: (_ source: String, _ path: String, _ original: Data) throws -> Bool = writeFixedSource
+  ) -> Int32 {
+    let sources: [(source: String, contents: Data, expanded: ExpandedFile)]
     switch expandSources(options: ExpandOptions(paths: options.paths, symbols: options.symbols), expander: expander) {
     case .success(let expanded):
       sources = expanded
@@ -58,8 +65,8 @@ extension Scanner {
 
     var appliedCount = 0
     var fixedFiles = 0
-    var failed = false
-    for (source, expanded) in sources {
+    var failedFiles = 0
+    for (source, contents, expanded) in sources {
       let fixed = fixSource(
         source,
         expanded: expanded,
@@ -73,10 +80,12 @@ extension Scanner {
       }
       if !options.dryRun {
         do {
-          try writeSource(fixed.source, toFile: expanded.file)
+          guard try write(fixed.source, expanded.file, contents) else {
+            continue
+          }
         } catch {
           writeToStandardError("error: could not write '\(expanded.file)': \(error)\n")
-          failed = true
+          failedFiles += 1
           continue
         }
       }
@@ -85,20 +94,62 @@ extension Scanner {
       fixedFiles += 1
     }
 
-    writeToStandardOutput(renderFixSummary(applied: appliedCount, files: fixedFiles, dryRun: options.dryRun))
-    return failed ? 1 : 0
+    writeToStandardOutput(
+      renderFixSummary(applied: appliedCount, files: fixedFiles, failed: failedFiles, dryRun: options.dryRun)
+    )
+    return failedFiles > 0 ? 1 : 0
   }
 }
 
-/// Writes `source` to the file at `path` in place, so a symbolic link keeps pointing to the file and a
-/// hard link keeps sharing it, and a writable file can be written in a read-only directory. Keeps the
-/// UTF-8 byte order mark of the file, which the source doesn't have because reading it as a `String`
-/// removes it.
-func writeSource(_ source: String, toFile path: String) throws {
+/// Why `writeFixedSource` didn't write a file.
+struct FixWriteError: Error, CustomStringConvertible {
+  let description: String
+}
+
+/// Writes `source`, the fixed source of the file at `path`, whose contents were `original`, and
+/// returns whether it changed the file.
+///
+/// The file must still have the contents that `fix` read, so a change that an editor saved meanwhile
+/// isn't lost. A file that already has the fixed contents, because `fix` wrote it through another
+/// hard link, is left as it is. It keeps the UTF-8 byte order mark of the file, which `readSource`
+/// removes from the source.
+///
+/// The file is written in place, so on macOS and Linux its links, permissions, owner, extended
+/// attributes and ACLs stay, and a read-only file isn't written. When the write fails, the original contents are written back,
+/// and the error tells whether the file is unchanged. When that fails too, the original contents are
+/// saved to a file in the temporary directory, which the error names.
+@discardableResult
+func writeFixedSource(_ source: String, toFile path: String, original: Data) throws -> Bool {
   let url = URL(fileURLWithPath: path)
-  let byteOrderMark: [UInt8] = [0xEF, 0xBB, 0xBF]
-  let hasByteOrderMark = try Data(contentsOf: url).starts(with: byteOrderMark)
-  try Data((hasByteOrderMark ? byteOrderMark : []) + Array(source.utf8)).write(to: url)
+  let contents = Data((original.starts(with: utf8ByteOrderMark) ? utf8ByteOrderMark : []) + Array(source.utf8))
+  guard let current = try? Data(contentsOf: url) else {
+    throw FixWriteError(description: "the file can't be read anymore")
+  }
+  guard current != contents else {
+    return false
+  }
+  guard current == original else {
+    throw FixWriteError(description: "the file changed after fix read it")
+  }
+  do {
+    try contents.write(to: url)
+  } catch {
+    if (try? Data(contentsOf: url)) != original {
+      try? original.write(to: url)
+    }
+    if (try? Data(contentsOf: url)) == original {
+      throw FixWriteError(description: "\(error); the file is unchanged")
+    }
+    let backup = FileManager.default.temporaryDirectory.appendingPathComponent(
+      "\(url.lastPathComponent).\(UUID().uuidString).original"
+    )
+    let saved = (try? original.write(to: backup)) != nil
+    throw FixWriteError(
+      description: "\(error); the file can be incomplete"
+        + (saved ? ", and its original contents are in '\(backup.path)'" : "")
+    )
+  }
+  return true
 }
 
 /// The most times that `fixSource` expands a file again after applying Fix-Its.
@@ -126,10 +177,17 @@ func fixSource(
     fixed = applyFixIts(to: fixed.source, diagnostics: selected(diagnostics))
     applied += fixed.applied
   }
+  // After the last pass, expand once more to tell whether Fix-Its are left.
+  let reachedPassLimit =
+    !fixed.applied.isEmpty
+    && !applyFixIts(
+      to: fixed.source,
+      diagnostics: selected(expander.expand(fixed.source, expanded.file, symbols).diagnostics)
+    ).applied.isEmpty
   return FixedSource(
     source: fixed.source,
     fixIts: applied + fixed.fixIts.filter { $0.skipReason != nil },
-    reachedPassLimit: !fixed.applied.isEmpty
+    reachedPassLimit: reachedPassLimit
   )
 }
 
@@ -217,12 +275,16 @@ func renderSkippedFixIts(_ fixed: FixedSource, file: String) -> String {
   return text
 }
 
-/// The summary line of `fix`, for example `Applied 3 Fix-Its in 2 files.`
-func renderFixSummary(applied: Int, files: Int, dryRun: Bool) -> String {
-  guard applied > 0 else {
-    return "No Fix-Its to apply.\n"
+/// The summary line of `fix`, for example `Applied 3 Fix-Its in 2 files.` or, when files couldn't be
+/// written, `Applied 1 Fix-It in 1 file. Could not write 1 file.`
+func renderFixSummary(applied: Int, files: Int, failed: Int = 0, dryRun: Bool) -> String {
+  let count = { (n: Int, noun: String) in "\(n) \(noun)\(n == 1 ? "" : "s")" }
+  var parts: [String] = []
+  if applied > 0 {
+    parts.append("\(dryRun ? "Would apply" : "Applied") \(count(applied, "Fix-It")) in \(count(files, "file")).")
+  }
+  if failed > 0 {
+    parts.append("Could not write \(count(failed, "file")).")
   }
-  let fixIts = "\(applied) Fix-It\(applied == 1 ? "" : "s")"
-  let fileCount = "\(files) file\(files == 1 ? "" : "s")"
-  return "\(dryRun ? "Would apply" : "Applied") \(fixIts) in \(fileCount).\n"
+  return (parts.isEmpty ? "No Fix-Its to apply." : parts.joined(separator: " ")) + "\n"
 }

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

@@ -207,8 +207,8 @@ struct ExportedEvent: Encodable, Equatable {
   /// The single payload parameter's type, or `nil` for a no-payload `() -> Void` event.
   var payload: TypeNode?
 
-  /// `@Event(.sync)`, dispatching inline on the JS thread instead of scheduling.
-  let isSync: Bool
+  /// How the event is dispatched: the default `scheduled`, or the `.inline` or `.blocking` option.
+  let dispatch: ExportedEventDispatch
 
   /// The spelled access modifier, or `nil` when none is written.
   let accessLevel: String?
@@ -216,8 +216,7 @@ struct ExportedEvent: Encodable, Equatable {
   let platforms: [ExportedPlatform]
 
   private enum CodingKeys: String, CodingKey {
-    case name, jsName, payload, accessLevel, platforms
-    case isSync = "sync"
+    case name, jsName, payload, dispatch, accessLevel, platforms
   }
 
   func encode(to encoder: Encoder) throws {
@@ -225,7 +224,7 @@ struct ExportedEvent: Encodable, Equatable {
     try container.encode(name, forKey: .name)
     try container.encode(jsName, forKey: .jsName)
     try container.encodeIfPresent(payload, forKey: .payload)
-    try container.encode(isSync, forKey: .isSync)
+    try container.encode(dispatch, forKey: .dispatch)
     try container.encodeIfPresent(accessLevel, forKey: .accessLevel)
     try container.encode(platforms, forKey: .platforms)
   }
@@ -471,6 +470,13 @@ struct ExportedSurface: Encodable, Equatable {
   let unions: [ExportedUnion]
 }
 
+/// How an `@Event` is dispatched to JavaScript, from its option. Mirrors `EventDispatch` in the macros.
+enum ExportedEventDispatch: String, Encodable, Equatable {
+  case scheduled
+  case inline
+  case blocking
+}
+
 /// Version of the `scan-exports` output shape. Bumped on any breaking change to the envelope or to
 /// anything under `exports`, so a consumer can verify it understands the output before trusting it.
 /// Versioned independently of `scanModulesSchemaVersion`: the two commands serve different consumers
@@ -481,8 +487,9 @@ struct ExportedSurface: Encodable, Equatable {
 /// declarations in `#if` blocks, adds `platforms` (with deprecations), `accessLevel`, and
 /// `defaultValue`, and replaces `constructorParameters` with `initializer`; version 9 adds the
 /// `sharedRef` type kind and the `sharedRef` of a shared object; version 10 adds the `tuple` and `object` type kinds (named after a tuple alias)
-/// and resolves the tuple type aliases declared in `@ExpoModule` and `@SharedObject` classes.
-let scanExportsSchemaVersion = 10
+/// and resolves the tuple type aliases declared in `@ExpoModule` and `@SharedObject` classes; version 11
+/// replaces the `sync` flag of an event with `dispatch`.
+let scanExportsSchemaVersion = 11
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).