expo-modules-macros 0.31.0 → 0.33.0

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

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

package/AGENTS.md

@@ -4,9 +4,10 @@
 
 ## Layout
 
-- `Package.swift`: the SwiftPM package, at the root so that its identity is `expo-modules-macros` (an `apple/` manifest would have the identity `apple`, which conflicts with other packages that keep theirs in `apple/`). The targets name their paths under `apple/`. The `ExpoModulesMacrosPlugin` library product vends the macro target to Swift packages, and its name must differ from the target's. The test targets are declared only when `apple/Tests` exists, because the published npm package leaves it out.
+- `Package.swift`: the SwiftPM package, at the root so that its identity is `expo-modules-macros` (an `apple/` manifest would have the identity `apple`, which conflicts with other packages that keep theirs in `apple/`). The targets name their paths under `apple/`. The `ExpoModulesMacrosPlugin` library product vends the macro target to Swift packages through a target of the same name, and its name must differ from the macro target's. The test targets are declared only when `apple/Tests` exists, because the published npm package leaves it out.
 - `apple/Sources/ExpoModulesMacrosCore`: the macro implementations, in a library target so that both executables below can link them. `Macros/` holds one file per macro, and `Support/` the code that several macros share. `ProvidedMacros.swift` lists every macro with its attribute name and conformances in `ProvidedMacro.all`. `PluginServer.swift` runs the compiler plugin protocol with a provider that resolves the macros of `ProvidedMacro.all` by type name, because the default `CompilerPlugin` lookup expects them in a module named `ExpoModulesMacros`. It uses the `@_spi(PluginMessage)` API of swift-syntax.
 - `apple/Sources/ExpoModulesMacros`: the `.macro` target that the `ExpoModulesMacrosPlugin` product vends to Swift packages. It only runs the plugin server, so Swift packages don't compile the CLI.
+- `apple/Sources/ExpoModulesMacrosPlugin`: an empty target that the `ExpoModulesMacrosPlugin` product holds in place of the macro target, which it depends on. Xcode fails an iOS build when the product holds the macro target directly (see `Package.swift`).
 - `apple/Sources/ExpoModulesMacrosTool`: the executable that ships as `apple/ExpoModulesMacros` and in the Windows and Linux packages. `main.swift` runs the plugin server without arguments and sends any invocation with arguments to the CLI.
 - `apple/Sources/ExpoModulesCLI`: the library behind the command-line tool. `CLI.swift` parses the arguments, `Commands/` holds one directory per subcommand (`ScanModules/` for autolinking, `ScanExports/` for type generation, `Expand/` for `expand`, with `MacroExpander.swift`, which runs the macros in process, and `Fix/` for `fix`, which applies the Fix-Its that `expand` reports), and `Core/` holds the shared parsing, `#if` evaluation and output.
 - `apple/Sources/ExpoModulesOptimized`: declarations for the `@OptimizedFunction` macro.
@@ -31,7 +32,7 @@ pnpm run swift:format        # format the Swift sources in place
 pnpm run swift:lint          # check the formatting, as CI does
 ```
 
-CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `pnpm run typecheck`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `pnpm run swift:lint`. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
+CI runs on macOS (`.github/workflows/macos.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, runs `swift test` and `pnpm run typecheck`, then scans through the TypeScript wrapper with `scripts/check-scan.js`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. On every platform, `check-scan.js` also requires `scanExports` to report the surface in `scripts/check-scan-exports.json` for its fixture, so the generated types are the same on each OS. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `pnpm run swift:lint`. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
 
 ## Windows
 
@@ -57,6 +58,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 ## Changing macros
 
 - The scanner re-implements the macros' naming and member rules on the syntax tree; it does not call the macro code. When a macro changes which members it binds or how it names them (the `@JS` name override, the `on` prefix `@Event` strips, which properties `@Record` treats as fields), change `scan-exports` to match, or generated TypeScript types drift from the runtime.
+- When the `scan-exports` output changes on purpose, update `scripts/check-scan-exports.json`: run `swift build`, then `node scripts/check-scan.js . --update .build/debug/ExpoModulesMacrosTool`, and review the diff. CI compares it with the output on macOS, Windows and Linux.
 - The scanner only parses files that pass the pre-filter, `MacroPrefilter` in `ExpoModulesCLI/Core/SourceScan.swift`. Each command builds it from the `macros` and `conformances` arguments of its `scanFiles` call. A new attribute or conformance the scanner must detect has to be added to those arguments (an attribute also needs a `DetectedMacro` case), or files that use it are skipped without an error.
 - A new macro needs: the implementation in `apple/Sources/ExpoModulesMacrosCore/Macros`, an entry in `ProvidedMacro.all` in `ProvidedMacros.swift` (with the attribute name and the extension conformances of its declaration), an expansion test file, the `#externalMacro` declaration in `expo-modules-core`, and an entry in the macro list in `README.md`.
 

package/Package.swift

@@ -14,7 +14,7 @@ let package = Package(
     // `#externalMacro(module: "ExpoModulesMacros", ...)` depends on this product, and the targets that
     // depend on it get the plugin too. CocoaPods builds keep loading the prebuilt binary. The name
     // differs from the macro target's, because SwiftPM already has a product of that name for it.
-    .library(name: "ExpoModulesMacrosPlugin", targets: ["ExpoModulesMacros"]),
+    .library(name: "ExpoModulesMacrosPlugin", targets: ["ExpoModulesMacrosPlugin"]),
     .executable(name: "ExpoModulesMacrosTool", targets: ["ExpoModulesMacrosTool"]),
   ],
   dependencies: [
@@ -51,6 +51,15 @@ let package = Package(
       ],
       path: "apple/Sources/ExpoModulesMacros"
     ),
+    // The target of the `ExpoModulesMacrosPlugin` product. The product must not hold the macro target
+    // itself: Xcode then passes the module map of `ExpoModulesMacrosCore`, which it builds for the
+    // host only, to the iOS target that depends on the product, and the build fails with
+    // `ExpoModulesMacrosCore.modulemap not found`.
+    .target(
+      name: "ExpoModulesMacrosPlugin",
+      dependencies: ["ExpoModulesMacros"],
+      path: "apple/Sources/ExpoModulesMacrosPlugin"
+    ),
     // The shipped binary, `apple/ExpoModulesMacros` and the Windows and Linux binaries. It is both the
     // compiler plugin and the scanner CLI: the compiler launches it without arguments and speaks the
     // plugin protocol over stdin, while an invocation with arguments dispatches into `ScannerCLI`

package/README.md

@@ -25,11 +25,11 @@ This package lists them as optional dependencies, and their `os`, `cpu` and (on
 # Macros
 
 - **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none. It adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet (see [Sendable conformance](#sendable-conformance)).
-- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. The macro also checks that every type crossing the boundary is convertible in the direction it travels. Outside a module or shared object, a bad type is reported on the author's own declaration. In an `@ExpoModule` or `@SharedObject` class, the class macro makes the check, since only it sees the type aliases in the class body, so the error is reported on the class and names the member and its argument labels, such as `local function 'move(_:by:returning:)' requires that 'Point' conform to 'JavaScriptEncodable'`. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. Because of that, a `.concurrent` function and a function with `.withAsync` can't take a JavaScript value such as `JavaScriptValue` or `JavaScriptObject`, which is valid only on the JavaScript thread; the macro reports such a parameter. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
-- **`@Event(_ name: String? = nil, _ options: EventOptions...)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. By default the event is scheduled on the JavaScript thread. The `.inline` option runs the listeners before the call returns when it is made on the JavaScript thread, and schedules the event otherwise; it never blocks. The `.blocking` option runs the listeners before the call returns on any thread, so a call from another thread blocks until the JavaScript thread runs them. An event property is callable from any thread with each option.
-- **`@SharedObject(_ name: String? = nil)`** on a subclass of `SharedObject`, direct or not, such as a `SharedRef<T>` subclass. Binds the class's `@JS` members through the `SharedObject` hooks that core calls when it builds the JavaScript class, and emits the JS class name, which defaults to the class name. A module exposes the class through `@ExpoModule(classes:)`, which only accepts `SharedObject` subclasses. A subclass of another `@SharedObject` class also gets the `@JS` members of that class, and its own members replace inherited members with the same JS name. A subclass that isn't `final` can't be constructed from JavaScript through the `@JS init` of its superclass, so give each subclass that JavaScript constructs its own `@JS init`. Like `@ExpoModule`, it adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet.
-- **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. A record converts only from and to JavaScript values: its `from(dictionary:appContext:)` throws `RecordDictionaryConversionException`, so a record can't be created from a native `[String: Any]`. A `@Union` can be a record property. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
-- **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first.
+- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. The class macro reads only the class body, so `@JS` on a member of an extension, or of a type that is neither a module nor a shared object, is an error. So is `@JS` on an initializer or a `static` member of a module, since JavaScript doesn't construct a module and gets only its instance. `@JS` on any other declaration, such as a subscript, is an error too. A `@JS` function or initializer can't be generic, since the binding converts each value by its static type. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. A name that JavaScript already gives a meaning on the object is an error too: `__proto__` on any object, `constructor` on a shared object's prototype, and `prototype` on its constructor. The macro also checks that every type crossing the boundary is convertible in the direction it travels. For a top-level declaration, a bad type is reported on the author's own declaration. In an `@ExpoModule` or `@SharedObject` class, the class macro makes the check, since only it sees the type aliases in the class body, so the error is reported on the class and names the member and its argument labels, such as `local function 'move(_:by:returning:)' requires that 'Point' conform to 'JavaScriptEncodable'`. A `lazy var` is read-only from JavaScript. On the first read, its getter stores the value as a data property on the JavaScript object, so later reads don't call into native code. On a frozen object the value isn't stored, and each read calls the getter. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. Because of that, a `.concurrent` function and a function with `.withAsync` can't take a JavaScript value such as `JavaScriptValue` or `JavaScriptObject`, which is valid only on the JavaScript thread; the macro reports such a parameter. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
+- **`@Event(_ name: String? = nil, _ options: EventOptions...)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `@ExpoModule` and `@SharedObject` warn when two events in the class body have the same JS name. By default the event is scheduled on the JavaScript thread. The `.inline` option runs the listeners before the call returns when it is made on the JavaScript thread, and schedules the event otherwise; it never blocks. The `.blocking` option runs the listeners before the call returns on any thread, so a call from another thread blocks until the JavaScript thread runs them. An event property is callable from any thread with each option.
+- **`@SharedObject(_ name: String? = nil)`** on a subclass of `SharedObject`, direct or not, such as a `SharedRef<T>` subclass. Binds the class's `@JS` members through the `SharedObject` hooks that core calls when it builds the JavaScript class, and emits the JS class name, which defaults to the class name. A class without an inheritance clause is an error, with a Fix-It that adds `: SharedObject`. A module exposes the class through `@ExpoModule(classes:)`, which only accepts `SharedObject` subclasses. A subclass of another `@SharedObject` class also gets the `@JS` members of that class, and its own members replace inherited members with the same JS name. A subclass that isn't `final` can't be constructed from JavaScript through the `@JS init` of its superclass, so give each subclass that JavaScript constructs its own `@JS init`. Like `@ExpoModule`, it adds an `@unchecked Sendable` conformance when the class isn't `Sendable` yet.
+- **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. A record converts only from and to JavaScript values: its `from(dictionary:appContext:)` throws `RecordDictionaryConversionException`, so a record can't be created from a native `[String: Any]`. A `@Union` can be a record property. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional. The memberwise initializer sets every field, so a field that is a `let` with a default value is an error. It doesn't set a `private` or `fileprivate` stored property, so such a property needs a default value, unless it's an optional `var` or the type declares its own memberwise initializer.
+- **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first. The macro warns about a case that an earlier case always decodes first: any case after a `JavaScriptValue` case, and a case with a payload that decodes only numbers, such as `Float` or `Int32`, after a `Double`, `Float` or `CGFloat` case.
 
 The members and conformances that `@Record` and `@Union` generate are `nonisolated`, so they also work in a module that builds with a default isolation, such as `-default-isolation MainActor`. The stored properties of a record still take that isolation. A class record, or a struct record with a property whose type isn't `Sendable`, then needs `nonisolated` on its declaration, for example `@Record nonisolated final class Options`.
 
@@ -180,7 +180,7 @@ to `OTHER_SWIFT_FLAGS` for `ExpoModulesCore`, every pod that depends on it, and
 
 ## Swift packages
 
-The package manifest is `Package.swift` at the root of this package, so a Swift package can depend on it by its path in `node_modules` or by the URL of this repository. Its identity is then `expo-modules-macros`. The `ExpoModulesMacrosPlugin` library product holds the `ExpoModulesMacros` macro target:
+The package manifest is `Package.swift` at the root of this package, so a Swift package can depend on it by its path in `node_modules` or by the URL of this repository. Its identity is then `expo-modules-macros`. The `ExpoModulesMacrosPlugin` library product gives the `ExpoModulesMacros` macro target to the targets that depend on it:
 
 ```swift
 dependencies: [

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

@@ -1,7 +1,8 @@
-/// The deep-scan surface: the full JS-exported shape of every `@ExpoModule`, `@SharedObject`, and
-/// `@Record` type, with the per-member detail a TypeScript type generator needs. Read syntactically
-/// (like the macros): each boundary type becomes a structured `TypeNode` tree so the consumer walks a
-/// tagged tree rather than re-parsing Swift type syntax.
+/// The deep-scan surface: the full JS-exported shape of every `@ExpoModule`, `@SharedObject`,
+/// `@Record`, `@Union`, and `@ExpoView` type and every `Enumerable` enum, with the per-member detail a
+/// TypeScript type generator needs. Read syntactically (like the macros): each boundary type becomes a
+/// structured `TypeNode` tree so the consumer walks a tagged tree rather than re-parsing Swift type
+/// syntax.
 ///
 /// Every declaration and member carries the `platforms` that build it, and the ones that can be
 /// written with an access modifier carry the `accessLevel` they spell. A declaration no platform
@@ -460,6 +461,122 @@ struct ExportedUnion: Encodable, Equatable {
   let file: String
 }
 
+/// An `@ExpoView` class with the props and events of the `@ViewProps` struct in its generic argument.
+/// It is reported on its own rather than under a module, because core reaches it through its
+/// `AnyNativeView` conformance.
+struct ExportedView: Encodable, Equatable {
+  /// The Swift class name. Only a view declared at file scope is reported, as in `scan-modules`.
+  let name: String
+
+  /// The name the view registers under. `@ExpoView` takes no name, so it is always the class name.
+  let jsName: String
+
+  /// The props type: the generic argument of `@ExpoView<CardProps>`, as written without backticks, or
+  /// the qualified name of the scanned `@ViewProps` struct it names (`CardView.Props`). A class without
+  /// the generic argument is not reported, because the macro rejects it.
+  var propsType: String
+
+  /// The name `propsType` is looked up under: its spelling without generic arguments, or `nil` when it
+  /// isn't a plain or qualified type name. Not encoded.
+  var propsTypeLookupName: String? = nil
+
+  /// The value props of the `@ViewProps` struct, or `nil` when the scan declares no struct named
+  /// `propsType` on a platform of the view. A struct shared by several views is copied into each of
+  /// them, and a struct declared in several `#if` branches contributes the props of each declaration
+  /// whose platforms overlap the view's.
+  var props: [ExportedViewProp]? = nil
+
+  /// The events of the `@ViewProps` struct, or `nil` when `props` is `nil`.
+  var events: [ExportedViewEvent]? = nil
+
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+
+  let file: String
+
+  private enum CodingKeys: String, CodingKey {
+    case name, jsName, propsType, props, events, accessLevel, platforms, file
+  }
+}
+
+/// One value prop of a `@ViewProps` struct: a stored property that isn't function-typed. Like
+/// `ExportedRecordProperty`, but with no `required`: core resets a prop that React leaves out to its
+/// default, so JS can always omit one.
+struct ExportedViewProp: Encodable, Equatable {
+  let name: String
+
+  /// The annotated type, or the type of a literal initial value. A property with neither is not
+  /// reported, because the macro rejects it.
+  var type: TypeNode
+
+  /// The initial value as source text, or `nil` when none is written.
+  let defaultValue: String?
+
+  /// The spelled access modifier, or `nil` when none is written. Never `private` or `fileprivate`,
+  /// since those exclude a property from the props.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+
+  /// Optional-typed, read from `type`, so every spelling of an optional counts (`T?`, `T!`,
+  /// `Optional<T>`, `(T?)`). Encoded as `optional`.
+  var isOptional: Bool {
+    if case .optional = type {
+      return true
+    }
+    return false
+  }
+
+  private enum CodingKeys: String, CodingKey {
+    case name, type, defaultValue, accessLevel, platforms
+    case isOptional = "optional"
+  }
+
+  func encode(to encoder: Encoder) throws {
+    var container = encoder.container(keyedBy: CodingKeys.self)
+    try container.encode(name, forKey: .name)
+    try container.encode(type, forKey: .type)
+    try container.encode(isOptional, forKey: .isOptional)
+    try container.encodeIfPresent(defaultValue, forKey: .defaultValue)
+    try container.encodeIfPresent(accessLevel, forKey: .accessLevel)
+    try container.encode(platforms, forKey: .platforms)
+  }
+}
+
+/// One event of a `@ViewProps` struct: a function-typed stored property. Its name is the React prop
+/// name as written, with no `on` prefix stripped, so it carries no `jsName`.
+struct ExportedViewEvent: Encodable, Equatable {
+  /// The Swift property name, e.g. `onTap`.
+  let name: String
+
+  /// The type of the function's single parameter, or `nil` when it takes none (`() -> Void`) or more
+  /// than one.
+  var payload: TypeNode?
+
+  /// The spelled access modifier, or `nil` when none is written.
+  let accessLevel: String?
+
+  let platforms: [ExportedPlatform]
+}
+
+/// A `@ViewProps` struct the scan found. Not encoded: `ExportedSurface.joiningViewProps(_:)` copies its
+/// props and events into each view that names it, and a struct that no view names is not reported.
+struct ViewPropsDeclaration: Equatable {
+  /// The Swift struct name, qualified with the types it is nested in (`CardView.Props`).
+  let name: String
+
+  /// The value props, in declaration order.
+  let props: [ExportedViewProp]
+
+  /// The events, in declaration order.
+  let events: [ExportedViewEvent]
+
+  /// The platforms that build the struct, to match it with the views that build on them.
+  let platforms: [ExportedPlatform]
+}
+
 /// The exported types grouped by kind, nested under `exports` in the result so the surface is one
 /// self-contained object separate from `stats`.
 struct ExportedSurface: Encodable, Equatable {
@@ -468,6 +585,7 @@ struct ExportedSurface: Encodable, Equatable {
   let records: [ExportedRecord]
   let enums: [ExportedEnum]
   let unions: [ExportedUnion]
+  let views: [ExportedView]
 }
 
 /// How an `@Event` is dispatched to JavaScript, from its option. Mirrors `EventDispatch` in the macros.
@@ -488,7 +606,8 @@ enum ExportedEventDispatch: String, Encodable, Equatable {
 /// `defaultValue`, and replaces `constructorParameters` with `initializer`; version 9 adds the
 /// `sharedRef` type kind and the `sharedRef` of a shared object; version 10 adds the `tuple` and `object` type kinds (named after a tuple alias)
 /// and resolves the tuple type aliases declared in `@ExpoModule` and `@SharedObject` classes; version 11
-/// replaces the `sync` flag of an event with `dispatch`.
+/// replaces the `sync` flag of an event with `dispatch`. A new field that older consumers can ignore,
+/// such as `views`, doesn't change the version.
 let scanExportsSchemaVersion = 11
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from

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

@@ -83,7 +83,8 @@ extension ExportedSurface {
       sharedObjects: sharedObjects.map { merged($0, chain: []) },
       records: records,
       enums: enums,
-      unions: unions
+      unions: unions,
+      views: views
     )
   }
 }

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

@@ -74,26 +74,32 @@ struct RefIndex {
   /// dropped one at a time (`Media.Status` -> `Status`): a use site may qualify a name with a module
   /// the scan doesn't see, which is how the conformance and raw-type checks already match names.
   func lookup(_ name: String, in scope: String) -> Entry? {
-    let name = name.hasPrefix("Self.") ? String(name.dropFirst("Self.".count)) : name
-    var components = scope.split(separator: ".").map(String.init)
-    while true {
-      if let entry = entries[(components + [name]).joined(separator: ".")] {
-        return entry
-      }
-      if components.isEmpty {
-        break
-      }
-      components.removeLast()
+    return scopedLookup(name, in: scope, entries: entries)
+  }
+}
+
+/// The entry that a use of `name` written inside the type `scope` names, from `entries` keyed by
+/// qualified name. Swift's lookup rules, as `RefIndex.lookup(_:in:)` documents them.
+private func scopedLookup<Entry>(_ name: String, in scope: String, entries: [String: Entry]) -> Entry? {
+  let name = name.hasPrefix("Self.") ? String(name.dropFirst("Self.".count)) : name
+  var components = scope.split(separator: ".").map(String.init)
+  while true {
+    if let entry = entries[(components + [name]).joined(separator: ".")] {
+      return entry
     }
-    var suffix = name.split(separator: ".").map(String.init).dropFirst()
-    while !suffix.isEmpty {
-      if let entry = entries[suffix.joined(separator: ".")] {
-        return entry
-      }
-      suffix = suffix.dropFirst()
+    if components.isEmpty {
+      break
+    }
+    components.removeLast()
+  }
+  var suffix = name.split(separator: ".").map(String.init).dropFirst()
+  while !suffix.isEmpty {
+    if let entry = entries[suffix.joined(separator: ".")] {
+      return entry
     }
-    return nil
+    suffix = suffix.dropFirst()
   }
+  return nil
 }
 
 /// The JS category a raw-value enum crosses as: its raw value's. A bare `Enumerable` conformance with
@@ -214,6 +220,59 @@ extension ExportedSurface {
           return resolvedMember
         }
         return resolved
+      },
+      // The props and events are written in the `@ViewProps` struct, so their refs are looked up from
+      // it. `joiningViewProps(_:)` runs first and sets `propsType` to the struct's qualified name.
+      views: views.map { view in
+        var resolved = view
+        resolved.props = view.props?.map { prop in
+          var resolvedProp = prop
+          resolvedProp.type = prop.type.resolvingRefs(using: index, in: view.propsType)
+          return resolvedProp
+        }
+        resolved.events = view.events?.map { event in
+          var resolvedEvent = event
+          resolvedEvent.payload = event.payload?.resolvingRefs(using: index, in: view.propsType)
+          return resolvedEvent
+        }
+        return resolved
+      }
+    )
+  }
+
+  /// This surface with the props and events of each view's `@ViewProps` struct copied into the view.
+  /// The struct is looked up from the view like a ref, by its name without generic arguments, so it
+  /// may be declared in another file or nested (`CardView.Props`). A found struct gives the view its
+  /// qualified name as `propsType`. A view whose struct the scan doesn't declare keeps `props` and
+  /// `events` at `nil`, and `propsType` as written.
+  ///
+  /// A struct declared more than once, in `#if` branches, contributes the props and events of each
+  /// declaration whose platforms overlap the platforms of the view, as a superclass does in
+  /// `mergingInheritedMembers()`. Each prop and event keeps its own `platforms`. A view that builds on
+  /// none of those platforms is treated as one whose struct the scan doesn't declare.
+  func joiningViewProps(_ declarations: [ViewPropsDeclaration]) -> ExportedSurface {
+    let entries = Dictionary(grouping: declarations, by: \.name)
+    return ExportedSurface(
+      modules: modules,
+      sharedObjects: sharedObjects,
+      records: records,
+      enums: enums,
+      unions: unions,
+      views: views.map { view in
+        let platforms = Set(view.platforms.map(\.name))
+        guard let name = view.propsTypeLookupName,
+          let variants = scopedLookup(name, in: view.name, entries: entries)?.filter({ declaration in
+            declaration.platforms.contains { platforms.contains($0.name) }
+          }),
+          let first = variants.first
+        else {
+          return view
+        }
+        var joined = view
+        joined.propsType = first.name
+        joined.props = variants.flatMap(\.props)
+        joined.events = variants.flatMap(\.events)
+        return joined
       }
     )
   }

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

@@ -26,11 +26,11 @@ extension Scanner {
   }
 }
 
-/// Scans `paths` for `@ExpoModule`, `@SharedObject`, `@Record`, and `@Union` types plus `Enumerable`
-/// enums, and returns their exported surface plus the run's stats. Separate from the public entry so
-/// tests can drive it without argv/stdout.
+/// Scans `paths` for `@ExpoModule`, `@SharedObject`, `@Record`, `@Union`, `@ExpoView`, and
+/// `@ViewProps` types plus `Enumerable` enums, and returns their exported surface plus the run's stats.
+/// Separate from the public entry so tests can drive it without argv/stdout.
 ///
-/// The pre-filter omits `@Event`: an event only declares a member of one of these three types, so a
+/// The pre-filter omits `@Event`: an event only declares a member of a module or shared object, so a
 /// file containing one already matches on its enclosing type. It does include `Enumerable`, which is a
 /// conformance rather than an attribute: an enum is commonly declared in a file of its own, which no
 /// macro attribute would match.
@@ -40,10 +40,12 @@ func scanExports(paths: [String]) -> ScanExportsResult {
   var records: [ExportedRecord] = []
   var enums: [ExportedEnum] = []
   var unions: [ExportedUnion] = []
+  var views: [ExportedView] = []
+  var viewProps: [ViewPropsDeclaration] = []
 
   let stats = scanFiles(
     paths: paths,
-    macros: [.expoModule, .sharedObject, .record, .union],
+    macros: [.expoModule, .sharedObject, .record, .union, .expoView, .viewProps],
     conformances: [enumerableConformanceName]
   ) { source, file in
     let tree = Parser.parse(source: source)
@@ -54,18 +56,23 @@ func scanExports(paths: [String]) -> ScanExportsResult {
     records.append(contentsOf: visitor.records)
     enums.append(contentsOf: visitor.enums)
     unions.append(contentsOf: visitor.unions)
+    views.append(contentsOf: visitor.views)
+    viewProps.append(contentsOf: visitor.viewProps)
   }
 
   // Refs resolve only once every file has been walked: a type parsed in one file may name a type
   // declared in another, so the full set of declarations has to exist before any lookup is valid. The
-  // same holds for a superclass, so the inherited members are merged after that.
+  // same holds for a view's `@ViewProps` struct, which is joined before the refs resolve so that the
+  // refs in its props resolve from the struct, and for a superclass, so the inherited members are
+  // merged last.
   let surface = ExportedSurface(
     modules: modules,
     sharedObjects: sharedObjects,
     records: records,
     enums: enums,
-    unions: unions
-  ).resolvingRefs().mergingInheritedMembers()
+    unions: unions,
+    views: views
+  ).joiningViewProps(viewProps).resolvingRefs().mergingInheritedMembers()
 
   return ScanExportsResult(
     schemaVersion: scanExportsSchemaVersion,