react-native-litert-lm 0.2.1 → 0.3.0

package/nitrogen/generated/shared/c++/MemoryUsage.hpp

@@ -0,0 +1,95 @@
+///
+/// MemoryUsage.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+
+
+namespace margelo::nitro::litertlm {
+
+  /**
+   * A struct which can be represented as a JavaScript object (MemoryUsage).
+   */
+  struct MemoryUsage final {
+  public:
+    double nativeHeapBytes     SWIFT_PRIVATE;
+    double residentBytes     SWIFT_PRIVATE;
+    double availableMemoryBytes     SWIFT_PRIVATE;
+    bool isLowMemory     SWIFT_PRIVATE;
+
+  public:
+    MemoryUsage() = default;
+    explicit MemoryUsage(double nativeHeapBytes, double residentBytes, double availableMemoryBytes, bool isLowMemory): nativeHeapBytes(nativeHeapBytes), residentBytes(residentBytes), availableMemoryBytes(availableMemoryBytes), isLowMemory(isLowMemory) {}
+
+  public:
+    friend bool operator==(const MemoryUsage& lhs, const MemoryUsage& rhs) = default;
+  };
+
+} // namespace margelo::nitro::litertlm
+
+namespace margelo::nitro {
+
+  // C++ MemoryUsage <> JS MemoryUsage (object)
+  template <>
+  struct JSIConverter<margelo::nitro::litertlm::MemoryUsage> final {
+    static inline margelo::nitro::litertlm::MemoryUsage fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::litertlm::MemoryUsage(
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "nativeHeapBytes"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "residentBytes"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "availableMemoryBytes"))),
+        JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isLowMemory")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::litertlm::MemoryUsage& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "nativeHeapBytes"), JSIConverter<double>::toJSI(runtime, arg.nativeHeapBytes));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "residentBytes"), JSIConverter<double>::toJSI(runtime, arg.residentBytes));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "availableMemoryBytes"), JSIConverter<double>::toJSI(runtime, arg.availableMemoryBytes));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "isLowMemory"), JSIConverter<bool>::toJSI(runtime, arg.isLowMemory));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "nativeHeapBytes")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "residentBytes")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "availableMemoryBytes")))) return false;
+      if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isLowMemory")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-litert-lm",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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.33.2",
+    "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.33.2"
+    "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,283 @@
+#!/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"
+
+# ---- 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

package/scripts/postinstall.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js
+ *
+ * Downloads prebuilt LiteRT-LM iOS frameworks from this package's GitHub
+ * releases when consumers run `npm install react-native-litert-lm`.
+ *
+ * Skips download if:
+ *   - Not on macOS (iOS builds require macOS)
+ *   - Frameworks already exist
+ *   - CI environment with SKIP_IOS_FRAMEWORK_DOWNLOAD=1
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const PACKAGE_JSON = require('../package.json');
+const PACKAGE_VERSION = PACKAGE_JSON.version;
+const GITHUB_REPO = 'hung-yueh/react-native-litert-lm';
+const ASSET_NAME = 'LiteRTLM-ios-frameworks.zip';
+
+const SCRIPT_DIR = __dirname;
+const PACKAGE_ROOT = path.resolve(SCRIPT_DIR, '..');
+const FRAMEWORKS_DIR = path.join(PACKAGE_ROOT, 'ios', 'Frameworks');
+
+function log(msg) {
+  console.log(`[react-native-litert-lm] ${msg}`);
+}
+
+function shouldSkip() {
+  // Skip if not macOS
+  if (process.platform !== 'darwin') {
+    log('Skipping iOS framework download (not macOS).');
+    return true;
+  }
+
+  // Skip if explicitly disabled
+  if (process.env.SKIP_IOS_FRAMEWORK_DOWNLOAD === '1') {
+    log('Skipping iOS framework download (SKIP_IOS_FRAMEWORK_DOWNLOAD=1).');
+    return true;
+  }
+
+  // Skip if frameworks already exist
+  if (fs.existsSync(FRAMEWORKS_DIR) && fs.readdirSync(FRAMEWORKS_DIR).length > 0) {
+    log('iOS frameworks already present, skipping download.');
+    return true;
+  }
+
+  return false;
+}
+
+function downloadFile(url, destPath, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects <= 0) {
+      return reject(new Error('Too many redirects'));
+    }
+
+    const protocol = url.startsWith('https') ? https : require('http');
+
+    protocol.get(url, { headers: { 'User-Agent': 'react-native-litert-lm' } }, (res) => {
+      // Follow redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return downloadFile(res.headers.location, destPath, maxRedirects - 1)
+          .then(resolve)
+          .catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+      }
+
+      const file = fs.createWriteStream(destPath);
+      res.pipe(file);
+      file.on('finish', () => {
+        file.close();
+        resolve();
+      });
+      file.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+async function main() {
+  if (shouldSkip()) return;
+
+  const releaseUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${PACKAGE_VERSION}/${ASSET_NAME}`;
+
+  log(`Downloading iOS frameworks from: ${releaseUrl}`);
+
+  const tmpZip = path.join(PACKAGE_ROOT, '.ios-frameworks-tmp.zip');
+
+  try {
+    await downloadFile(releaseUrl, tmpZip);
+
+    // Extract
+    fs.mkdirSync(FRAMEWORKS_DIR, { recursive: true });
+    execSync(`unzip -o -q "${tmpZip}" -d "${FRAMEWORKS_DIR}"`, { stdio: 'inherit' });
+
+    // Cleanup
+    fs.unlinkSync(tmpZip);
+
+    log('iOS frameworks installed successfully.');
+  } catch (err) {
+    // Don't fail the install — iOS frameworks are optional (Android-only users)
+    log(`Warning: Could not download iOS frameworks: ${err.message}`);
+    log('iOS builds will not work until frameworks are available.');
+    log('Run: scripts/download-ios-frameworks.sh to download manually.');
+
+    // Cleanup partial download
+    try { fs.unlinkSync(tmpZip); } catch {}
+  }
+}
+
+main();