@klera/native-driver-ios

In-app native DeviceDriver for iOS — the preferred device-action path for klera flows (ADR-0019). Ships as an Expo Module auto-linked via its config plugin; apps still on Expo Go fall back to the engine's idb-backed driver automatically.

Requirements

klera requires React Native's New Architecture (Bridgeless / Fabric, default since RN 0.74) — see ADR-0036. The runtime probes global.RN$Bridgeless at start-up and refuses to connect on Old Architecture. This native driver itself is architecture-agnostic at the UIKit layer (UIApplication.shared, UIAlertController, etc. are unchanged across architectures), but it only ever ships against hosts the runtime accepts.

Installing

npm install --save-dev @klera/native-driver-ios

Add the config plugin to your app.json:

{
  "expo": {
    "plugins": ["@klera/native-driver-ios"]
  }
}

Then prebuild and rebuild the iOS project:

npx expo prebuild --platform ios
npm run ios

Wiring

Pass KleraDriver to RuntimeClient alongside the usual provider and dispatcher:

import { RuntimeClient } from "@klera/runtime";
import { KleraDriver } from "@klera/native-driver-ios";

const client = new RuntimeClient({
  url: "ws://127.0.0.1:7345",
  info: { runtimeVersion: "1.0.0", platform: "ios", appId: "com.example.app" },
  provider,
  dispatcher,
  deviceDriver: KleraDriver,
});

When a dismissAlert step runs, the engine sends a device_action over the existing WebSocket bridge; the runtime hands it to KleraDriver.execute, which calls the Swift module via the Expo Module bridge; UIKit does the tap on the real UIAlertController.

Capabilities shipped

• ✅ dismissAlert(label) — taps the UIAlertAction whose title matches label. Works for both .alert and .actionSheet styles.

See docs/compatibility-matrix.md at the repo root for the wider parity roadmap. Each capability wave adds a method here + a matching branch in the JS wrapper + a Swift implementation.

Dev-only

The podspec flags this module as dev-only via the KLERA_DEV_ONLY compile flag. The Swift code uses one non-public UIKit API (UIAlertAction.handler) — the same pattern Detox, Appium, and EarlGrey use. Keep the module in devDependencies so release builds never link it.

Behaviour when unlinked

If the native module is not linked (Expo Go, Android build, production build that skipped the pod), requireNativeModule throws at call time. The runtime catches this and replies to the bridge with no_driver_linked, which the engine's composite driver interprets as "fall back to idb". No flow changes required — the same YAML runs against the same engine regardless of which driver answered.