expo-modules-macros 0.29.0 → 0.30.0

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

@@ -0,0 +1,228 @@
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
+import Foundation
+#endif
+
+/// The options of `fix`, parsed by `ScannerCLI`.
+struct FixOptions: Equatable {
+  var paths: [String] = []
+  var symbols: [String] = []
+  var dryRun = false
+  var onlyErrors = false
+}
+
+/// A Fix-It that `fix` applied or skipped, at the location of its diagnostic.
+struct FixItReport: Equatable {
+  let line: Int
+  let column: Int
+  let message: String
+
+  /// Why `fix` skipped the Fix-It, or `nil` when it applied it.
+  let skipReason: String?
+}
+
+/// The result of applying the Fix-Its of one file.
+struct FixedSource: Equatable {
+  /// The source with the applied Fix-Its.
+  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.
+  var reachedPassLimit = false
+
+  var applied: [FixItReport] {
+    fixIts.filter { $0.skipReason == nil }
+  }
+}
+
+extension Scanner {
+  /// Runs `fix`: expands the macros in each file like `expand` and applies the Fix-Its of their
+  /// diagnostics to the file, in place (see `fixSource`). It doesn't format the file.
+  ///
+  /// Each applied Fix-It is printed to stdout as `<file>:<line>:<column>: fix-it: <message>` after its
+  /// file is written, followed by a summary, and each skipped one to stderr as a warning. With
+  /// `--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)]
+    switch expandSources(options: ExpandOptions(paths: options.paths, symbols: options.symbols), expander: expander) {
+    case .success(let expanded):
+      sources = expanded
+    case .failure(let error):
+      writeToStandardError("error: \(error.message)\n")
+      return 2
+    }
+
+    var appliedCount = 0
+    var fixedFiles = 0
+    var failed = false
+    for (source, expanded) in sources {
+      let fixed = fixSource(
+        source,
+        expanded: expanded,
+        symbols: options.symbols,
+        onlyErrors: options.onlyErrors,
+        expander: expander
+      )
+      writeToStandardError(renderSkippedFixIts(fixed, file: expanded.file))
+      guard !fixed.applied.isEmpty else {
+        continue
+      }
+      if !options.dryRun {
+        do {
+          try writeSource(fixed.source, toFile: expanded.file)
+        } catch {
+          writeToStandardError("error: could not write '\(expanded.file)': \(error)\n")
+          failed = true
+          continue
+        }
+      }
+      writeToStandardOutput(renderAppliedFixIts(fixed, file: expanded.file))
+      appliedCount += fixed.applied.count
+      fixedFiles += 1
+    }
+
+    writeToStandardOutput(renderFixSummary(applied: appliedCount, files: fixedFiles, dryRun: options.dryRun))
+    return failed ? 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 {
+  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)
+}
+
+/// The most times that `fixSource` expands a file again after applying Fix-Its.
+let maxFixPasses = 10
+
+/// Applies the Fix-Its of `expanded`, the expansion of `source`, to `source`. A macro can stop at its
+/// first error, so after applying Fix-Its, this expands the result again and applies the new Fix-Its,
+/// until none applies or after `maxFixPasses` passes. The location of an applied Fix-It is in the
+/// source of its pass. The skipped Fix-Its are those of the last pass. With `onlyErrors`, the Fix-Its
+/// of warnings and other diagnostics that aren't errors are left out.
+func fixSource(
+  _ source: String,
+  expanded: ExpandedFile,
+  symbols: [String],
+  onlyErrors: Bool = false,
+  expander: MacroExpander
+) -> FixedSource {
+  let selected = { (diagnostics: [ExpansionDiagnostic]) in
+    onlyErrors ? diagnostics.filter { $0.severity == .error } : diagnostics
+  }
+  var fixed = applyFixIts(to: source, diagnostics: selected(expanded.diagnostics))
+  var applied = fixed.applied
+  for _ in 1..<maxFixPasses where !fixed.applied.isEmpty {
+    let diagnostics = expander.expand(fixed.source, expanded.file, symbols).diagnostics
+    fixed = applyFixIts(to: fixed.source, diagnostics: selected(diagnostics))
+    applied += fixed.applied
+  }
+  return FixedSource(
+    source: fixed.source,
+    fixIts: applied + fixed.fixIts.filter { $0.skipReason != nil },
+    reachedPassLimit: !fixed.applied.isEmpty
+  )
+}
+
+/// Applies the Fix-Its of `diagnostics` to `source`, which is the file that they were reported for.
+///
+/// A diagnostic with more than one Fix-It is skipped, because they are alternatives. So is a Fix-It
+/// whose edits aren't in the file, or whose edits overlap the edits of a Fix-It before it. A Fix-It
+/// with the same edits as one before it, which a macro can report twice, is left out. A diagnostic
+/// without `fixItEdits`, such as a syntax error, is left out too.
+func applyFixIts(to source: String, diagnostics: [ExpansionDiagnostic]) -> FixedSource {
+  let text = Array(source.utf8)
+  var accepted: [ExpansionEdit] = []
+  var reports: [FixItReport] = []
+
+  for diagnostic in diagnostics
+  where !diagnostic.fixIts.isEmpty && diagnostic.fixItEdits.count == diagnostic.fixIts.count {
+    let report = { (message: String, reason: String?) in
+      reports.append(
+        FixItReport(line: diagnostic.line, column: diagnostic.column, message: message, skipReason: reason)
+      )
+    }
+    guard diagnostic.fixIts.count == 1, let message = diagnostic.fixIts.first, let edits = diagnostic.fixItEdits.first
+    else {
+      for message in diagnostic.fixIts {
+        report(message, "the diagnostic has \(diagnostic.fixIts.count) Fix-Its to choose from")
+      }
+      continue
+    }
+    if !edits.isEmpty && edits.allSatisfy(accepted.contains) {
+      continue
+    }
+    guard !edits.isEmpty, edits.allSatisfy({ matches($0, in: text) }) else {
+      report(message, "its edits aren't in the file")
+      continue
+    }
+    let overlaps = edits.enumerated().contains { index, edit in
+      (accepted + edits.prefix(index)).contains { overlap(edit, $0) }
+    }
+    guard !overlaps else {
+      report(message, "it overlaps another Fix-It")
+      continue
+    }
+    accepted += edits
+    report(message, nil)
+  }
+
+  var fixed = text
+  for edit in accepted.sorted(by: { $0.offset > $1.offset }) {
+    fixed.replaceSubrange(edit.offset..<(edit.offset + edit.original.utf8.count), with: Array(edit.replacement.utf8))
+  }
+  return FixedSource(source: String(decoding: fixed, as: UTF8.self), fixIts: reports)
+}
+
+/// Whether `text` has the original text of `edit` at its offset.
+private func matches(_ edit: ExpansionEdit, in text: [UInt8]) -> Bool {
+  let original = Array(edit.original.utf8)
+  return edit.offset >= 0 && edit.offset + original.count <= text.count
+    && text[edit.offset..<(edit.offset + original.count)].elementsEqual(original)
+}
+
+/// Whether two edits change the same bytes, or insert at the same offset, where their order would
+/// matter.
+private func overlap(_ a: ExpansionEdit, _ b: ExpansionEdit) -> Bool {
+  let aEnd = a.offset + a.original.utf8.count
+  let bEnd = b.offset + b.original.utf8.count
+  return a.offset == b.offset || (a.offset < bEnd && b.offset < aEnd)
+}
+
+/// The applied Fix-Its of `fixed`, one line each.
+func renderAppliedFixIts(_ fixed: FixedSource, file: String) -> String {
+  fixed.applied.map { "\(file):\($0.line):\($0.column): fix-it: \($0.message)\n" }.joined()
+}
+
+/// The warnings for the skipped Fix-Its of `fixed`, and for reaching the pass limit.
+func renderSkippedFixIts(_ fixed: FixedSource, file: String) -> String {
+  var text = ""
+  for fixIt in fixed.fixIts {
+    if let reason = fixIt.skipReason {
+      text += "\(file):\(fixIt.line):\(fixIt.column): warning: skipped fix-it '\(fixIt.message)': \(reason)\n"
+    }
+  }
+  if fixed.reachedPassLimit {
+    text += "\(file): warning: stopped after \(maxFixPasses) passes; run fix again for the Fix-Its left\n"
+  }
+  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"
+  }
+  let fixIts = "\(applied) Fix-It\(applied == 1 ? "" : "s")"
+  let fileCount = "\(files) file\(files == 1 ? "" : "s")"
+  return "\(dryRun ? "Would apply" : "Applied") \(fixIts) in \(fileCount).\n"
+}

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

@@ -207,7 +207,7 @@ struct ExportedEvent: Encodable, Equatable {
   /// The single payload parameter's type, or `nil` for a no-payload `() -> Void` event.
   var payload: TypeNode?
 
-  /// `@Event(sync: true)`, dispatching inline on the JS thread instead of scheduling.
+  /// `@Event(.sync)`, dispatching inline on the JS thread instead of scheduling.
   let isSync: Bool
 
   /// The spelled access modifier, or `nil` when none is written.

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

@@ -285,7 +285,7 @@ final class SurfaceVisitor: SyntaxVisitor {
       return []
     }
     let override = stringArgument(of: attribute)
-    let isSync = boolArgument(of: attribute, label: "sync") == true
+    let isSync = hasEventOption(attribute, named: "sync")
     var result: [ExportedEvent] = []
 
     for binding in varDecl.bindings {
@@ -704,18 +704,16 @@ private func isVoidEventReturn(_ type: TypeSyntax) -> Bool {
   return text == "Void" || text == "()" || text == "Swift.Void"
 }
 
-/// The value of a labeled boolean macro argument (`@Event(sync: true)`), or `nil` when absent.
-private func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool? {
+/// True if an `@Event` attribute lists the given option member (`@Event(.sync)` or
+/// `@Event("name", EventOptions.sync)`). Like `hasOption` in the macros, but without the array-literal
+/// branch, which `EventOptions...` doesn't accept.
+private func hasEventOption(_ attribute: AttributeSyntax, named option: String) -> Bool {
   guard let arguments = attribute.arguments?.as(LabeledExprListSyntax.self) else {
-    return nil
+    return false
   }
-  for argument in arguments where argument.label?.text == label {
-    guard let literal = argument.expression.as(BooleanLiteralExprSyntax.self) else {
-      return nil
-    }
-    return literal.literal.tokenKind == .keyword(.true)
+  return arguments.contains { argument in
+    argument.expression.as(MemberAccessExprSyntax.self)?.declName.baseName.text == option
   }
-  return nil
 }
 
 /// The name in a `@JS` attribute's `.withAsync("name")` option, in the arguments or inside an array

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

@@ -34,19 +34,19 @@ public enum Scanner {
   }
 }
 
-/// One module in the `scan-modules` output. Trimmed to what `expo-modules-autolinking` needs to
-/// register a module: the Swift class name, the JS name it registers under, the platforms that
-/// include it, and the file it's in. The richer fields the visitor captures (declaration kind, raw
-/// macro arguments, line/column) are dropped here — they're redundant for this command (the macro
-/// is always `@ExpoModule` on a class) and the deep `scan-exports` surface carries the richer
-/// per-member detail instead.
-struct ScannedModule: Codable, Equatable {
-  /// The Swift class name the module is declared as.
+/// One class in the `scan-modules` output: an `@ExpoModule` class in `modules`, or a `@SharedObject`
+/// class in `sharedObjects`. Trimmed to what `expo-modules-autolinking` needs to register the class:
+/// the Swift class name, the JS name it registers under, the platforms that include it, and the file
+/// it's in. The richer fields the visitor captures (declaration kind, raw macro arguments,
+/// line/column) are dropped here, because this command doesn't need them (the macro is always on a
+/// class) and the deep `scan-exports` surface carries the richer per-member detail instead.
+struct ScannedClass: Codable, Equatable {
+  /// The Swift class name.
   let name: String
 
-  /// The fully-resolved JS module name: the `@ExpoModule("Foo")` override when present, otherwise the
-  /// class name. Resolved here (rather than left `nil`) so it matches how the macro derives the name
-  /// and the consumer never has to apply the fallback itself.
+  /// The fully-resolved JS name: the `@ExpoModule("Foo")` or `@SharedObject("Foo")` override when
+  /// present, otherwise the class name. Resolved here (rather than left `nil`) so it matches how the
+  /// macro derives the name and the consumer never has to apply the fallback itself.
   let jsName: String
 
   /// The class's spelled access modifier (`open`, `public`, `package`, `fileprivate`, `private`),
@@ -56,20 +56,21 @@ struct ScannedModule: Codable, Equatable {
   let accessLevel: String
 
   /// The Apple OSes whose builds include this class, spelled as `os(...)` spells them and compared
-  /// case-sensitively. An unconditional module lists every OS. Empty means no build is known to
+  /// case-sensitively. An unconditional class lists every OS. Empty means no build is known to
   /// include it, because the enclosing conditions depend on flags not asserted with `--define` or
   /// on conditions a static scan cannot answer (those are reported in `warnings`). The consumer
   /// must not assume such a class exists.
   let platforms: [String]
 
-  /// Source file the module was found in, relative to the path the scanner was invoked with.
+  /// Source file the class was found in, relative to the path the scanner was invoked with.
   let file: String
 }
 
 /// Version of the `scan-modules` output shape. Bumped on any breaking change to the envelope or to
-/// `ScannedModule`, so `expo-modules-autolinking` can verify it understands the output before
+/// `ScannedClass`, so `expo-modules-autolinking` can verify it understands the output before
 /// trusting it (and fall back to config-declared modules when it doesn't). Version 2 added the
-/// per-module `platforms` list and made the module list platform-agnostic.
+/// per-module `platforms` list and made the module list platform-agnostic. A new field that older
+/// consumers can ignore, such as `sharedObjects`, doesn't change the version.
 let scanModulesSchemaVersion = 2
 
 /// The `scan-modules` result: the detected modules plus the stats describing the run. Encoded as the
@@ -77,7 +78,11 @@ let scanModulesSchemaVersion = 2
 /// serve different consumers and don't share an envelope.)
 struct ScanModulesResult: Codable, Equatable {
   let schemaVersion: Int
-  let modules: [ScannedModule]
+  let modules: [ScannedClass]
+
+  /// The top-level `@SharedObject` classes, in the same order and with the same platform rules as
+  /// `modules`.
+  let sharedObjects: [ScannedClass]
 
   /// Warnings for `#if` conditions the scan couldn't answer statically (see `ScanWarning`). Carried
   /// in the report rather than on stderr so the consumer can attach them to its own output.
@@ -97,25 +102,28 @@ private let platformUniverse: [(condition: String, reported: String)] = [
   (condition: "visionOS", reported: "visionOS"),
 ]
 
-/// Scans the given paths for top-level `@ExpoModule` types and returns every module found in any
+/// Scans the given paths for top-level `@ExpoModule` and `@SharedObject` types and returns every one
+/// found in any
 /// `#if` branch (in file then source order), each with the platforms whose builds include it, plus
 /// the stats for the run — the `scan-modules` command. Kept separate from the public entry (and
 /// `internal`) so tests can drive it without going through argv/stdout.
 ///
 /// Each file is parsed once and walked once per platform (plus once unconditionally to enumerate
-/// every module): a module's `platforms` are the OSes whose evaluated walk reached it, given the
+/// every type): a type's `platforms` are the OSes whose evaluated walk reached it, given the
 /// asserted `defines`. The scanner reports the facts; filtering to the platform being linked is the
 /// consumer's call.
 func scanModules(paths: [String], defines: Set<String> = []) -> ScanModulesResult {
-  var modules: [ScannedModule] = []
+  var modules: [ScannedClass] = []
+  var sharedObjects: [ScannedClass] = []
   var warnings: [ScanWarning] = []
   var seenWarnings = Set<ScanWarning>()
 
-  let stats = scanFiles(paths: paths, macros: [.expoModule]) { source, file in
+  let macros: Set<DetectedMacro> = [.expoModule, .sharedObject]
+  let stats = scanFiles(paths: paths, macros: macros) { source, file in
     let tree = Parser.parse(source: source)
 
-    // The unconditional walk enumerates every module in the file, in source order.
-    let allModules = DetectionVisitor(file: file, tree: tree, detectedMacros: [.expoModule], configuration: nil)
+    // The unconditional walk enumerates every type in the file, in source order.
+    let allModules = DetectionVisitor(file: file, tree: tree, detectedMacros: macros, configuration: nil)
     allModules.walk(tree)
 
     // One evaluated walk per OS attributes each module to the platforms that include it. The walks
@@ -126,7 +134,7 @@ func scanModules(paths: [String], defines: Set<String> = []) -> ScanModulesResul
       let visitor = DetectionVisitor(
         file: file,
         tree: tree,
-        detectedMacros: [.expoModule],
+        detectedMacros: macros,
         configuration: configuration
       )
       visitor.walk(tree)
@@ -140,24 +148,30 @@ func scanModules(paths: [String], defines: Set<String> = []) -> ScanModulesResul
       }
     }
 
-    for detection in allModules.detections {
-      // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` override, else
-      // the class name.
-      modules.append(
-        ScannedModule(
-          name: detection.name,
-          jsName: detection.jsName ?? detection.name,
-          accessLevel: detection.accessLevel,
-          platforms: platformsByDetection[detectionKey(detection)] ?? [],
-          file: detection.file
-        )
+    // The macros reject anything but a class, so a struct with one of them is never registered.
+    for detection in allModules.detections where detection.declarationKind == "class" {
+      // Resolve the JS name the way the macro does: explicit `@ExpoModule("Foo")` or
+      // `@SharedObject("Foo")` override, else the class name.
+      let scanned = ScannedClass(
+        name: detection.name,
+        jsName: detection.jsName ?? detection.name,
+        accessLevel: detection.accessLevel,
+        platforms: platformsByDetection[detectionKey(detection)] ?? [],
+        file: detection.file
       )
+      switch detection.macro {
+      case .sharedObject:
+        sharedObjects.append(scanned)
+      default:
+        modules.append(scanned)
+      }
     }
   }
 
   return ScanModulesResult(
     schemaVersion: scanModulesSchemaVersion,
     modules: modules,
+    sharedObjects: sharedObjects,
     warnings: warnings,
     stats: stats
   )

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

@@ -32,7 +32,7 @@ import SwiftSyntaxMacros
 /// also self-contained: `@ExpoModule`/`@SharedObject` neither collect `@Event` members nor register
 /// their names anywhere.
 ///
-/// `@Event(sync: true)` opts into **synchronous dispatch**: the closure calls `emitSync` (inline
+/// `@Event(.sync)` opts into **synchronous dispatch**: the closure calls `emitSync` (inline
 /// conversion + dispatch, no scheduling) instead of `emit`, and `@ExpoModule`/`@SharedObject` stamp
 /// the member `@JavaScriptActor` so the compiler forces the call site onto the JS thread, the
 /// inverse of the async default. The isolation is on the property access, so it guards the inline
@@ -127,7 +127,7 @@ private struct EventMember {
   let jsName: String
   /// The payload type as written, or `nil` for a no-payload `() -> Void` event.
   let payloadType: String?
-  /// Whether the event dispatches synchronously (`@Event(sync: true)`) via `emitSync`.
+  /// Whether the event dispatches synchronously (`@Event(.sync)`) via `emitSync`.
   let isSync: Bool
 
   var hasPayload: Bool {
@@ -212,7 +212,7 @@ private func validatedEvent(
     swiftName: swiftName,
     jsName: jsNameArgument(of: node) ?? defaultEventName(for: withoutBackticks(swiftName)),
     payloadType: functionType.parameters.first?.type.trimmedDescription,
-    isSync: boolArgument(of: node, label: "sync") == true
+    isSync: hasOption(node, named: "sync")
   )
 }
 

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

@@ -38,6 +38,13 @@ public struct ExpoModuleMacro: MemberMacro {
     guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
       throw MacroExpansionErrorMessage("@ExpoModule can only be applied to a class")
     }
+    diagnoseNonPublicClass(
+      classDecl,
+      macroName: "@ExpoModule",
+      reason: "register it",
+      idPrefix: "expomodule",
+      in: context
+    )
 
     // The module name is fully resolved here (the explicit `@ExpoModule("…")` argument, else the
     // class name) and emitted as a non-optional `_jsName` static below — so the
@@ -160,7 +167,7 @@ extension ExpoModuleMacro: MemberAttributeMacro {
     // checked at compile time. Skipped when the member already chose an isolation
     // (`nonisolated` or another global actor), or when `.concurrent` or `.withAsync("name")` runs
     // it on the concurrent pool. See `shouldStampJavaScriptActor`.
-    // `@Event(sync: true)` members get the stamp too: a sync event dispatches inline, so the
+    // `@Event(.sync)` members get the stamp too: a sync event dispatches inline, so the
     // isolation forces its call site onto the JS thread. Async events (the default) are
     // deliberately left unstamped — their `emit` schedules onto the JS thread itself.
     if memberHasJSAttribute(member) || isSyncEventMember(member),

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

@@ -36,6 +36,7 @@ public struct JSMacro: PeerMacro {
     diagnoseClosureTypes(in: declaration, in: context)
     diagnoseConcurrentOption(of: node, on: declaration, in: context)
     diagnoseAsyncVariantOption(of: node, on: declaration, in: context)
+    diagnoseJavaScriptValuesOffThread(of: node, on: declaration, in: context)
 
     // In an `@ExpoModule` or `@SharedObject` class, the class macro emits the assertion instead: it sees
     // the type aliases declared in the class body, which this macro can't (see `TupleTypeAliases`).
@@ -83,7 +84,7 @@ private func diagnoseConcurrentOption(
   on declaration: some DeclSyntaxProtocol,
   in context: some MacroExpansionContext
 ) {
-  guard hasJSOption(node, named: "concurrent") else {
+  guard hasOption(node, named: "concurrent") else {
     return
   }
   if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
@@ -248,6 +249,58 @@ private func insertAsyncFixIt(for funcDecl: FunctionDeclSyntax) -> FixIt {
 /// `consuming`, `sending`) are fine: the binding passes the decoded value under whichever convention
 /// the parameter asks for. The specifier is left off the decode and the assertion (see
 /// `SpecifiedType`); a parameter reported here is also left out of the assertion.
+/// The JSI types that own an engine value and release it wherever they are dropped. Such a value is
+/// valid only on the JavaScript thread. `JavaScriptPromise` releases its value on the JavaScript
+/// thread, and `JavaScriptRef` and `JavaScriptCallback` exist to carry a value across threads, so they
+/// aren't listed.
+private let javaScriptThreadBoundTypes: Set<String> = [
+  "JavaScriptValue", "JavaScriptObject", "JavaScriptFunction", "JavaScriptArray", "JavaScriptArrayBuffer",
+  "JavaScriptTypedArray", "JavaScriptBigInt", "JavaScriptWeakObject",
+]
+
+/// Emits the diagnostic for a JSI value parameter of a `@JS(.concurrent)` function or of the variant
+/// that `@JS(.withAsync("name"))` adds. Both run the body on the concurrent thread pool, never on the
+/// JavaScript thread, so the body can't use the value, and the value is released off the JavaScript
+/// thread too.
+private func diagnoseJavaScriptValuesOffThread(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  guard let funcDecl = declaration.as(FunctionDeclSyntax.self) else {
+    return
+  }
+  let option: String
+  let reason: String
+  if hasOption(node, named: "concurrent") {
+    option = ".concurrent"
+    reason = "'.concurrent' runs the body on the concurrent thread pool"
+  } else if asyncVariantOption(of: node) != nil {
+    option = ".withAsync"
+    reason = "the variant that '.withAsync' adds runs the function on the concurrent thread pool"
+  } else {
+    return
+  }
+  for parameter in funcDecl.signature.parameterClause.parameters {
+    let type = SpecifiedType(parameter.type).type
+    guard let name = baseIdentifier(of: optionalWrappedType(type) ?? type), javaScriptThreadBoundTypes.contains(name)
+    else {
+      continue
+    }
+    let parameterName = (parameter.secondName ?? parameter.firstName).text
+    context.diagnose(
+      Diagnostic(
+        node: parameter.type,
+        message: JSDiagnosticMessage(
+          "'\(parameterName)' can't be a '\(name)' in a '\(option)' function: \(reason), and a JavaScript value is valid only on the JavaScript thread. Take a native type that the value decodes to, such as a @Record or [String: Any], or remove '\(option)'.",
+          id: "js-javascript-value-off-thread",
+          severity: .error
+        )
+      )
+    )
+  }
+}
+
 private func diagnoseParameterSpecifiers(
   in declaration: some DeclSyntaxProtocol,
   in context: some MacroExpansionContext

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

@@ -8,7 +8,7 @@ import SwiftSyntaxMacros
 /// is emitted as a `_jsName` override.
 ///
 ///   @SharedObject
-///   final class Cache: SharedObject {
+///   public final class Cache: SharedObject {
 ///     @JS
 ///     init(name: String) { self.name = name }
 ///
@@ -34,6 +34,13 @@ public struct SharedObjectMacro: MemberMacro {
     guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
       throw MacroExpansionErrorMessage("@SharedObject can only be applied to a class")
     }
+    diagnoseNonPublicClass(
+      classDecl,
+      macroName: "@SharedObject",
+      reason: "export it",
+      idPrefix: "sharedobject",
+      in: context
+    )
 
     // 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
@@ -164,7 +171,7 @@ extension SharedObjectMacro: MemberAttributeMacro {
     providingAttributesFor member: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [AttributeSyntax] {
-    // `@Event(sync: true)` members are stamped alongside `@JS` ones: a sync event dispatches
+    // `@Event(.sync)` members are stamped alongside `@JS` ones: a sync event dispatches
     // inline, so the isolation forces its call site onto the JS thread. Async events (the
     // default) stay unstamped — their `emit` schedules onto the JS thread itself.
     guard memberHasJSAttribute(member) || isSyncEventMember(member) else {

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

@@ -139,23 +139,37 @@ private func fieldAttributeDiagnostic(
   for attribute: AttributeSyntax,
   on varDecl: VariableDeclSyntax
 ) -> Diagnostic {
-  // Rebuild the attribute list without this entry, so the fix-it removes the attribute and the
-  // trivia it carried rather than leaving a blank line behind.
-  var attributes = varDecl.attributes
-  if let index = attributes.firstIndex(where: { element in
+  // The token after the attribute takes over the trivia of the attribute: the line break,
+  // indentation and comments before it, and the comments after it. Its own leading whitespace is
+  // left out unless a comment comes before it, so `@Field var size` and `@Field` on its own line both
+  // become `var size` on the line of the attribute, and `@Field // note` keeps the line break after
+  // the comment.
+  var newDecl = varDecl
+  if let next = attribute.lastToken(viewMode: .sourceAccurate)?.nextToken(viewMode: .sourceAccurate) {
+    let comments = Trivia(pieces: attribute.trailingTrivia.pieces.drop(while: \.isWhitespace))
+    let nextTrivia =
+      comments.isEmpty ? Trivia(pieces: next.leadingTrivia.pieces.drop(while: \.isWhitespace)) : next.leadingTrivia
+    newDecl =
+      LeadingTriviaRewriter(token: next.id, trivia: attribute.leadingTrivia + comments + nextTrivia)
+      .rewrite(varDecl).cast(VariableDeclSyntax.self)
+  }
+  // Then remove the attribute with its trivia, so it doesn't leave a blank line behind. The rewritten
+  // declaration is a new tree, so the attribute is found by its place in the list.
+  if let index = varDecl.attributes.firstIndex(where: { element in
     guard case .attribute(let candidate) = element else {
       return false
     }
     return candidate == attribute
   }) {
-    attributes.remove(at: index)
+    let offset = varDecl.attributes.distance(from: varDecl.attributes.startIndex, to: index)
+    newDecl.attributes.remove(at: newDecl.attributes.index(newDecl.attributes.startIndex, offsetBy: offset))
   }
   let fixIt = FixIt(
     message: ViewPropsFixItMessage("Remove the '@Field' attribute", id: "viewprops-remove-field"),
     changes: [
       .replace(
         oldNode: Syntax(varDecl),
-        newNode: Syntax(varDecl.with(\.attributes, attributes))
+        newNode: Syntax(newDecl)
       )
     ]
   )
@@ -166,6 +180,22 @@ private func fieldAttributeDiagnostic(
   return Diagnostic(node: attribute, message: message, fixIts: [fixIt])
 }
 
+/// Replaces the leading trivia of one token.
+private final class LeadingTriviaRewriter: SyntaxRewriter {
+  private let token: SyntaxIdentifier
+  private let trivia: Trivia
+
+  init(token: SyntaxIdentifier, trivia: Trivia) {
+    self.token = token
+    self.trivia = trivia
+    super.init(viewMode: .sourceAccurate)
+  }
+
+  override func visit(_ token: TokenSyntax) -> TokenSyntax {
+    token.id == self.token ? token.with(\.leadingTrivia, trivia) : token
+  }
+}
+
 /// The error for an optional event prop, attached to the declared type and carrying a fix-it that
 /// unwraps it. Events are registered once at view creation from a static name list, so there is no
 /// shape that could express "sometimes emitted".