0048. On native, effects cross one JSON bridge, and an effect not built for native fails the build
- Status: Proposed
- Date: 2026-11-14
- Decided by: native emit domain (internal only), pending Mik's approval
- Planning item: WP11 (native effects)
Context
Decision 0050 splits each effect into an app-facing half in TypeScript and a platform half per platform. The native build bundled @duolith/effects' web code, so on a device storage meant localStorage and share meant navigator.share. Nothing reached the Kotlin and Swift halves in native/*/effects, and --target native wrote no permission declarations.
Decision
- One module, two methods. Each shell registers a Lynx native module,
DuolithEffects, withcall(effect, method, argsJson)for what the platform answers at once andcallAsync(effect, method, argsJson, done)for what waits on the user or the system. Arguments are the contract's own, as a JSON array. An answer is{"value": …}or{"error": {"code", "message"}}with a catalogue code. What a platform reports by itself (storage changed elsewhere, the app went to the background) arrives as theduolithEffectglobal event, with{effect, event, value}. - One bridge per platform.
EffectsBridge(native/android/effects/ Bridge.kt,native/ios/effects/Bridge.swift) holds the dispatch table. The shell module only forwards to it. - The native bundle swaps the platform halves only. The engine's bundle aliases
@duolith/effectstopackages/effects/src/native, which builds the same app-facing halves with platforms that call the bridge (callPlatform,callPlatformLaterandonPlatformEventfrom@duolith/engine). No web platform code is bundled. - Built for native is in the catalogue.
spec/effects/effects.yamlmarks withnative: trueeach effect that has both halves on both platforms. Importing any other effect in a native build is E0202, an error naming the effect and listing those that are built. Nothing falls back to the web code. - Declarations.
--target nativeruns the same effects analysis as the web build and writesnative/android/AndroidManifest.permissions.xmlandnative/ios/Info.permissions.plistinto the build. Gradle merges the first through the debug and release source sets. The iOS project merges the second into the built Info.plist with PlistBuddy. - The first-screen render does nothing. ReactLynx renders the first screen on Lynx's main thread, which has no native modules. There the bridge answers
null, a promise that never settles, and no events. The background thread's render replaces it.
Consequences
- Seven effects work on native: storage, secureStorage, permissions, share, haptics, lifecycle and minimumVersion. signIn, push, purchases and camera fail the native build until their halves are written.
- Lynx for Web checks the TypeScript side end to end with a fake module (
packages/engine/test/native-effects-in-browser.test.ts). The Kotlin halves compile in the Android build. The Swift halves have not been compiled: there was no Swift toolchain. Device behaviour is innative/DEVICE-CHECKLIST.md. permissions.request("camera")without the camera effect declares no camera permission, so Android answers "denied". This follows decision 0051: declarations come from the effects an app imports.