@orqo/foundationmodels-react-native

React Native / Expo TurboModule host that maps the FoundationModels JS contract to FoundationModelsIOSBridge in-process (ADR-0002 / SPC-0065).

| Layer | Path | Role | |---|---|---| | JS client | src/client.ts | health / availability / respond | | Native host | ios/FoundationModelsReactNativeModule.swift | Expo module → FoundationModelsBridge.shared | | Swift core | swift/ios-bridge + swift/FoundationModelsCore | Real Core (not a stub — SPC-0064) | | Tests | test/ | Mock native module — no device required |

This package is the host glue residual named in docs/ios.md. It does not change the macOS daemon path or the public @orqo/foundationmodels API.

Install (monorepo / app)

# From an Expo (or RN) app that can see this monorepo
pnpm add @orqo/foundationmodels-react-native
# peer (Expo)
pnpm add expo-modules-core

1. Link local Swift packages

In the Xcode / Expo ios project, add local Swift packages:

1. swift/FoundationModelsCore
2. swift/ios-bridge (product FoundationModelsIOSBridge)

Platforms: iOS 27+ (matches Core). See docs/ios.md.

The podspec (ios/FoundationModelsReactNative.podspec) exports:

• FOUNDATIONMODELS_IOS_BRIDGE_PATH
• FOUNDATIONMODELS_CORE_PATH

pointing at those monorepo paths when this package lives inside the repo checkout.

2. Autolinking (Expo)

expo-module.config.json registers FoundationModelsReactNativeModule. After install:

npx pod-install
# or: cd ios && pod install

3. Use from JS / TS

import {
  createFoundationModelsNativeClient,
  createMockNativeModule,
  isNativeHostAvailable,
  registerNativeModule,
  NATIVE_MODULE_NAME
} from "@orqo/foundationmodels-react-native";

// Production (device / iOS simulator with host linked)
const client = createFoundationModelsNativeClient();

const health = await client.health();
// health.stub === false, health.transport === "in-process"

const availability = await client.availability();

const result = await client.respond({
  input: "Hello",
  config: {
    modelId: "apple.system",
    maximumResponseTokens: 128,
    temperature: 0.2
  }
});

Tests / CI without a device

import {
  createFoundationModelsNativeClient,
  createMockNativeModule
} from "@orqo/foundationmodels-react-native";

const client = createFoundationModelsNativeClient({
  nativeModule: createMockNativeModule()
});

await client.health();     // non-stub mock shape
await client.respond({ input: "ping" });

Or register once for the process:

registerNativeModule(createMockNativeModule());
const client = createFoundationModelsNativeClient();

Native surface

| JS method | Swift | |---|---| | health() | FoundationModelsBridge.shared.health() | | availability() | FoundationModelsBridge.shared.availability() | | respond(input, config?) | FoundationModelsBridge.shared.respond(input:config:) |

Module name: FoundationModelsReactNative (NATIVE_MODULE_NAME).

Classic TurboModule (non-Expo)

Expo is the default host. A classic RN New Architecture TurboModule should export the same three methods under the same module name; the JS resolver checks TurboModuleRegistry and NativeModules after Expo.

Build / test (this package)

# From monorepo root
pnpm --filter @orqo/foundationmodels-react-native install
pnpm --filter @orqo/foundationmodels-react-native build
pnpm --filter @orqo/foundationmodels-react-native test
pnpm --filter @orqo/foundationmodels-react-native typecheck

Swift bridge (separate, requires Xcode + macOS 27 SDK tooling):

swift test --package-path swift/ios-bridge
swift build --package-path swift/ios-bridge

Out of scope (SPC-0065)

• App Store submit / entitlements packaging
• Full agent UI
• Changing the public macOS TS package API
• Shipping a prebuilt XCFramework of the bridge (consumer links monorepo SPM paths)

Author

Cristiano Aredes — sole author and maintainer.

• GitHub: @cristianoaredes
• X: @CristianoAredes
• LinkedIn: Cristiano Aredes

Part of FoundationModels JS.

License

AGPL-3.0-only — see LICENSE. Copyright © 2026 Cristiano Aredes.

Network clause (AGPL §13): modified versions offered as a network service must provide Corresponding Source to users of that service.