vybekiit 0.7.26 → 0.7.27

package/dist/global-skills/expo-brownfield/references/brownfield-isolated.md

@@ -16,17 +16,17 @@ If a single team owns both layers, is comfortable with React Native tooling and
 | Platform | Artifact                                                                                                                                                                                                                | Default location                                              |
 | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
 | Android  | `{group}:{libraryName}:{version}` AAR                                                                                                                                                                                   | Local Maven (`~/.m2`) by default; remote Maven also supported |
-| iOS      | Set of `.xcframework`s — see [the iOS section below](#ios) for how `ios.buildReactNativeFromSource` (default `false` on SDK 56+) controls whether you get 5 frameworks or 2 — or a single Swift Package via `--package` | `./artifacts`                                                 |
+| iOS      | Set of `.xcframework`s (depends on source/prebuilt settings and package version), or a Swift Package via `--package`; see [iOS](#ios) | `./artifacts`                                                 |
 
 The JavaScript bundle is **embedded inside the artifact** in release builds, so the native app does not need Metro at runtime in production.
 
 ## Prerequisites
 
-- **Expo SDK 55 or later** — brownfield support, `expo-brownfield`, and the required runtime classes are only available on SDK 55+. Earlier SDKs will not work.
+- **Expo SDK 55 or later for this Expo toolkit** — `expo-brownfield` was introduced in SDK 55. Match package versions and native requirements to the selected SDK; this is not a minimum for historical integrated setups.
 - **Node.js (LTS)** — runs JavaScript and the Expo CLI.
-- **Yarn** — manages JavaScript dependencies.
+- The existing package manager and lockfile. Yarn is not required.
 
-Node and Yarn are only needed in the environment that _builds_ the artifact. The consuming native app does not need them.
+Node and the JS package manager are only needed in the environment that _builds_ the artifact. The consuming native app does not need them.
 
 ---
 
@@ -35,10 +35,10 @@ Node and Yarn are only needed in the environment that _builds_ the artifact. The
 ### Create a new Expo project
 
 ```sh
-npx create-expo-app@latest my-project --template default@sdk-55
+npx create-expo-app@latest my-project --template blank@latest
 ```
 
-**Pin to SDK 55 or later — earlier SDKs do not support brownfield.** The project can live in a separate repo or alongside the native app in a monorepo; it does not need to be inside the native project.
+Use this current stable blank template for a small embedded feature after the [version/toolchain checks](./version-compatibility.md). If host constraints require another SDK, select its published template tag instead. Keep an existing producer and its entry point when present. The project can live in a separate repo or alongside the native app in a monorepo; it does not need to be inside the native project.
 
 ### Install expo-brownfield
 
@@ -47,7 +47,7 @@ cd my-project
 npx expo install expo-brownfield
 ```
 
-The plugin self-registers in `app.json` with defaults derived from your app config.
+Check that the plugin registered in `app.json`; add it explicitly if the install command did not update the config (for example, with dynamic app configuration). Defaults derive from your app config.
 
 ### Check what the host app already ships
 
@@ -92,7 +92,7 @@ To override the auto-generated names, expand the plugin entry in `app.json`:
 
 ### Speed up iOS builds with prebuilt Expo modules
 
-Enable `expo-build-properties`'s `ios.usePrecompiledModules` so `pod install` downloads each Expo module as a prebuilt `.xcframework` instead of compiling it from source. `build:ios` detects those xcframeworks under `ios/Pods/` and bundles them into the Swift Package output alongside the brownfield framework, React, Hermes, and `ReactNativeDependencies`.
+SDK 57 enables precompiled Expo modules by default. For a supported SDK where an explicit opt-in is needed, install `expo-build-properties` with `npx expo install expo-build-properties` and enable its `ios.usePrecompiledModules` so `pod install` downloads each Expo module as a prebuilt `.xcframework` instead of compiling it from source. `build:ios` detects those xcframeworks under `ios/Pods/` and bundles them into the Swift Package output alongside the brownfield framework, React, Hermes, and `ReactNativeDependencies`.
 
 ```json
 {
@@ -208,56 +208,52 @@ Not everything is fused: the React Native runtime, Kotlin stdlib, host-common li
 npx expo-brownfield build:ios
 ```
 
-Outputs to `./artifacts`. The set depends on the `ios.buildReactNativeFromSource` flag (set via `expo-build-properties`):
+Outputs to `./artifacts`. Set `ios.buildReactNativeFromSource` on the **`expo-brownfield` plugin**; it applies the build-properties configuration itself and can override a separate `expo-build-properties` entry. The set depends on that setting and the installed package version:
 
-- **`buildReactNativeFromSource: false`** (default on SDK 56+) — React Native is consumed as a prebuilt binary, so `build:ios` emits five xcframeworks side-by-side: `{TargetName}.xcframework`, `React.xcframework`, `ReactNativeDependencies.xcframework`, `ExpoModulesJSI.xcframework`, and `hermesvm.xcframework`.
-- **`buildReactNativeFromSource: true`** (default on SDK 55, opt-in on SDK 56+) — React Native is compiled from source and statically linked into the brownfield framework, leaving two xcframeworks: `{TargetName}.xcframework` and `hermesvm.xcframework`.
+- **`buildReactNativeFromSource: false`** (default on SDK 56+) — React Native is consumed as a prebuilt binary. A typical set includes: `{TargetName}.xcframework`, `React.xcframework`, `ReactNativeDependencies.xcframework`, `ExpoModulesJSI.xcframework`, and `hermesvm.xcframework`.
+- **`buildReactNativeFromSource: true`** (default on SDK 55, opt-in on SDK 56+) — React Native is compiled from source and statically linked into the brownfield framework, typically leaving: `{TargetName}.xcframework` and `hermesvm.xcframework`.
 
-To force source builds on SDK 56+, add `expo-build-properties` to `app.json`:
+To force source builds, configure the brownfield plugin directly in `app.json`:
 
 ```json
 {
   "expo": {
     "plugins": [
       [
-        "expo-build-properties",
+        "expo-brownfield",
         { "ios": { "buildReactNativeFromSource": true } }
-      ],
-      "expo-brownfield"
+      ]
     ]
   }
 }
 ```
 
-**Every xcframework in the produced set must be embedded in the consuming app** (Embed & Sign). The Swift Package output below (`--package`) wires this for you automatically.
+Use the actual output and generated package manifest as the dependency inventory; precompiled modules can add more binaries. Link all required frameworks and **Embed & Sign dynamic frameworks**. Static binaries are linked, not embedded. Do not mix source-linked React Native with another copy already in the host. The Swift Package output below describes the produced dependencies.
 
-> **iOS deployment target:** the brownfield artifact inherits the Expo project's iOS deployment target (16.4 on SDK 56+). The consuming app's deployment target must be set to 16.4 or higher; otherwise Xcode will refuse to link the embedded frameworks. If the host app is on an older floor (e.g. iOS 14.0), bump its `IPHONEOS_DEPLOYMENT_TARGET` before adding the artifact.
+> **iOS deployment target:** compare the host's supported OS versions with the selected Expo/RN version and every produced binary. If the artifact requires a higher floor, resolve that product constraint before integration; changing a build setting cannot make a newer binary support older iOS releases.
 
 #### Ship as a Swift Package (recommended)
 
-Pass `--package [name]` to bundle the output as a self-contained Swift Package instead of separate `.xcframework` directories. The host iOS app then consumes it via **Add Package Dependencies → Add Local** in Xcode and links every bundled framework automatically — no manual drag-and-drop, no per-framework "Embed & Sign" toggles.
+Pass `--package [name]` to generate a local Swift Package around the XCFramework output. Add it with **Add Package Dependencies → Add Local**, then inspect `Package.swift` and select the products the host requires. Packaging layout and products vary by CLI version.
 
 ```sh
 npx expo-brownfield build:ios --release --package MyAppPackage
 ```
 
-The flag accepts an optional name. If omitted, the package is named `{TargetName}Artifacts`. The resulting directory is a complete Swift Package:
+Confirm `--package` in the installed CLI's help before using it. It accepts an optional package name. Inspect the printed output directory and its `Package.swift` instead of assuming the package name also changes the framework/module name (`MyBrownfield` in this guide).
 
-```
-artifacts/MyAppPackage/
-├── Package.swift
-└── xcframeworks/
-    ├── MyAppPackage.xcframework
-    ├── hermesvm.xcframework
-    ├── React.xcframework
-    └── ReactNativeDependencies.xcframework
+Use separate output directories for Debug and Release. The CLI can clear its selected artifacts directory before writing a package, so changing only the package name is not a safe way to preserve the previous flavor:
+
+```sh
+npx expo-brownfield build:ios --debug --artifacts ./artifacts-debug --package MyAppPackage
+npx expo-brownfield build:ios --release --artifacts ./artifacts-release --package MyAppPackage
 ```
 
-When `usePrecompiledModules` is enabled, the package directory is suffixed with the build flavor (e.g. `MyAppPackage-release/`) and includes every prebuilt Expo module xcframework. Run `build:ios --debug --package …` and `build:ios --release --package …` separately, and point your host app at the matching package for each build configuration.
+Build Debug and Release artifacts separately when the producer requires a single flavor per package. A host built in Debug with a Release binary still contains Release RN code; it does not become a Metro-enabled artifact. Swift Package Manager does not select `.binaryTarget(path:)` by Xcode configuration. Select the matching package before each host build, or use explicit build-system wiring that supplies matching binaries; do not link both packages with duplicate module names into one target.
 
 ### Generate native projects for debugging
 
-To inspect or debug the generated native code, run prebuild:
+To inspect the generated native code, run prebuild **from the separate Expo producer whose native directories are CNG-owned**, never from the consuming host:
 
 ```sh
 npx expo prebuild
@@ -349,31 +345,31 @@ startActivity(Intent(this, ExpoActivity::class.java))
 If you built a **Swift Package** (`build:ios --package …`):
 
 - In Xcode, **File → Add Package Dependencies… → Add Local…**, then select the generated package directory (e.g. `artifacts/MyAppPackage/`).
-- Add the package's product to your app target. Xcode links every bundled XCFramework through the aggregate library product — no manual "Embed & Sign" step.
-- If you produced both debug and release packages (because `usePrecompiledModules` is enabled), point the host app at the matching package per build configuration.
+- In `expo-brownfield@57.0.18`, precompiled-module builds generate a configuration-suffixed package/product such as `MyAppPackage-release`; select that aggregate product, which includes the binary targets. The Swift import remains the configured framework module (`MyBrownfield`), not the package name. Without precompiled modules, the CLI generates separate library products: add all required products from `Package.swift`. SDK 55.0.28 likewise exposes separate `MyBrownfield` and `hermesvm` products.
+- If you produced Debug and Release packages, explicitly select the matching dependency before building the host; Xcode does not switch local binary packages automatically.
 
 If you built **standalone XCFrameworks** (default output):
 
 - Drag **every** `.xcframework` produced under `./artifacts` into the Xcode project navigator.
 - In the import dialog, check **Copy items if needed** and add them to your app target.
-- Under the app target's **General** tab → **Frameworks, Libraries, and Embedded Content**, set **every** framework to **Embed & Sign**. Forgetting one (commonly `hermesvm.xcframework`) is a leading cause of runtime "Library not loaded" crashes — see [./troubleshooting.md](./troubleshooting.md#ios-xcframework-signing-isolated-approach).
+- Under the app target's **General** tab → **Frameworks, Libraries, and Embedded Content**, embed and sign the dynamic frameworks; link static binaries without embedding them. For missing runtime dependencies, see [./troubleshooting.md](./troubleshooting.md#ios-xcframework-signing-isolated-approach).
 
 #### Initialize React Native at app launch
 
-Call `ReactNativeHostManager.shared.initialize()` from `AppDelegate` **before any React Native view is created**. Initialization is asynchronous-friendly but must precede the first `ReactNativeViewController`/`ReactNativeView` instantiation.
+Merge `ReactNativeHostManager.shared.initialize()` into the existing launch callback **before any React Native view is created**. Keep the native window and navigation. This delegate example uses the generated framework's `ExpoBrownfieldAppDelegate` to forward lifecycle callbacks; if a custom superclass prevents that, use the delegate-forwarding path in [feature integration](./feature-integration.md#forward-lifecycle-events).
 
 ```swift
 import UIKit
-import MyAppBrownfield // Replace with your target name
+import MyBrownfield // The configured framework target, not the Swift Package name
 
-@main
-class AppDelegate: UIResponder, UIApplicationDelegate {
-  func application(
+// Merge into the existing delegate. Keep its existing @main only for a UIKit entry point.
+class AppDelegate: ExpoBrownfieldAppDelegate {
+  override func application(
     _ application: UIApplication,
     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
   ) -> Bool {
     ReactNativeHostManager.shared.initialize()
-    return true
+    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
   }
 }
 ```
@@ -382,7 +378,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 
 ```swift
 import UIKit
-import MyAppBrownfield
+import MyBrownfield
 
 class ViewController: UIViewController {
   @IBAction func openReactNative(_ sender: Any) {
@@ -406,9 +402,11 @@ let rnViewController = ReactNativeViewController(
 
 #### Present a React Native view (SwiftUI)
 
+Keep the existing `@main struct HostApp: App`. Add `@UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate` there only if the host has no delegate adaptor yet. Extend an existing delegate instead of introducing a second one. This connects initialization and lifecycle forwarding without changing the `WindowGroup`.
+
 ```swift
 import SwiftUI
-import MyAppBrownfield
+import MyBrownfield
 
 struct ContentView: View {
   @State private var showReactNative = false
@@ -436,11 +434,11 @@ Start Metro in the Expo project:
 npx expo start
 ```
 
-Build and run the native app in debug. React Native screens load JS from the Metro dev server over HTTP with full hot reloading. The device or emulator must be able to reach the dev machine — see [./troubleshooting.md](./troubleshooting.md) if Metro connections fail.
+Build a Debug artifact (`npx expo-brownfield build:ios --debug` on iOS), select it in the host, then build and run the native app in Debug. React Native screens load JS from the Metro dev server over HTTP with full hot reloading. The device or emulator must be able to reach the dev machine — see [./troubleshooting.md](./troubleshooting.md) if Metro connections fail.
 
 ### Production (release builds)
 
-The JS bundle is embedded inside the AAR/XCFramework. Metro is not used. Build the native app in Release configuration and confirm the React Native screen loads.
+Build/select the Release artifact and build the host in Release. Stop Metro and verify JS and image assets load, then exercise input, result, dismissal, and reopening using the [acceptance scenario](./feature-integration.md#acceptance-scenario).
 
 ---
 

package/dist/global-skills/expo-brownfield/references/comparison.md

@@ -11,7 +11,7 @@ Use this reference to choose between the two ways of adding React Native + Expo
 - **Choose isolated** if React Native and the native app live in **separate repositories**, or release on **different cadences**.
 - **Choose isolated** if the existing native build is heavily customized (Tuist, Bazel, Buck, custom Gradle plugins) and adding the React Native Gradle plugin or CocoaPods autolinking would be disruptive.
 - **Choose integrated** if a **single team** owns the native and React Native code and is willing to maintain the RN build chain inside the native project.
-- **Choose integrated** if you want **hot reload, JS source maps, and devtools** to "just work" inside the existing native build with no extra orchestration.
+- Both approaches can use **Metro and Fast Refresh** in Debug; choose based on artifact/build ownership.
 - **Choose integrated** if you expect to add many Expo modules and want them autolinked by the standard Expo tooling rather than rebuilt into a fresh artifact each time.
 
 When in doubt — and especially when the question is "can the native team avoid React Native tooling?" — pick **isolated**.
@@ -22,7 +22,7 @@ When in doubt — and especially when the question is "can the native team avoid
 | ---------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
 | What ships to the native app                         | Prebuilt AAR + XCFramework                                              | React Native + Expo sources, autolinked into the existing build       |
 | Native team needs Node / Yarn / RN CLI               | **No**                                                                  | **Yes**                                                               |
-| Build-system footprint                               | Minimal — one Maven dependency, two embedded XCFrameworks               | Pervasive — React Native Gradle plugin, Podfile, autolinking, codegen |
+| Build-system footprint                               | Artifact dependency plus its required runtime libraries               | Pervasive — React Native Gradle plugin, Podfile, autolinking, codegen |
 | Iteration speed for RN devs                          | Fast in isolation; native rebuild needed to pick up new artifact        | Fast end-to-end; one combined build                                   |
 | Dev-time hot reload                                  | Yes (via Metro, when running the consumer app in debug)                 | Yes (native build embeds Metro detection)                             |
 | Production JS bundle location                        | Embedded in the AAR/XCFramework                                         | Embedded in the APK/IPA by the RN Gradle plugin / Xcode build phase   |
@@ -44,10 +44,10 @@ When in doubt — and especially when the question is "can the native team avoid
 → **Isolated.** Removing the dependency removes the framework; the native build is barely touched.
 
 **"Our iOS team uses Tuist and refuses to add Node to the iOS build."**
-→ **Isolated.** Ship an XCFramework. The iOS team adds two `.xcframework` files and one call to `ReactNativeHostManager.shared.initialize()` in `AppDelegate`. No Node, no CocoaPods changes to Expo.
+→ **Isolated.** Ship an XCFramework. The iOS team adds the generated Swift Package or complete XCFramework set and one call to `ReactNativeHostManager.shared.initialize()` in `AppDelegate`. No Node, no CocoaPods changes to Expo.
 
 **"We have one repo, one team, and we want to deeply integrate React Native with the onboarding flow to an existing Android app."**
-→ **Integrated.** Move the existing `android-project` into `my-project/android/`, add the React Native Gradle plugin to `settings.gradle`, register `MainApplication`, and host the flow in a `ReactActivity`. One build pipeline.
+→ **Integrated.** Keep the host layout or place its Gradle root directly at `my-project/android/`, add the React Native Gradle plugin to `settings.gradle`, register `MainApplication`, and host the flow in a `ReactActivity`. One build pipeline.
 
 **"We want to use CNG on the RN code and not worry about manual RN upgrades."**
 → **Isolated.** The AAR/XCFramework approach decouples the Expo RN version from the native app's build, so you can upgrade Expo and React Native independently of the native app's release cycle. The integrated approach requires more coordination between the RN version and the native app's build.
@@ -59,5 +59,5 @@ When in doubt — and especially when the question is "can the native team avoid
 
 ## What is different at runtime
 
-- **Isolated** uses Expo's brownfield runtime wrappers — `ReactNativeHostManager`, `BrownfieldActivity`, `ReactNativeViewController`, `ReactNativeView`. These are generated by `npx expo-brownfield build:*` and bundled into the artifact.
+- **Isolated** uses Expo's brownfield runtime wrappers — `ReactNativeHostManager`, `BrownfieldActivity`, `ReactNativeViewController`, `ReactNativeView`. These are generated by the Expo config plugin and bundled into the artifact.
 - **Integrated** uses the standard React Native runtime — `ReactActivity`, `ReactActivityDelegate`, `RCTReactNativeFactory`, `ExpoReactNativeFactory` — exposed by `react-native` and `expo` directly.

package/dist/global-skills/expo-brownfield/references/feature-integration.md

@@ -0,0 +1,163 @@
+# Integrate a complete native-hosted feature
+
+Read after choosing the build approach. Packaging a framework and displaying its first view are only part of integration: the host also owns presentation, input, results, and lifecycle events.
+
+## Define the boundary
+
+- Use initial props for a presentation's input, including a fresh `requestId` to correlate replies. Use JSON-compatible values rather than Swift objects or JS callbacks.
+- Use messages for events such as context requests, completed, and cancelled. Subscribe before mounting the feature. Keep required startup data in initial props; a message sent during mounting is not a durable inbox or an acknowledgement that the receiving native emitter is ready. Correlate and acknowledge later updates if delivery matters.
+- Keep long-lived business state in its existing owner. If both sides must observe mutable state, inspect the installed `expo-brownfield` shared-state APIs (`useSharedState`, `setSharedStateValue`, and `deleteSharedState`) and native facade. Namespace per-feature keys and clear session data when its owner ends the session. Messages alone do not provide persistent state or delivery guarantees.
+
+## Register the component that receives input
+
+For a small standalone producer, set `package.json`'s `main` to `index.ts` and register a component explicitly. If the scaffold has no TypeScript setup, first run `npx expo install typescript @types/react`:
+
+```ts
+import { registerRootComponent } from 'expo';
+import Feature from './Feature';
+
+registerRootComponent(Feature); // Registers "main", matching the native examples.
+```
+
+Do not overwrite an existing app entry point blindly. A Router-based producer needs an explicit adapter to carry root props into the feature; native `initialProps` are not automatically route parameters.
+
+`Feature.tsx`:
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, Text, View } from 'react-native';
+import * as Brownfield from 'expo-brownfield';
+
+export default function Feature({ requestId, userId, greeting: initialGreeting }: {
+  requestId: string; userId: string; greeting: string;
+}) {
+  const [greeting, setGreeting] = useState(initialGreeting);
+
+  useEffect(() => {
+    const subscription = Brownfield.addMessageListener((event) => {
+      if (event.requestId === requestId && event.type === 'feature.context') {
+        setGreeting(String(event.greeting));
+      }
+    });
+    return () => subscription.remove();
+  }, [requestId]);
+
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', padding: 24 }}>
+      <Text>{greeting}: {userId}</Text>
+      <Button title="Refresh greeting" onPress={() => Brownfield.sendMessage({
+        type: 'feature.request-context', requestId,
+      })} />
+      <Button title="Done" onPress={() => Brownfield.sendMessage({
+        type: 'feature.completed', requestId, selectedId: 'item-42',
+      })} />
+      <Button title="Cancel" onPress={() => Brownfield.sendMessage({
+        type: 'feature.cancelled', requestId,
+      })} />
+    </View>
+  );
+}
+```
+
+## SwiftUI host: receive the result and dismiss
+
+This example uses **Expo's isolated generated framework**, configured as `MyBrownfield`, with `ReactNativeHostManager.shared.initialize()` already connected to the host's app delegate as in [isolated setup](./brownfield-isolated.md). It adds a feature to the existing SwiftUI view hierarchy; it introduces no app entry point.
+
+```swift
+import SwiftUI
+import MyBrownfield
+
+private struct FeatureRequest: Identifiable {
+  let id = UUID().uuidString
+  let userId: String
+}
+
+struct FeatureLauncher: View {
+  @State private var request: FeatureRequest?
+  @State private var listenerId: String?
+  @State private var selectedId: String?
+
+  var body: some View {
+    VStack {
+      Text(selectedId ?? "No selection")
+      Button("Open feature") { openFeature(userId: "123") }
+    }
+    .sheet(item: $request, onDismiss: stopListening) { request in
+      ReactNativeView(
+        moduleName: "main",
+        initialProps: ["requestId": request.id, "userId": request.userId, "greeting": "Hello"]
+      )
+    }
+  }
+
+  private func openFeature(userId: String) {
+    guard request == nil else { return }
+    stopListening()
+    let next = FeatureRequest(userId: userId)
+    listenerId = BrownfieldMessaging.addListener { message in
+      // Messaging callbacks are not a promise of execution on the UI thread.
+      DispatchQueue.main.async {
+        guard request?.id == next.id,
+              message["requestId"] as? String == next.id,
+              let type = message["type"] as? String else { return }
+        switch type {
+        case "feature.request-context":
+          BrownfieldMessaging.sendMessage([
+            "type": "feature.context", "requestId": next.id, "greeting": "Updated hello"
+          ])
+        case "feature.completed":
+          guard let value = message["selectedId"] as? String else { return }
+          selectedId = value
+          closeFeature()
+        case "feature.cancelled":
+          closeFeature()
+        default:
+          break
+        }
+      }
+    }
+    request = next
+  }
+
+  private func closeFeature() {
+    stopListening()
+    request = nil
+  }
+
+  private func stopListening() {
+    if let listenerId {
+      BrownfieldMessaging.removeListener(id: listenerId)
+      self.listenerId = nil
+    }
+  }
+}
+```
+
+The same message contract works with UIKit: the presenting coordinator owns the subscription, passes the request as `initialProps`, handles the result on the main thread, then pops or dismisses its controller. Remove the subscription on interactive cancellation and coordinator teardown too. Remove only the listener you own, not every feature's listeners.
+
+For **integrated** builds, install/autolink `expo-brownfield` only if using these APIs. The isolated plugin's generated `BrownfieldMessaging` facade is not automatically present in the host. In `expo-brownfield` 55.0.28 and 57.0.18, `internal import ExpoBrownfield` (matching the generated module provider) exposes `BrownfieldMessagingInternal.shared` with instance `addListener`, `sendMessage`, and `removeListener(id:)` methods. Confirm the installed Swift interface before adapting the example, or keep a small host adapter around that SDK-specific surface. Use the [integrated controller](./brownfield-integrated.md#present-a-react-native-screen) instead of the isolated `ReactNativeView`.
+
+Navigation behavior depends on the native container. In the SDK 55 and 57 wrappers, the generated UIKit controller handles `popToNative()` by popping its navigation controller, while the generated SwiftUI `ReactNativeView` also listens for that event and calls SwiftUI `dismiss()`. A custom integrated controller does not acquire these handlers automatically. The example above lets the host consume a result before closing its sheet. Use either that result/close contract or the wrapper's navigation API for a given action; do not trigger both.
+
+## Forward lifecycle events
+
+Some modules require launch, URL, notification, and application-state callbacks even when a basic RN view renders successfully.
+
+- **iOS:** use `ExpoAppDelegate` forwarding when compatible with the host's delegate. The isolated generated framework exports `ExpoBrownfieldAppDelegate`; the integrated app uses `ExpoAppDelegate` from `Expo`. Preserve existing override behavior and call the superclass. With a required custom superclass, an isolated host can retain a generated `ExpoBrownfieldAppDelegate` helper and forward the relevant delegate methods to it. An integrated host can use `ExpoAppDelegateSubscriberManager` from `ExpoModulesCore` directly, following the installed SDK's interface. Forward each event once. For scene-based URL handling, connect the existing scene/SwiftUI handler to the module's required callback; an app-delegate adaptor alone does not replace scene delivery.
+- **Android:** preserve `ApplicationLifecycleDispatcher` calls and the activity lifecycle/back handling from the chosen approach. Exercise configuration changes and native back navigation in the host.
+
+Use the [Expo lifecycle guide](https://docs.expo.dev/brownfield/lifecycle-listeners/) and the installed delegate source to choose callbacks. Test the actual modules in use, including warm/cold deep links or push registration where applicable; a first-screen render does not verify these paths.
+
+## Acceptance scenario
+
+1. Build the existing host and record its native launch/navigation behavior before integration.
+2. Build/select the matching Debug artifact (isolated), run Metro in the producer, and open the feature from the native host with identifiable input.
+3. Confirm initial input on screen, then use **Refresh greeting** to verify a later native reply. Complete once: native receives one matching result and closes the feature.
+4. Reopen with a fresh request ID and different input. Verify no stale result or duplicate callback. Cancel through both the RN button and native swipe/back dismissal; repeat.
+5. Build/select the Release artifact and host Release configuration. Stop Metro, launch afresh, and repeat the interaction, including any bundled images/fonts. Check the original native screens and relevant lifecycle callbacks.
+
+For runnable examples of both SwiftUI hosts, see the [iOS brownfield playgrounds](https://github.com/expo/skills/tree/main/tests/fixtures/expo-brownfield).
+
+EAS Build/Submit can distribute the host after this integration works; they do not implement the runtime boundary. EAS Update requires an updates-enabled RN runtime and separate brownfield setup, not just an EAS project ID. Consult the [existing-native-app Update guide](https://docs.expo.dev/eas-update/integration-in-existing-native-apps/) if requested; use the chosen toolchain's setup for isolated artifacts. Updates cannot replace compiled Swift code or add a native module absent from the shipped binary.
+
+Select the matching SDK/API using [version compatibility](./version-compatibility.md). Current reference: [Brownfield API](https://docs.expo.dev/versions/latest/sdk/brownfield/); implementation: [Expo SDK 57 brownfield](https://github.com/expo/expo/tree/sdk-57/packages/expo-brownfield).

package/dist/global-skills/expo-brownfield/references/troubleshooting.md

@@ -6,19 +6,12 @@ Cross-cutting issues that apply to both the isolated and integrated approaches.
 
 **Symptom:** Gradle or Xcode build fails after a config change, dependency upgrade, or Expo SDK bump.
 
-- **Integrated approach** — regenerate native projects from scratch:
-  ```sh
-  npx expo prebuild --clean
-  ```
-  Then `cd ios && pod install` and re-open the `.xcworkspace`.
-- **Isolated approach** — clear the local Maven cache and rebuild the artifact:
-  ```sh
-  rm -rf ~/.m2/repository/<group>/<libraryName>
-  npx expo-brownfield build:android
-  npx expo-brownfield build:ios
-  ```
-- For stubborn iOS issues, also delete `ios/build/`, `ios/Pods/`, and `ios/Podfile.lock`, then re-run `pod install`.
-- For stubborn Android issues, `./gradlew clean` and delete the project's `.gradle/` and `build/` directories.
+First inspect the failing build step and the dependency/configuration diff.
+
+- **Integrated approach:** keep the hand-maintained host intact. Run `npx expo install --check` in the JS project, apply SDK-matched native template changes selectively, then run `bundle exec pod install` (or `pod install` without Bundler) in the host's Podfile directory. Open the `.xcworkspace`. Neither `prebuild` nor `prebuild --clean` is a recovery step for this host: [clean prebuild deletes native directories](https://docs.expo.dev/workflow/continuous-native-generation/#optionality).
+- **Isolated approach:** rebuild the affected platform in the separate Expo producer, then replace the consumer's artifact and its accompanying dependencies. CNG regeneration belongs only in that producer, after checking that its native files are generated and reproducible.
+- For stale iOS build products, clean the affected target's build folder/DerivedData. Preserve `Podfile.lock`; deleting it changes dependency resolution and can hide the cause. Reinstall pods only when the error points to the pod installation.
+- For Android, clean the affected project's build outputs with its Gradle wrapper. Inspect publication coordinates and dependency resolution before removing a specific stale local Maven artifact; do not clear unrelated caches.
 
 ## Missing autolinked Expo modules
 
@@ -42,9 +35,9 @@ Cross-cutting issues that apply to both the isolated and integrated approaches.
 
 **Symptom:** App launches but immediately crashes with "Library not loaded" or codesign errors during archive.
 
-- **Every** xcframework produced by `build:ios` must be set to **Embed & Sign** in the app target's **Frameworks, Libraries, and Embedded Content** section. On SDK 56+ this is five frameworks: `{TargetName}.xcframework`, `React.xcframework`, `ReactNativeDependencies.xcframework`, `ExpoModulesJSI.xcframework`, and `hermesvm.xcframework`. On SDK 55 it's two: `{TargetName}.xcframework` and `hermesvm.xcframework`. Missing any of them is a common cause of runtime crashes.
+- Inspect the actual output and generated `Package.swift`; the framework set depends on package version and source/prebuilt settings, not only the SDK major. Link all required binaries and embed/sign dynamic frameworks. Do not apply **Embed & Sign** to static binaries. See the [artifact instructions](./brownfield-isolated.md#ios).
 - The frameworks must be added to the _app target_, not a framework or extension target.
-- Prefer the Swift Package output (`build:ios --package`) — it links every bundled xcframework through one aggregate product, so you cannot forget one.
+- With Swift Package output (`build:ios --package`), inspect the manifest and link all required products. Precompiled builds on SDK 57 expose an aggregate product; other configurations and older packages can expose separate products. See [version compatibility](./version-compatibility.md).
 
 ## iOS architecture / simulator mismatch
 
@@ -81,8 +74,15 @@ Cross-cutting issues that apply to both the isolated and integrated approaches.
 
 ## After upgrading Expo SDK
 
-If the brownfield setup stops building after an SDK upgrade:
+First check the selected SDK's Node, Xcode, and minimum OS requirements in [version compatibility](./version-compatibility.md). An unsupported compiler or older deployment target is not repaired by clearing caches. If the brownfield setup stops building after an SDK upgrade:
 
 - Re-run `npx expo install --fix` in the Expo project to align native module versions.
-- Rebuild the artifact (isolated) or run `npx expo prebuild --clean` (integrated).
+- Isolated: regenerate only the CNG-owned producer if needed, rebuild its artifact, and update the host dependency. Integrated: apply native upgrade diffs to the existing host and reinstall pods; preserve its source files and project configuration.
 - Compare the new `templates/expo-template-bare-minimum` for the target SDK against your customized native files — Expo occasionally changes Gradle plugin names, Podfile helpers, or AppDelegate entry points across SDKs.
+
+## Result missing, duplicate callbacks, or a sheet that will not close
+
+- Check the module registration and per-presentation request ID. Root props need an explicit JS entry point; do not assume a Router route receives native `initialProps` directly.
+- Attach the host listener before mounting RN and supply required startup data through initial props. For live updates, verify subscription readiness and use acknowledgements where delivery matters; messages are not a durable queue.
+- Remove only this feature's listeners on completion, cancellation, and host dismissal. Dispatch UI changes to the main thread.
+- `popToNative()` depends on the native wrapper: the SDK 55 UIKit controller pops navigation, and its SwiftUI wrapper separately calls `dismiss()`. Custom integrated containers need their own handler. Check which wrapper is actually mounted, or let the host close it on a result/close message. See [feature integration](./feature-integration.md).

package/dist/global-skills/expo-brownfield/references/version-compatibility.md

@@ -0,0 +1,40 @@
+# Select versions before integrating
+
+Keep the workflow version-aware rather than pinning every host to one SDK. Existing projects retain their SDK unless an upgrade is part of the task. New producers should use the current stable Expo release when the host and toolchain can support it.
+
+## Inspect and select
+
+1. Read the producer's `package.json` and lockfile; record resolved `expo`, `react-native`, and `expo-brownfield` versions. Check the host's deployment targets, Xcode/Node versions, and native dependency graph, including any existing RN runtime.
+2. For new work, check the [Expo releases](https://expo.dev/changelog/) and [SDK compatibility table](https://docs.expo.dev/versions/latest/#each-expo-sdk-version-depends-on-a-react-native-version). `npm view expo dist-tags --json` can confirm the current stable `latest` version. Do not infer stability from the highest SDK number or select `canary`/`next` by default.
+3. Select an SDK compatible with the host's supported OS versions, modules, and build tools. Do not silently raise the host's minimum OS or swap its toolchain to satisfy a tutorial. If a constraint conflicts, explain the concrete choices before changing that product requirement.
+4. Use that SDK's versioned Brownfield API docs and `sdk-<major>` native template. Install modules with `npx expo install`; run `npx expo install --check` before native builds. For an SDK upgrade, use `expo-upgrade`, preserve the host, and apply native diffs selectively.
+5. Inspect the **installed** CLI's `build:ios --help` / `build:android --help`, plugin schema, generated Swift/Kotlin wrappers, and `Package.swift`. Flags, prebuilt defaults, import names, and binary products can change within a major release.
+
+To scaffold a small new feature after those checks:
+
+```sh
+npx create-expo-app@latest my-project --template blank@latest
+cd my-project
+npx expo install expo-brownfield typescript @types/react
+```
+
+This avoids adding a Router shell just to export one component. For an existing Router app, preserve it and add the root-props adapter described in [feature integration](./feature-integration.md). If selecting an older SDK, use a verified template tag such as `blank@sdk-55`; the scaffolder's own `@latest` version does not determine the template's SDK. Commit the producer's lockfile for repeatable builds.
+
+## SDK requirements and build defaults
+
+| Surface | SDK 55 | SDK 57 |
+| --- | --- | --- |
+| React Native family | 0.83 | 0.86 |
+| iOS minimum in the Expo template | 15.1 | 16.4 |
+| Documented minimum Node / Xcode | 20.19.x / 26.2 | 22.13.x / 26.4 |
+| Brownfield React Native build default | Source | Prebuilt |
+| Precompiled Expo modules | Version/configuration dependent | Enabled by default in the native template |
+| Swift Package products | 55.0.28: separate feature and Hermes products | 57.0.18: one aggregate product when precompiled modules are detected; otherwise separate products |
+
+React Native prebuilt binaries and precompiled Expo modules are separate settings. Set React Native source mode on `expo-brownfield`'s `ios.buildReactNativeFromSource`. Expo module precompilation is controlled by `expo-build-properties`' `ios.usePrecompiledModules`. Do not disable defaults as a generic build fix; first inspect the failing dependency and toolchain requirement.
+
+In 57.0.18, precompiled builds suffix the generated package/product with its configuration (`MyAppPackage-release` or `MyAppPackage-debug`). They do not rename the generated Swift module: continue to import the configured target, such as `MyBrownfield`. Inspect the emitted manifest instead of constructing an assumed package path.
+
+SDK 56 introduced additional brownfield capabilities carried into SDK 57, including experimental multiple isolated frameworks and registering host Turbo Module classes. Load the selected SDK's API and installed interfaces only when the task needs them. Do not enable experimental multi-framework support for a single feature or assume two independently packaged RN runtimes can be linked together without collision handling.
+
+Sources: [SDK requirements](https://docs.expo.dev/versions/latest/), [SDK 57 Brownfield API](https://docs.expo.dev/versions/v57.0.0/sdk/brownfield/), [SDK 57 native template](https://github.com/expo/expo/tree/sdk-57/templates/expo-template-bare-minimum), [SDK 56 brownfield additions](https://expo.dev/changelog/sdk-56), [published Brownfield package](https://www.npmjs.com/package/expo-brownfield).

package/dist/global-skills/expo-data-fetching/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: expo-data-fetching
-description: Framework (OSS). Use when implementing or debugging ANY network request, API call, or data fetching. Covers fetch API, React Query, SWR, error handling, caching, offline support, and Expo Router data loaders (`useLoaderData`).
+description: Framework (OSS). Use when implementing or debugging ANY network request, API call, or data fetching. Covers fetch API, React Query, SWR, error handling, caching, offline support, loading/empty/error screen states, and Expo Router data loaders (`useLoaderData`).
 version: 1.0.0
 license: MIT
 ---
@@ -36,6 +36,17 @@ Use this skill when:
 
 - Avoid axios, prefer expo/fetch
 
+## Every Screen Has Four States
+
+Design **loading**, **error**, **empty**, and **content** for screens that load data. These can overlap: a refresh error should coexist with cached content.
+
+- **Loading ≠ empty.** Empty means *resolved with zero items*, not missing data. Handle initial loading, failure, and hydration before checking list length. In TanStack Query v5, `isLoading` means the first fetch is running; a disabled or offline-paused query can have no data without being loading. Show the prerequisite or offline state in that case.
+- **Empty is a designed state, not a blank list.** Use `ListEmptyComponent` on FlatList/FlashList: explain why it is empty and offer the relevant next action. "No items yet" can offer Create; "No results" should offer changing or clearing the search/filter.
+- **Refetches keep stale content.** Render cached `data` even if a refresh fails, with a nonblocking error and retry. Use `isLoading` for first-fetch spinners and `isFetching` for background activity; prefer a skeleton for a slow initial load with a known layout, and `RefreshControl` for user-initiated refresh.
+- **Gate on hydration.** When initial UI or a redirect depends on persisted state (auth token, onboarding flag), the root layout renders nothing - or the splash - until that state has loaded. Deciding on unhydrated state flashes the wrong screen on every cold start and misroutes deep links that arrive before hydration.
+
+**Saves preserve work.** While a mutation is pending, disable repeat submission. On failure, retain the draft, show an inline error, and let the user retry; clear or dismiss only after success. If updating optimistically, restore the previous value or mark the edit as unsynced on failure. Verify with a failed save followed by retry.
+
 ## Common Issues & Solutions
 
 ### 1. Basic Fetch Usage
@@ -110,15 +121,23 @@ export default function RootLayout() {
 import { useQuery } from "@tanstack/react-query";
 
 function UserProfile({ userId }: { userId: string }) {
-  const { data, isLoading, error, refetch } = useQuery({
+  const { data, fetchStatus, error, refetch } = useQuery({
     queryKey: ["user", userId],
     queryFn: () => fetchUser(userId),
   });
 
-  if (isLoading) return <Loading />;
-  if (error) return <Error message={error.message} />;
+  if (data === undefined) {
+    if (error) return <ErrorState message={error.message} onRetry={() => refetch()} />;
+    if (fetchStatus === "paused") return <OfflineState />;
+    return <Loading />;
+  }
 
-  return <Profile user={data} />;
+  return (
+    <>
+      {error && <InlineError message="Could not refresh. Showing saved data." onRetry={() => refetch()} />}
+      {data === null ? <EmptyState message="User not found" /> : <Profile user={data} />}
+    </>
+  );
 }
 ```
 
@@ -139,10 +158,12 @@ function CreateUserForm() {
   });
 
   const handleSubmit = (data: UserData) => {
+    if (mutation.isPending) return;
     mutation.mutate(data);
   };
 
-  return <Form onSubmit={handleSubmit} isLoading={mutation.isPending} />;
+  // Form keeps its draft on error and disables Submit while isLoading.
+  return <Form onSubmit={handleSubmit} isLoading={mutation.isPending} error={mutation.error?.message} />;
 }
 ```