@expo/expo-modules-macros-plugin 0.2.1 → 0.3.0

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -0,0 +1,390 @@
+import SwiftSyntax
+
+/**
+ A `@JS func` collected for **direct JSI binding**. Instead of describing the function with a
+ `Function(...)` / `AsyncFunction(...)` DSL entry that the runtime interprets per call,
+ `@ExpoModule` synthesizes a `_decorateModule` that binds each such function into the module's JS object
+ via the closure-taking `JavaScriptObject.setProperty(_:)`, with the decode-call-encode body
+ inlined into the closure. This omits the `[Any]`/`toTuple` dynamic-call path: every argument is
+ decoded individually by its static type.
+
+ The receiver is the module's real `self` (a module is a singleton instance), so the body calls
+ `self.<name>(...)` directly and ignores the JS `this`. An `async` `@JS func` produces an `async`
+ closure body and is installed through the async `setProperty(_:)` overload (so JS gets a promise).
+ */
+internal struct JSFunction {
+  let swiftName: String
+  let jsName: String
+  let parameters: [FunctionParameterSyntax]
+  /// The declared return type as written, or `nil` when the function returns `Void`/nothing.
+  let returnType: String?
+  let isThrowing: Bool
+  let isAsync: Bool
+
+  init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
+    self.swiftName = funcDecl.name.text
+    self.jsName = jsNameArgument(of: attribute) ?? funcDecl.name.text
+    self.parameters = Array(funcDecl.signature.parameterClause.parameters)
+
+    let declaredReturnType = funcDecl.signature.returnClause?.type
+    self.returnType = isVoidType(declaredReturnType) ? nil : declaredReturnType?.trimmedDescription
+
+    let effectSpecifiers = funcDecl.signature.effectSpecifiers
+    self.isThrowing = effectSpecifiers?.throwsClause?.throwsSpecifier != nil
+    self.isAsync = effectSpecifiers?.asyncSpecifier != nil
+  }
+
+  /// The number of leading parameters that must always be supplied: the total minus the maximal
+  /// trailing run of *omittable* parameters (each having a default value or an optional type). A
+  /// non-omittable parameter part-way through stops the run, since arguments are positional — a
+  /// required parameter after an omittable one forces the earlier one to be supplied too.
+  private var requiredArgumentCount: Int {
+    var required = parameters.count
+    for parameter in parameters.reversed() {
+      guard isOmittable(parameter) else {
+        break
+      }
+      required -= 1
+    }
+    return required
+  }
+
+  /// The decode-call-encode statements that form the host-function body, indented with the given
+  /// prefix. An arity guard (an exact check when every parameter is required, otherwise a range
+  /// check) throwing `Exceptions.ArgumentsRangeMismatch`; then the decode of the always-present
+  /// required prefix (primitives via a direct typed accessor like `asDouble()` on a zero-copy
+  /// `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`); then the call and
+  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`). When a
+  /// trailing run of parameters is omittable the call branches on `arguments.count`, decoding only
+  /// the slots that branch actually has — `arguments[i]` traps past `count`, so a slot the caller
+  /// didn't pass is never indexed.
+  private func bodyStatements(indent: String) -> String {
+    let required = requiredArgumentCount
+    let maximum = parameters.count
+    var lines: [String] = []
+
+    if required == maximum {
+      lines.append(
+        """
+        guard arguments.count == \(maximum) else {
+          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+        }
+        """)
+    } else {
+      lines.append(
+        """
+        guard arguments.count >= \(required) && arguments.count <= \(maximum) else {
+          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+        }
+        """)
+    }
+
+    // Decode the required prefix once — these slots are present in every accepted arity, so the
+    // decode is shared rather than repeated per branch.
+    for index in 0..<required {
+      lines.append(decodeStatement(at: index))
+    }
+
+    if required == maximum {
+      // No omittable trailing run: a single flat call with every argument decoded.
+      lines.append(contentsOf: callAndEncodeLines(arity: maximum, decodingFrom: required))
+    } else {
+      // One call shape per accepted arity. Each branch decodes only the trailing slots it has and
+      // fills the rest (defaulted params drop their label so Swift applies the default; optional
+      // params are passed `nil`). A value-returning function binds the result from a `switch`
+      // expression and encodes once after it; a no-return one calls inline in a `switch` statement
+      // and returns `.undefined`.
+      if returnType != nil {
+        lines.append("let result = switch arguments.count {")
+      } else {
+        lines.append("switch arguments.count {")
+      }
+      for arity in required...maximum {
+        let label = arity == maximum ? "default:" : "case \(arity):"
+        lines.append(label)
+        for index in required..<arity {
+          lines.append("  " + decodeStatement(at: index))
+        }
+        lines.append("  \(callExpression(arity: arity))")
+      }
+      lines.append("}")
+      lines.append(contentsOf: encodeResultLines())
+    }
+
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { indent + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// `let arg<index> = …` decoding the slot at `index` by its static type: a primitive through a
+  /// direct typed accessor on a borrowed `JavaScriptUnownedValue` (no owning value, no `jsi::Value`
+  /// copy, no `getDynamicType()` allocation, no `Any` boxing, no force-cast — still validating and
+  /// throwing `TypeError` on a mismatch), any other type through the dynamic converter (which needs
+  /// an owning value, so it indexes the buffer directly).
+  private func decodeStatement(at index: Int) -> String {
+    let type = parameters[index].type.trimmedDescription
+    if let accessor = fastDecodeAccessor(for: type) {
+      return "let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()"
+    }
+    return "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)"
+  }
+
+  /// The `self.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
+  /// `arg<i>`; a trailing optional-without-default slot that this arity omits is passed `nil`; a
+  /// trailing defaulted slot that this arity omits is dropped entirely so Swift applies its default.
+  private func callExpression(arity: Int) -> String {
+    var callArguments: [String] = []
+    for (index, parameter) in parameters.enumerated() {
+      let label = parameter.firstName.text
+      let value: String?
+      if index < arity {
+        value = "arg\(index)"
+      } else if hasDefaultValue(parameter) {
+        // Omitted defaulted slot: drop it from the call so Swift fills in the default.
+        value = nil
+      } else {
+        // Omitted optional-without-default slot: pass `nil`.
+        value = "nil"
+      }
+      guard let value else {
+        continue
+      }
+      callArguments.append(label == "_" ? value : "\(label): \(value)")
+    }
+    let tryKeyword = (isThrowing || isAsync) ? "try " : ""
+    let awaitKeyword = isAsync ? "await " : ""
+    return "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
+  }
+
+  /// The flat (single-arity) call-and-encode lines used when no trailing parameter is omittable:
+  /// `let result = self.f(...)` then the return encode (or the no-return `self.f(...)` + `.undefined`).
+  private func callAndEncodeLines(arity: Int, decodingFrom: Int) -> [String] {
+    var lines: [String] = []
+    for index in decodingFrom..<arity {
+      lines.append(decodeStatement(at: index))
+    }
+    if returnType != nil {
+      lines.append("let result = \(callExpression(arity: arity))")
+      lines.append(contentsOf: encodeResultLines())
+    } else {
+      lines.append(callExpression(arity: arity))
+      lines.append("return .undefined")
+    }
+    return lines
+  }
+
+  /// Encode the `result` local back to JS and return it: a primitive through `toJavaScriptValue(in:)`
+  /// (the typed `JavaScriptRepresentable` conversion — no `Any`, no dynamic-type allocation), any
+  /// other type through the dynamic converter. A no-return function returns `.undefined` instead.
+  private func encodeResultLines() -> [String] {
+    guard let returnType else {
+      return ["return .undefined"]
+    }
+    if fastDecodeAccessor(for: returnType) != nil {
+      return ["return result.toJavaScriptValue(in: runtime)"]
+    }
+    return ["return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)"]
+  }
+
+  /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
+  /// body is inlined directly into the closure passed to the closure-taking `setProperty` overload
+  /// (which creates the host function under the hood) — no separate named binding. For an `async`
+  /// function the body `await`s the call, which selects the async `setProperty` overload (so JS
+  /// receives a promise).
+  ///
+  /// Capture mirrors core's `SyncFunctionDefinition.build`: `self` (the module) is captured
+  /// **strong** — the host-function closure is what keeps the native callable alive for as long as
+  /// JS can invoke it; its lifetime is bounded by the JS VM's garbage collection of the object.
+  /// `appContext` is captured **weak** (and guarded) so it doesn't form a real retain cycle through
+  /// the app context. When no argument or return value goes through the dynamic-type converter the
+  /// body never references `appContext`, so the capture and guard are omitted to avoid the
+  /// unused-capture warning.
+  var decorateStatements: String {
+    if usesAppContext {
+      return """
+          object.setProperty("\(jsName)") { [weak appContext, self] this, arguments in
+            guard let appContext else {
+              throw Exceptions.AppContextLost()
+            }
+        \(bodyStatements(indent: "    "))
+          }
+        """
+    }
+    return """
+        object.setProperty("\(jsName)") { [self] this, arguments in
+      \(bodyStatements(indent: "    "))
+        }
+      """
+  }
+
+  /// True when the host-function body references `appContext` — i.e. some parameter or the return
+  /// type lacks a fast accessor and decodes/encodes through `getDynamicType()`, which threads
+  /// `appContext` in.
+  private var usesAppContext: Bool {
+    if parameters.contains(where: { fastDecodeAccessor(for: $0.type.trimmedDescription) == nil }) {
+      return true
+    }
+    if let returnType, fastDecodeAccessor(for: returnType) == nil {
+      return true
+    }
+    return false
+  }
+}
+
+/// A `@JS var` collected for **direct JSI binding**. Instead of describing the property with a
+/// `Property(...)` DSL entry, `@ExpoModule` synthesizes a get/set accessor into the module's JS
+/// object inside `_decorateModule`: it builds a descriptor object (`enumerable` + `get`, and `set`
+/// when the property is settable) and installs it with `object.defineProperty(name, descriptor:)`,
+/// mirroring core's `PropertyDefinition.buildDescriptor`. The `get`/`set` host functions are
+/// installed the same way `@JS func`s are — the closure-taking `setProperty(_:)` overload, with the
+/// read/write body inlined into the closure.
+///
+/// The receiver is the module's real `self`, so the getter reads `self.<name>` and the setter writes
+/// `self.<name> = …` directly, ignoring the JS `this`. Decode/encode of the value reuse the same
+/// static-type fast path as functions (primitives through a direct typed accessor / `toJavaScriptValue`,
+/// other types through the `getDynamicType()` converter).
+internal struct JSProperty {
+  let swiftName: String
+  let jsName: String
+  /// The property's value type as written, or `nil` when it couldn't be inferred (no annotation and
+  /// no literal default). When `nil` the getter still works (the encode infers from `self.<name>`)
+  /// but the setter uses an untyped closure parameter.
+  let valueType: String?
+  /// Whether the property is settable from JS: `true` for a stored `var` or a computed `var` with an
+  /// explicit `set` accessor; `false` for a getter-only computed `var` or a `let`.
+  let isSettable: Bool
+
+  /// The statements that install this property's accessor on the JS object, indented for the
+  /// `_decorateModule` body. Builds a descriptor object (`enumerable` + `get`, and `set` when
+  /// settable) via the closure-taking `setProperty(_:)` overload — with the read/write body inlined
+  /// into each closure — and installs it with `object.defineProperty(name, descriptor:)`. Capture
+  /// matches the function bindings: `self` strong, `appContext` weak + guarded — and, like functions,
+  /// the `appContext` capture + guard are omitted from an accessor whose body never references it (a
+  /// primitive value, decoded/encoded without the dynamic converter), to avoid the unused-capture
+  /// warning. Getter and setter are gated independently.
+  var decorateStatements: String {
+    let descriptorName = "\(swiftName)Descriptor"
+    // A primitive value type encodes/decodes without `getDynamicType()`, so its accessor body never
+    // references `appContext`. `nil` (untyped) goes through the dynamic-less `toJavaScriptValue`
+    // getter, which also doesn't use it.
+    let usesAppContext = valueType.map { fastDecodeAccessor(for: $0) == nil } ?? false
+    var lines: [String] = []
+
+    lines.append("let \(descriptorName) = runtime.createObject()")
+    lines.append("\(descriptorName).setProperty(\"enumerable\", value: true)")
+
+    // Getter: read `self.<name>` and encode the result back to JS.
+    let getEncode: String
+    if let valueType, fastDecodeAccessor(for: valueType) != nil {
+      getEncode = "return self.\(swiftName).toJavaScriptValue(in: runtime)"
+    } else if let valueType {
+      getEncode =
+        "return try \(valueType).getDynamicType().castToJS(self.\(swiftName), appContext: appContext, in: runtime)"
+    } else {
+      // No known type: fall back to converting whatever `self.<name>` is. This only happens when the
+      // declaration has neither an annotation nor a literal default, which is rare for a stored var.
+      getEncode = "return self.\(swiftName).toJavaScriptValue(in: runtime)"
+    }
+    lines.append(accessorClosure(descriptorName, "get", usesAppContext: usesAppContext, body: getEncode))
+
+    // Setter: decode argument 0 by the static type and write `self.<name>`. A typed setter needs a
+    // known value type; when the type couldn't be inferred the property is bound getter-only (a
+    // settable var with neither an annotation nor a literal default is rare and can't be decoded).
+    if isSettable, let valueType {
+      let setDecode: String
+      if let accessor = fastDecodeAccessor(for: valueType) {
+        setDecode = "self.\(swiftName) = try arguments.unownedValue(at: 0).\(accessor)()"
+      } else {
+        setDecode =
+          "self.\(swiftName) = try \(valueType).getDynamicType().cast(jsValue: arguments[0], appContext: appContext) as! \(valueType)"
+      }
+      lines.append(
+        accessorClosure(descriptorName, "set", usesAppContext: usesAppContext, body: "\(setDecode)\nreturn .undefined"))
+    }
+
+    lines.append("object.defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
+
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { "  " + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// One `descriptor.setProperty("get"/"set") { … }` accessor entry. Captures `self` strong and, when
+  /// `usesAppContext`, `appContext` weak + guarded (matching the function bindings); otherwise the
+  /// capture and guard are omitted so a primitive accessor doesn't warn on an unused capture.
+  private func accessorClosure(
+    _ descriptorName: String, _ key: String, usesAppContext: Bool, body: String
+  ) -> String {
+    // Indent each line of a (possibly multi-line) body to sit one level inside the closure, aligned
+    // with the `guard`; a bare `\(body)` interpolation would only indent the first line.
+    let indentedBody = body
+      .split(separator: "\n", omittingEmptySubsequences: false)
+      .map { "  \($0)" }
+      .joined(separator: "\n")
+    if usesAppContext {
+      return """
+        \(descriptorName).setProperty("\(key)") { [weak appContext, self] this, arguments in
+          guard let appContext else {
+            throw Exceptions.AppContextLost()
+          }
+        \(indentedBody)
+        }
+        """
+    }
+    return """
+      \(descriptorName).setProperty("\(key)") { [self] this, arguments in
+      \(indentedBody)
+      }
+      """
+  }
+}
+
+/// The single generated function that decorates the module's JS object. Core supplies the object;
+/// this binds every `@JS func` (via an inlined `setProperty` closure) and every `@JS var` (via a
+/// `defineProperty` accessor) into it. Mirrors core's `ObjectDefinition.decorate(object:)`, including
+/// its `borrowing` object parameter (it mutates through the reference without reassigning or taking
+/// ownership). Named `_decorateModule` with the leading-underscore convention for synthesized members
+/// the **runtime calls by name**; the `ExpoModule` suffix names the `@ExpoModule` macro it came from (a
+/// shared object's counterpart is `_decorateSharedObject`).
+internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties: [JSProperty]) -> DeclSyntax {
+  let functionBody = functions.map { $0.decorateStatements }
+  let propertyBody = properties.map { $0.decorateStatements }
+  let body = (functionBody + propertyBody).joined(separator: "\n")
+  return """
+    @JavaScriptActor
+    public func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws {
+    \(raw: body)
+    }
+    """
+}
+
+/// The throwing `JavaScriptUnownedValue` accessor that decodes the given primitive type directly,
+/// bypassing the dynamic-type converter (`asDouble()` for `Double`, etc.). Returns `nil` for
+/// types without a dedicated accessor — arrays, records, optionals, shared objects, other numeric
+/// widths — which decode through `getDynamicType().cast(...)`.
+private func fastDecodeAccessor(for type: String) -> String? {
+  switch type {
+  case "Bool":
+    return "asBool"
+  case "Int":
+    return "asInt"
+  case "Double":
+    return "asDouble"
+  case "String":
+    return "asString"
+  default:
+    return nil
+  }
+}
+
+/// True when a return clause is absent or written as `Void` / `()` — i.e. the function returns
+/// nothing JS-visible, so the binding returns `.undefined`.
+private func isVoidType(_ type: TypeSyntax?) -> Bool {
+  guard let type else {
+    return true
+  }
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()"
+}

package/apple/Sources/ExpoModulesMacros/EventMacro.swift

@@ -0,0 +1,330 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+/// Accessor macro applied to a function-typed `var` on a module or shared object, turning it into a
+/// typed JavaScript event. A function-typed `var` can't be a stored property without an initializer,
+/// so the macro expands it into a computed getter returning a closure that dispatches by name into
+/// the `EventEmitter` `emit` overloads (core conforms both `BaseModule` and `SharedObject` to that
+/// protocol, so `self.emit` resolves on each):
+///
+///   @Event
+///   var onProgress: (ProgressEvent) -> Void
+///   // expands to:
+///   var onProgress: (ProgressEvent) -> Void {
+///     get {
+///       { [weak self] payload in self?.emit(event: "progress", payload: payload) }
+///     }
+///   }
+///
+/// A no-payload event (`() -> Void`) dispatches through the dedicated `emit(event:)` overload.
+/// The JS event name defaults to the property name with the conventional `on` prefix stripped
+/// (see `defaultEventName(for:)`); `@Event("customName")` overrides it verbatim.
+///
+/// The closure captures `self` **weakly**: it's usually invoked inline (`self.onProgress(…)`), but an
+/// author may store it or hand it to a delegate, and a strong capture would then extend the module's
+/// lifetime. After the emitter deallocates the closure silently no-ops, which matches what `emit`
+/// already does once the runtime is gone.
+///
+/// The synthesized property is deliberately **not** isolated to `@JavaScriptActor`, unlike `@JS`
+/// members: `emit` is itself non-isolated and schedules the dispatch onto the JS thread internally,
+/// so the event is callable from any thread or isolation with no actor hop at the call site. It is
+/// 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
+/// 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
+/// `self.onTick(…)` usage; a closure stored or handed off escapes it, after which `emitSync` runs
+/// wherever the caller invokes it.
+///
+/// As a **peer**, the macro emits a never-called conformance assertion (see
+/// `TypeConformanceAssertion.swift`) checking that the payload type is JS-convertible and that the
+/// enclosing type conforms to `EventEmitter`, so both failure modes surface as clear conformance
+/// errors on the user's own declaration.
+public struct EventMacro: AccessorMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingAccessorsOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [AccessorDeclSyntax] {
+    let event = try validatedEvent(of: node, on: declaration)
+    // The closure's parameter and return types are inferred from the property's declared type
+    // through the getter, so the body never has to spell the payload type. A sync event calls
+    // `emitSync` (inline dispatch, JS thread only); the default calls the scheduling `emit`.
+    let emitMethod = event.isSync ? "emitSync" : "emit"
+    let closure = event.hasPayload
+      ? "{ [weak self] payload in self?.\(emitMethod)(event: \"\(event.jsName)\", payload: payload) }"
+      : "{ [weak self] in self?.\(emitMethod)(event: \"\(event.jsName)\") }"
+    return [
+      """
+      get {
+        \(raw: closure)
+      }
+      """
+    ]
+  }
+}
+
+extension EventMacro: PeerMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingPeersOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    // Diagnostics are owned by the accessor expansion; an invalid declaration silently emits no
+    // peer here so each error is reported once.
+    guard let event = try? validatedEvent(of: node, on: declaration) else {
+      return []
+    }
+    // One nested helper asserts everything in a single call: the payload type is JS-convertible
+    // (the `P` parameter, dropped for no-payload events and known-conforming primitives) and the
+    // enclosing type can emit (the `E` parameter, always present since any `@Event` dispatches
+    // through `self.emit`). Named after the member so the member shows up in either diagnostic,
+    // and asserting the enclosing type by its spelled name so the conformance error names the
+    // user's type rather than 'Self'.
+    let name = event.swiftName
+    let payload = event.payloadType.flatMap(assertableBoundaryType)
+    let owner = enclosingTypeName(in: context) ?? "Self"
+    let helper = payload != nil
+      ? "func \(name)<P: \(jsConvertibleProtocolName), E: \(eventEmitterProtocolName)>(_: P.Type, _: E.Type) {}"
+      : "func \(name)<E: \(eventEmitterProtocolName)>(_: E.Type) {}"
+    let call = payload.map { "\(name)(\($0).self, \(owner).self)" } ?? "\(name)(\(owner).self)"
+    return [
+      """
+      private func _assertTypesConformance_\(raw: name)() {
+      \(raw: helper)
+      \(raw: call)
+      }
+      """
+    ]
+  }
+}
+
+/// What the expansions need to know about a validated `@Event` declaration: the property name, the
+/// JS event name (after an `@Event("…")` override), and the payload type when the function type
+/// takes one.
+private struct EventMember {
+  let swiftName: String
+  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`.
+  let isSync: Bool
+
+  var hasPayload: Bool {
+    return payloadType != nil
+  }
+}
+
+/// Validates the declaration `@Event` is attached to and reads the event out of it. The checks
+/// mirror what the expansion relies on: a single-binding instance `var` (the macro synthesizes a
+/// computed getter, so `let`, accessors, and initializers are all incompatible) whose type is a
+/// function type returning `Void` with at most one payload parameter.
+private func validatedEvent(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol
+) throws -> EventMember {
+  guard let varDecl = declaration.as(VariableDeclSyntax.self) else {
+    throw MacroExpansionErrorMessage("@Event can only be applied to a property")
+  }
+  if varDecl.attributes.firstAttribute(named: "JS") != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event and @JS cannot be combined on the same property; an event is exposed to JS on its own, so remove one of the attributes")
+  }
+  // The compiler also rejects accessor macros on a `let`, but with a generic message; this one says
+  // what to do instead and carries the fix-it doing it. The synthesized property is getter-only, so
+  // switching to `var` loses nothing.
+  if varDecl.bindingSpecifier.tokenKind == .keyword(.let) {
+    throw letBindingDiagnostic(for: varDecl)
+  }
+  if varDecl.modifiers.contains(where: isTypeLevelModifier) {
+    throw MacroExpansionErrorMessage(
+      "@Event must be an instance property; events are emitted from a module or shared object instance.")
+  }
+  guard varDecl.bindings.count == 1, let binding = varDecl.bindings.first,
+    let identifier = binding.pattern.as(IdentifierPatternSyntax.self) else {
+    throw MacroExpansionErrorMessage(
+      "@Event must be applied to a single named property; declare each event separately")
+  }
+  if binding.initializer != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event property cannot have an initial value; the macro synthesizes the closure")
+  }
+  if binding.accessorBlock != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event property cannot declare its own accessors; the macro synthesizes the getter")
+  }
+  guard let functionType = underlyingFunctionType(of: binding.typeAnnotation?.type) else {
+    throw MacroExpansionErrorMessage(
+      "@Event property must declare a function type, such as '(Payload) -> Void' or '() -> Void'")
+  }
+  guard isVoidReturn(functionType.returnClause.type) else {
+    throw MacroExpansionErrorMessage(
+      "@Event function type must return 'Void'; an event dispatches to JS and has no return value")
+  }
+  guard functionType.parameters.count <= 1 else {
+    throw MacroExpansionErrorMessage(
+      "@Event function type takes at most one payload parameter; combine multiple values into a single record")
+  }
+
+  let swiftName = identifier.identifier.text
+  return EventMember(
+    swiftName: swiftName,
+    jsName: jsNameArgument(of: node) ?? defaultEventName(for: swiftName),
+    payloadType: functionType.parameters.first?.type.trimmedDescription,
+    isSync: boolArgument(of: node, label: "sync") == true
+  )
+}
+
+// MARK: - Default event name
+
+/// The default JS event name for a property: the Swift name with the conventional `on` prefix
+/// stripped and the remainder decapitalized (`onStatusChange` → `statusChange`). The two sides
+/// idiomatically want different names: the Swift property reads as invoking a handler
+/// (`self.onStatusChange(…)`) and the prefix keeps it from colliding with a state property
+/// (`status`), while JS listens by bare name (`addListener("statusChange")`, the Node/DOM idiom
+/// that module and shared-object events follow). Names without the prefix (`statusChange`,
+/// `online`) pass through verbatim, and an explicit `@Event("name")` override is never
+/// transformed — that's also the escape hatch for legacy `onX` wire names.
+private func defaultEventName(for swiftName: String) -> String {
+  guard swiftName.hasPrefix("on") else {
+    return swiftName
+  }
+  let rest = swiftName.dropFirst(2)
+  guard let first = rest.first, first.isUppercase else {
+    return swiftName
+  }
+  return decapitalized(String(rest))
+}
+
+/// Lowercases the leading uppercase run the way Swift's API importer does: a single leading
+/// capital is lowercased (`StatusChange` → `statusChange`); a longer acronym run keeps its last
+/// capital when a lowercase letter follows it, since that capital starts the next word
+/// (`URLChange` → `urlChange`, `URL` → `url`).
+private func decapitalized(_ name: String) -> String {
+  let runEnd = name.firstIndex { !$0.isUppercase } ?? name.endIndex
+  if name[..<runEnd].count > 1 && runEnd != name.endIndex {
+    let lastCapital = name.index(before: runEnd)
+    return name[..<lastCapital].lowercased() + name[lastCapital...]
+  }
+  return name[..<runEnd].lowercased() + name[runEnd...]
+}
+
+// MARK: - The `let` diagnostic
+
+/// The error for `@Event let`, attached to the `let` keyword itself and carrying a fix-it that
+/// replaces it with `var`. Unlike the other checks (plain thrown messages located at the attribute),
+/// this one is a structured `Diagnostic` so Xcode can offer the one-click fix.
+private func letBindingDiagnostic(for varDecl: VariableDeclSyntax) -> DiagnosticsError {
+  let specifier = varDecl.bindingSpecifier
+  let fixIt = FixIt(
+    message: EventFixItMessage("Replace 'let' with 'var'", id: "event-let-to-var"),
+    changes: [
+      // Rewriting just the token's kind keeps its surrounding trivia (indentation, the space
+      // before the property name) intact.
+      .replace(
+        oldNode: Syntax(specifier),
+        newNode: Syntax(specifier.with(\.tokenKind, .keyword(.var)))
+      )
+    ]
+  )
+  let message = EventDiagnosticMessage(
+    "@Event must be applied to a 'var': it expands into a computed property, which a 'let' cannot be. The synthesized property is read-only anyway.",
+    id: "event-on-let"
+  )
+  return DiagnosticsError(diagnostics: [
+    Diagnostic(node: specifier, message: message, fixIts: [fixIt])
+  ])
+}
+
+private struct EventDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+private struct EventFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+// MARK: - Declaration shape helpers
+
+/// The spelled name of the innermost type declaration enclosing the macro, read from the lexical
+/// context, so the emitter assertion can name the user's type in the conformance diagnostic
+/// ("requires that 'MyModule' conform to 'EventEmitter'" instead of "'Self'"). Returns `nil` (the
+/// caller falls back to `Self`) when there's no enclosing type, or when it's a generic type
+/// declaration: `Foo.self` isn't valid for an unbound generic, while `Self` works anywhere. An
+/// extension can't be detected as generic syntactically (see the extension case below).
+private func enclosingTypeName(in context: some MacroExpansionContext) -> String? {
+  for scope in context.lexicalContext {
+    if let classDecl = scope.as(ClassDeclSyntax.self) {
+      return classDecl.genericParameterClause == nil ? classDecl.name.text : nil
+    }
+    if let structDecl = scope.as(StructDeclSyntax.self) {
+      return structDecl.genericParameterClause == nil ? structDecl.name.text : nil
+    }
+    if let actorDecl = scope.as(ActorDeclSyntax.self) {
+      return actorDecl.genericParameterClause == nil ? actorDecl.name.text : nil
+    }
+    if let extensionDecl = scope.as(ExtensionDeclSyntax.self) {
+      // An extension carries no generic-parameter clause of its own, so a bare extended type
+      // (`extension Box`) is indistinguishable from a non-generic one (`extension Foo`); both read
+      // as a plain identifier here. A written bound form (`extension Box<Int>`) is valid as `.self`,
+      // and the common non-generic case keeps its spelled name in the diagnostic. The unguarded gap
+      // is `extension <Generic>` with the parameters omitted, where the spelled name is an unbound
+      // generic invalid as `.self`; events on generic types in an extension are rare enough that the
+      // resulting compile error is an acceptable price for naming the user's type everywhere else.
+      return extensionDecl.extendedType.trimmedDescription
+    }
+  }
+  return nil
+}
+
+private func isTypeLevelModifier(_ modifier: DeclModifierSyntax) -> Bool {
+  return modifier.name.tokenKind == .keyword(.static) || modifier.name.tokenKind == .keyword(.class)
+}
+
+/// The function type underlying a property's type annotation, unwrapping attributes
+/// (`@Sendable (P) -> Void`) and single-element parentheses (`((P) -> Void)`). Returns `nil` when
+/// the annotation is missing or isn't a function type, including an optional function type:
+/// an event is always present, never `nil`.
+private func underlyingFunctionType(of type: TypeSyntax?) -> FunctionTypeSyntax? {
+  guard let type else {
+    return nil
+  }
+  if let attributed = type.as(AttributedTypeSyntax.self) {
+    return underlyingFunctionType(of: attributed.baseType)
+  }
+  if let tuple = type.as(TupleTypeSyntax.self),
+    tuple.elements.count == 1, let element = tuple.elements.first, element.firstName == nil {
+    return underlyingFunctionType(of: element.type)
+  }
+  return type.as(FunctionTypeSyntax.self)
+}
+
+/// True when the function type's return is written as `Void` / `()`. Function types always carry an
+/// explicit return clause, so unlike a function declaration there's no "absent" case. A module-qualified
+/// `Swift.Void` and redundant parentheses (`(Void)`, `(())`) are accepted too, so a valid void return
+/// written one of those ways isn't rejected with a misleading "must return 'Void'" diagnostic.
+private func isVoidReturn(_ type: TypeSyntax) -> Bool {
+  // Peel single-element, unlabeled parentheses: `(Void)` and `(())` are the same type as their content.
+  if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
+    let element = tuple.elements.first, element.firstName == nil {
+    return isVoidReturn(element.type)
+  }
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()" || text == "Swift.Void"
+}

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -6,11 +6,13 @@ import SwiftSyntaxMacros
  Macro applied to a module class. It plays three roles, each implemented in its own
  extension below:
 
- - `MemberMacro`: scans the class body for `@JS`-marked declarations and synthesizes a
-   framework-internal `_synthesizedDefinition()` returning `[AnyDefinition]`, which
-   `expo-modules-core` calls automatically and merges into the module's definition. When
-   the class doesn't already inherit `Module`/`BaseModule`, it also synthesizes the
-   `appContext` storage and `init(appContext:)` those base classes would have provided.
+ - `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
+   synthesizes the `appContext` storage and `init(appContext:)` those base classes provide.
  - `MemberAttributeMacro`: stamps `@JavaScriptActor` on `@JS` sync members and
    `@ModuleDefinitionBuilder` on a `definition()` method.
  - `ExtensionMacro`: adds the `AnyModule` conformance when the class doesn't inherit it.
@@ -39,14 +41,18 @@ public struct ExpoModuleMacro: MemberMacro {
       throw MacroExpansionErrorMessage("@ExpoModule can only be applied to a class")
     }
 
+    // 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
+    // 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) ?? classDecl.name.text
-    var entries: [String] = ["Name(\"\(moduleName)\")"]
+    var entries: [String] = []
 
-    // `@JS func`s (sync and async) are bound directly into the JS object by the synthesized
-    // `_decorateModule` rather than described with a `Function(...)` / `AsyncFunction(...)` DSL entry,
-    // so they're collected here instead of appended to `entries`. Properties still go through
-    // the DSL for now.
+    // `@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`.
     var functions: [JSFunction] = []
+    var properties: [JSProperty] = []
 
     for typeName in classListArgument(of: node, label: "classes") {
       entries.append("\(typeName)._synthesizedClassDefinition()")
@@ -63,15 +69,25 @@ public struct ExpoModuleMacro: MemberMacro {
 
       if let varDecl = decl.as(VariableDeclSyntax.self),
         let attribute = varDecl.attributes.firstAttribute(named: "JS") {
-        entries.append(contentsOf: buildPropertyEntries(varDecl: varDecl, attribute: attribute))
+        properties.append(contentsOf: collectProperties(varDecl: varDecl, attribute: attribute))
       }
     }
 
-    let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
-    let body = "  return [\n\(lines)\n  ]"
+    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
+    // instead of the retired `Name(…)` DSL element; it feeds both native registration and the
+    // JS object name, so they can't diverge.
+    emitted.append("public static let _jsName = \"\(raw: moduleName)\"")
+
     // `Module`/`BaseModule` already provide `appContext` storage and the
     // `init(appContext:)` requirement, so we only synthesize them for classes that
     // inherit from neither. Each is skipped individually if the user wrote their own,
@@ -100,11 +116,11 @@ public struct ExpoModuleMacro: MemberMacro {
       """
     emitted.append(method)
 
-    // Direct JSI binding: one `_decorateModule` that binds each `@JS func` into the module's JS object,
-    // with the decode-call-encode body inlined into each closure. Only emitted when there are
-    // functions to bind.
-    if !functions.isEmpty {
-      emitted.append(buildDecorateJavaScriptObject(functions: functions))
+    // 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.
+    if !functions.isEmpty || !properties.isEmpty {
+      emitted.append(buildDecorateJavaScriptObject(functions: functions, properties: properties))
     }
 
     return emitted
@@ -127,7 +143,10 @@ extension ExpoModuleMacro: MemberAttributeMacro {
     // `@JS` sync members run on the JS thread; stamp `@JavaScriptActor` so isolation is
     // checked at compile time. Skipped when the member already chose an isolation
     // (`async`, `nonisolated`, or another global actor) — see `shouldStampJavaScriptActor`.
-    if memberHasJSAttribute(member),
+    // `@Event(sync: true)` 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),
       shouldStampJavaScriptActor(on: member, enclosedBy: declaration) {
       attributes.append("@JavaScriptActor")
     }
@@ -228,19 +247,52 @@ private func hasAppContextInitializer(_ classDecl: ClassDeclSyntax) -> Bool {
 
 // MARK: - Member builders
 
-private func buildPropertyEntries(
+private func collectProperties(
   varDecl: VariableDeclSyntax,
   attribute: AttributeSyntax
-) -> [String] {
+) -> [JSProperty] {
   let jsNameOverride = jsNameArgument(of: attribute)
+  // A `let` is never settable; only `var` bindings can carry a setter.
+  let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
 
   return varDecl.bindings.compactMap { binding in
     guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
       return nil
     }
     let swiftName = ident.identifier.text
-    let jsName = jsNameOverride ?? swiftName
-    return "Property(\"\(jsName)\") { self.\(swiftName) }"
+    // Prefer the explicit annotation; recover the type from a literal default (`var x = false`)
+    // when there's none. `nil` falls back to inference at the use site.
+    let valueType = binding.typeAnnotation?.type.trimmedDescription
+      ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
+    return JSProperty(
+      swiftName: swiftName,
+      jsName: jsNameOverride ?? swiftName,
+      valueType: valueType,
+      isSettable: isVar && bindingIsSettable(binding)
+    )
+  }
+}
+
+/// Whether a `var` binding is settable from JS. A stored property (no accessor block) is settable;
+/// a computed property is settable only when it declares an explicit `set` accessor. A getter-only
+/// computed property (`{ get }` or a single getter body) stays read-only. `willSet`/`didSet`
+/// observers imply stored storage, which is also settable.
+private func bindingIsSettable(_ binding: PatternBindingSyntax) -> Bool {
+  guard let accessorBlock = binding.accessorBlock else {
+    return true
+  }
+  switch accessorBlock.accessors {
+  case .accessors(let accessors):
+    return accessors.contains { accessor in
+      switch accessor.accessorSpecifier.tokenKind {
+      case .keyword(.set), .keyword(.willSet), .keyword(.didSet):
+        return true
+      default:
+        return false
+      }
+    }
+  case .getter:
+    return false
   }
 }
 

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -14,6 +14,64 @@ internal func jsNameArgument(of attribute: AttributeSyntax) -> String? {
   return segment.content.text
 }
 
+/**
+ Reads a labeled boolean-literal argument of an attribute, e.g. `@Event(sync: true)` -> true.
+ Returns nil if the attribute has no argument with that label or its value isn't a boolean literal.
+ */
+internal func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool? {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return nil
+  }
+  for arg in args where arg.label?.text == label {
+    guard let literal = arg.expression.as(BooleanLiteralExprSyntax.self) else {
+      return nil
+    }
+    return literal.literal.tokenKind == .keyword(.true)
+  }
+  return nil
+}
+
+/// True if the type is written as an optional: `T?`, `T!`, or the explicit `Optional<T>`. Used to
+/// decide argument requiredness (an optional parameter may be omitted) and record-field nullability.
+internal func isOptionalType(_ type: TypeSyntax) -> Bool {
+  if type.is(OptionalTypeSyntax.self) || type.is(ImplicitlyUnwrappedOptionalTypeSyntax.self) {
+    return true
+  }
+  if let identifier = type.as(IdentifierTypeSyntax.self), identifier.name.text == "Optional" {
+    return true
+  }
+  return false
+}
+
+/// 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.
+internal func isOmittable(_ parameter: FunctionParameterSyntax) -> Bool {
+  return hasDefaultValue(parameter) || isOptionalType(parameter.type)
+}
+
+/// True if the parameter declares a default value (`b: Int = 5`). An omitted defaulted slot is left
+/// out of the call so Swift fills in the default, distinguishing it from an omitted optional slot
+/// (passed `nil`).
+internal func hasDefaultValue(_ parameter: FunctionParameterSyntax) -> Bool {
+  return parameter.defaultValue != nil
+}
+
+/**
+ True if the declaration is a `@Event(sync: true)` property. A sync event dispatches inline on the
+ JS thread instead of scheduling, so `@ExpoModule`/`@SharedObject` stamp it with `@JavaScriptActor`,
+ making "must be called on the JS thread" a compile-time guarantee at the call site. Async events
+ (the default) are deliberately not stamped: their `emit` schedules onto the JS thread itself, so
+ they stay callable from any thread.
+ */
+internal func isSyncEventMember(_ decl: DeclSyntaxProtocol) -> Bool {
+  guard let varDecl = decl.as(VariableDeclSyntax.self),
+    let attribute = varDecl.attributes.firstAttribute(named: "Event") else {
+    return false
+  }
+  return boolArgument(of: attribute, label: "sync") == true
+}
+
 /**
  Reads a labeled array-literal argument of an attribute, e.g. `@ExpoModule(classes: [Foo.self, Bar.self])`,
  and returns the type names referenced (e.g. `["Foo", "Bar"]`). Each element must be a
@@ -155,6 +213,27 @@ private func hasGlobalActorShape(_ element: AttributeListSyntax.Element) -> Bool
   return name.hasSuffix("Actor")
 }
 
+/// The Swift default type of a literal expression — `String`, `Double`, `Int`, or `Bool` — or `nil`
+/// when the expression isn't one of those literals. Used to recover a property's type when it has no
+/// annotation but does have a literal default (`var name = "foo"` → `String`). This matches the type
+/// Swift itself would infer for the same un-annotated declaration; expressions whose type a syntactic
+/// macro can't know (function calls, collection literals, member access) return `nil`.
+internal func inferredLiteralType(of expression: ExprSyntax) -> String? {
+  if expression.is(StringLiteralExprSyntax.self) {
+    return "String"
+  }
+  if expression.is(FloatLiteralExprSyntax.self) {
+    return "Double"
+  }
+  if expression.is(IntegerLiteralExprSyntax.self) {
+    return "Int"
+  }
+  if expression.is(BooleanLiteralExprSyntax.self) {
+    return "Bool"
+  }
+  return nil
+}
+
 extension AttributeListSyntax {
   internal func firstAttribute(named name: String) -> AttributeSyntax? {
     for element in self {

package/apple/Sources/ExpoModulesMacros/Plugin.swift

@@ -6,6 +6,7 @@ struct ExpoModulesMacrosPlugin: CompilerPlugin {
   let providingMacros: [Macro.Type] = [
     OptimizedFunctionAttachedMacro.self,
     JSMacro.self,
+    EventMacro.self,
     ExpoModuleMacro.self,
     SharedObjectMacro.self,
     RecordMacro.self,

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -453,42 +453,6 @@ private func isExcludedByModifier(_ modifiers: DeclModifierListSyntax) -> Bool {
   return false
 }
 
-/**
- The Swift default type of a literal expression — `String`, `Double`, `Int`, or `Bool` — or `nil`
- when the expression isn't one of those literals. Used to recover a property's type when it has no
- annotation but does have a literal default (`var name = "foo"` → `String`). This matches the type
- Swift itself would infer for the same un-annotated declaration; expressions whose type a syntactic
- macro can't know (function calls, collection literals, member access) return `nil`.
- */
-private func inferredLiteralType(of expression: ExprSyntax) -> String? {
-  if expression.is(StringLiteralExprSyntax.self) {
-    return "String"
-  }
-  if expression.is(FloatLiteralExprSyntax.self) {
-    return "Double"
-  }
-  if expression.is(IntegerLiteralExprSyntax.self) {
-    return "Int"
-  }
-  if expression.is(BooleanLiteralExprSyntax.self) {
-    return "Bool"
-  }
-  return nil
-}
-
-/**
- True if the type syntax is optional: `T?`, `T!`, or the spelled-out `Optional<T>`.
- */
-private func isOptionalType(_ type: TypeSyntax) -> Bool {
-  if type.is(OptionalTypeSyntax.self) || type.is(ImplicitlyUnwrappedOptionalTypeSyntax.self) {
-    return true
-  }
-  if let identifier = type.as(IdentifierTypeSyntax.self), identifier.name.text == "Optional" {
-    return true
-  }
-  return false
-}
-
 /**
  True if the type's inheritance clause already lists a protocol with the given name.
  Matches either the bare identifier (`Record`) or a qualified member access ending in

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -95,7 +95,10 @@ extension SharedObjectMacro: MemberAttributeMacro {
     providingAttributesFor member: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [AttributeSyntax] {
-    guard memberHasJSAttribute(member),
+    // `@Event(sync: true)` 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),
       shouldStampJavaScriptActor(on: member, enclosedBy: declaration) else {
       return []
     }

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -5,6 +5,11 @@ import SwiftSyntax
 /// asserts the conformance (`@JS`, `@Record`, …).
 internal let jsConvertibleProtocolName = "AnyArgument"
 
+/// The protocol a type must conform to for `self.emit(event:…)` to resolve; core conforms
+/// `BaseModule` and `SharedObject` to it. Asserted by `@Event` so attaching it to a type that can't
+/// emit fails with a conformance diagnostic instead of an opaque "no member 'emit'" error.
+internal let eventEmitterProtocolName = "EventEmitter"
+
 /// Types we never assert because they're statically known to conform and never reach the dynamic
 /// converter: the JS primitives. Asserting them would only add noise to the expansion. Kept here
 /// (rather than reusing the decode-path's `fastDecodeAccessor`) because "known-to-conform" is a
@@ -66,6 +71,15 @@ internal func typeConformanceAssertions(for assertions: [ConformanceAssertion])
     """
 }
 
+/// The type to assert for a boundary type as written: trailing optional markers are unwrapped to the
+/// core type, and a known-conforming primitive returns `nil` (nothing to assert). Shared with
+/// `@Event`, which folds its single payload type into a combined assertion of its own shape rather
+/// than reusing the whole body fragment below.
+internal func assertableBoundaryType(_ type: String) -> String? {
+  let unwrapped = unwrappedOptional(type)
+  return knownConformingPrimitives.contains(unwrapped) ? nil : unwrapped
+}
+
 /// The assertion's body fragment: a nested generic helper named after the member, plus one call per
 /// distinct non-primitive type. Nesting the helper keeps the constraint entirely local — no shared
 /// symbol, nothing to collide, nothing left in the type's namespace — and naming it after the member

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/expo-modules-macros-plugin",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Swift macro plugin for Expo modules",
   "license": "MIT",
   "author": "650 Industries, Inc.",

package/apple/Sources/ExpoModulesMacros/DecorateFunctionBuilder.swift

@@ -1,196 +0,0 @@
-import SwiftSyntax
-
-/**
- A `@JS func` collected for **direct JSI binding**. Instead of describing the function with a
- `Function(...)` / `AsyncFunction(...)` DSL entry that the runtime interprets per call,
- `@ExpoModule` synthesizes a `_decorateModule` that binds each such function into the module's JS object
- via the closure-taking `JavaScriptObject.setProperty(_:)`, with the decode-call-encode body
- inlined into the closure. This omits the `[Any]`/`toTuple` dynamic-call path: every argument is
- decoded individually by its static type.
-
- The receiver is the module's real `self` (a module is a singleton instance), so the body calls
- `self.<name>(...)` directly and ignores the JS `this`. An `async` `@JS func` produces an `async`
- closure body and is installed through the async `setProperty(_:)` overload (so JS gets a promise).
- */
-internal struct JSFunction {
-  let swiftName: String
-  let jsName: String
-  let parameters: [FunctionParameterSyntax]
-  /// The declared return type as written, or `nil` when the function returns `Void`/nothing.
-  let returnType: String?
-  let isThrowing: Bool
-  let isAsync: Bool
-
-  init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
-    self.swiftName = funcDecl.name.text
-    self.jsName = jsNameArgument(of: attribute) ?? funcDecl.name.text
-    self.parameters = Array(funcDecl.signature.parameterClause.parameters)
-
-    let declaredReturnType = funcDecl.signature.returnClause?.type
-    self.returnType = isVoidType(declaredReturnType) ? nil : declaredReturnType?.trimmedDescription
-
-    let effectSpecifiers = funcDecl.signature.effectSpecifiers
-    self.isThrowing = effectSpecifiers?.throwsClause?.throwsSpecifier != nil
-    self.isAsync = effectSpecifiers?.asyncSpecifier != nil
-  }
-
-  /**
-   The `#name` host-function body: a `@JavaScriptActor private func` matching the
-   `createFunction` closure shape `(this, arguments) throws -> JavaScriptValue`, threading
-   `appContext`/`runtime` in as parameters. It checks arity, decodes each argument by its static
-   type — primitives through a direct typed accessor (`asDouble()`, …) on a borrowed
-   `JavaScriptUnownedValue`, other types through the
-   `T.getDynamicType()` converter — calls `self.<name>(...)`, and converts the result back to JS.
-   */
-  /// The decode-call-encode statements that form the host-function body, indented with the given
-  /// prefix. Arity guard, then per-argument decode (primitives via a direct typed accessor like
-  /// `asDouble()` on a zero-copy `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`),
-  /// the `self.<name>(...)` call, and the
-  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`).
-  private func bodyStatements(indent: String) -> String {
-    var lines: [String] = []
-
-    lines.append(
-      """
-      guard arguments.count == \(parameters.count) else {
-        throw Exception(name: "InvalidArgumentCount", description: "Function '\(jsName)' expects \(parameters.count) argument(s), but got \\(arguments.count)")
-      }
-      """)
-
-    var callArguments: [String] = []
-    for (index, parameter) in parameters.enumerated() {
-      let type = parameter.type.trimmedDescription
-
-      // Primitives decode through a direct typed accessor (`asDouble()`, etc.) on a borrowed
-      // `JavaScriptUnownedValue` — no owning `JavaScriptValue` allocation, no `jsi::Value` copy, no
-      // `getDynamicType()` allocation, no `Any` boxing, no force-cast — while still validating and
-      // throwing `TypeError` on a mismatch. Other types fall back to the dynamic converter, which
-      // needs an owning value, so they index the buffer directly.
-      if let accessor = fastDecodeAccessor(for: type) {
-        lines.append("let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()")
-      } else {
-        lines.append(
-          "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)")
-      }
-
-      let label = parameter.firstName.text
-      callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")
-    }
-
-    let tryKeyword = (isThrowing || isAsync) ? "try " : ""
-    let awaitKeyword = isAsync ? "await " : ""
-    let callExpression =
-      "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
-
-    if let returnType {
-      lines.append("let result = \(callExpression)")
-      // Primitives encode through `toJavaScriptValue(in:)` (the typed `JavaScriptRepresentable`
-      // conversion) — no `Any`, no dynamic-type allocation. Others go through the dynamic converter.
-      if fastDecodeAccessor(for: returnType) != nil {
-        lines.append("return result.toJavaScriptValue(in: runtime)")
-      } else {
-        lines.append("return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)")
-      }
-    } else {
-      lines.append(callExpression)
-      lines.append("return .undefined")
-    }
-
-    return lines
-      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
-      .map { indent + $0 }
-      .joined(separator: "\n")
-  }
-
-  /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
-  /// body is inlined directly into the closure passed to the closure-taking `setProperty` overload
-  /// (which creates the host function under the hood) — no separate named binding. For an `async`
-  /// function the body `await`s the call, which selects the async `setProperty` overload (so JS
-  /// receives a promise).
-  ///
-  /// Capture mirrors core's `SyncFunctionDefinition.build`: `self` (the module) is captured
-  /// **strong** — the host-function closure is what keeps the native callable alive for as long as
-  /// JS can invoke it; its lifetime is bounded by the JS VM's garbage collection of the object.
-  /// `appContext` is captured **weak** (and guarded) so it doesn't form a real retain cycle through
-  /// the app context. When no argument or return value goes through the dynamic-type converter the
-  /// body never references `appContext`, so the capture and guard are omitted to avoid the
-  /// unused-capture warning.
-  var decorateStatements: String {
-    if usesAppContext {
-      return """
-          object.setProperty("\(jsName)") { [weak appContext, self] this, arguments in
-            guard let appContext else {
-              throw Exceptions.AppContextLost()
-            }
-        \(bodyStatements(indent: "    "))
-          }
-        """
-    }
-    return """
-        object.setProperty("\(jsName)") { [self] this, arguments in
-      \(bodyStatements(indent: "    "))
-        }
-      """
-  }
-
-  /// True when the host-function body references `appContext` — i.e. some parameter or the return
-  /// type lacks a fast accessor and decodes/encodes through `getDynamicType()`, which threads
-  /// `appContext` in.
-  private var usesAppContext: Bool {
-    if parameters.contains(where: { fastDecodeAccessor(for: $0.type.trimmedDescription) == nil }) {
-      return true
-    }
-    if let returnType, fastDecodeAccessor(for: returnType) == nil {
-      return true
-    }
-    return false
-  }
-}
-
-/**
- The single generated function that decorates the module's JS object. Core supplies the object;
- this binds every `@JS func` into it via one inlined `setProperty` closure per function. Mirrors
- core's `ObjectDefinition.decorate(object:)`, including its `borrowing` object parameter (it
- mutates through the reference without reassigning or taking ownership). Named `_decorateModule`
- with the leading-underscore convention for synthesized members the **runtime calls by name**; the
- `ExpoModule` suffix names the `@ExpoModule` macro it came from (a shared object's counterpart is
- `_decorateSharedObject`).
- */
-internal func buildDecorateJavaScriptObject(functions: [JSFunction]) -> DeclSyntax {
-  let body = functions.map { $0.decorateStatements }.joined(separator: "\n")
-  return """
-    @JavaScriptActor
-    public func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws {
-    \(raw: body)
-    }
-    """
-}
-
-/// The throwing `JavaScriptUnownedValue` accessor that decodes the given primitive type directly,
-/// bypassing the dynamic-type converter (`asDouble()` for `Double`, etc.). Returns `nil` for
-/// types without a dedicated accessor — arrays, records, optionals, shared objects, other numeric
-/// widths — which decode through `getDynamicType().cast(...)`.
-private func fastDecodeAccessor(for type: String) -> String? {
-  switch type {
-  case "Bool":
-    return "asBool"
-  case "Int":
-    return "asInt"
-  case "Double":
-    return "asDouble"
-  case "String":
-    return "asString"
-  default:
-    return nil
-  }
-}
-
-/// True when a return clause is absent or written as `Void` / `()` — i.e. the function returns
-/// nothing JS-visible, so the binding returns `.undefined`.
-private func isVoidType(_ type: TypeSyntax?) -> Bool {
-  guard let type else {
-    return true
-  }
-  let text = type.trimmedDescription
-  return text == "Void" || text == "()"
-}