create-disposabl-app 0.0.4 → 0.1.1

package/dist/templates/default/apps/mobile/.agents/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/templates/default/apps/mobile/.agents/skills/expo-brownfield/references/troubleshooting.md

@@ -0,0 +1,88 @@
+# Brownfield Troubleshooting
+
+Cross-cutting issues that apply to both the isolated and integrated approaches. For approach-specific setup, see [./brownfield-isolated.md](./brownfield-isolated.md) or [./brownfield-integrated.md](./brownfield-integrated.md).
+
+## Build failures
+
+**Symptom:** Gradle or Xcode build fails after a config change, dependency upgrade, or Expo SDK bump.
+
+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
+
+**Symptom:** Compilation succeeds but a module throws "Native module cannot be null" / "Cannot find native module 'X'" at runtime.
+
+- Install with `npx expo install <package>` rather than plain `yarn add` — `expo install` picks the version compatible with the current SDK.
+- After installing a new module, rebuild the native app. Autolinking runs at native build time, not at JS bundle time.
+- For the **isolated approach**, you must re-run `npx expo-brownfield build:android|ios` after adding a module, and republish/re-embed the new artifact.
+
+## Metro connection
+
+**Symptom:** "Could not connect to development server" / red screen on launch in debug.
+
+- Ensure the device or emulator can reach the dev machine. The Android emulator can talk to the host via `10.0.2.2`; physical devices need a reachable LAN IP.
+- For physical Android devices on USB: `adb reverse tcp:8081 tcp:8081`.
+- Confirm Metro is actually running: `npx expo start` from the Expo project (or `yarn start` from the workspace root).
+- Verify the debug `AndroidManifest.xml` enables cleartext traffic — Android 9+ blocks HTTP by default. The debug variant should include `android:usesCleartextTraffic="true"` on `<application>`, or a `network_security_config` allowing the dev server.
+- iOS simulator: Metro should be reachable at `localhost:8081`. If it is not, check that ATS exceptions are still in place in `Info.plist` for `localhost` (the Expo template ships this by default).
+
+## iOS XCFramework signing (isolated approach)
+
+**Symptom:** App launches but immediately crashes with "Library not loaded" or codesign errors during archive.
+
+- 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.
+- 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
+
+**Symptom:** "Building for iOS Simulator, but the linked library was built for iOS" or "Undefined symbols for architecture arm64".
+
+- The XCFramework includes both device and simulator slices. If a slice is missing, rebuild on the missing platform. The `expo-brownfield build:ios` command produces both by default.
+- On Apple Silicon simulators, do **not** set `EXCLUDED_ARCHS = arm64` for the simulator configuration — Apple Silicon simulators require `arm64`. The classic Rosetta-only exclusion is no longer correct.
+
+## Android `mavenLocal()` not found (isolated approach)
+
+**Symptom:** Gradle reports "Could not find com.example:mybrownfield:1.0.0" even after a successful `expo-brownfield build:android`.
+
+- `mavenLocal()` must be declared under `dependencyResolutionManagement { repositories { ... } }` in `settings.gradle.kts`, not the deprecated top-level `allprojects { repositories { ... } }` block. The deprecated form is silently ignored when `dependencyResolutionManagement` is present.
+- Confirm the artifact actually landed in `~/.m2`:
+  ```sh
+  find ~/.m2/repository -name "mybrownfield*"
+  ```
+- Verify the `group` and `libraryName` in the consumer's dependency line match what the plugin config emitted.
+
+## Module name mismatch
+
+**Symptom:** The native view loads but renders a blank screen, with "Application 'X' has not been registered" in the JS logs.
+
+- The `moduleName` passed to `ReactNativeViewController(moduleName: "main")` (iOS) or returned from `getMainComponentName()` (Android) must equal the name passed to `AppRegistry.registerComponent("main", () => App)` in the JS entry point.
+- The default Expo template registers `"main"`. If you changed the registration, update every native call site.
+
+## Monorepo: autolinking can't find the Expo project
+
+**Symptom:** Gradle or CocoaPods fails resolving Expo modules even though they are installed.
+
+- **Android (integrated):** set `root = file("../../my-project")` (or the correct relative path) inside the `react { ... }` block in `app/build.gradle`, and explicitly set the project root in `settings.gradle` before `expoAutolinking.useExpoModules()`.
+- **iOS (integrated):** set `:app_path` in `use_react_native!` to the absolute path of the Expo project root. Optionally pass `EXPO_PROJECT_ROOT=/abs/path` to `pod install`.
+- Confirm `node_modules/` is installed at the workspace root (`yarn install` from the monorepo root, not from the Expo project subdirectory).
+
+## After upgrading Expo SDK
+
+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.
+- 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/templates/default/apps/mobile/.agents/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).