@lynxship/expo 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @lynxship/expo
+
+Expo Modules API integration for embedding an official Lynx `LynxView` inside
+an Expo/React Native application. The native view uses the LynxShip Android or
+iOS OTA client when an OTA endpoint is configured and otherwise renders the
+embedded `main.lynx.bundle` fallback.
+
+## Install
+
+```bash
+npx expo install @lynxship/expo
+npx expo prebuild
+npx pod-install
+```
+
+When the project uses a static `app.json` or `app.config.json`, the Expo CLI
+automatically adds `@lynxship/expo` to `expo.plugins` during `npx expo install`.
+The plugin's defaults are safe for the first build, so no manual config edit
+is required for the basic integration. `npx expo prebuild` then applies the
+Android and iOS native changes before the native build.
+
+If the project uses a dynamic `app.config.js`/`app.config.ts`, or if custom OTA
+options are needed, add the config plugin manually:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@lynxship/expo",
+        {
+          "endpoint": "https://api.example.com",
+          "projectId": "00000000-0000-4000-8000-000000000000",
+          "channel": "production",
+          "runtimeVersion": "lynx-runtime-2026-01",
+          "publicKeys": {
+            "release-key-1": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+          },
+          "embeddedBundle": "main.lynx.bundle",
+          "lynxVersion": "auto"
+        }
+      ]
+    ]
+  }
+}
+```
+
+For a dynamic config, keep the same `plugins` entry in the returned Expo
+configuration. Expo cannot safely rewrite JavaScript or TypeScript config
+files automatically.
+
+The endpoint must be HTTPS outside localhost. The public verification key is
+safe to ship in the application; private signing keys must remain in the
+LynxShip CLI or CI secret store.
+
+`lynxVersion` defaults to `auto`. Android resolves the current Lynx release
+through Gradle and iOS resolves the current CocoaPods release. Gradle and
+CocoaPods lockfiles retain the concrete versions selected by the first native
+install, so normal rebuilds remain reproducible. Set an exact semver only when
+you intentionally operate a pinned native compatibility lane; do not put
+`latest` in a production lockfile without reviewing the resulting native
+build.
+
+## Use the view
+
+```tsx
+import { LynxView } from "@lynxship/expo";
+
+export function LynxScreen() {
+  return (
+    <LynxView
+      style={{ flex: 1 }}
+      bundle="main.lynx.bundle"
+      initialData="{}"
+      reloadOnUpdate
+    />
+  );
+}
+```
+
+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
+after its runtime, manifest signature, asset paths, sizes and SHA-256 hashes
+pass validation. `onReady` is emitted after Lynx reports its first screen, not
+merely after the render request is queued. Native code, permissions, native
+modules and Lynx runtime changes still require a new binary.
+
+## Build workflow
+
+From the Expo project:
+
+```bash
+lynxship init
+lynxship doctor --platform android
+lynxship doctor --platform ios
+lynxship build --platform android --profile production
+lynxship build --platform ios --profile production
+lynxship ota doctor --platform android
+lynxship ota doctor --platform ios
+```
+
+The package does not silently replace an existing native host. `expo prebuild`
+and the official Lynx dependencies remain the source of truth for native
+project generation. iOS builds still require macOS/Xcode; Android builds use
+the Android SDK and Gradle toolchain.
+
+## Official compatibility boundary
+
+This package follows the official brownfield Lynx integration: `LynxView` is a
+native Android/iOS view and the host supplies the template provider. Lynx's
+engine does not itself implement application-specific network downloads, so
+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)
+- [Expo native view modules](https://docs.expo.dev/modules/native-view-tutorial/)
+- [Expo module configuration](https://docs.expo.dev/modules/module-config/)
+- [LynxShip OTA security and compatibility](../../docs/compatibility.md)
+
+The native targets must be built on their real platform. The repository's
+Windows checks validate the JavaScript API, package metadata and generated
+configuration; they cannot replace a real Android Gradle or macOS Xcode
+runtime build.

package/android/build.gradle

@@ -0,0 +1,40 @@
+plugins {
+    id "com.android.library"
+}
+
+// `latest.release` is used only when the app does not provide an exact
+// version. Gradle dependency locking then records the resolved version for
+// reproducible subsequent builds.
+def lynxVersion = project.findProperty("LYNXSHIP_LYNX_VERSION") ?: "latest.release"
+
+android {
+    namespace "com.lynxship.expo"
+    compileSdk 35
+
+    defaultConfig {
+        minSdk 24
+        consumerProguardFiles "consumer-rules.pro"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+dependencies {
+    implementation "org.lynxsdk.lynx:lynx:${lynxVersion}"
+    implementation "org.lynxsdk.lynx:lynx-jssdk:${lynxVersion}"
+    implementation "org.lynxsdk.lynx:lynx-trace:${lynxVersion}"
+    implementation "org.lynxsdk.lynx:primjs:${lynxVersion}"
+    implementation "org.lynxsdk.lynx:lynx-service-image:${lynxVersion}"
+    implementation "org.lynxsdk.lynx:lynx-service-log:${lynxVersion}"
+    implementation "org.lynxsdk.lynx:lynx-service-http:${lynxVersion}"
+    implementation "com.facebook.fresco:fresco:2.3.0"
+    implementation "com.facebook.fresco:animated-gif:2.3.0"
+    implementation "com.facebook.fresco:animated-webp:2.3.0"
+    implementation "com.facebook.fresco:webpsupport:2.3.0"
+    implementation "com.facebook.fresco:animated-base:2.3.0"
+    implementation "com.squareup.okhttp3:okhttp:4.9.0"
+    implementation project(":lynxship-sdk-android")
+}

package/android/consumer-rules.pro

@@ -0,0 +1,34 @@
+# These rules are the public keep rules required by the Lynx Android runtime
+# when an application enables R8/minification. Keep this file in the Expo
+# module so consuming apps do not need to copy framework rules manually.
+-dontwarn android.support.annotation.Keep
+-keep @android.support.annotation.Keep class **
+-keep @android.support.annotation.Keep class ** {
+    @android.support.annotation.Keep <fields>;
+    @android.support.annotation.Keep <methods>;
+}
+-dontwarn androidx.annotation.Keep
+-keep @androidx.annotation.Keep class **
+-keep @androidx.annotation.Keep class ** {
+    @androidx.annotation.Keep <fields>;
+    @androidx.annotation.Keep <methods>;
+}
+-keepclasseswithmembers,includedescriptorclasses class * {
+    native <methods>;
+}
+-keepclasseswithmembers class * {
+    @com.lynx.tasm.base.CalledByNative <methods>;
+}
+-keepclasseswithmembers class * {
+    @com.lynx.jsbridge.LynxMethod <methods>;
+}
+-keepclassmembers class * {
+    @com.lynx.tasm.behavior.LynxProp <methods>;
+    @com.lynx.tasm.behavior.LynxPropGroup <methods>;
+    @com.lynx.tasm.behavior.LynxUIMethod <methods>;
+}
+-keep class com.lynx.jsbridge.LynxModule { *; }
+-keep class * extends com.lynx.tasm.behavior.ui.LynxBaseUI
+-keep class * extends com.lynx.tasm.behavior.shadow.ShadowNode
+-keep class * extends com.lynx.jsbridge.LynxModule { *; }
+-keep class * extends com.lynx.jsbridge.LynxContextModule

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

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

@@ -0,0 +1,30 @@
+package com.lynxship.expo
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class LynxShipExpoModule : Module() {
+    override fun definition() = ModuleDefinition {
+        Name("LynxShip")
+
+        View(LynxShipExpoView::class) {
+            Events("onReady", "onError", "onUpdate")
+
+            Prop("bundle") { view: LynxShipExpoView, value: String? ->
+                view.bundleName = value ?: "main.lynx.bundle"
+            }
+
+            Prop("initialData") { view: LynxShipExpoView, value: String? ->
+                view.initialData = value ?: ""
+            }
+
+            Prop("reloadOnUpdate") { view: LynxShipExpoView, value: Boolean? ->
+                view.reloadOnUpdate = value ?: true
+            }
+
+            AsyncFunction("reload") { view: LynxShipExpoView ->
+                view.reload()
+            }
+        }
+    }
+}

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

@@ -0,0 +1,196 @@
+package com.lynxship.expo
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.os.Bundle
+import android.provider.Settings
+import com.facebook.drawee.backends.pipeline.Fresco
+import com.facebook.imagepipeline.core.ImagePipelineConfig
+import com.facebook.imagepipeline.memory.PoolConfig
+import com.facebook.imagepipeline.memory.PoolFactory
+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.LynxView
+import com.lynx.tasm.LynxViewClient
+import com.lynx.tasm.LynxViewBuilder
+import com.lynx.tasm.provider.AbsTemplateProvider
+import com.lynx.tasm.service.LynxServiceCenter
+import com.lynxship.sdk.android.LynxShipOtaClient
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.events.EventDispatcher
+import expo.modules.kotlin.views.ExpoView
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.io.IOException
+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 onError by EventDispatcher()
+    private val onUpdate 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) {
+            Thread {
+                try {
+                    val bytes = otaClient?.openActiveAsset(uri) ?: readEmbeddedAsset(uri)
+                    callback.onSuccess(bytes)
+                    otaClient?.markLaunchSuccess()
+                } catch (error: Exception) {
+                    callback.onFailed(error.message ?: "Unable to load Lynx bundle")
+                }
+            }.start()
+        }
+    }
+    private val lynxView: LynxView
+    var bundleName: String = metadata.getString("com.lynxship.expo.embeddedBundle", "main.lynx.bundle")
+    var initialData: String = ""
+    var reloadOnUpdate: Boolean = true
+
+    init {
+        initializeLynx(context)
+        lynxView = LynxViewBuilder().setTemplateProvider(templateProvider).build(applicationContext)
+        lynxView.addLynxViewClient(object : LynxViewClient() {
+            override fun onFirstScreen() {
+                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)))
+            }
+        })
+        addView(lynxView, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
+    }
+
+    override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        try {
+            otaClient?.beginLaunch()
+            installUpdateInBackground()
+            render()
+        } catch (error: Exception) {
+            onError(mapOf("message" to (error.message ?: "Lynx startup failed")))
+        }
+    }
+
+    fun reload() {
+        render()
+    }
+
+    private fun render() {
+        try {
+            lynxView.renderTemplateUrl(bundleName, initialData)
+        } catch (error: Exception) {
+            onError(mapOf("message" to (error.message ?: "Lynx render failed")))
+        }
+    }
+
+    private fun installUpdateInBackground() {
+        otaClient?.checkAndInstallAsync(object : LynxShipOtaClient.Listener {
+            override fun onSuccess(updateAvailable: Boolean) {
+                if (!updateAvailable) return
+                try {
+                    otaClient.activateCandidate()
+                    post {
+                        onUpdate(mapOf("sequence" to otaClient.activeSequence))
+                        if (reloadOnUpdate) render()
+                    }
+                } catch (error: Exception) {
+                    emitError(error, "OTA activation failed", recoverable = true)
+                }
+            }
+
+            override fun onFailure(error: Exception) {
+                emitError(error, "OTA check failed", recoverable = true)
+            }
+        })
+    }
+
+    private fun emitError(error: Exception, fallback: String, recoverable: Boolean = false) {
+        post {
+            onError(
+                mapOf(
+                    "message" to (error.message ?: fallback),
+                    "recoverable" to recoverable,
+                ),
+            )
+        }
+    }
+
+    private fun readEmbeddedAsset(path: String): ByteArray {
+        if (path.contains("..") || path.startsWith("/") || path.contains("\\")) throw IOException("Unsafe Lynx asset path")
+        applicationContext.assets.open(path).use { input ->
+            ByteArrayOutputStream().use { output ->
+                input.copyTo(output)
+                return output.toByteArray()
+            }
+        }
+    }
+
+    private fun createOtaClient(context: Context): LynxShipOtaClient? {
+        val endpoint = metadata.getString("com.lynxship.expo.endpoint", "")
+        val projectId = metadata.getString("com.lynxship.expo.projectId", "")
+        val runtimeVersion = metadata.getString("com.lynxship.expo.runtimeVersion", "")
+        val keyJson = metadata.getString("com.lynxship.expo.publicKeys", "{}")
+        if (endpoint.isBlank() || projectId.isBlank() || runtimeVersion.isBlank()) return null
+        return try {
+            val keys = org.json.JSONObject(keyJson).let { json ->
+                buildMap {
+                    json.keys().forEach { key -> put(key, json.getString(key)) }
+                }
+            }
+            val installationId = preferences.getString("installationId", null) ?: Settings.Secure.getString(context.contentResolver, Settings.Secure.ANDROID_ID) ?: UUID.randomUUID().toString()
+            preferences.edit().putString("installationId", installationId).apply()
+            LynxShipOtaClient(
+                LynxShipOtaClient.Config(
+                    File(context.filesDir, "lynxship-ota"), endpoint, projectId,
+                    metadata.getString("com.lynxship.expo.channel", "production"), "android",
+                    runtimeVersion, installationId, keys, { path -> readEmbeddedAsset(path) },
+                    3,
+                    metadata.getString("com.lynxship.expo.maxReleaseBytes", "104857600").toLong(),
+                    10_000,
+                    30_000,
+                ),
+            )
+        } catch (error: Exception) {
+            onError(mapOf("message" to (error.message ?: "Invalid LynxShip OTA configuration")))
+            null
+        }
+    }
+
+    private fun initializeLynx(context: Context) {
+        synchronized(LynxShipExpoView::class.java) {
+            if (!initialized) {
+                val applicationContext = context.applicationContext
+                // Lynx's official Android integration requires these services
+                // before a LynxView is created. Expo does not give this package
+                // an application subclass, so initialize them once at the
+                // first view creation. If the host already initialized Fresco,
+                // keep that host-owned instance and continue registering Lynx's
+                // services against it.
+                val factory = PoolFactory(PoolConfig.newBuilder().build())
+                val builder = ImagePipelineConfig.newBuilder(applicationContext).setPoolFactory(factory)
+                try {
+                    Fresco.initialize(applicationContext, builder.build())
+                } catch (_: IllegalStateException) {
+                    // Fresco was initialized by the host application.
+                }
+                LynxServiceCenter.inst().registerService(LynxImageService.getInstance())
+                LynxServiceCenter.inst().registerService(LynxLogService)
+                LynxServiceCenter.inst().registerService(LynxHttpService)
+                LynxEnv.inst().init(applicationContext, null, null, null)
+                initialized = true
+            }
+        }
+    }
+
+    companion object {
+        @Volatile private var initialized = false
+    }
+}

package/app.plugin.cjs

@@ -0,0 +1,204 @@
+const {
+  withAndroidManifest,
+  withGradleProperties,
+  withInfoPlist,
+  withPodfile,
+  withSettingsGradle,
+} = require("@expo/config-plugins");
+
+const MARKER = "# @lynxship/expo managed";
+const DEFAULT_LYNX_VERSION = "auto";
+
+function optionsFromPluginEntry(entry) {
+  if (Array.isArray(entry) && entry[0] === "@lynxship/expo")
+    return entry[1] || {};
+  return {};
+}
+
+function getOptions(config) {
+  return (
+    (config.plugins || [])
+      .map(optionsFromPluginEntry)
+      .find((value) => Object.keys(value).length > 0) || {}
+  );
+}
+
+function assertOptions(options) {
+  if (options.endpoint) {
+    const url = new URL(options.endpoint);
+    if (
+      url.protocol !== "https:" &&
+      !["localhost", "127.0.0.1"].includes(url.hostname)
+    ) {
+      throw new Error(
+        "@lynxship/expo endpoint must use HTTPS outside localhost",
+      );
+    }
+  }
+  if (options.publicKeys) {
+    for (const [key, value] of Object.entries(options.publicKeys)) {
+      if (
+        !key ||
+        typeof value !== "string" ||
+        !value.includes("BEGIN PUBLIC KEY")
+      ) {
+        throw new Error(
+          "@lynxship/expo publicKeys must contain PEM public keys",
+        );
+      }
+    }
+  }
+  if (
+    options.lynxVersion !== undefined &&
+    options.lynxVersion !== "auto" &&
+    options.lynxVersion !== "latest" &&
+    !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(options.lynxVersion)
+  ) {
+    throw new Error(
+      "@lynxship/expo lynxVersion must be auto, latest, or an exact semver",
+    );
+  }
+  return options;
+}
+
+function lynxVersion(options) {
+  return options.lynxVersion || DEFAULT_LYNX_VERSION;
+}
+
+function gradleLynxVersion(options) {
+  const value = lynxVersion(options);
+  return value === "auto" || value === "latest" ? "latest.release" : value;
+}
+
+function addAndroidMetaData(application, name, value) {
+  application["meta-data"] = application["meta-data"] || [];
+  const existing = application["meta-data"].find(
+    (item) => item.$ && item.$["android:name"] === name,
+  );
+  if (existing) existing.$["android:value"] = value;
+  else
+    application["meta-data"].push({
+      $: { "android:name": name, "android:value": value },
+    });
+}
+
+function withLynxShipAndroidManifest(config, options) {
+  return withAndroidManifest(config, (value) => {
+    const manifest = value.modResults.manifest;
+    manifest["uses-permission"] = manifest["uses-permission"] || [];
+    if (
+      !manifest["uses-permission"].some(
+        (item) =>
+          item.$ && item.$["android:name"] === "android.permission.INTERNET",
+      )
+    ) {
+      manifest["uses-permission"].push({
+        $: { "android:name": "android.permission.INTERNET" },
+      });
+    }
+    const application = manifest.application && manifest.application[0];
+    if (!application)
+      throw new Error("@lynxship/expo requires an Android application node");
+    const metadata = {
+      endpoint: options.endpoint || "",
+      projectId: options.projectId || "",
+      channel: options.channel || "production",
+      runtimeVersion: options.runtimeVersion || "",
+      embeddedBundle: options.embeddedBundle || "main.lynx.bundle",
+      publicKeys: JSON.stringify(options.publicKeys || {}),
+      maxReleaseBytes: String(options.maxReleaseBytes || 104857600),
+    };
+    for (const [key, item] of Object.entries(metadata))
+      addAndroidMetaData(application, `com.lynxship.expo.${key}`, item);
+    return value;
+  });
+}
+
+function withLynxShipInfoPlist(config, options) {
+  return withInfoPlist(config, (value) => {
+    value.modResults.LynxShipExpo = {
+      endpoint: options.endpoint || "",
+      projectId: options.projectId || "",
+      channel: options.channel || "production",
+      runtimeVersion: options.runtimeVersion || "",
+      embeddedBundle: options.embeddedBundle || "main.lynx.bundle",
+      publicKeys: options.publicKeys || {},
+      maxReleaseBytes: options.maxReleaseBytes || 104857600,
+    };
+    return value;
+  });
+}
+
+function withLynxShipGradle(config, options) {
+  return withGradleProperties(config, (value) => {
+    const properties = value.modResults;
+    const key = "LYNXSHIP_LYNX_VERSION";
+    const current = properties.find((item) => item.key === key);
+    if (current) current.value = gradleLynxVersion(options);
+    else
+      properties.push({
+        type: "property",
+        key,
+        value: gradleLynxVersion(options),
+      });
+    const androidX = properties.find(
+      (item) => item.key === "android.useAndroidX",
+    );
+    if (androidX) androidX.value = "true";
+    else
+      properties.push({
+        type: "property",
+        key: "android.useAndroidX",
+        value: "true",
+      });
+    return value;
+  });
+}
+
+function withLynxShipAndroidSdk(config) {
+  return withSettingsGradle(config, (value) => {
+    const settings = value.modResults.contents;
+    if (settings.includes("@lynxship/expo managed sdk")) return value;
+    value.modResults.contents = `${settings.trimEnd()}\n\n// @lynxship/expo managed sdk\ninclude ':lynxship-sdk-android'\nproject(':lynxship-sdk-android').projectDir = new File(rootDir, '../node_modules/@lynxship/sdk-android')\n`;
+    return value;
+  });
+}
+
+function withLynxShipPodfile(config, options) {
+  return withPodfile(config, (value) => {
+    const podfile = value.modResults.contents;
+    if (podfile.includes(MARKER)) return value;
+    const additions = [
+      `  ${MARKER}`,
+      ...(lynxVersion(options) === "auto" || lynxVersion(options) === "latest"
+        ? []
+        : [`  ENV['LYNXSHIP_LYNX_VERSION'] = '${lynxVersion(options)}'`]),
+      "  pod 'LynxShipOta', :path => '../node_modules/@lynxship/sdk-ios'",
+      `  ${MARKER} end`,
+    ].join("\n");
+    const target = podfile.search(/^target\s+['\"][^'\"]+['\"]\s+do\s*$/m);
+    if (target < 0)
+      throw new Error("@lynxship/expo could not find an iOS Podfile target");
+    const lineEnd = podfile.indexOf("\n", target);
+    value.modResults.contents = `${podfile.slice(0, lineEnd + 1)}${additions}\n${podfile.slice(lineEnd + 1)}`;
+    return value;
+  });
+}
+
+function withLynxShipExpo(config, props = {}) {
+  const options = assertOptions({ ...getOptions(config), ...props });
+  return withLynxShipPodfile(
+    withLynxShipAndroidSdk(
+      withLynxShipGradle(
+        withLynxShipInfoPlist(
+          withLynxShipAndroidManifest(config, options),
+          options,
+        ),
+        options,
+      ),
+    ),
+    options,
+  );
+}
+
+module.exports = withLynxShipExpo;

package/app.plugin.js

@@ -0,0 +1,4 @@
+// Expo resolves package config plugins through this conventional entry point.
+// Keep the implementation CommonJS so it can be evaluated by Expo's Node.js
+// config phase regardless of the consuming app's module configuration.
+module.exports = require("./app.plugin.cjs");

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export interface LynxShipExpoConfig {
+    endpoint?: string;
+    projectId?: string;
+    channel?: string;
+    runtimeVersion?: string;
+    publicKeys?: Record<string, string>;
+    embeddedBundle?: string;
+    lynxVersion?: string;
+    maxReleaseBytes?: number;
+}
+export declare function validateLynxShipExpoConfig(value?: LynxShipExpoConfig): LynxShipExpoConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD,wBAAgB,0BAA0B,CACxC,KAAK,GAAE,kBAAuB,GAC7B,kBAAkB,CAkCpB"}

package/dist/config.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateLynxShipExpoConfig = validateLynxShipExpoConfig;
+/** Let the native package manager resolve the current Lynx SDK by default. */
+const DEFAULT_LYNX_VERSION = "auto";
+function validateLynxShipExpoConfig(value = {}) {
+    if (value.endpoint !== undefined) {
+        const url = new URL(value.endpoint);
+        if (url.protocol !== "https:" && !isLocalDevelopment(url.hostname))
+            throw new Error("LynxShip Expo endpoint must use HTTPS outside localhost");
+    }
+    for (const [key, publicKey] of Object.entries(value.publicKeys ?? {})) {
+        if (!key.trim() || !publicKey.includes("BEGIN PUBLIC KEY"))
+            throw new Error("LynxShip Expo publicKeys must contain PEM public keys");
+    }
+    if (value.maxReleaseBytes !== undefined) {
+        if (!Number.isInteger(value.maxReleaseBytes) || value.maxReleaseBytes < 1)
+            throw new Error("LynxShip Expo maxReleaseBytes must be a positive integer");
+    }
+    if (value.lynxVersion !== undefined &&
+        value.lynxVersion !== "auto" &&
+        value.lynxVersion !== "latest" &&
+        !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value.lynxVersion)) {
+        throw new Error("LynxShip Expo lynxVersion must be auto, latest, or an exact semver");
+    }
+    return {
+        ...value,
+        channel: value.channel ?? "production",
+        embeddedBundle: value.embeddedBundle ?? "main.lynx.bundle",
+        lynxVersion: value.lynxVersion ?? DEFAULT_LYNX_VERSION,
+    };
+}
+function isLocalDevelopment(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1";
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type ComponentType } from "react";
+import type { ViewProps } from "react-native";
+import { type LynxShipExpoConfig } from "./config.js";
+export type { LynxShipExpoConfig } from "./config.js";
+export { validateLynxShipExpoConfig } from "./config.js";
+export interface LynxViewProps extends ViewProps {
+    /** Bundle name resolved by the native Lynx template provider. */
+    bundle?: string;
+    /** Optional initial data passed to Lynx when the view is rendered. */
+    initialData?: string;
+    /** Requests a fresh render after an OTA candidate has been activated. */
+    reloadOnUpdate?: boolean;
+}
+/**
+ * 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): unknown;
+export declare const LynxShipView: ComponentType<LynxViewProps>;
+export declare function defineLynxShipExpoConfig(config: LynxShipExpoConfig): LynxShipExpoConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAE1D,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,OAAO,CAOtD;AAED,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,aAAa,CAAY,CAAC;AAEnE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,GACzB,kBAAkB,CAEpB"}

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LynxShipView = exports.validateLynxShipExpoConfig = void 0;
+exports.LynxView = LynxView;
+exports.defineLynxShipExpoConfig = defineLynxShipExpoConfig;
+const react_1 = require("react");
+const expo_modules_core_1 = require("expo-modules-core");
+const config_js_1 = require("./config.js");
+var config_js_2 = require("./config.js");
+Object.defineProperty(exports, "validateLynxShipExpoConfig", { enumerable: true, get: function () { return config_js_2.validateLynxShipExpoConfig; } });
+const NativeLynxView = (0, expo_modules_core_1.requireNativeViewManager)("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.
+ */
+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;
+function defineLynxShipExpoConfig(config) {
+    return (0, config_js_1.validateLynxShipExpoConfig)(config);
+}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["android", "ios"],
+  "android": {
+    "modules": ["com.lynxship.expo.LynxShipExpoModule"]
+  },
+  "ios": {
+    "modules": ["LynxShipExpoModule"]
+  }
+}

package/ios/LynxShipExpoModule.swift

@@ -0,0 +1,22 @@
+import ExpoModulesCore
+
+public class LynxShipExpoModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("LynxShip")
+    View(LynxShipExpoView.self) {
+      Events("onReady", "onError", "onUpdate")
+      Prop("bundle") { (view: LynxShipExpoView, value: String?) in
+        view.bundleName = value ?? "main.lynx.bundle"
+      }
+      Prop("initialData") { (view: LynxShipExpoView, value: String?) in
+        view.initialData = value ?? ""
+      }
+      Prop("reloadOnUpdate") { (view: LynxShipExpoView, value: Bool?) in
+        view.reloadOnUpdate = value ?? true
+      }
+      AsyncFunction("reload") { (view: LynxShipExpoView) in
+        try view.reload()
+      }
+    }
+  }
+}

package/ios/LynxShipExpoView.swift

@@ -0,0 +1,150 @@
+import ExpoModulesCore
+import Foundation
+import Lynx
+import LynxShipOta
+import UIKit
+
+private final class LynxShipTemplateProvider: NSObject, LynxTemplateProvider {
+  private let load: (String) throws -> Data
+  private let onLoaded: () -> Void
+
+  init(load: @escaping (String) throws -> Data, onLoaded: @escaping () -> Void) {
+    self.load = load
+    self.onLoaded = onLoaded
+  }
+
+  func loadTemplate(withUrl url: String!, onComplete callback: LynxTemplateLoadBlock!) {
+    do {
+      callback(load(url), nil)
+      onLoaded()
+    } catch {
+      callback(nil, error)
+    }
+  }
+}
+
+public final class LynxShipExpoView: ExpoView {
+  let onReady = EventDispatcher()
+  let onError = EventDispatcher()
+  let onUpdate = 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
+      guard let self else { return }
+      try? self.otaClient?.markLaunchSuccess()
+      DispatchQueue.main.async {
+        self.onReady(["bundle": self.bundleName, "sequence": self.otaClient?.activeSequence ?? 0])
+      }
+    }
+  )
+
+  private lazy var lynxView: LynxView = {
+    LynxView { builder in
+      builder.config = LynxConfig(provider: self.templateProvider)
+      builder.fontScale = 1.0
+    }
+  }()
+
+  private var otaClient: LynxShipOtaClient?
+  private var hasRendered = false
+  var bundleName = "main.lynx.bundle"
+  var initialData = ""
+  var reloadOnUpdate = true
+
+  public required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    LynxEnv.sharedInstance()
+    otaClient = makeOtaClient()
+    addSubview(lynxView)
+  }
+
+  public override func layoutSubviews() {
+    super.layoutSubviews()
+    lynxView.frame = bounds
+    lynxView.preferredLayoutWidth = bounds.width
+    lynxView.preferredLayoutHeight = bounds.height
+  }
+
+  public override func didMoveToWindow() {
+    super.didMoveToWindow()
+    guard window != nil, !hasRendered else { return }
+    do {
+      try otaClient?.beginLaunch()
+      render()
+      checkForUpdate()
+    } catch {
+      onError(["message": error.localizedDescription])
+    }
+  }
+
+  func reload() throws {
+    render()
+  }
+
+  private func render() {
+    lynxView.loadTemplate(fromURL: bundleName, initData: initialData)
+    hasRendered = true
+  }
+
+  private func checkForUpdate() {
+    Task { [weak self] in
+      guard let self else { return }
+      do {
+        guard let otaClient else { return }
+        guard try await otaClient.checkAndInstall() else { return }
+        try otaClient.activateCandidate()
+        await MainActor.run {
+          self.onUpdate(["sequence": otaClient.activeSequence])
+          if self.reloadOnUpdate { self.render() }
+        }
+      } catch {
+        await MainActor.run {
+          self.onError(["message": error.localizedDescription, "recoverable": true])
+        }
+      }
+    }
+  }
+
+  private func readEmbeddedAsset(_ path: String) throws -> Data {
+    guard !path.isEmpty, !path.hasPrefix("/"), !path.contains(".."), !path.contains("\\") else {
+      throw NSError(domain: "LynxShip", code: 2, userInfo: [NSLocalizedDescriptionKey: "Unsafe Lynx asset path"])
+    }
+    guard let url = Bundle.main.url(forResource: path, withExtension: nil) ?? Bundle.main.url(forResource: path, withExtension: "bundle") else {
+      throw NSError(domain: "LynxShip", code: 3, userInfo: [NSLocalizedDescriptionKey: "Embedded Lynx bundle not found: \(path)"])
+    }
+    return try Data(contentsOf: url)
+  }
+
+  private func makeOtaClient() -> LynxShipOtaClient? {
+    guard let value = Bundle.main.object(forInfoDictionaryKey: "LynxShipExpo") as? [String: Any],
+          let endpointString = value["endpoint"] as? String, !endpointString.isEmpty,
+          let endpoint = URL(string: endpointString),
+          let projectId = value["projectId"] as? String, !projectId.isEmpty,
+          let runtimeVersion = value["runtimeVersion"] as? String, !runtimeVersion.isEmpty else { return nil }
+    do {
+      let keys = value["publicKeys"] as? [String: String] ?? [:]
+      let channel = value["channel"] as? String ?? "production"
+      let storage = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0].appendingPathComponent("lynxship-ota", isDirectory: true)
+      let installationId = UIDevice.current.identifierForVendor?.uuidString ?? UUID().uuidString
+      let configuration = try LynxShipOtaClient.Configuration(
+        storageDirectory: storage,
+        endpoint: endpoint,
+        projectID: projectId,
+        channel: channel,
+        runtimeVersion: runtimeVersion,
+        installationID: installationId,
+        publicKeys: keys,
+        embeddedAssets: readEmbeddedAsset,
+        maxReleaseBytes: value["maxReleaseBytes"] as? Int ?? 100 * 1024 * 1024
+      )
+      return try LynxShipOtaClient(configuration: configuration)
+    } catch {
+      onError(["message": error.localizedDescription])
+      return nil
+    }
+  }
+}

package/lynxship-expo.podspec

@@ -0,0 +1,25 @@
+Pod::Spec.new do |s|
+  s.name = 'LynxShipExpo'
+  s.version = '0.1.0'
+  s.summary = 'Expo native LynxView integration for LynxShip.'
+  s.license = { :type => 'MIT' }
+  s.author = { 'LynxShip' => 'opensource@lynxship.dev' }
+  s.source = { :path => '.' }
+  s.source_files = 'ios/**/*.{h,m,mm,swift}'
+  s.platform = :ios, '15.0'
+  s.swift_version = '5.9'
+  s.dependency 'ExpoModulesCore'
+  s.dependency 'LynxShipOta'
+  lynx_version = ENV['LYNXSHIP_LYNX_VERSION']
+  if lynx_version && !lynx_version.empty? && lynx_version != 'auto' && lynx_version != 'latest'
+    s.dependency 'Lynx', lynx_version, :subspecs => ['Framework']
+    s.dependency 'PrimJS', lynx_version, :subspecs => ['quickjs', 'napi']
+    s.dependency 'LynxService', lynx_version, :subspecs => ['Image', 'Log', 'Http']
+  else
+    s.dependency 'Lynx', :subspecs => ['Framework']
+    s.dependency 'PrimJS', :subspecs => ['quickjs', 'napi']
+    s.dependency 'LynxService', :subspecs => ['Image', 'Log', 'Http']
+  end
+  s.dependency 'SDWebImage', '5.15.5'
+  s.dependency 'SDWebImageWebPCoder', '0.11.0'
+end

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lynxship/expo",
+  "version": "0.1.0",
+  "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",
+    "src",
+    "app.plugin.js",
+    "app.plugin.cjs",
+    "expo-module.config.json",
+    "lynxship-expo.podspec",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/p0ulsh3n/lynx-ship.git",
+    "directory": "packages/expo"
+  },
+  "bugs": {
+    "url": "https://github.com/p0ulsh3n/lynx-ship/issues"
+  },
+  "homepage": "https://github.com/p0ulsh3n/lynx-ship/tree/main/packages/expo#readme",
+  "keywords": [
+    "lynxjs",
+    "lynx",
+    "expo",
+    "react-native",
+    "ota"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@expo/config-plugins": ">=9",
+    "expo": ">=52",
+    "expo-modules-core": ">=1",
+    "react": ">=18",
+    "react-native": ">=0.76"
+  },
+  "dependencies": {
+    "@lynxship/sdk-android": "0.1.0",
+    "@lynxship/sdk-ios": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json --pretty false"
+  }
+}

package/src/config.ts

@@ -0,0 +1,55 @@
+export interface LynxShipExpoConfig {
+  endpoint?: string;
+  projectId?: string;
+  channel?: string;
+  runtimeVersion?: string;
+  publicKeys?: Record<string, string>;
+  embeddedBundle?: string;
+  lynxVersion?: string;
+  maxReleaseBytes?: number;
+}
+
+/** Let the native package manager resolve the current Lynx SDK by default. */
+const DEFAULT_LYNX_VERSION = "auto";
+
+export function validateLynxShipExpoConfig(
+  value: LynxShipExpoConfig = {},
+): LynxShipExpoConfig {
+  if (value.endpoint !== undefined) {
+    const url = new URL(value.endpoint);
+    if (url.protocol !== "https:" && !isLocalDevelopment(url.hostname))
+      throw new Error(
+        "LynxShip Expo endpoint must use HTTPS outside localhost",
+      );
+  }
+  for (const [key, publicKey] of Object.entries(value.publicKeys ?? {})) {
+    if (!key.trim() || !publicKey.includes("BEGIN PUBLIC KEY"))
+      throw new Error("LynxShip Expo publicKeys must contain PEM public keys");
+  }
+  if (value.maxReleaseBytes !== undefined) {
+    if (!Number.isInteger(value.maxReleaseBytes) || value.maxReleaseBytes < 1)
+      throw new Error(
+        "LynxShip Expo maxReleaseBytes must be a positive integer",
+      );
+  }
+  if (
+    value.lynxVersion !== undefined &&
+    value.lynxVersion !== "auto" &&
+    value.lynxVersion !== "latest" &&
+    !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value.lynxVersion)
+  ) {
+    throw new Error(
+      "LynxShip Expo lynxVersion must be auto, latest, or an exact semver",
+    );
+  }
+  return {
+    ...value,
+    channel: value.channel ?? "production",
+    embeddedBundle: value.embeddedBundle ?? "main.lynx.bundle",
+    lynxVersion: value.lynxVersion ?? DEFAULT_LYNX_VERSION,
+  };
+}
+
+function isLocalDevelopment(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1";
+}

package/src/externals.d.ts

@@ -0,0 +1,23 @@
+declare module "react" {
+  export type ComponentType<Props = Record<string, unknown>> = (
+    props: Props,
+  ) => unknown;
+  export function createElement(
+    type: unknown,
+    props: Record<string, unknown> | null,
+  ): unknown;
+}
+
+declare module "react-native" {
+  export interface ViewProps {
+    accessibilityLabel?: string;
+    style?: unknown;
+    testID?: string;
+  }
+}
+
+declare module "expo-modules-core" {
+  export function requireNativeViewManager<Props = Record<string, unknown>>(
+    moduleName: string,
+  ): (props: Props) => unknown;
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+import { createElement, type ComponentType } from "react";
+import { requireNativeViewManager } from "expo-modules-core";
+import type { ViewProps } from "react-native";
+import {
+  validateLynxShipExpoConfig,
+  type LynxShipExpoConfig,
+} from "./config.js";
+
+export type { LynxShipExpoConfig } from "./config.js";
+
+export { validateLynxShipExpoConfig } from "./config.js";
+
+export interface LynxViewProps extends ViewProps {
+  /** Bundle name resolved by the native Lynx template provider. */
+  bundle?: string;
+  /** Optional initial data passed to Lynx when the view is rendered. */
+  initialData?: string;
+  /** Requests a fresh render after an OTA candidate has been activated. */
+  reloadOnUpdate?: boolean;
+}
+
+const NativeLynxView = requireNativeViewManager<LynxViewProps>("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): unknown {
+  return createElement(NativeLynxView, {
+    bundle: props.bundle ?? "main.lynx.bundle",
+    initialData: props.initialData ?? "",
+    reloadOnUpdate: props.reloadOnUpdate ?? true,
+    ...props,
+  });
+}
+
+export const LynxShipView: ComponentType<LynxViewProps> = LynxView;
+
+export function defineLynxShipExpoConfig(
+  config: LynxShipExpoConfig,
+): LynxShipExpoConfig {
+  return validateLynxShipExpoConfig(config);
+}