react-native-litert-lm 0.2.2 → 0.3.1

package/nitrogen/generated/android/c++/JHybridLiteRTLMSpec.hpp

@@ -18,34 +18,33 @@ namespace margelo::nitro::litertlm {
 
   using namespace facebook;
 
-  class JHybridLiteRTLMSpec: public jni::HybridClass<JHybridLiteRTLMSpec, JHybridObject>,
-                             public virtual HybridLiteRTLMSpec {
+  class JHybridLiteRTLMSpec: public virtual HybridLiteRTLMSpec, public virtual JHybridObject {
   public:
-    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/dev/litert/litertlm/HybridLiteRTLMSpec;";
-    static jni::local_ref<jhybriddata> initHybrid(jni::alias_ref<jhybridobject> jThis);
-    static void registerNatives();
-
-  protected:
-    // C++ constructor (called from Java via `initHybrid()`)
-    explicit JHybridLiteRTLMSpec(jni::alias_ref<jhybridobject> jThis) :
-      HybridObject(HybridLiteRTLMSpec::TAG),
-      HybridBase(jThis),
-      _javaPart(jni::make_global(jThis)) {}
+    struct JavaPart: public jni::JavaClass<JavaPart, JHybridObject::JavaPart> {
+      static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/dev/litert/litertlm/HybridLiteRTLMSpec;";
+      std::shared_ptr<JHybridLiteRTLMSpec> getJHybridLiteRTLMSpec();
+    };
+    struct CxxPart: public jni::HybridClass<CxxPart, JHybridObject::CxxPart> {
+      static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/dev/litert/litertlm/HybridLiteRTLMSpec$CxxPart;";
+      static jni::local_ref<jhybriddata> initHybrid(jni::alias_ref<jhybridobject> jThis);
+      static void registerNatives();
+      using HybridBase::HybridBase;
+    protected:
+      std::shared_ptr<JHybridObject> createHybridObject(const jni::local_ref<JHybridObject::JavaPart>& javaPart) override;
+    };
 
   public:
+    explicit JHybridLiteRTLMSpec(const jni::local_ref<JHybridLiteRTLMSpec::JavaPart>& javaPart):
+      HybridObject(HybridLiteRTLMSpec::TAG),
+      JHybridObject(javaPart),
+      _javaPart(jni::make_global(javaPart)) {}
     ~JHybridLiteRTLMSpec() override {
       // Hermes GC can destroy JS objects on a non-JNI Thread.
       jni::ThreadScope::WithClassLoader([&] { _javaPart.reset(); });
     }
 
   public:
-    size_t getExternalMemorySize() noexcept override;
-    bool equals(const std::shared_ptr<HybridObject>& other) override;
-    void dispose() noexcept override;
-    std::string toString() override;
-
-  public:
-    inline const jni::global_ref<JHybridLiteRTLMSpec::javaobject>& getJavaPart() const noexcept {
+    inline const jni::global_ref<JHybridLiteRTLMSpec::JavaPart>& getJavaPart() const noexcept {
       return _javaPart;
     }
 
@@ -70,9 +69,7 @@ namespace margelo::nitro::litertlm {
     void close() override;
 
   private:
-    friend HybridBase;
-    using HybridBase::HybridBase;
-    jni::global_ref<JHybridLiteRTLMSpec::javaobject> _javaPart;
+    jni::global_ref<JHybridLiteRTLMSpec::JavaPart> _javaPart;
   };
 
 } // namespace margelo::nitro::litertlm

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/HybridLiteRTLMSpec.kt

@@ -25,23 +25,6 @@ import com.margelo.nitro.core.HybridObject
   "LocalVariableName", "PropertyName", "PrivatePropertyName", "FunctionName"
 )
 abstract class HybridLiteRTLMSpec: HybridObject() {
-  @DoNotStrip
-  private var mHybridData: HybridData = initHybrid()
-
-  init {
-    super.updateNative(mHybridData)
-  }
-
-  override fun updateNative(hybridData: HybridData) {
-    mHybridData = hybridData
-    super.updateNative(hybridData)
-  }
-
-  // Default implementation of `HybridObject.toString()`
-  override fun toString(): String {
-    return "[HybridObject LiteRTLM]"
-  }
-
   // Properties
   
 
@@ -108,7 +91,21 @@ abstract class HybridLiteRTLMSpec: HybridObject() {
   @Keep
   abstract fun close(): Unit
 
-  private external fun initHybrid(): HybridData
+  // Default implementation of `HybridObject.toString()`
+  override fun toString(): String {
+    return "[HybridObject LiteRTLM]"
+  }
+
+  // C++ backing class
+  @DoNotStrip
+  @Keep
+  protected open class CxxPart(javaPart: HybridLiteRTLMSpec): HybridObject.CxxPart(javaPart) {
+    // C++ JHybridLiteRTLMSpec::CxxPart::initHybrid(...)
+    external override fun initHybrid(): HybridData
+  }
+  override fun createCxxPart(): CxxPart {
+    return CxxPart(this)
+  }
 
   companion object {
     protected const val TAG = "HybridLiteRTLMSpec"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-litert-lm",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "High-performance LLM inference for React Native using LiteRT-LM. Optimized for Gemma 3n and other on-device language models.",
   "license": "MIT",
   "author": "Hugh Chen (https://github.com/hung-yueh)",
@@ -37,9 +37,14 @@
     "android/src",
     "android/build.gradle",
     "android/CMakeLists.txt",
-    "ios",
+    "ios/*.mm",
+    "ios/*.m",
     "cpp",
     "nitrogen/generated",
+    "scripts/postinstall.js",
+    "scripts/download-ios-frameworks.sh",
+    "scripts/build-ios-engine.sh",
+    "scripts/stubs",
     "react-native.config.js",
     "react-native-litert-lm.podspec",
     "app.plugin.js",
@@ -50,12 +55,14 @@
     "node": ">=22"
   },
   "scripts": {
+    "postinstall": "node scripts/postinstall.js",
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "lint": "eslint \"**/*.{js,ts,tsx}\" --fix",
     "prepack": "npm run build",
     "specs": "npx nitrogen",
-    "clean": "rm -rf lib android/build ios/build nitrogen/generated",
+    "clean": "rm -rf lib android/build ios/build ios/Frameworks nitrogen/generated",
+    "download-frameworks": "scripts/download-ios-frameworks.sh",
     "android": "expo run:android",
     "android:clean": "cd android && ./gradlew clean",
     "ios": "expo run:ios",
@@ -65,7 +72,7 @@
     "@expo/config-plugins": "~54.0.4",
     "@types/react": "~19.1.10",
     "expo": "^54.0.31",
-    "nitrogen": "^0.34.1",
+    "nitrogen": "^0.35.0",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "release-it": "^19.2.4",
@@ -82,6 +89,6 @@
     }
   },
   "dependencies": {
-    "react-native-nitro-modules": "^0.34.1"
+    "react-native-nitro-modules": "^0.35.0"
   }
 }

package/react-native-litert-lm.podspec

@@ -16,36 +16,49 @@ Pod::Spec.new do |s|
 
   s.source_files = [
     # Implementation (C++)
-    "cpp/**/*.{hpp,cpp}",
+    "cpp/**/*.{hpp,cpp,h}",
     # Autolinking (Objective-C++)
     "ios/**/*.{m,mm}",
     # Nitrogen generated iOS bridge
     "nitrogen/generated/ios/**/*.{mm,swift}",
   ]
 
+  # Exclude Android-only JNI files from iOS build
+  s.exclude_files = [
+    "cpp/cpp-adapter.cpp",
+  ]
+
+  # Prebuilt LiteRT-LM C engine (static library built from Bazel //c:engine target).
+  # Downloaded from GitHub releases by postinstall.js, or built locally via:
+  #   scripts/build-ios-engine.sh
+  s.vendored_frameworks = 'ios/Frameworks/LiteRTLM.xcframework'
+
   s.pod_target_xcconfig = {
     'CLANG_CXX_LANGUAGE_STANDARD' => 'c++20',
     'CLANG_CXX_LIBRARY' => 'libc++',
     'HEADER_SEARCH_PATHS' => [
       '"$(PODS_TARGET_SRCROOT)/cpp"',
+      '"$(PODS_TARGET_SRCROOT)/cpp/include"',
       '"$(PODS_TARGET_SRCROOT)/nitrogen/generated/shared/c++"',
       '"$(PODS_TARGET_SRCROOT)/nitrogen/generated/ios"',
     ].join(' '),
-    # Stub mode - LiteRT-LM iOS not yet available
-    'GCC_PREPROCESSOR_DEFINITIONS' => '$(inherited) LITERT_LM_IOS_STUB=1',
+    'OTHER_LDFLAGS' => '$(inherited) -ObjC',
   }
 
   # Load nitrogen autolinking
   load 'nitrogen/generated/ios/LiteRTLM+autolinking.rb'
   add_nitrogen_files(s)
 
-  # Core dependencies only - no LLM runtime yet
+  # Core React Native dependencies
   s.dependency 'React-jsi'
   s.dependency 'React-callinvoker'
   s.dependency 'ReactCommon/turbomodule/core'
-  
-  # TODO: Add LiteRT-LM iOS dependency when officially released
-  # s.dependency 'LiteRTLM', '~> 1.0'
+
+  # Apple frameworks needed by LiteRT-LM engine
+  # Metal/MPS: GPU inference, Accelerate: BLAS/LAPACK, CoreML: delegate
+  s.frameworks = ['Metal', 'MetalPerformanceShaders', 'Accelerate', 'CoreML', 'CoreGraphics']
+  s.libraries = ['c++']
 
   install_modules_dependencies(s)
 end
+

package/scripts/build-ios-engine.sh

@@ -0,0 +1,302 @@
+#!/bin/bash
+# build-ios-engine.sh
+#
+# Builds the LiteRT-LM C engine as a static library for iOS (device + simulator)
+# using Bazel, then packages it into an XCFramework for CocoaPods.
+#
+# Prerequisites:
+#   - Bazel 7.6.1+ (via Bazelisk recommended)
+#   - Xcode command line tools
+#
+# Usage:
+#   ./scripts/build-ios-engine.sh
+#
+# Output:
+#   ios/Frameworks/LiteRTLM.xcframework/  (static library + headers)
+
+set -euo pipefail
+
+LITERT_LM_VERSION="v0.9.0"
+LITERT_LM_REPO="https://github.com/google-ai-edge/LiteRT-LM.git"
+FRAMEWORK_NAME="LiteRTLM"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+OUTPUT_DIR="$PROJECT_ROOT/ios/Frameworks"
+C_API_HEADER_DIR="$PROJECT_ROOT/cpp/include"
+BUILD_DIR="$PROJECT_ROOT/.litert-lm-build"
+
+echo "==> Building LiteRT-LM ${LITERT_LM_VERSION} C engine for iOS..."
+echo ""
+
+# ---- 1. Clone / update the LiteRT-LM repo --------------------------------
+echo "==> Step 1: Preparing LiteRT-LM source..."
+if [ -f "$BUILD_DIR/LiteRT-LM/.bazelrc" ] && [ -f "$BUILD_DIR/LiteRT-LM/requirements.txt" ]; then
+  echo "   Source already exists, checking out ${LITERT_LM_VERSION}..."
+  cd "$BUILD_DIR/LiteRT-LM"
+  git fetch --tags 2>/dev/null || true
+  git checkout "$LITERT_LM_VERSION" 2>/dev/null || git checkout "tags/$LITERT_LM_VERSION"
+else
+  # Clean up any failed previous clone
+  rm -rf "$BUILD_DIR/LiteRT-LM"
+  mkdir -p "$BUILD_DIR"
+  echo "   Cloning LiteRT-LM (shallow, skipping LFS)..."
+
+  # Clone without LFS filter to avoid requiring git-lfs installation.
+  # The prebuilt/ directory will contain LFS pointer files but we don't
+  # need those — we're building the engine from source.
+  GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 --branch "$LITERT_LM_VERSION" \
+    -c filter.lfs.smudge=cat \
+    -c filter.lfs.process= \
+    -c filter.lfs.clean=cat \
+    -c filter.lfs.required=false \
+    "$LITERT_LM_REPO" "$BUILD_DIR/LiteRT-LM"
+
+  cd "$BUILD_DIR/LiteRT-LM"
+fi
+
+LITERT_SRC="$BUILD_DIR/LiteRT-LM"
+
+# ---- 1b. Apply iOS-specific patches ---------------------------------------
+# These patches fix:
+# - mmap PROT_WRITE removal (iOS rejects CoW for large files)
+# - Error capture API (litert_lm_get_last_error)
+# - Engine registerer moved outside anonymous namespace (iOS linker stripping)
+# - Minijinja/Rust stub replacement (custom C++ prompt template)
+PATCHES_DIR="$PROJECT_ROOT/scripts/patches"
+if [ -d "$PATCHES_DIR" ]; then
+  for PATCH_FILE in "$PATCHES_DIR"/*.patch; do
+    if [ -f "$PATCH_FILE" ]; then
+      echo "   Applying patch: $(basename "$PATCH_FILE")..."
+      cd "$LITERT_SRC"
+      git apply --check "$PATCH_FILE" 2>/dev/null && \
+        git apply "$PATCH_FILE" || \
+        echo "   (patch already applied or conflicts, skipping)"
+    fi
+  done
+fi
+
+# ---- 2. Verify Bazel is available -----------------------------------------
+echo ""
+echo "==> Step 2: Checking Bazel..."
+if command -v bazelisk &>/dev/null; then
+  BAZEL="bazelisk"
+elif command -v bazel &>/dev/null; then
+  BAZEL="bazel"
+else
+  echo "Error: Bazel is not installed."
+  echo "Install via: brew install bazelisk"
+  echo "Or download from: https://github.com/bazelbuild/bazelisk"
+  exit 1
+fi
+
+BAZEL_VERSION=$($BAZEL --version 2>&1 | head -1)
+echo "   Using: $BAZEL ($BAZEL_VERSION)"
+
+# ---- 3. Build the C engine static library for iOS -------------------------
+echo ""
+echo "==> Step 3: Building //c:engine for iOS..."
+
+cd "$LITERT_SRC"
+
+# Get Bazel output base (where all .o files live in the actual filesystem)
+BAZEL_OUTPUT_BASE=$($BAZEL info output_base 2>/dev/null)
+BAZEL_EXECROOT="$BAZEL_OUTPUT_BASE/execroot"
+
+STAGE_DIR="$BUILD_DIR/staged-libs"
+mkdir -p "$STAGE_DIR"
+
+# Helper: build for a config, then merge ALL transitive .o files into one .a
+# Bazel's cc_library produces thin archives — the engine's transitive deps
+# (absl, protobuf, runtime, KleidiAI, etc.) are separate .o files that must
+# be merged into a single self-contained static library for Xcode.
+build_fat_static_lib() {
+  local CONFIG="$1"
+  local CONFIG_DIR="$2"  # e.g. "ios_arm64-opt" or "ios_sim_arm64-opt"
+  local OUTPUT_PATH="$3"
+
+  echo "   Building for $CONFIG..."
+  # Build both the engine AND all cc_proto_library targets in a single Bazel
+  # invocation. Bazel's cc_proto_library compiles proto-generated code, but
+  # the .pb.o files only appear in the output tree if these targets are
+  # explicitly requested alongside the engine.
+  $BAZEL build \
+    //c:engine \
+    @sentencepiece//:sentencepiece_cc_proto \
+    @sentencepiece//:sentencepiece_model_cc_proto \
+    //runtime/proto:engine_cc_proto \
+    //runtime/proto:sampler_params_cc_proto \
+    //runtime/proto:llm_metadata_cc_proto \
+    //runtime/proto:token_cc_proto \
+    //runtime/proto:llm_model_type_cc_proto \
+    //runtime/util:external_file_cc_proto \
+    @com_google_protobuf//:protobuf \
+    @com_googlesource_code_re2//:re2 \
+    --config=$CONFIG 2>&1 | tail -5
+
+  echo "   Collecting transitive object files from $CONFIG_DIR..."
+  local OBJ_LIST="$STAGE_DIR/${CONFIG}-objects.txt"
+  find "$BAZEL_EXECROOT" -path "*/${CONFIG_DIR}/bin/*" -name "*.o" \
+    ! -name "*.h.processed" 2>/dev/null | sort > "$OBJ_LIST"
+
+  # ---- Compile stubs for Rust/llguidance deps (unavailable on iOS) ----------
+  local EXTRA_OBJS="$STAGE_DIR/${CONFIG}-extra-objs"
+  rm -rf "$EXTRA_OBJS"
+  mkdir -p "$EXTRA_OBJS"
+
+  local STUBS_DIR="$PROJECT_ROOT/scripts/stubs"
+  local STUB_FILES=$(find "$STUBS_DIR" \( -name "*.cc" -o -name "*.c" \) 2>/dev/null)
+  if [ -n "$STUB_FILES" ]; then
+    echo "   Compiling stubs for unavailable dependencies..."
+    local SDK_NAME="iphoneos"
+    local TARGET_TRIPLE="arm64-apple-ios15.0"
+    if [[ "$CONFIG_DIR" == *"sim"* ]]; then
+      SDK_NAME="iphonesimulator"
+      TARGET_TRIPLE="arm64-apple-ios15.0-simulator"
+    fi
+    local SDK_PATH=$(xcrun --sdk "$SDK_NAME" --show-sdk-path)
+    
+    for STUB_SRC in $STUB_FILES; do
+      local STUB_BASE=$(basename "$STUB_SRC")
+      local STUB_NAME="${STUB_BASE%.*}"
+      local STUB_EXT="${STUB_BASE##*.}"
+      echo "     → $STUB_NAME ($STUB_EXT)"
+      
+      if [ "$STUB_EXT" = "cc" ]; then
+        xcrun clang++ -c -std=c++20 \
+          -target "$TARGET_TRIPLE" \
+          -isysroot "$SDK_PATH" \
+          -DNDEBUG \
+          -o "$EXTRA_OBJS/${STUB_NAME}.o" \
+          "$STUB_SRC" 2>&1 || true
+      else
+        xcrun clang -c \
+          -target "$TARGET_TRIPLE" \
+          -isysroot "$SDK_PATH" \
+          -DNDEBUG \
+          -o "$EXTRA_OBJS/${STUB_NAME}.o" \
+          "$STUB_SRC" 2>&1 || true
+      fi
+    done
+    
+    # Add successfully compiled stubs to the object list
+    find "$EXTRA_OBJS" -name "*.o" -size +0c >> "$OBJ_LIST"
+  fi
+
+  local OBJ_COUNT=$(wc -l < "$OBJ_LIST" | tr -d ' ')
+  echo "   Found $OBJ_COUNT total object files (including proto + stubs)"
+
+  if [ "$OBJ_COUNT" -eq 0 ]; then
+    echo "Error: No object files found for $CONFIG in $CONFIG_DIR"
+    exit 1
+  fi
+
+  # Merge all .o files into a single fat static library using libtool
+  echo "   Merging into fat static library..."
+  xcrun libtool -static -o "$OUTPUT_PATH" -filelist "$OBJ_LIST" 2>&1 | grep -v "has no symbols" || true
+
+  local LIB_SIZE=$(du -h "$OUTPUT_PATH" | cut -f1)
+  echo "   ✅ $CONFIG: $LIB_SIZE ($OBJ_COUNT objects)"
+}
+
+# Build for device (arm64)
+DEVICE_LIB="$STAGE_DIR/libengine-device.a"
+build_fat_static_lib "ios_arm64" "ios_arm64-opt" "$DEVICE_LIB"
+
+echo ""
+
+# Build for simulator (sim_arm64)
+SIM_LIB="$STAGE_DIR/libengine-sim.a"
+build_fat_static_lib "ios_sim_arm64" "ios_sim_arm64-opt" "$SIM_LIB"
+
+echo ""
+echo "   Device lib: $DEVICE_LIB ($(du -h "$DEVICE_LIB" | cut -f1))"
+echo "   Simulator lib: $SIM_LIB ($(du -h "$SIM_LIB" | cut -f1))"
+
+# ---- 4. Copy the C API header ---------------------------------------------
+echo ""
+echo "==> Step 4: Vendoring C API header..."
+mkdir -p "$C_API_HEADER_DIR"
+cp "$LITERT_SRC/c/engine.h" "$C_API_HEADER_DIR/litert_lm_engine.h"
+echo "   ✅ Copied engine.h → cpp/include/litert_lm_engine.h"
+
+# ---- 5. Create XCFramework from static libraries --------------------------
+echo ""
+echo "==> Step 5: Creating XCFramework..."
+
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR"
+
+TMP_DIR="$(mktemp -d)"
+cleanup() { rm -rf "$TMP_DIR"; }
+trap cleanup EXIT
+
+# Create framework bundles from static libraries
+for ARCH_NAME in "device" "simulator"; do
+  if [ "$ARCH_NAME" = "device" ]; then
+    LIB_PATH="$DEVICE_LIB"
+  else
+    LIB_PATH="$SIM_LIB"
+  fi
+
+  FW_DIR="$TMP_DIR/$ARCH_NAME/$FRAMEWORK_NAME.framework"
+  mkdir -p "$FW_DIR/Headers"
+
+  # Copy static lib as the framework binary
+  cp "$LIB_PATH" "$FW_DIR/$FRAMEWORK_NAME"
+
+  # Copy headers
+  cp "$C_API_HEADER_DIR/litert_lm_engine.h" "$FW_DIR/Headers/"
+
+  # Create Info.plist
+  cat > "$FW_DIR/Info.plist" << PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleExecutable</key>
+  <string>${FRAMEWORK_NAME}</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.google.ai.edge.litert-lm</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>${FRAMEWORK_NAME}</string>
+  <key>CFBundlePackageType</key>
+  <string>FMWK</string>
+  <key>CFBundleShortVersionString</key>
+  <string>0.9.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>MinimumOSVersion</key>
+  <string>15.0</string>
+</dict>
+</plist>
+PLIST
+done
+
+# Create XCFramework
+xcodebuild -create-xcframework \
+  -framework "$TMP_DIR/device/$FRAMEWORK_NAME.framework" \
+  -framework "$TMP_DIR/simulator/$FRAMEWORK_NAME.framework" \
+  -output "$OUTPUT_DIR/$FRAMEWORK_NAME.xcframework" 2>&1
+
+echo "   ✅ XCFramework created at: ios/Frameworks/${FRAMEWORK_NAME}.xcframework"
+
+# ---- 6. Create zip for release asset --------------------------------------
+echo ""
+echo "==> Step 6: Creating release asset zip..."
+cd "$OUTPUT_DIR"
+zip -r "$PROJECT_ROOT/LiteRTLM-ios-frameworks.zip" . -x ".*" 2>&1
+ZIP_SIZE=$(du -h "$PROJECT_ROOT/LiteRTLM-ios-frameworks.zip" | cut -f1)
+echo "   ✅ Created LiteRTLM-ios-frameworks.zip (${ZIP_SIZE})"
+
+echo ""
+echo "==> Done! iOS engine built and packaged."
+echo ""
+echo "Contents:"
+find "$OUTPUT_DIR" -type f | head -20 | while read f; do
+  echo "  $(echo "$f" | sed "s|$PROJECT_ROOT/||") ($(du -h "$f" | cut -f1))"
+done

package/scripts/download-ios-frameworks.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# download-ios-frameworks.sh
+#
+# Downloads prebuilt LiteRT-LM iOS static engine from this project's GitHub
+# releases. If the prebuilt asset is not available, falls back to building
+# from source via Bazel (see build-ios-engine.sh).
+#
+# The XCFramework contains a static library compiled from the LiteRT-LM
+# C engine (//c:engine Bazel target) for both device (arm64) and simulator
+# (sim_arm64).
+#
+# Usage:
+#   ./scripts/download-ios-frameworks.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+OUTPUT_DIR="$PROJECT_ROOT/ios/Frameworks"
+C_API_HEADER_DIR="$PROJECT_ROOT/cpp/include"
+
+LITERT_LM_VERSION="v0.9.0"
+GITHUB_RAW="https://github.com/google-ai-edge/LiteRT-LM/raw/${LITERT_LM_VERSION}"
+
+# Read version from package.json
+PACKAGE_VERSION=$(node -e "console.log(require('$PROJECT_ROOT/package.json').version)" 2>/dev/null || echo "0.0.0")
+GITHUB_REPO="hung-yueh/react-native-litert-lm"
+ASSET_NAME="LiteRTLM-ios-frameworks.zip"
+
+# Skip if already present
+if [ -d "$OUTPUT_DIR" ] && [ "$(find "$OUTPUT_DIR" -name "*.xcframework" 2>/dev/null | wc -l)" -gt 0 ]; then
+  echo "[LiteRT-LM] iOS frameworks already present at ios/Frameworks/, skipping."
+  exit 0
+fi
+
+# ---- Ensure C API header is vendored --------------------------------------
+echo "[LiteRT-LM] Vendoring C API header..."
+mkdir -p "$C_API_HEADER_DIR"
+curl -fsSL -o "$C_API_HEADER_DIR/litert_lm_engine.h" \
+  "${GITHUB_RAW}/c/engine.h" 2>/dev/null || true
+
+# ---- Try downloading prebuilt from our GitHub releases --------------------
+RELEASE_URL="https://github.com/${GITHUB_REPO}/releases/download/v${PACKAGE_VERSION}/${ASSET_NAME}"
+
+echo "[LiteRT-LM] Attempting to download prebuilt iOS engine from:"
+echo "   ${RELEASE_URL}"
+
+TMP_ZIP="$PROJECT_ROOT/.ios-frameworks-tmp.zip"
+if curl -fsSL -o "$TMP_ZIP" "$RELEASE_URL" 2>/dev/null; then
+  echo "[LiteRT-LM] Download successful, extracting..."
+  rm -rf "$OUTPUT_DIR"
+  mkdir -p "$OUTPUT_DIR"
+  unzip -o -q "$TMP_ZIP" -d "$OUTPUT_DIR"
+  rm -f "$TMP_ZIP"
+  echo "[LiteRT-LM] ✅ iOS frameworks installed from prebuilt release."
+  exit 0
+fi
+
+rm -f "$TMP_ZIP"
+echo "[LiteRT-LM] Prebuilt not available for v${PACKAGE_VERSION}."
+
+# ---- Fall back to building from source ------------------------------------
+echo "[LiteRT-LM] Falling back to building from source via Bazel..."
+echo ""
+
+if [ -x "$SCRIPT_DIR/build-ios-engine.sh" ]; then
+  exec "$SCRIPT_DIR/build-ios-engine.sh"
+else
+  echo "Error: build-ios-engine.sh not found or not executable."
+  echo "Run manually: ./scripts/build-ios-engine.sh"
+  exit 1
+fi