feat(0.2.0-rc.0): iOS LiteRT-LM hardening — file:// URLs, cancel latency, xcframework publish

- ios/ExpoLitertLmModule.swift: accept POSIX paths and file:// URLs in loadModel;
  retain security-scoped resource access for the lifetime of the loaded model
- example/App.tsx: pass raw DocumentPicker URI through (no caller-side strip);
  record cancelLatencyMs even on early cancel before first token
- package.json: 0.1.0 -> 0.2.0-rc.0; npm files now includes
  ios/BinaryPods/Frameworks/CLiteRTLM.xcframework +
  GemmaModelConstraintProvider.xcframework + rewrap-manifest.json
- ios/BinaryPods/Frameworks/.npmignore: keep xcframeworks in tarball even though
  they are gitignored (consumers must not rebuild from source)
- README/CHANGELOG/example docs: SE 3rd gen + Gemma 3 1B INT4 iOS framing,
  no Gemma 4 E2B iOS claim; npm badges + View-on-npm link added

Verification (all green):
- npm run build, npx tsc -p example/tsconfig.json --noEmit
- make verify (Layer A/B/C CocoaPods checks)
- npm publish --tag next --dry-run: 48 files, 14.5 MB packed, xcframeworks included
- xcodebuild CODE_SIGNING_ALLOWED=NO -> BUILD SUCCEEDED

Android guardrail: zero diff under android/, src/, lib/.

Pre-release under --tag next; latest stays at 0.1.2 until competition fully ends.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: helenkwok

CHANGELOG.md

@@ -1,19 +1,24 @@
 # Changelog
 
-## 0.2.0-dev.1 — Phase 14 (in progress, 2026-05-15)
+## 0.2.0 — 2026-05-16
 
+- **Added:** iOS LiteRT-LM text generation via vendored LiteRTLM-Swift / `CLiteRTLM.xcframework`. Validated on iPhone SE 3rd gen with `gemma3-1b-it-int4.litertlm` (Gemma 3 1B INT4). Gemma 4 E2B remains Android-validated only; it was not tested on SE 3rd gen because of memory limits.
 - **Added:** `sampleMemoryAsync()` — returns the current process `phys_footprint` in MB for Stage B integration measurement (Phase 14 D-07). iOS only; surfaced via colocated `ios/MemoryProbe.swift` (task_info / TASK_VM_INFO). Stage B example app under `example/` exercises the full Expo + RN + native bridge end-to-end against the rewrapped LiteRTLM-Swift xcframework on SE 3rd gen.
 - **Changed:** `scripts/sync-litertlm-swift.sh` rewritten — now fetches rewrapped LiteRTLM-Swift from `helenkwok/LiteRTLM-Swift`'s GitHub Release by tag, verifies SHA-256 against `rewrap-manifest.json`, places artifacts under `ios/BinaryPods/Frameworks/`. Manual sync per Phase 14 D-34. Run `make sync TAG=v<upstream>+rewrap.<n>`.
 - **Added:** `ios/BinaryPods/Frameworks/rewrap-manifest.json` — trust anchor (source-controlled JSON, populated by sync script). xcframework binaries remain gitignored.
 - **Added:** `ExpoLitertLm.podspec` now reads `vendored_frameworks` and `s.version` from `ios/BinaryPods/Frameworks/rewrap-manifest.json` via Ruby `JSON.parse` at install time. Phase 14 D-31 single source of truth.
 - **Added:** Layer A/B/C verification gates (`scripts/verify-consumption.sh`, `make verify`). Layer A = pod install from fresh consumer; Layer B = grep gate for raw xcframework refs; Layer C = manifest-driven podspec consistency.
 - **Added:** `.github/workflows/verify-consumption.yml` — CI mirrors fork's three-layer gate on macos-latest.
+- **Added:** Expo config plugin (`app.plugin.js`) that injects the split binary pods required for iOS consumers. Verified under `useFrameworks: "static"`; `useFrameworks: "dynamic"` was rejected by CocoaPods because Expo SDK 55 includes static transitive binaries.
+- **Fixed:** iOS `loadModelAsync` accepts either a POSIX path or a `file://` URL, including values returned by `expo-document-picker`.
+- **Fixed:** Stage B example now records `cancelLatencyMs` when cancellation ends before a final token event arrives.
 
 - **BREAKING:** iOS path migrated from `MediaPipeTasksGenAI` default-dep to vendored `LiteRTLM-Swift` (`CLiteRTLM.xcframework` + `GemmaModelConstraintProvider.xcframework`). Consumers must run `pod install` after upgrade.
 - **BREAKING:** `ExpoLitertLm.podspec` no longer carries `static_framework = true` — see CocoaPods issue [#11948](https://github.com/CocoaPods/CocoaPods/issues/11948) + offlineaid Phase 14 CONTEXT D-21. Static linkage of a dylib-containing xcframework crashes the host app at launch.
 - **BREAKING:** MediaPipe `.task` support moves to opt-in `MediaPipeFallback` subspec; default install does not include `MediaPipeTasksGenAI` on iOS. Consumers who need it: `pod 'ExpoLitertLm', :subspecs => ['Core', 'MediaPipeFallback']` in their Podfile.
-- Added: `scripts/sync-litertlm-swift.sh` for manual fork sync. `helenkwok/LiteRTLM-Swift` is the upstream fork pinned by SHA; vendoring happens at sync-time, not at `pod install`-time.
-- Added: `scripts/rewrap-xcframework.sh` in the fork resolves upstream issue [#6](https://github.com/mylovelycodes/LiteRTLM-Swift/issues/6) offline (Info.plist `CFBundleShortVersionString`, loose-dylib promotion, dSYM emission). TestFlight validation deferred to v1.2 per offlineaid CONTEXT D-25.
+- **Added:** `scripts/sync-litertlm-swift.sh` for manual fork sync. `helenkwok/LiteRTLM-Swift` is the upstream fork pinned by SHA; vendoring happens at sync-time, not at `pod install`-time.
+- **Added:** `scripts/rewrap-xcframework.sh` in the fork resolves upstream issue [#6](https://github.com/mylovelycodes/LiteRTLM-Swift/issues/6) offline (Info.plist `CFBundleShortVersionString`, loose-dylib promotion, dSYM emission). TestFlight validation deferred to v1.2 per offlineaid CONTEXT D-25.
+- **Synced:** Rewrapped LiteRTLM-Swift `v0.10.2+rewrap.5` (2 xcframeworks, first sha256 `ba2d0c9a6b2a...`).
 
 ## 0.1.2 — 2026-05-12
 
@@ -26,5 +31,3 @@
 ## 0.1.0
 
 - feat: initial expo-litert-lm — Expo Modules bindings for LiteRT-LM.
-2026-05-16 — synced rewrapped LiteRTLM-Swift v0.10.2+rewrap.1 (2 xcframeworks, first sha256: 10565a593a70...)
-2026-05-16 — synced rewrapped LiteRTLM-Swift v0.10.2+rewrap.5 (2 xcframeworks, first sha256: ba2d0c9a6b2a...)

README.md

@@ -1,12 +1,22 @@
 # expo-litert-lm
 
-> Expo Modules bindings for [Google AI Edge LiteRT-LM](https://github.com/google-ai-edge/litert-lm) — on-device Gemma 4 / Gemma 3n inference for Expo apps.
+[![npm version](https://img.shields.io/npm/v/expo-litert-lm.svg)](https://www.npmjs.com/package/expo-litert-lm)
+[![npm downloads](https://img.shields.io/npm/dm/expo-litert-lm.svg)](https://www.npmjs.com/package/expo-litert-lm)
+[![license](https://img.shields.io/npm/l/expo-litert-lm.svg)](https://github.com/helenkwok/expo-litert-lm/blob/main/LICENSE)
 
-**Status:** Android-first. iOS scaffold exists; full LiteRT-LM iOS support pending. Production-tested in [OfflineAid](https://github.com/helenkwok/offlineaid) (audio + chat).
+> Expo Modules bindings for [Google AI Edge LiteRT-LM](https://github.com/google-ai-edge/litert-lm) - on-device Gemma inference for Expo apps. **[View on npm →](https://www.npmjs.com/package/expo-litert-lm)**
+
+**Status:** Android production-tested in [OfflineAid](https://github.com/helenkwok/offlineaid) with Gemma 4 E2B chat + audio. iOS LiteRT-LM text generation is validated on iPhone SE 3rd gen with `gemma3-1b-it-int4.litertlm` (Gemma 3 1B INT4); iOS audio/vision remain planned.
 
 ## What this is
 
-Native bridge for Expo SDK 56+ apps to load and run `.litertlm` and `.task` models from Google's `litert-community` Hugging Face org via the official `litertlm-android:0.11.0` SDK. MIT licensed.
+Native bridge for Expo SDK 55+ apps to load and run `.litertlm` and `.task` models from Google's `litert-community` Hugging Face org.
+
+- Android uses Google's official `litertlm-android:0.11.0` SDK plus MediaPipe Tasks GenAI.
+- iOS uses vendored LiteRTLM-Swift wrapping the LiteRT-LM C API (`CLiteRTLM.xcframework` + `GemmaModelConstraintProvider.xcframework`, rewrapped from LiteRTLM-Swift `v0.10.2+rewrap.5`).
+- iOS `.task` support is available only through the opt-in `MediaPipeFallback` CocoaPods subspec; the default iOS install is LiteRT-LM only.
+
+MIT licensed.
 
 ## What this is *not*
 
@@ -15,10 +25,10 @@ Native bridge for Expo SDK 56+ apps to load and run `.litertlm` and `.task` mode
 | | `expo-litert-lm` (this) | `react-native-litert-lm` |
 |---|---|---|
 | Framework | Expo Modules | Nitro Modules + Expo plugin |
-| iOS LiteRT-LM | Scaffold only | Full |
+| iOS LiteRT-LM | Text/chat validated on iPhone SE 3rd gen with Gemma 3 1B INT4; audio/vision deferred | Full |
 | Android API | 31+ (S) | 26+ |
 | MTP / speculative decoding | `ExperimentalFlags.enableSpeculativeDecoding` wired against v0.11.0; blocked upstream on non-Adreno Android by [LiteRT-LM#2211](https://github.com/google-ai-edge/LiteRT-LM/issues/2211) (sampler `dlopen` fails on Tensor G2/G6 — cross-validated 2026-05-12) and [#2227](https://github.com/google-ai-edge/LiteRT-LM/issues/2227) (drafter regression on PowerVR even with sampler loaded). Architecture verified 2.01× lossless on Mac via mlx-vlm. | Not exposed |
-| Audio encoder | Production use | iOS limited |
+| Audio encoder | Android production use; iOS throws a clear not-yet-available error | iOS limited |
 | Multi-runtime | LiteRT-LM `.litertlm` + MediaPipe Tasks GenAI `.task` | LiteRT-LM only |
 
 Both packages exist deliberately. Pick what fits your app.
@@ -37,7 +47,7 @@ Or pin a specific version in `package.json`:
 
 ```jsonc
 "dependencies": {
-  "expo-litert-lm": "^0.1.1"
+  "expo-litert-lm": "^0.2.0"
 }
 ```
 
@@ -82,10 +92,30 @@ if (await isLiteRtAvailable()) {
 
 ## Requirements
 
-- Expo SDK 56+
+- Expo SDK 55+
 - Android 12 (API 31) or newer
-- A device with GPU support for best performance (e.g. Pixel 7+)
-- Models: `.litertlm` (LiteRT-LM) or `.task` (MediaPipe Tasks GenAI)
+- iOS 17.0 or newer for the LiteRT-LM path
+- Android: a device with GPU support for best performance (e.g. Pixel 7+)
+- iOS: iPhone SE 3rd gen / A15 is the validated floor for Gemma 3 1B INT4. Gemma 4 E2B has not been validated on SE 3rd gen due to memory limits.
+- Models: `.litertlm` (LiteRT-LM) or `.task` (MediaPipe Tasks GenAI; Android by default, iOS only with `MediaPipeFallback`)
+
+## iOS Notes
+
+`v0.2.0` adds the iOS LiteRT-LM path and ships the rewrapped xcframeworks inside the npm tarball. The included Expo config plugin injects the two binary pods that CocoaPods needs:
+
+```jsonc
+{
+  "expo": {
+    "plugins": ["expo-litert-lm"]
+  }
+}
+```
+
+The plugin is compatible with Expo's `useFrameworks: "static"` consumer apps. A `useFrameworks: "dynamic"` diagnostic was run on the example app and CocoaPods rejected it because Expo SDK 55 has static transitive binaries (`ExpoModulesCore` / `ExpoModulesJSI`), so the split-binary pod path is intentional.
+
+The iOS loader accepts both POSIX paths and `file://` URLs, including values returned by `expo-document-picker`.
+
+The SE 3rd gen validation used the default CPU backend. iOS Metal/GPU acceleration is not claimed in this release.
 
 ## Security
 

example/App.tsx

@@ -63,12 +63,17 @@ export default function App() {
   const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const cancelTsRef = useRef<number | null>(null);
 
+  const finishCancelLatency = () => {
+    if (cancelTsRef.current === null) return;
+    setCancelLatencyMs(Date.now() - cancelTsRef.current);
+    cancelTsRef.current = null;
+  };
+
   useEffect(() => {
     const sub = addLiteRtTokenListener((event: LiteRtTokenEvent) => {
       setOutput(event.text);
       if (cancelTsRef.current !== null && event.done) {
-        setCancelLatencyMs(Date.now() - cancelTsRef.current);
-        cancelTsRef.current = null;
+        finishCancelLatency();
       }
     });
     return () => sub.remove();
@@ -83,10 +88,9 @@ export default function App() {
     if (res.canceled) return;
     const uri = res.assets?.[0]?.uri;
     if (uri) {
-      // Native module's URL(fileURLWithPath:) treats its arg as POSIX path,
-      // so a file:// scheme prefix breaks fileExists. Strip it for Stage B.
-      // Phase 14-09 follow-up: native module should accept either form.
-      setModelPath(uri.startsWith('file://') ? uri.replace(/^file:\/\//, '') : uri);
+      // Keep the picker URI intact so the native module exercises its
+      // file:// URL normalization path.
+      setModelPath(uri);
     }
   };
 
@@ -139,6 +143,7 @@ export default function App() {
     } catch (e) {
       setErrorText(e instanceof Error ? e.message : String(e));
     } finally {
+      finishCancelLatency();
       await stopPollingAndWrite();
       setRunning(false);
     }

example/README.md

@@ -38,7 +38,8 @@ LiteRTLM-rewrapped.xcframework via the `file:..` link to the parent module.
    A 250 ms `sampleMemoryAsync` poll updates the on-screen MB and peakMb labels.
 3. Run finishes after ~50 s; final peakMb is the gate value.
 4. Re-tap **Run spike**, then **Cancel** mid-stream — verifies IOSC-03
-   cancellation latency from the JS surface.
+   cancellation latency from the JS surface. The app records latency even
+   when native cancellation ends before a final token event is emitted.
 5. Retrieve `rss-stageB-*.ndjson` from Xcode → Devices → expolitertlmexample
    → Download Container → AppData/Documents.
 
@@ -49,3 +50,8 @@ LiteRTLM-rewrapped.xcframework via the `file:..` link to the parent module.
 - No audio / vision surface. Phase 14 spike scope is chat-only (D-02).
 - No model download from JS. Files-app-copy keeps the harness deterministic
   and the example free of HF auth code.
+
+## Notes
+
+- The picker passes its raw `file://` URI into `loadLiteRtModel`; the native
+  iOS module accepts both picker URIs and POSIX paths.

ios/BinaryPods/Frameworks/.npmignore

@@ -0,0 +1,6 @@
+# The xcframeworks are gitignored but must be published to npm; consumers need
+# them during CocoaPods install.
+!.gitignore
+!*.xcframework
+!*.xcframework/**
+!rewrap-manifest.json

ios/ExpoLitertLmModule.swift

@@ -33,6 +33,7 @@ public final class ExpoLitertLmModule: Module {
   private var loadedRuntime: LoadedRuntime?
   private var loadedConfig: LiteRtLoadConfig?
   private var loadedModelPath: String?
+  private var securityScopedModelURL: URL?
 
   private let stateQueue = DispatchQueue(label: "expo.modules.litertlm.state")
   private var activeGenerationID: UUID?
@@ -65,9 +66,11 @@ public final class ExpoLitertLmModule: Module {
       try self.ensureSupportedOS()
 
       let resolvedBackend = (preferredBackend ?? "cpu").lowercased()
+      let modelURL = try Self.resolveModelURL(modelPath)
+      let resolvedModelPath = modelURL.path
       let nextConfig = LiteRtLoadConfig(
         maxTokens: maxTokens,
-        modelPath: modelPath,
+        modelPath: resolvedModelPath,
         preferredBackend: resolvedBackend,
         temperature: temperature,
         topK: topK
@@ -77,14 +80,17 @@ public final class ExpoLitertLmModule: Module {
       if self.loadedConfig == nextConfig, self.loadedRuntime != nil {
         return [
           "backend": resolvedBackend,
-          "modelPath": modelPath,
+          "modelPath": resolvedModelPath,
         ]
       }
 
       self.cancelActiveGeneration()
       await self.unloadInternalAsync()
 
-      if Self.isLiteRtLmModelPath(modelPath) {
+      let didStartSecurityScope = modelURL.startAccessingSecurityScopedResource()
+      var shouldStopSecurityScopeOnExit = didStartSecurityScope
+
+      if Self.isLiteRtLmModelPath(resolvedModelPath) {
         // LiteRTLM-Swift path — default for `.litertlm` models.
         // textOnly: true is REQUIRED for the v1.1 floor-device model
         // (gemma3-1b-it-int4.litertlm has no vision/audio encoders). Stage A
@@ -93,13 +99,16 @@ public final class ExpoLitertLmModule: Module {
         // Expo Modules consumer. Multimodal Gemma 4 callers must set this
         // to false explicitly when that path is wired (Phase 16).
         let engine = LiteRTLMEngine(
-          modelPath: URL(fileURLWithPath: modelPath),
+          modelPath: modelURL,
           backend: resolvedBackend,
           textOnly: true
         )
         do {
           try await engine.load()
         } catch {
+          if shouldStopSecurityScopeOnExit {
+            modelURL.stopAccessingSecurityScopedResource()
+          }
           throw LiteRtModuleError(
             message: self.message(from: error, fallback: "LiteRT model loading failed.")
           )
@@ -114,32 +123,42 @@ public final class ExpoLitertLmModule: Module {
         let engine = MediaPipeFallbackEngine()
         do {
           try engine.load(
-            modelPath: modelPath,
+            modelPath: resolvedModelPath,
             maxTokens: maxTokens,
             topK: topK,
             temperature: temperature,
             preferredBackend: resolvedBackend
           )
         } catch {
+          if shouldStopSecurityScopeOnExit {
+            modelURL.stopAccessingSecurityScopedResource()
+          }
           throw LiteRtModuleError(
             message: self.message(from: error, fallback: "MediaPipe model loading failed.")
           )
         }
         self.mediaPipeFallback = engine
         self.loadedRuntime = .mediaPipe
         #else
+        if shouldStopSecurityScopeOnExit {
+          modelURL.stopAccessingSecurityScopedResource()
+        }
         throw LiteRtModuleError(
           message: ".task models require the MediaPipeFallback subspec. Add `pod 'ExpoLitertLm', :subspecs => ['Core', 'MediaPipeFallback']` to your Podfile per ExpoLitertLm CHANGELOG v0.2.0."
         )
         #endif
       }
 
       self.loadedConfig = nextConfig
-      self.loadedModelPath = modelPath
+      self.loadedModelPath = resolvedModelPath
+      if didStartSecurityScope {
+        self.securityScopedModelURL = modelURL
+        shouldStopSecurityScopeOnExit = false
+      }
 
       return [
         "backend": resolvedBackend,
-        "modelPath": modelPath,
+        "modelPath": resolvedModelPath,
       ]
     }
 
@@ -227,6 +246,25 @@ public final class ExpoLitertLmModule: Module {
     (modelPath as NSString).pathExtension.lowercased() == "litertlm"
   }
 
+  private static func resolveModelURL(_ modelPath: String) throws -> URL {
+    if modelPath.lowercased().hasPrefix("file://") {
+      if let url = URL(string: modelPath), url.isFileURL {
+        return url
+      }
+
+      let pathWithoutScheme = String(modelPath.dropFirst("file://".count))
+      return URL(fileURLWithPath: pathWithoutScheme.removingPercentEncoding ?? pathWithoutScheme)
+    }
+
+    if modelPath.contains("://") {
+      throw LiteRtModuleError(
+        message: "LiteRT models must be loaded from a local path or file:// URL."
+      )
+    }
+
+    return URL(fileURLWithPath: modelPath)
+  }
+
   // MARK: - LiteRTLM-Swift generation
 
   private func runLitertLmGeneration(
@@ -321,6 +359,10 @@ public final class ExpoLitertLmModule: Module {
     loadedRuntime = nil
     loadedConfig = nil
     loadedModelPath = nil
+    if let url = securityScopedModelURL {
+      url.stopAccessingSecurityScopedResource()
+      securityScopedModelURL = nil
+    }
   }
 
   private func emitTokenEvent(text: String, delta: String, done: Bool) async {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-litert-lm",
-  "version": "0.2.0-litertlm.0.10.2.r5",
+  "version": "0.2.0-rc.0",
   "description": "Expo Modules bindings for on-device LLM inference. Android: Google's litert-lm-android (LiteRT-LM Engine + MediaPipe Tasks GenAI). iOS: vendored LiteRTLM-Swift wrapping the LiteRT-LM C API; MediaPipe Tasks GenAI available as opt-in MediaPipeFallback subspec. Supports .litertlm and .task model formats.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -15,6 +15,8 @@
     "ios/ExpoLitertLm.podspec",
     "ios/BinaryPods/CLiteRTLMBinary.podspec",
     "ios/BinaryPods/GemmaModelConstraintProviderBinary.podspec",
+    "ios/BinaryPods/Frameworks/CLiteRTLM.xcframework",
+    "ios/BinaryPods/Frameworks/GemmaModelConstraintProvider.xcframework",
     "ios/BinaryPods/Frameworks/rewrap-manifest.json",
     "src",
     "lib",