@lynxship/expo 0.1.7 → 0.1.8

package/README.md

@@ -134,12 +134,47 @@ export function LynxScreen() {
       style={{ flex: 1 }}
       bundle="main.lynx.bundle"
       initialData="{}"
+      globalProps={{ theme: "dark" }}
+      autoGlobalProps
       reloadOnUpdate
     />
   );
 }
 ```
 
+`globalProps` is passed to `lynx.__globalProps` during the native template
+load. It can also be changed without remounting the React Native screen. The
+native ref exposes the same host controls on Android and iOS:
+
+```tsx
+const viewRef = useRef<LynxViewRef>(null);
+
+viewRef.current?.updateData('{"screen":"inbox"}');
+viewRef.current?.updateGlobalProps({ theme: "light" });
+viewRef.current?.updateGlobalPropsByIncrement({ unreadCount: 3 });
+viewRef.current?.sendGlobalEvent("accountChanged", [{ id: "user-1" }]);
+await viewRef.current?.reload();
+```
+
+`updateData` uses Lynx's official host-data update API and accepts a JSON
+string up to 8 MiB without remounting the view. Its optional second argument
+selects a registered Lynx data processor. `show`, `hide` and
+`updateViewport({ width, height })` are also available.
+`updateGlobalPropsByIncrement` applies only the supplied keys and is useful for
+small host-state changes; `updateGlobalProps` remains the full replacement API.
+The ref also exposes `getContainerId()`, `getLoadState()` and
+`isLoadSuccess()`, matching the native container state contract without
+requiring a React remount.
+The viewport is updated automatically from the native view layout, so the
+usual `style={{ flex: 1 }}` remains the recommended layout. The native view
+owns the Lynx lifecycle and is destroyed when Expo releases the view; this
+prevents an old page/runtime from surviving React reconciliation.
+
+The view also exposes lifecycle events that can drive application-owned UI:
+`onLoadStart`, `onResourceFetchStart`, `onLoadSuccess`, `onReady` (first screen), `onError`, `onUpdate` (OTA or non-remounting data update),
+`onShow` and `onHide`. The events are notifications only; they do not replace
+the native permission, navigation or OTA policy owned by the host.
+
 The native module initializes Lynx, creates the official `LynxView`, and
 provides a template provider. The provider first reads the verified active OTA
 asset and falls back to the embedded bundle. An OTA release is accepted only
@@ -190,8 +225,13 @@ the provider is the integration point for the LynxShip OTA cache.
 
 References:
 
-- [Lynx integration with existing apps](https://lynxjs.org/3.8/guide/start/integrate-with-existing-apps.html)
+- [Lynx/Rspeedy existing-app integration](https://lynxjs.org/next/rspeedy/start/integrate-with-existing-apps)
+- [Lynx native `LynxView` API](https://lynxjs.org/next/api/lynx-native-api/lynx-view/lynx-view.html)
+- [Lynx global props](https://lynxjs.org/next/api/lynx-api/lynx/lynx-global-props.html)
+- [Lynx global events](https://lynxjs.org/next/api/lynx-native-api/lynx-view/send-global-event.html)
+- [Lynx native viewport API](https://lynxjs.org/next/api/lynx-native-api/lynx-view/update-viewport.html)
 - [Expo native view modules](https://docs.expo.dev/modules/native-view-tutorial/)
+- [Expo view refs and async functions](https://docs.expo.dev/modules/module-api/)
 - [Expo module configuration](https://docs.expo.dev/modules/module-config/)
 - [LynxShip OTA security and compatibility](../../docs/compatibility.md)
 

package/android/build.gradle

@@ -42,6 +42,7 @@ android {
 
 dependencies {
     implementation "org.lynxsdk.lynx:lynx:${lynxVersion}"
+    implementation "androidx.annotation:annotation:1.10.0"
     implementation "org.lynxsdk.lynx:lynx-jssdk:${lynxVersion}"
     implementation "org.lynxsdk.lynx:lynx-trace:${lynxVersion}"
     implementation "org.lynxsdk.lynx:primjs:${lynxVersion}"

package/android/src/main/java/com/lynxship/expo/LynxShipExpoModule.kt

@@ -8,14 +8,22 @@ class LynxShipExpoModule : Module() {
         Name("LynxShip")
 
         View(LynxShipExpoView::class) {
-            Events("onReady", "onError", "onUpdate")
+            Events("onReady", "onLoadStart", "onResourceFetchStart", "onLoadSuccess", "onError", "onUpdate", "onShow", "onHide")
 
             Prop("bundle") { view: LynxShipExpoView, value: String? ->
-                view.bundleName = value ?: "main.lynx.bundle"
+                view.setBundleName(value ?: "main.lynx.bundle")
             }
 
             Prop("initialData") { view: LynxShipExpoView, value: String? ->
-                view.initialData = value ?: ""
+                view.setInitialData(value ?: "")
+            }
+
+            Prop("globalProps") { view: LynxShipExpoView, value: Map<String, Any?>? ->
+                view.updateGlobalProps(value ?: emptyMap())
+            }
+
+            Prop("autoGlobalProps") { view: LynxShipExpoView, value: Boolean? ->
+                view.autoGlobalProps = value ?: true
             }
 
             Prop("reloadOnUpdate") { view: LynxShipExpoView, value: Boolean? ->
@@ -25,6 +33,46 @@ class LynxShipExpoModule : Module() {
             AsyncFunction("reload") { view: LynxShipExpoView ->
                 view.reload()
             }
+
+            AsyncFunction("getContainerId") { view: LynxShipExpoView ->
+                view.getContainerId()
+            }
+
+            AsyncFunction("getLoadState") { view: LynxShipExpoView ->
+                view.getLoadState()
+            }
+
+            AsyncFunction("isLoadSuccess") { view: LynxShipExpoView ->
+                view.isLoadSuccess()
+            }
+
+            AsyncFunction("updateData") { view: LynxShipExpoView, data: String, processorName: String? ->
+                view.updateData(data, processorName)
+            }
+
+            AsyncFunction("updateGlobalProps") { view: LynxShipExpoView, props: Map<String, Any?> ->
+                view.updateGlobalProps(props)
+            }
+
+            AsyncFunction("updateGlobalPropsByIncrement") { view: LynxShipExpoView, props: Map<String, Any?> ->
+                view.updateGlobalPropsByIncrement(props)
+            }
+
+            AsyncFunction("sendGlobalEvent") { view: LynxShipExpoView, eventName: String, params: List<Any?> ->
+                view.sendGlobalEvent(eventName, params)
+            }
+
+            AsyncFunction("show") { view: LynxShipExpoView -> view.show() }
+
+            AsyncFunction("hide") { view: LynxShipExpoView -> view.hide() }
+
+            AsyncFunction("updateViewport") { view: LynxShipExpoView, viewport: Map<String, Double> ->
+                view.updateViewport(viewport["width"] ?: 0.0, viewport["height"] ?: 0.0)
+            }
+
+            OnViewDestroys { view: LynxShipExpoView ->
+                view.release()
+            }
         }
     }
 }

package/android/src/main/java/com/lynxship/expo/LynxShipExpoView.kt

@@ -3,8 +3,16 @@ package com.lynxship.expo
 import android.app.Application
 import android.content.Context
 import android.content.SharedPreferences
+import android.content.res.Configuration
 import android.os.Bundle
+import android.os.Build
+import android.os.PowerManager
 import android.provider.Settings
+import android.view.View
+import android.view.View.MeasureSpec
+import android.view.WindowInsets
+import android.view.accessibility.AccessibilityManager
+import com.lynx.react.bridge.JavaOnlyArray
 import com.facebook.drawee.backends.pipeline.Fresco
 import com.facebook.imagepipeline.core.ImagePipelineConfig
 import com.facebook.imagepipeline.memory.PoolConfig
@@ -13,6 +21,10 @@ import com.lynx.service.http.LynxHttpService
 import com.lynx.service.image.LynxImageService
 import com.lynx.service.log.LynxLogService
 import com.lynx.tasm.LynxEnv
+import com.lynx.tasm.LynxError
+import com.lynx.tasm.LynxLoadMeta
+import com.lynx.tasm.LynxUpdateMeta
+import com.lynx.tasm.TemplateData
 import com.lynx.tasm.LynxView
 import com.lynx.tasm.LynxViewClient
 import com.lynx.tasm.LynxViewBuilder
@@ -30,13 +42,19 @@ import java.util.UUID
 class LynxShipExpoView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
     private val applicationContext = context.applicationContext
     private val onReady by EventDispatcher()
+    private val onLoadStart by EventDispatcher()
+    private val onResourceFetchStart by EventDispatcher()
+    private val onLoadSuccess by EventDispatcher()
     private val onError by EventDispatcher()
     private val onUpdate by EventDispatcher()
+    private val onShow by EventDispatcher()
+    private val onHide by EventDispatcher()
     private val preferences: SharedPreferences = applicationContext.getSharedPreferences("lynxship-expo", Context.MODE_PRIVATE)
     private val metadata: Bundle = applicationContext.applicationInfo.metaData ?: Bundle()
     private val otaClient = createOtaClient(applicationContext)
     private val templateProvider = object : AbsTemplateProvider() {
         override fun loadTemplate(uri: String, callback: Callback) {
+            post { onResourceFetchStart(mapOf("bundle" to uri)) }
             Thread {
                 try {
                     val bytes = otaClient?.openActiveAsset(uri) ?: readEmbeddedAsset(uri)
@@ -49,9 +67,21 @@ class LynxShipExpoView(context: Context, appContext: AppContext) : ExpoView(cont
         }
     }
     private val lynxView: LynxView
-    var bundleName: String = metadata.getString("com.lynxship.expo.embeddedBundle", "main.lynx.bundle")
-    var initialData: String = ""
+    private var bundleNameValue: String = metadata.getString("com.lynxship.expo.embeddedBundle", "main.lynx.bundle")
+    private var initialDataValue: String = ""
+    private var globalProps: Map<String, Any?> = emptyMap()
     var reloadOnUpdate: Boolean = true
+    var autoGlobalProps: Boolean = true
+        set(value) {
+            field = value
+            if (hasRendered) pushGlobalProps()
+        }
+    private var hasRendered = false
+    private var loadState = "idle"
+    private var started = false
+    private val containerId = UUID.randomUUID().toString()
+    private val containerInitTime = System.currentTimeMillis().toString()
+    private var appInBackground = false
 
     init {
         initializeLynx(context)
@@ -59,13 +89,26 @@ class LynxShipExpoView(context: Context, appContext: AppContext) : ExpoView(cont
         // application context only for process-wide services and storage.
         lynxView = LynxViewBuilder().setTemplateProvider(templateProvider).build(context)
         lynxView.addLynxViewClient(object : LynxViewClient() {
+            override fun onPageStart(url: String?) {
+                loadState = "loading"
+                onLoadStart(mapOf("bundle" to (url ?: bundleNameValue)))
+            }
+
             override fun onFirstScreen() {
+                loadState = "loaded"
                 try {
                     otaClient?.markLaunchSuccess()
                 } catch (error: IOException) {
                     onError(mapOf("message" to (error.message ?: "Could not record Lynx launch"), "recoverable" to true))
                 }
-                onReady(mapOf("bundle" to bundleName, "sequence" to (otaClient?.activeSequence() ?: 0)))
+                val event = mapOf("bundle" to bundleNameValue, "sequence" to (otaClient?.activeSequence() ?: 0))
+                onLoadSuccess(event)
+                onReady(event)
+            }
+
+            override fun onReceivedError(error: LynxError) {
+                loadState = "failed"
+                onError(mapOf("message" to error.toString(), "recoverable" to false))
             }
         })
         addView(lynxView, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
@@ -73,27 +116,238 @@ class LynxShipExpoView(context: Context, appContext: AppContext) : ExpoView(cont
 
     override fun onAttachedToWindow() {
         super.onAttachedToWindow()
+        lynxView.onEnterForeground()
+        onShow(emptyMap<String, Any>())
+        if (started) return
+        started = true
         try {
             otaClient?.beginLaunch()
             installUpdateInBackground()
-            render()
+            if (!hasRendered) render()
         } catch (error: Exception) {
             onError(mapOf("message" to (error.message ?: "Lynx startup failed")))
         }
     }
 
+    override fun onDetachedFromWindow() {
+        lynxView.onEnterBackground()
+        onHide(emptyMap<String, Any>())
+        super.onDetachedFromWindow()
+    }
+
     fun reload() {
         render()
     }
 
+    fun getContainerId(): String = containerId
+
+    fun getLoadState(): String = loadState
+
+    fun isLoadSuccess(): Boolean = loadState == "loaded"
+
+    fun updateData(data: String, processorName: String? = null) {
+        require(data.length <= 8 * 1024 * 1024) { "Lynx update data is larger than 8 MiB" }
+        check(hasRendered) { "Lynx view has not loaded a bundle" }
+        if (processorName != null) {
+            require(processorName.isNotBlank() && processorName.length <= 256 && processorName.none { it.isISOControl() }) {
+                "Lynx data processor name is invalid"
+            }
+        }
+        val templateData = TemplateData.fromString(data)
+        processorName?.let(templateData::markState)
+        val builder = LynxUpdateMeta.Builder()
+        builder.setUpdatedData(templateData)
+        lynxView.updateMetaData(builder.build())
+        initialDataValue = data
+        onUpdate(mapOf("bundle" to bundleNameValue, "reason" to "data"))
+    }
+
+    fun setBundleName(value: String) {
+        if (value == bundleNameValue) return
+        bundleNameValue = value
+        if (started) render()
+    }
+
+    fun setInitialData(value: String) {
+        if (value == initialDataValue) return
+        initialDataValue = value
+        if (started) render()
+    }
+
+    fun updateGlobalProps(props: Map<String, Any?>) {
+        globalProps = props.toMap()
+        pushGlobalProps()
+    }
+
+    fun updateGlobalPropsByIncrement(props: Map<String, Any?>) {
+        if (props.isEmpty()) return
+        globalProps = buildMap {
+            putAll(globalProps)
+            putAll(props)
+        }
+        lynxView.updateGlobalProps(TemplateData.fromMap(props))
+    }
+
+    fun sendGlobalEvent(eventName: String, params: List<Any?>) {
+        require(eventName.isNotBlank()) { "Lynx global event name cannot be blank" }
+        require(eventName.length <= 256) { "Lynx global event name is too long" }
+        require(params.size <= 256) { "Lynx global event payload is too large" }
+        lynxView.sendGlobalEvent(
+            eventName,
+            JavaOnlyArray.from(params),
+        )
+    }
+
+    fun show() {
+        visibility = View.VISIBLE
+    }
+
+    fun hide() {
+        visibility = View.INVISIBLE
+    }
+
+    fun updateViewport(width: Double, height: Double) {
+        require(width.isFinite() && height.isFinite() && width >= 0 && height >= 0) {
+            "Lynx viewport dimensions must be finite and non-negative"
+        }
+        lynxView.updateViewport(
+            MeasureSpec.makeMeasureSpec(width.toInt(), MeasureSpec.EXACTLY),
+            MeasureSpec.makeMeasureSpec(height.toInt(), MeasureSpec.EXACTLY),
+        )
+    }
+
     private fun render() {
         try {
-            lynxView.renderTemplateUrl(bundleName, initialData)
+            loadState = "loading"
+            val builder = LynxLoadMeta.Builder()
+            builder.setUrl(bundleNameValue)
+            if (initialDataValue.isNotEmpty()) {
+                builder.setInitialData(TemplateData.fromString(initialDataValue))
+            }
+            if (autoGlobalProps || globalProps.isNotEmpty()) {
+                builder.setGlobalProps(TemplateData.fromMap(effectiveGlobalProps()))
+            }
+            lynxView.loadTemplate(builder.build())
+            hasRendered = true
         } catch (error: Exception) {
+            loadState = "failed"
             onError(mapOf("message" to (error.message ?: "Lynx render failed")))
         }
     }
 
+    override fun onSizeChanged(width: Int, height: Int, oldWidth: Int, oldHeight: Int) {
+        super.onSizeChanged(width, height, oldWidth, oldHeight)
+        if (width > 0 && height > 0) {
+            lynxView.updateViewport(
+                MeasureSpec.makeMeasureSpec(width, MeasureSpec.EXACTLY),
+                MeasureSpec.makeMeasureSpec(height, MeasureSpec.EXACTLY),
+            )
+            if (hasRendered && autoGlobalProps) pushGlobalProps()
+        }
+    }
+
+    override fun onWindowVisibilityChanged(visibility: Int) {
+        super.onWindowVisibilityChanged(visibility)
+        val nextBackground = visibility != View.VISIBLE
+        if (nextBackground == appInBackground) return
+        appInBackground = nextBackground
+        if (hasRendered && autoGlobalProps) pushGlobalProps()
+    }
+
+    private fun pushGlobalProps() {
+        if (!autoGlobalProps && globalProps.isEmpty()) return
+        lynxView.updateGlobalProps(TemplateData.fromMap(effectiveGlobalProps()))
+    }
+
+    private fun effectiveGlobalProps(): Map<String, Any?> {
+        if (!autoGlobalProps) return globalProps
+        val metrics = resources.displayMetrics
+        val density = metrics.density.takeIf { it > 0f } ?: 1f
+        val screenWidth = metrics.widthPixels.toDouble() / density
+        val screenHeight = metrics.heightPixels.toDouble() / density
+        val contentWidth = width.toDouble() / density
+        val contentHeight = height.toDouble() / density
+        val insets = systemInsets()
+        val orientation = if (resources.configuration.orientation == Configuration.ORIENTATION_LANDSCAPE) {
+            "landscape"
+        } else {
+            "portrait"
+        }
+        val night = resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+        val theme = if (night == Configuration.UI_MODE_NIGHT_YES) "dark" else "light"
+        val locale = resources.configuration.locales[0]?.toLanguageTag() ?: "en-US"
+        val powerManager = getContext().getSystemService(Context.POWER_SERVICE) as? PowerManager
+        val hasCutout = Build.VERSION.SDK_INT >= Build.VERSION_CODES.P && rootWindowInsets?.displayCutout != null
+        val isTablet = resources.configuration.smallestScreenWidthDp >= 600
+        return buildMap {
+            putAll(globalProps)
+            put("os", "android")
+            put("osVersion", Build.VERSION.RELEASE ?: "unknown")
+            put("deviceModel", Build.MODEL ?: "unknown")
+            put("containerID", containerId)
+            put("containerInitTime", containerInitTime)
+            put("screenWidth", screenWidth)
+            put("screenHeight", screenHeight)
+            put("contentWidth", contentWidth.coerceAtLeast(0.0))
+            put("contentHeight", contentHeight.coerceAtLeast(0.0))
+            put("safeAreaInsets", insets)
+            put("pixelRatio", density.toDouble())
+            put("accessibleMode", accessibilityMode())
+            put("isIPhoneX", 0)
+            put("isIPhoneXMax", 0)
+            put("isPad", if (isTablet) 1 else 0)
+            put("isNotchScreen", hasCutout)
+            put("isLowPowerMode", if (powerManager?.isPowerSaveMode == true) 1 else 0)
+            put("orientation", orientation)
+            put("screenOrientation", orientation)
+            put("theme", theme)
+            put("appLanguage", locale.substringBefore('-'))
+            put("appLocale", locale)
+            put("isAppBackground", appInBackground)
+            put("queryItems", emptyMap<String, String>())
+            put("statusBarHeight", insets["top"] ?: 0.0)
+            put("navigationBarHeight", insets["bottom"] ?: 0.0)
+            put("safeAreaHeight", insets["top"] ?: 0.0)
+        }
+    }
+
+    private fun systemInsets(): Map<String, Double> {
+        val insets = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            rootWindowInsets?.getInsets(WindowInsets.Type.systemBars())
+        } else {
+            null
+        }
+        val density = resources.displayMetrics.density.takeIf { it > 0f } ?: 1f
+        if (insets != null) {
+            return mapOf(
+                "top" to (insets.top / density).toDouble(),
+                "right" to (insets.right / density).toDouble(),
+                "bottom" to (insets.bottom / density).toDouble(),
+                "left" to (insets.left / density).toDouble(),
+            )
+        }
+        val legacy = rootWindowInsets
+        return mapOf(
+            "top" to (((legacy?.systemWindowInsetTop ?: 0) / density).toDouble()),
+            "right" to (((legacy?.systemWindowInsetRight ?: 0) / density).toDouble()),
+            "bottom" to (((legacy?.systemWindowInsetBottom ?: 0) / density).toDouble()),
+            "left" to (((legacy?.systemWindowInsetLeft ?: 0) / density).toDouble()),
+        )
+    }
+
+    private fun accessibilityMode(): Int {
+        val manager = getContext().getSystemService(Context.ACCESSIBILITY_SERVICE) as? AccessibilityManager
+        return if (manager?.isTouchExplorationEnabled == true) 1 else 0
+    }
+
+    fun release() {
+        if (hasRendered) {
+            lynxView.destroy()
+            hasRendered = false
+        }
+        loadState = "released"
+    }
+
     private fun installUpdateInBackground() {
         otaClient?.checkAndInstallAsync(object : LynxShipOtaClient.Listener {
             override fun onSuccess(updateAvailable: Boolean) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentType, type ReactNode } from "react";
+import { type ComponentType } from "react";
 import type { ViewProps } from "react-native";
 import { type LynxShipExpoConfig } from "./config.js";
 export type { LynxShipExpoConfig } from "./config.js";
@@ -8,14 +8,84 @@ export interface LynxViewProps extends ViewProps {
     bundle?: string;
     /** Optional initial data passed to Lynx when the view is rendered. */
     initialData?: string;
+    /** Global props exposed as `lynx.__globalProps` in the loaded Lynx page. */
+    globalProps?: Readonly<Record<string, unknown>>;
+    /** Injects the standard OS, size, safe-area and lifecycle host props. */
+    autoGlobalProps?: boolean;
     /** Requests a fresh render after an OTA candidate has been activated. */
     reloadOnUpdate?: boolean;
+    /** Emitted after Lynx reports that the first screen layout completed. */
+    onReady?: (event: LynxViewReadyEvent) => void;
+    /** Emitted when Lynx begins loading a bundle. */
+    onLoadStart?: (event: LynxViewLoadStartEvent) => void;
+    /** Emitted when the native provider starts fetching bundle bytes. */
+    onResourceFetchStart?: (event: LynxViewResourceFetchStartEvent) => void;
+    /** Emitted when the first rendered screen is available. */
+    onLoadSuccess?: (event: LynxViewReadyEvent) => void;
+    /** Emitted when the native host or bundle provider reports an error. */
+    onError?: (event: LynxViewErrorEvent) => void;
+    /** Emitted after a verified OTA candidate has been activated. */
+    onUpdate?: (event: LynxViewUpdateEvent) => void;
+    /** Emitted when the native Lynx view becomes visible. */
+    onShow?: () => void;
+    /** Emitted when the native Lynx view leaves the window. */
+    onHide?: () => void;
+}
+export interface LynxViewLoadStartEvent {
+    readonly nativeEvent: {
+        readonly bundle: string;
+    };
+}
+export interface LynxViewResourceFetchStartEvent {
+    readonly nativeEvent: {
+        readonly bundle: string;
+    };
+}
+export interface LynxViewReadyEvent {
+    readonly nativeEvent: {
+        readonly bundle: string;
+        readonly sequence: number;
+    };
+}
+export interface LynxViewErrorEvent {
+    readonly nativeEvent: {
+        readonly message: string;
+        readonly recoverable?: boolean;
+    };
+}
+export interface LynxViewUpdateEvent {
+    readonly nativeEvent: {
+        readonly sequence: number;
+    };
+}
+export interface LynxViewViewport {
+    readonly width: number;
+    readonly height: number;
+}
+export type LynxViewLoadState = "idle" | "loading" | "loaded" | "failed" | "released";
+/** Imperative controls implemented by the native LynxView ref. */
+export interface LynxViewRef {
+    getContainerId(): Promise<string>;
+    getLoadState(): Promise<LynxViewLoadState>;
+    isLoadSuccess(): Promise<boolean>;
+    reload(): Promise<void>;
+    /** Updates Lynx initData without remounting the native view. */
+    updateData(data: string, processorName?: string): Promise<void>;
+    updateGlobalProps(props: Readonly<Record<string, unknown>>): Promise<void>;
+    /** Merges a partial global-props patch without remounting the Lynx page. */
+    updateGlobalPropsByIncrement(props: Readonly<Record<string, unknown>>): Promise<void>;
+    sendGlobalEvent(eventName: string, params?: readonly unknown[]): Promise<void>;
+    show(): Promise<void>;
+    hide(): Promise<void>;
+    updateViewport(viewport: LynxViewViewport): Promise<void>;
 }
 /**
  * A LynxView that can be placed anywhere in an Expo/React Native view tree.
  * Native OTA configuration is supplied by the LynxShip config plugin.
  */
-export declare function LynxView(props: LynxViewProps): ReactNode;
+export declare const LynxView: ComponentType<LynxViewProps & {
+    ref?: LynxViewRef | null | undefined;
+}>;
 export declare const LynxShipView: ComponentType<LynxViewProps>;
 export declare function defineLynxShipExpoConfig(config: LynxShipExpoConfig): LynxShipExpoConfig;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAOxD;AAED,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,aAAa,CAAY,CAAC;AAEnE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,GACzB,kBAAkB,CAEpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LynxShipView = exports.validateLynxShipExpoConfig = void 0;
-exports.LynxView = LynxView;
+exports.LynxShipView = exports.LynxView = exports.validateLynxShipExpoConfig = void 0;
 exports.defineLynxShipExpoConfig = defineLynxShipExpoConfig;
 const react_1 = require("react");
 const expo_modules_core_1 = require("expo-modules-core");
@@ -13,15 +12,16 @@ const NativeLynxView = (0, expo_modules_core_1.requireNativeViewManager)("LynxSh
  * A LynxView that can be placed anywhere in an Expo/React Native view tree.
  * Native OTA configuration is supplied by the LynxShip config plugin.
  */
-function LynxView(props) {
-    return (0, react_1.createElement)(NativeLynxView, {
-        bundle: props.bundle ?? "main.lynx.bundle",
-        initialData: props.initialData ?? "",
-        reloadOnUpdate: props.reloadOnUpdate ?? true,
-        ...props,
-    });
-}
-exports.LynxShipView = LynxView;
+exports.LynxView = (0, react_1.forwardRef)((props, ref) => (0, react_1.createElement)(NativeLynxView, {
+    bundle: props.bundle ?? "main.lynx.bundle",
+    initialData: props.initialData ?? "",
+    globalProps: props.globalProps ?? {},
+    autoGlobalProps: props.autoGlobalProps ?? true,
+    reloadOnUpdate: props.reloadOnUpdate ?? true,
+    ...props,
+    ref,
+}));
+exports.LynxShipView = exports.LynxView;
 function defineLynxShipExpoConfig(config) {
     return (0, config_js_1.validateLynxShipExpoConfig)(config);
 }

package/ios/LynxShipExpoModule.swift

@@ -4,12 +4,18 @@ public class LynxShipExpoModule: Module {
   public func definition() -> ModuleDefinition {
     Name("LynxShip")
     View(LynxShipExpoView.self) {
-      Events("onReady", "onError", "onUpdate")
+      Events("onReady", "onLoadStart", "onResourceFetchStart", "onLoadSuccess", "onError", "onUpdate", "onShow", "onHide")
       Prop("bundle") { (view: LynxShipExpoView, value: String?) in
-        view.bundleName = value ?? "main.lynx.bundle"
+        view.setBundleName(value ?? "main.lynx.bundle")
       }
       Prop("initialData") { (view: LynxShipExpoView, value: String?) in
-        view.initialData = value ?? ""
+        view.setInitialData(value ?? "")
+      }
+      Prop("globalProps") { (view: LynxShipExpoView, value: [String: Any]?) in
+        view.updateGlobalProps(value ?? [:])
+      }
+      Prop("autoGlobalProps") { (view: LynxShipExpoView, value: Bool?) in
+        view.autoGlobalProps = value ?? true
       }
       Prop("reloadOnUpdate") { (view: LynxShipExpoView, value: Bool?) in
         view.reloadOnUpdate = value ?? true
@@ -17,6 +23,36 @@ public class LynxShipExpoModule: Module {
       AsyncFunction("reload") { (view: LynxShipExpoView) in
         try view.reload()
       }
+      AsyncFunction("getContainerId") { (view: LynxShipExpoView) in
+        view.getContainerId()
+      }
+      AsyncFunction("getLoadState") { (view: LynxShipExpoView) in
+        view.getLoadState()
+      }
+      AsyncFunction("isLoadSuccess") { (view: LynxShipExpoView) in
+        view.isLoadSuccess()
+      }
+      AsyncFunction("updateData") { (view: LynxShipExpoView, data: String, processorName: String?) in
+        try view.updateData(data, processorName: processorName)
+      }
+      AsyncFunction("updateGlobalProps") { (view: LynxShipExpoView, props: [String: Any]) in
+        view.updateGlobalProps(props)
+      }
+      AsyncFunction("updateGlobalPropsByIncrement") { (view: LynxShipExpoView, props: [String: Any]) in
+        view.updateGlobalPropsByIncrement(props)
+      }
+      AsyncFunction("sendGlobalEvent") { (view: LynxShipExpoView, eventName: String, params: [Any]) in
+        try view.sendGlobalEvent(eventName, params: params)
+      }
+      AsyncFunction("show") { (view: LynxShipExpoView) in
+        view.show()
+      }
+      AsyncFunction("hide") { (view: LynxShipExpoView) in
+        view.hide()
+      }
+      AsyncFunction("updateViewport") { (view: LynxShipExpoView, viewport: [String: Double]) in
+        try view.updateViewport(viewport)
+      }
     }
   }
 }

package/ios/LynxShipExpoView.swift

@@ -6,38 +6,79 @@ import UIKit
 
 private final class LynxShipTemplateProvider: NSObject, LynxTemplateProvider {
   private let load: (String) throws -> Data
-  private let onLoaded: () -> Void
+  private let onStart: (String) -> Void
 
-  init(load: @escaping (String) throws -> Data, onLoaded: @escaping () -> Void) {
+  init(load: @escaping (String) throws -> Data, onStart: @escaping (String) -> Void) {
     self.load = load
-    self.onLoaded = onLoaded
+    self.onStart = onStart
   }
 
   func loadTemplate(withUrl url: String!, onComplete callback: LynxTemplateLoadBlock!) {
+    onStart(url ?? "")
     do {
       callback(load(url), nil)
-      onLoaded()
     } catch {
       callback(nil, error)
     }
   }
 }
 
+private final class LynxShipLifecycleClient: NSObject, LynxViewLifecycle {
+  private let onStart: () -> Void
+  private let onFirstScreen: () -> Void
+
+  init(onStart: @escaping () -> Void, onFirstScreen: @escaping () -> Void) {
+    self.onStart = onStart
+    self.onFirstScreen = onFirstScreen
+  }
+
+  func lynxViewDidStartLoading(_ view: LynxView) {
+    onStart()
+  }
+
+  func lynxViewDidFirstScreen(_ view: LynxView) {
+    onFirstScreen()
+  }
+}
+
 public final class LynxShipExpoView: ExpoView {
   let onReady = EventDispatcher()
+  let onLoadStart = EventDispatcher()
+  let onResourceFetchStart = EventDispatcher()
+  let onLoadSuccess = EventDispatcher()
   let onError = EventDispatcher()
   let onUpdate = EventDispatcher()
+  let onShow = EventDispatcher()
+  let onHide = EventDispatcher()
 
   private lazy var templateProvider = LynxShipTemplateProvider(
     load: { [weak self] path in
       guard let self else { throw NSError(domain: "LynxShip", code: 1, userInfo: [NSLocalizedDescriptionKey: "Lynx view was released"]) }
       return try self.otaClient?.openActiveAsset(path) ?? self.readEmbeddedAsset(path)
     },
-    onLoaded: { [weak self] in
+    onStart: { [weak self] bundle in
+      DispatchQueue.main.async { self?.onResourceFetchStart(["bundle": bundle]) }
+    }
+  )
+
+  private lazy var lifecycleClient = LynxShipLifecycleClient(
+    onStart: { [weak self] in
       guard let self else { return }
-      try? self.otaClient?.markLaunchSuccess()
+      self.loadState = "loading"
+      self.onLoadStart(["bundle": self.bundleName])
+    },
+    onFirstScreen: { [weak self] in
+      guard let self else { return }
+      self.loadState = "loaded"
+      do {
+        try self.otaClient?.markLaunchSuccess()
+      } catch {
+        self.onError(["message": error.localizedDescription, "recoverable": true])
+      }
       DispatchQueue.main.async {
-        self.onReady(["bundle": self.bundleName, "sequence": self.otaClient?.activeSequence ?? 0])
+        let event: [String: Any] = ["bundle": self.bundleName, "sequence": self.otaClient?.activeSequence ?? 0]
+        self.onLoadSuccess(event)
+        self.onReady(event)
       }
     }
   )
@@ -51,15 +92,26 @@ public final class LynxShipExpoView: ExpoView {
 
   private var otaClient: LynxShipOtaClient?
   private var hasRendered = false
+  private var loadState = "idle"
   var bundleName = "main.lynx.bundle"
   var initialData = ""
+  private var globalProps: [String: Any] = [:]
   var reloadOnUpdate = true
+  var autoGlobalProps = true {
+    didSet {
+      if hasRendered { pushGlobalProps() }
+    }
+  }
+  private let containerID = UUID().uuidString
+  private let containerInitTime = ISO8601DateFormatter().string(from: Date())
+  private var appInBackground = false
 
   public required init(appContext: AppContext? = nil) {
     super.init(appContext: appContext)
     LynxEnv.sharedInstance()
     otaClient = makeOtaClient()
     addSubview(lynxView)
+    lynxView.addLifecycleClient(lifecycleClient)
   }
 
   public override func layoutSubviews() {
@@ -67,16 +119,30 @@ public final class LynxShipExpoView: ExpoView {
     lynxView.frame = bounds
     lynxView.preferredLayoutWidth = bounds.width
     lynxView.preferredLayoutHeight = bounds.height
+    lynxView.updateViewport(withPreferredLayoutWidth: bounds.width,
+                            preferredLayoutHeight: bounds.height,
+                            needLayout: true)
+    if hasRendered && autoGlobalProps { pushGlobalProps() }
   }
 
   public override func didMoveToWindow() {
     super.didMoveToWindow()
+    appInBackground = window == nil
+    if window != nil {
+      lynxView.onEnterForeground()
+      onShow([:])
+    } else {
+      lynxView.onEnterBackground()
+      onHide([:])
+    }
+    if hasRendered && autoGlobalProps { pushGlobalProps() }
     guard window != nil, !hasRendered else { return }
     do {
       try otaClient?.beginLaunch()
       render()
       checkForUpdate()
     } catch {
+      loadState = "failed"
       onError(["message": error.localizedDescription])
     }
   }
@@ -85,11 +151,167 @@ public final class LynxShipExpoView: ExpoView {
     render()
   }
 
+  func getContainerId() -> String { containerID }
+
+  func getLoadState() -> String { loadState }
+
+  func isLoadSuccess() -> Bool { loadState == "loaded" }
+
+  func updateData(_ data: String, processorName: String? = nil) throws {
+    guard data.utf8.count <= 8 * 1024 * 1024 else {
+      throw NSError(domain: "LynxShip", code: 8, userInfo: [NSLocalizedDescriptionKey: "Lynx update data is larger than 8 MiB"])
+    }
+    guard hasRendered else {
+      throw NSError(domain: "LynxShip", code: 9, userInfo: [NSLocalizedDescriptionKey: "Lynx view has not loaded a bundle"])
+    }
+    if let processorName {
+      guard !processorName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+            processorName.count <= 256,
+            processorName.rangeOfCharacter(from: .controlCharacters) == nil else {
+        throw NSError(domain: "LynxShip", code: 10, userInfo: [NSLocalizedDescriptionKey: "Lynx data processor name is invalid"])
+      }
+      let templateData = LynxTemplateData(json: data)
+      templateData.markState(processorName)
+      lynxView.updateData(withTemplateData: templateData)
+    } else {
+      lynxView.updateData(withString: data)
+    }
+    initialData = data
+    onUpdate(["bundle": bundleName, "reason": "data"])
+  }
+
+  func setBundleName(_ value: String) {
+    guard value != bundleName else { return }
+    bundleName = value
+    if hasRendered { render() }
+  }
+
+  func setInitialData(_ value: String) {
+    guard value != initialData else { return }
+    initialData = value
+    if hasRendered { render() }
+  }
+
+  func updateGlobalProps(_ props: [String: Any]) {
+    globalProps = props
+    pushGlobalProps()
+  }
+
+  func updateGlobalPropsByIncrement(_ props: [String: Any]) {
+    guard !props.isEmpty else { return }
+    globalProps.merge(props) { _, newValue in newValue }
+    lynxView.updateGlobalProps(withDictionary: props)
+  }
+
+  func sendGlobalEvent(_ eventName: String, params: [Any]) throws {
+    guard !eventName.isEmpty else {
+      throw NSError(domain: "LynxShip", code: 4, userInfo: [NSLocalizedDescriptionKey: "Lynx global event name cannot be empty"])
+    }
+    guard eventName.count <= 256 else {
+      throw NSError(domain: "LynxShip", code: 5, userInfo: [NSLocalizedDescriptionKey: "Lynx global event name is too long"])
+    }
+    guard params.count <= 256 else {
+      throw NSError(domain: "LynxShip", code: 6, userInfo: [NSLocalizedDescriptionKey: "Lynx global event payload is too large"])
+    }
+    lynxView.sendGlobalEvent(eventName, withParams: params)
+  }
+
+  func show() {
+    isHidden = false
+  }
+
+  func hide() {
+    isHidden = true
+  }
+
+  func updateViewport(_ viewport: [String: Double]) throws {
+    let width = viewport["width"] ?? 0
+    let height = viewport["height"] ?? 0
+    guard width.isFinite && height.isFinite && width >= 0 && height >= 0 else {
+      throw NSError(domain: "LynxShip", code: 7, userInfo: [NSLocalizedDescriptionKey: "Lynx viewport dimensions must be finite and non-negative"])
+    }
+    lynxView.updateViewport(withPreferredLayoutWidth: CGFloat(width),
+                            preferredLayoutHeight: CGFloat(height),
+                            needLayout: true)
+  }
+
   private func render() {
+    loadState = "loading"
+    if autoGlobalProps || !globalProps.isEmpty {
+      lynxView.updateGlobalProps(withDictionary: effectiveGlobalProps())
+    }
     lynxView.loadTemplate(fromURL: bundleName, initData: initialData)
     hasRendered = true
   }
 
+  private func pushGlobalProps() {
+    guard autoGlobalProps || !globalProps.isEmpty else { return }
+    lynxView.updateGlobalProps(withDictionary: effectiveGlobalProps())
+  }
+
+  private func effectiveGlobalProps() -> [String: Any] {
+    guard autoGlobalProps else { return globalProps }
+    let screen = window?.screen ?? UIScreen.main
+    let screenSize = screen.bounds.size
+    let insets = safeAreaInsets
+    let width = max(0, bounds.width)
+    let height = max(0, bounds.height)
+    let contentWidth = max(0, width - insets.left - insets.right)
+    let contentHeight = max(0, height - insets.top - insets.bottom)
+    let orientation: String
+    switch window?.windowScene?.interfaceOrientation {
+    case .landscapeLeft: orientation = "landscape-left"
+    case .landscapeRight: orientation = "landscape-right"
+    case .portraitUpsideDown: orientation = "portrait-upside-down"
+    case .portrait: orientation = "portrait"
+    default: orientation = width > height ? "landscape" : "portrait"
+    }
+    let theme: String
+    switch traitCollection.userInterfaceStyle {
+    case .dark: theme = "dark"
+    case .light: theme = "light"
+    default: theme = "system"
+    }
+    let locale = Locale.current.identifier
+    let language = Locale.current.languageCode ?? locale.split(separator: "_").first.map(String.init) ?? locale
+    let isTablet = UIDevice.current.userInterfaceIdiom == .pad
+    let isNotchScreen = UIDevice.current.userInterfaceIdiom == .phone && insets.top > 20
+    var props = globalProps
+    props["os"] = "ios"
+    props["osVersion"] = UIDevice.current.systemVersion
+    props["deviceModel"] = UIDevice.current.model
+    props["containerID"] = containerID
+    props["containerInitTime"] = containerInitTime
+    props["screenWidth"] = screenSize.width
+    props["screenHeight"] = screenSize.height
+    props["contentWidth"] = contentWidth
+    props["contentHeight"] = contentHeight
+    props["safeAreaInsets"] = [
+      "top": insets.top,
+      "right": insets.right,
+      "bottom": insets.bottom,
+      "left": insets.left,
+    ]
+    props["pixelRatio"] = screen.scale
+    props["accessibleMode"] = UIAccessibility.isVoiceOverRunning ? 1 : 0
+    props["isIPhoneX"] = isNotchScreen ? 1 : 0
+    props["isIPhoneXMax"] = isNotchScreen ? 1 : 0
+    props["isPad"] = isTablet ? 1 : 0
+    props["isNotchScreen"] = isNotchScreen
+    props["isLowPowerMode"] = ProcessInfo.processInfo.isLowPowerModeEnabled ? 1 : 0
+    props["orientation"] = orientation
+    props["screenOrientation"] = orientation
+    props["theme"] = theme
+    props["appLanguage"] = language
+    props["appLocale"] = locale
+    props["isAppBackground"] = appInBackground
+    props["queryItems"] = [String: String]()
+    props["topHeight"] = insets.top
+    props["bottomHeight"] = insets.bottom
+    props["safeAreaHeight"] = insets.top
+    return props
+  }
+
   private func checkForUpdate() {
     Task { [weak self] in
       guard let self else { return }
@@ -150,4 +372,9 @@ public final class LynxShipExpoView: ExpoView {
       return nil
     }
   }
+
+  deinit {
+    loadState = "released"
+    lynxView.destroy()
+  }
 }

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@lynxship/expo",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Expo native LynxView with LynxShip OTA delivery and cache support.",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "android",
-    "ios",
+    "android/build.gradle",
+    "android/consumer-rules.pro",
+    "android/src",
+    "ios/*.podspec",
+    "ios/*.h",
+    "ios/*.m",
+    "ios/*.swift",
     "src",
     "app.plugin.js",
     "app.plugin.cjs",

package/src/externals.d.ts

@@ -17,6 +17,9 @@ declare module "react" {
     type: unknown,
     props: Record<string, unknown> | null,
   ): ReactNode;
+  export function forwardRef<T, Props>(
+    render: (props: Props, ref: T | null) => ReactNode,
+  ): ComponentType<Props & { ref?: T | null }>;
 }
 
 declare module "react-native" {

package/src/index.ts

@@ -1,4 +1,9 @@
-import { createElement, type ComponentType, type ReactNode } from "react";
+import {
+  createElement,
+  forwardRef,
+  type ComponentType,
+  type ReactNode,
+} from "react";
 import { requireNativeViewManager } from "expo-modules-core";
 import type { ViewProps } from "react-native";
 import {
@@ -15,24 +20,112 @@ export interface LynxViewProps extends ViewProps {
   bundle?: string;
   /** Optional initial data passed to Lynx when the view is rendered. */
   initialData?: string;
+  /** Global props exposed as `lynx.__globalProps` in the loaded Lynx page. */
+  globalProps?: Readonly<Record<string, unknown>>;
+  /** Injects the standard OS, size, safe-area and lifecycle host props. */
+  autoGlobalProps?: boolean;
   /** Requests a fresh render after an OTA candidate has been activated. */
   reloadOnUpdate?: boolean;
+  /** Emitted after Lynx reports that the first screen layout completed. */
+  onReady?: (event: LynxViewReadyEvent) => void;
+  /** Emitted when Lynx begins loading a bundle. */
+  onLoadStart?: (event: LynxViewLoadStartEvent) => void;
+  /** Emitted when the native provider starts fetching bundle bytes. */
+  onResourceFetchStart?: (event: LynxViewResourceFetchStartEvent) => void;
+  /** Emitted when the first rendered screen is available. */
+  onLoadSuccess?: (event: LynxViewReadyEvent) => void;
+  /** Emitted when the native host or bundle provider reports an error. */
+  onError?: (event: LynxViewErrorEvent) => void;
+  /** Emitted after a verified OTA candidate has been activated. */
+  onUpdate?: (event: LynxViewUpdateEvent) => void;
+  /** Emitted when the native Lynx view becomes visible. */
+  onShow?: () => void;
+  /** Emitted when the native Lynx view leaves the window. */
+  onHide?: () => void;
 }
 
-const NativeLynxView = requireNativeViewManager<LynxViewProps>("LynxShip");
+export interface LynxViewLoadStartEvent {
+  readonly nativeEvent: { readonly bundle: string };
+}
+
+export interface LynxViewResourceFetchStartEvent {
+  readonly nativeEvent: { readonly bundle: string };
+}
+
+export interface LynxViewReadyEvent {
+  readonly nativeEvent: {
+    readonly bundle: string;
+    readonly sequence: number;
+  };
+}
+
+export interface LynxViewErrorEvent {
+  readonly nativeEvent: {
+    readonly message: string;
+    readonly recoverable?: boolean;
+  };
+}
+
+export interface LynxViewUpdateEvent {
+  readonly nativeEvent: {
+    readonly sequence: number;
+  };
+}
+
+export interface LynxViewViewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+export type LynxViewLoadState =
+  | "idle"
+  | "loading"
+  | "loaded"
+  | "failed"
+  | "released";
+
+/** Imperative controls implemented by the native LynxView ref. */
+export interface LynxViewRef {
+  getContainerId(): Promise<string>;
+  getLoadState(): Promise<LynxViewLoadState>;
+  isLoadSuccess(): Promise<boolean>;
+  reload(): Promise<void>;
+  /** Updates Lynx initData without remounting the native view. */
+  updateData(data: string, processorName?: string): Promise<void>;
+  updateGlobalProps(props: Readonly<Record<string, unknown>>): Promise<void>;
+  /** Merges a partial global-props patch without remounting the Lynx page. */
+  updateGlobalPropsByIncrement(
+    props: Readonly<Record<string, unknown>>,
+  ): Promise<void>;
+  sendGlobalEvent(
+    eventName: string,
+    params?: readonly unknown[],
+  ): Promise<void>;
+  show(): Promise<void>;
+  hide(): Promise<void>;
+  updateViewport(viewport: LynxViewViewport): Promise<void>;
+}
+
+const NativeLynxView = requireNativeViewManager<
+  LynxViewProps & { ref?: LynxViewRef | null }
+>("LynxShip");
 
 /**
  * A LynxView that can be placed anywhere in an Expo/React Native view tree.
  * Native OTA configuration is supplied by the LynxShip config plugin.
  */
-export function LynxView(props: LynxViewProps): ReactNode {
-  return createElement(NativeLynxView, {
-    bundle: props.bundle ?? "main.lynx.bundle",
-    initialData: props.initialData ?? "",
-    reloadOnUpdate: props.reloadOnUpdate ?? true,
-    ...props,
-  });
-}
+export const LynxView = forwardRef<LynxViewRef, LynxViewProps>(
+  (props, ref): ReactNode =>
+    createElement(NativeLynxView, {
+      bundle: props.bundle ?? "main.lynx.bundle",
+      initialData: props.initialData ?? "",
+      globalProps: props.globalProps ?? {},
+      autoGlobalProps: props.autoGlobalProps ?? true,
+      reloadOnUpdate: props.reloadOnUpdate ?? true,
+      ...props,
+      ref,
+    }),
+);
 
 export const LynxShipView: ComponentType<LynxViewProps> = LynxView;