@dvai-bridge/react-native 4.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+# Deep Voice Ai Limited - Software License Agreement
+
+**Version 1.0.0**
+
+This License Agreement governs the use of the DVAI-Bridge software (the "Software"). By downloading, installing, or using the Software, you agree to be bound by the terms of this License.
+
+---
+
+## 1. LICENSE GRANTS
+
+### 1.1 Development and Personal Use (Free Tier)
+Deep Voice Ai Limited ("Licensor") grants you a non-exclusive, non-transferable, royalty-free license to use the Software solely for:
+- Internal development and testing purposes.
+- Non-commercial personal projects.
+- Academic and non-profit research.
+
+### 1.2 Commercial Use (Paid Tier)
+Any use of the Software for **Commercial Purposes** requires a separate, paid Commercial License from Licensor. "Commercial Purposes" include:
+- Use in production environments.
+- Integration into revenue-generating products or services.
+- Distribution to third-party customers for a fee.
+- Use by an entity with more than $100,000 USD in annual revenue.
+
+To obtain a Commercial License, contact `info@deepvoiceai.co` or visit `https://deepvoiceai.co/licensing`.
+
+---
+
+## 2. RESTRICTIONS
+Except as expressly permitted, you may not:
+- Sublicense, rent, lease, or resell the Software without express permission.
+- Remove any proprietary notices or branding from the Software.
+- Use the Software for any illegal or malicious purposes.
+
+---
+
+## 3. INTELLECTUAL PROPERTY
+The Software is owned by **Deep Voice Ai Limited** and is protected by copyright and intellectual property laws. This agreement does not transfer ownership of the Software.
+
+---
+
+## 4. NO WARRANTY
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+---
+
+## 5. GOVERNING LAW
+This License shall be governed by and construed in accordance with the laws of the jurisdiction where Deep Voice Ai Limited is registered.
+
+---
+
+© 2026 Deep Voice Ai Limited. All rights reserved.

package/README.md

@@ -0,0 +1,199 @@
+![DVAI-Bridge](/assets/banner.png)
+
+# DVAI-Bridge
+
+<!-- [![Smoke — real models](https://github.com/Westenets/dvai-bridge/actions/workflows/smoke-real-models.yml/badge.svg?branch=main)](https://github.com/Westenets/dvai-bridge/actions/workflows/smoke-real-models.yml) -->
+
+[![License](https://img.shields.io/badge/License-Commercial-blue.svg)](LICENSE) ![Node.js](https://img.shields.io/badge/Node.js-22+-green?logo=node.js) ![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue?logo=typescript) ![Swift](https://img.shields.io/badge/Swift-5.9+-F05138?logo=swift) ![Kotlin](https://img.shields.io/badge/Kotlin-2.0+-7F52FF?logo=kotlin) ![Flutter](https://img.shields.io/badge/Flutter-3.39+-02569B?logo=flutter) ![.NET](https://img.shields.io/badge/.NET-10.0_LTS-512BD4?logo=dotnet)
+
+> **The local OpenAI server you embed inside your app.**
+> One library. One HTTP wire. Every platform. Zero install for your users.
+
+**Docs:** [dvai-bridge.deepvoiceai.co](https://dvai-bridge.deepvoiceai.co)
+
+```ts
+import { DVAI } from "@dvai-bridge/core";
+import OpenAI from "openai";
+
+const dvai = new DVAI({ backend: "transformers" });
+await dvai.initialize();
+
+const openai = new OpenAI({ baseURL: dvai.baseUrl, apiKey: "ignored" });
+await openai.chat.completions.create({
+  model: dvai.transformersModelId,
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+That's it. A real OpenAI-compatible server is now running inside your app's
+own process. Point any OpenAI client — LangChain, the OpenAI SDK, the Vercel
+AI SDK, anything — at `dvai.baseUrl` and your agent code keeps working.
+
+Built by **[Deep Voice AI](https://deepvoiceai.co)**.
+
+---
+
+## Why it exists
+
+Local AI works beautifully on a laptop with **Ollama + LangChain**. Then you
+try to ship the app and your users don't have Ollama. Mobile can't run it.
+Corporate IT won't add another daemon. So you reinvent the same plumbing —
+spawn an inference engine, bind a port, translate to OpenAI HTTP, handle
+CORS, manage lifecycle, wrap the accelerator of the day per platform — and
+do it all over again for every target OS.
+
+DVAI-Bridge is that plumbing, packaged as a library, for every client
+platform.
+
+---
+
+## What you get
+
+- **One OpenAI HTTP surface.** Bound on `127.0.0.1` (or `0.0.0.0` for
+  device-to-device). Streaming, embeddings, models, recovery — all built in.
+- **Six SDKs.** `@dvai-bridge/core` + `react` + `vanilla` + `capacitor`,
+  `DVAIBridge` (Swift / iOS), `co.deepvoiceai:dvai-bridge` (Kotlin / Android),
+  `@dvai-bridge/react-native`, `dvai_bridge` (Flutter), `co.deepvoiceai.dvai-bridge` (.NET).
+- **Nine backends.** WebLLM, Transformers.js, llama.cpp, Apple Foundation
+  Models, MLX, CoreML / ANE, MediaPipe LLM, LiteRT, ONNX Runtime GenAI —
+  selected per-platform, invisible to your agent code.
+- **Native acceleration** wherever it runs: WebGPU in browsers, CUDA / Metal
+  / Vulkan / DirectML on desktop, ANE / Metal / MLX on iOS, NNAPI / QNN
+  Hexagon / GPU delegate on Android.
+- **Multimodal.** Text, image, audio, video — declarative loader for
+  cutting-edge models (Gemma 4, LLaVA, Idefics) without waiting for library
+  updates.
+- **Distributed inference (v3.0+).** Phone too slow? Offload to your laptop
+  on the same Wi-Fi via mDNS pairing — same OpenAI wire, transparent to
+  your code. Internet path via a self-hostable rendezvous server.
+- **DVAI Hub (v3.1+).** A first-party desktop utility that turns any device
+  into a strong-peer for the rest of your fleet. Brand-neutral install via
+  Homebrew / winget / GitHub Releases, OR fork it for your own branded
+  companion. Routes through Ollama / LM Studio / vLLM / llama-server /
+  llamafile if you've already got those running.
+- **Zero user install.** It's a library, not a daemon. `npm install`,
+  `cocoapods`, gradle — your CI already has the muscle for it.
+
+---
+
+## Supported platforms
+
+| Stack | Package | Backends |
+| --- | --- | --- |
+| Browser (React, Vue, Svelte, vanilla JS) | `@dvai-bridge/core` + `react` / `vanilla` | WebLLM (WebGPU), Transformers.js (WebGPU / WASM SIMD) |
+| Node / Bun / Electron | `@dvai-bridge/core` | Transformers.js, native llama.cpp |
+| Capacitor hybrid mobile | `@dvai-bridge/capacitor` + backend slice | Native llama.cpp (Metal iOS, Vulkan / CPU Android) |
+| iOS native (Swift) | `DVAIBridge` (SPM / CocoaPods) | llama.cpp (Metal), CoreML / ANE, Apple Foundation Models, MLX |
+| Android native (Kotlin / Java) | `co.deepvoiceai:dvai-bridge` (AAR) | llama.cpp, MediaPipe LLM, LiteRT, NNAPI / QNN |
+| React Native (≥0.77, TurboModule) | `@dvai-bridge/react-native` | All iOS + Android backends (delegates) |
+| Flutter (≥3.39) | `dvai_bridge` (pub.dev) | All iOS + Android backends (Pigeon channels) |
+| .NET 10 LTS (MAUI / Avalonia / WinUI / Catalyst / desktop) | `co.deepvoiceai.dvai-bridge*` (NuGet) | iOS / Android delegate to native; desktop = llama.cpp + ONNX Runtime GenAI + ML.NET |
+
+Full quickstart per platform: [dvai-bridge.deepvoiceai.co/guide/getting-started](https://dvai-bridge.deepvoiceai.co/guide/getting-started)
+
+---
+
+## Examples
+
+```ts
+// React
+import { DVAIProvider, useDVAI } from "@dvai-bridge/react";
+<DVAIProvider config={{ backend: "transformers" }}>
+  <Chat />
+</DVAIProvider>;
+function Chat() {
+  const { isReady, baseUrl } = useDVAI();
+  return isReady ? <div>Local AI live at {baseUrl}</div> : <Loading />;
+}
+```
+
+```swift
+// iOS
+let server = try await DVAIBridge.shared.start()
+// server.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```kotlin
+// Android
+val server = DVAIBridge.start(context)
+// server.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```dart
+// Flutter
+final state = await DVAIBridge.instance.start(
+  backend: BackendKind.auto,
+  modelPath: '/path/to/model.gguf',
+);
+// state.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```csharp
+// .NET
+var server = await DVAIBridge.Shared.StartAsync(new StartOptions {
+    Backend = BackendKind.Auto,
+    ModelPath = "/path/to/model.gguf",
+});
+// server.BaseUrl = "http://127.0.0.1:38883/v1"
+```
+
+Multimodal, streaming, embeddings, distributed offload, the Hub —
+everything's at the [docs site](https://dvai-bridge.deepvoiceai.co).
+
+---
+
+## What's new in v3.1
+
+- **DVAI Hub** — Tauri desktop utility that's the strong-peer side of v3
+  distributed inference. `brew install deepvoiceai/dvai-hub/dvai-hub` (or
+  `winget install DeepVoiceAI.DVAIHub`) → mobile apps on the same Wi-Fi
+  pair with it and offload heavy inference. [Guide →](https://dvai-bridge.deepvoiceai.co/guide/dvai-hub)
+- **External-engine bridge.** Hub surfaces Ollama / LM Studio / vLLM /
+  llama-server / llamafile as additional backend pools so paired apps
+  serve from whatever's already cached. Opt-in per engine.
+- **Strict substitution policy.** Models with mismatched family / version /
+  size / type are refused by default; quant-only mismatches gated behind a
+  per-pairing `preferBetterQuant` flag. No silent mis-routing.
+- **HMAC-signed identity** on `/v1/chat/completions`. Per-app audit logs
+  surface who served what, with structured `(appId, peerDeviceId,
+  engine, requestedModel, servedModel, outcome)` rows.
+- **Library finalization.** `httpBindHost` (LAN bind), `chatCompletionInterceptor`
+  (extension point), HMAC primitives re-exported, `/v1/dvai/*` routes
+  actually dispatched, TransformersBackend Node-mode device fix.
+  [Migration v3.0 → v3.1 →](https://dvai-bridge.deepvoiceai.co/migration/v3.0-to-v3.1)
+
+---
+
+## Robustness
+
+Streaming-correct (SSE passthrough + blank-chunk detection), generation
+timeout, automatic engine-state recovery on fatal errors, port fallback,
+worker offloading, Private Network Access ready, CORS configured. The
+boring substrate so your agent code never has to think about it.
+
+---
+
+## Licensing
+
+Dual: **free for development & personal use** on `localhost` (verified at
+runtime). **Commercial use** requires a license key — `info@deepvoiceai.co`.
+
+---
+
+## Contributing
+
+PRs welcome.
+
+```bash
+pnpm install
+pnpm build
+bash scripts/build-all.sh   # full matrix (auto-skips per-host)
+```
+
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for the PR flow. Per-platform
+contributor docs (iOS / Android / RN / Flutter / .NET) under
+[`docs/development/`](./docs/development/).
+
+---
+
+© Deep Voice AI Limited. All rights reserved.

package/android/build.gradle

@@ -0,0 +1,132 @@
+// React Native TurboModule bridge for the DVAIBridge Android SDK
+// (Phase 3D umbrella, `co.deepvoiceai:dvai-bridge:2.1.0`).
+//
+// This module is **thin**: no inference engine, no model downloader, no HTTP
+// server. It depends on the umbrella AAR (declared below) and exposes its
+// `DVAIBridge` Kotlin singleton to React Native via a TurboModule.
+//
+// Consumers wiring this into their RN app need three things in their Android
+// project:
+//
+//   1. `mavenCentral()` and `google()` repositories (default RN template).
+//   2. A GitHub Packages Maven entry pointing at
+//      `https://maven.pkg.github.com/dvai-global/dvai-bridge` plus a
+//      `gpr.user` / `gpr.key` pair in `~/.gradle/gradle.properties` (or
+//      `GITHUB_ACTOR` / `GITHUB_TOKEN` env vars in CI). See the
+//      docs/guide/react-native-sdk.md guide for the snippet.
+//   3. `applicationContext` initialization in `Application.onCreate()`:
+//
+//          DVAIBridge.init(this)
+//
+//      The bridge re-runs `DVAIBridge.init(reactContext.applicationContext)`
+//      defensively on every TurboModule construction, so this step is
+//      strictly optional unless your consumer app needs Compose / Lifecycle
+//      observers wired up before the first JS-side `start()` call.
+
+buildscript {
+    ext {
+        kotlinVersion = project.findProperty('DVAIBridge_kotlinVersion') ?: '2.3.21'
+        agpVersion = project.findProperty('DVAIBridge_agpVersion') ?: '9.2.0'
+    }
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:${agpVersion}"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlinVersion}"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+def reactNativeArchitectures() {
+    def value = rootProject.getProperties().get("reactNativeArchitectures")
+    return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+    return rootProject.hasProperty("newArchEnabled") &&
+            rootProject.getProperty("newArchEnabled") == "true"
+}
+
+android {
+    namespace "co.deepvoiceai.bridge.rn"
+
+    compileSdkVersion safeExtGet("compileSdkVersion", 36)
+    buildToolsVersion safeExtGet("buildToolsVersion", "36.0.0")
+
+    defaultConfig {
+        minSdkVersion safeExtGet("minSdkVersion", 24)
+        targetSdkVersion safeExtGet("targetSdkVersion", 36)
+
+        // Codegen jsRootDir + libraryName align with package.json's
+        // codegenConfig block (jsSrcsDir + name).
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", "${isNewArchitectureEnabled()}"
+    }
+
+    buildFeatures {
+        buildConfig true
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        main {
+            if (isNewArchitectureEnabled()) {
+                java.srcDirs += [
+                    "src/newarch",
+                    // Codegen output dir injected by RN at sync time.
+                    "${project.buildDir}/generated/source/codegen/java",
+                ]
+            } else {
+                java.srcDirs += ["src/oldarch"]
+            }
+        }
+    }
+}
+
+kotlin {
+    jvmToolchain(17)
+}
+
+repositories {
+    mavenCentral()
+    google()
+    // Phase 3D umbrella + cores resolve here in dev (after running
+    // `bash scripts/android-publish-local.sh` locally).
+    mavenLocal()
+    maven {
+        // Production GitHub Packages Maven for the umbrella + cores. Picked up
+        // automatically when the consumer app exports `gpr.user` / `gpr.key`
+        // (or sets the matching env vars in CI).
+        url = uri("https://maven.pkg.github.com/dvai-global/dvai-bridge")
+        credentials {
+            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
+            password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
+        }
+    }
+}
+
+def dvaiBridgeVersion = project.findProperty('dvaiBridgeVersion') ?: '4.0.0'
+
+dependencies {
+    implementation "com.facebook.react:react-android"
+
+    // Phase 3D umbrella AAR — provides DVAIBridge, BackendKind, StartOptions,
+    // BoundServer, ProgressEvent, DVAIBridgeError. `api` instead of
+    // `implementation` so consumer apps that need to catch DVAIBridgeError
+    // subtypes (or pattern-match on BackendKind) see the symbols without
+    // adding a redundant top-level dependency.
+    api "co.deepvoiceai:dvai-bridge:${dvaiBridgeVersion}"
+
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2"
+}

package/android/gradle.properties

@@ -0,0 +1,7 @@
+android.useAndroidX=true
+kotlin.code.style=official
+android.nonTransitiveRClass=true
+org.gradle.jvmargs=-Xmx4096m
+# Pinned to match the Phase 3D umbrella's published version. Bumped together
+# in Task 14 of the Phase 3E plan.
+dvaiBridgeVersion=4.0.0

package/android/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'dvai-bridge-react-native'

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/co/deepvoiceai/bridge/rn/DVAIBridgeNativeModuleImpl.kt

@@ -0,0 +1,443 @@
+package co.deepvoiceai.bridge.rn
+
+import co.deepvoiceai.bridge.BackendKind
+import co.deepvoiceai.bridge.DVAIBridge
+import co.deepvoiceai.bridge.DVAIBridgeError
+import co.deepvoiceai.bridge.DownloadOptions
+import co.deepvoiceai.bridge.ProgressEvent
+import co.deepvoiceai.bridge.StartOptions
+import co.deepvoiceai.bridge.shared.core.CorsConfig
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.collect
+import kotlinx.coroutines.launch
+
+/**
+ * Shared implementation of the React Native TurboModule bridge for the
+ * DVAIBridge Android SDK (Phase 3D umbrella).
+ *
+ * This class is `internal` and called from the platform-specific module
+ * shims under `src/newarch/` (TurboModule subclass) and `src/oldarch/`
+ * (legacy `ReactContextBaseJavaModule` subclass). Both shims forward into
+ * a single instance of this class so the Kotlin business logic isn't
+ * duplicated.
+ *
+ * The bridge:
+ *
+ *  1. Calls `DVAIBridge.init(applicationContext)` once on first construction
+ *     so consumers don't have to remember to do it from their `Application`.
+ *  2. Translates `ReadableMap` opts ↔ `StartOptions` / `DownloadOptions`.
+ *  3. Wraps each `DVAIBridge.start(...)` / `.stop(...)` / etc. call in a
+ *     coroutine and resolves / rejects the corresponding `Promise`.
+ *  4. Collects from `DVAIBridge.progressFlow` and re-emits each event as
+ *     a `DVAIBridgeProgress` JS event with the canonical JSON shape.
+ *
+ * The progress collector is started once on first JS-side
+ * `addListener("DVAIBridgeProgress", …)` and torn down when listener count
+ * drops to zero (mirroring the iOS Combine subscription lifecycle).
+ */
+internal class DVAIBridgeNativeModuleImpl(
+    private val reactContext: ReactApplicationContext,
+) {
+    /** Coroutine scope tied to the lifetime of the React module instance. */
+    private val moduleJob: Job = SupervisorJob()
+    private val moduleScope: CoroutineScope = CoroutineScope(Dispatchers.Default + moduleJob)
+
+    /** Job for the active progress-event collector, if any. */
+    private var progressJob: Job? = null
+
+    /** Listener count tracked by RN's NativeEventEmitter. */
+    private var listenerCount: Int = 0
+
+    init {
+        // Defensive init — consumers SHOULD call DVAIBridge.init(this) from
+        // their Application.onCreate(), but we don't want a silent
+        // ConfigurationInvalid if they forget. The umbrella's init is
+        // idempotent so this is safe to re-run.
+        DVAIBridge.init(reactContext.applicationContext)
+    }
+
+    fun invalidate() {
+        progressJob?.cancel()
+        progressJob = null
+        moduleScope.cancel()
+    }
+
+    // MARK: - Lifecycle methods
+
+    fun startBridge(opts: ReadableMap, promise: Promise) {
+        val startOpts = try {
+            parseStartOptions(opts)
+        } catch (e: DVAIBridgeError) {
+            promise.rejectWith(e)
+            return
+        } catch (e: Throwable) {
+            promise.reject("configurationInvalid", e.message ?: "Failed to parse StartOptions", e)
+            return
+        }
+
+        moduleScope.launch {
+            try {
+                val server = DVAIBridge.start(startOpts)
+                val map = Arguments.createMap().apply {
+                    putString("baseUrl", server.baseUrl)
+                    putInt("port", server.port)
+                    putString("backend", server.backend.toJsName())
+                    putString("modelId", server.modelId)
+                }
+                promise.resolve(map)
+            } catch (e: DVAIBridgeError) {
+                promise.rejectWith(e)
+            } catch (e: Throwable) {
+                promise.reject("backendError", e.message ?: e::class.qualifiedName ?: "unknown", e)
+            }
+        }
+    }
+
+    fun stopBridge(promise: Promise) {
+        moduleScope.launch {
+            try {
+                DVAIBridge.stop()
+                promise.resolve(null)
+            } catch (e: DVAIBridgeError) {
+                promise.rejectWith(e)
+            } catch (e: Throwable) {
+                promise.reject("backendError", e.message ?: e::class.qualifiedName ?: "unknown", e)
+            }
+        }
+    }
+
+    fun status(promise: Promise) {
+        val info = DVAIBridge.status()
+        val map = Arguments.createMap().apply {
+            putBoolean("running", info.running)
+            info.baseUrl?.let { putString("baseUrl", it) }
+            info.backend?.let { putString("backend", it.toJsName()) }
+            info.modelId?.let { putString("modelId", it) }
+            // Port from baseUrl, when present. Mirrors the iOS impl.
+            info.baseUrl?.let { url ->
+                runCatching {
+                    val parsed = java.net.URI(url)
+                    if (parsed.port > 0) putInt("port", parsed.port)
+                }
+            }
+        }
+        promise.resolve(map)
+    }
+
+    fun downloadModel(opts: ReadableMap, promise: Promise) {
+        val url = opts.getString("url")
+            ?: return promise.reject("configurationInvalid", "downloadModel: missing `url`", null)
+        val sha256 = opts.getString("sha256")
+            ?: return promise.reject("configurationInvalid", "downloadModel: missing `sha256`", null)
+        val destFilename = opts.getString("destFilename")
+            ?: url.substringAfterLast('/').ifEmpty {
+                return promise.reject(
+                    "configurationInvalid",
+                    "downloadModel: cannot derive destFilename from URL `$url`; pass it explicitly.",
+                    null,
+                )
+            }
+
+        moduleScope.launch {
+            try {
+                val result = DVAIBridge.downloadModel(
+                    DownloadOptions(
+                        url = url,
+                        sha256 = sha256,
+                        destFilename = destFilename,
+                    ),
+                )
+                val map = Arguments.createMap().apply {
+                    putString("path", result.path)
+                    putString("sha256", result.sha256)
+                    putDouble("sizeBytes", result.sizeBytes.toDouble())
+                }
+                promise.resolve(map)
+            } catch (e: DVAIBridgeError) {
+                promise.rejectWith(e)
+            } catch (e: Throwable) {
+                promise.reject("downloadFailed", e.message ?: e::class.qualifiedName ?: "unknown", e)
+            }
+        }
+    }
+
+    /* ---------------------------------------------------------------- *
+     * v3.2 — pre-init hardware assessment                              *
+     * ---------------------------------------------------------------- */
+
+    fun assessHardware(hardwareMinimum: Double, minLocalCapability: Double, promise: Promise) {
+        try {
+            val a = DVAIBridge.assessHardware(
+                hardwareMinimum = hardwareMinimum,
+                minLocalCapability = minLocalCapability,
+            )
+            val hintsMap = Arguments.createMap().apply {
+                putBoolean("hasNpu", a.hints.hasNpu)
+                putInt("ramGb", a.hints.ramGb)
+                putString("gpuClass", a.hints.gpuClass.toJsName())
+                putString("cpuClass", a.hints.cpuClass.toJsName())
+            }
+            val map = Arguments.createMap().apply {
+                putString("mode", a.mode.toJsName())
+                putDouble("tokPerSec", a.tokPerSec)
+                putString("reason", a.reason)
+                putMap("hints", hintsMap)
+            }
+            promise.resolve(map)
+        } catch (e: Throwable) {
+            promise.reject(
+                "configurationInvalid",
+                e.message ?: e::class.qualifiedName ?: "assessHardware failed",
+                e,
+            )
+        }
+    }
+
+    // MARK: - Event emitter housekeeping
+
+    fun addListener(@Suppress("UNUSED_PARAMETER") eventName: String) {
+        if (listenerCount == 0) {
+            attachProgressCollector()
+        }
+        listenerCount += 1
+    }
+
+    fun removeListeners(count: Int) {
+        listenerCount = (listenerCount - count).coerceAtLeast(0)
+        if (listenerCount == 0) {
+            progressJob?.cancel()
+            progressJob = null
+        }
+    }
+
+    private fun attachProgressCollector() {
+        progressJob?.cancel()
+        progressJob = moduleScope.launch {
+            DVAIBridge.progressFlow.collect { event ->
+                val payload = event.toJsEvent()
+                emitProgressEvent(payload)
+            }
+        }
+    }
+
+    private fun emitProgressEvent(payload: WritableMap) {
+        // Use the bridge's DeviceEventManagerModule.RCTDeviceEventEmitter to
+        // dispatch events. Compatible with both old-arch and new-arch
+        // (Bridgeless) RN.
+        try {
+            reactContext
+                .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+                .emit("DVAIBridgeProgress", payload)
+        } catch (_: Throwable) {
+            // The JS context may have been torn down (e.g. fast-refresh
+            // in dev). Swallow rather than crash the host app.
+        }
+    }
+
+    // MARK: - Helpers
+
+    private fun parseStartOptions(opts: ReadableMap): StartOptions {
+        val backendStr = opts.getString("backend")
+            ?: throw DVAIBridgeError.ConfigurationInvalid("StartOptions: missing `backend`")
+        val backend = BackendKind.fromJsName(backendStr)
+            ?: throw DVAIBridgeError.BackendUnavailable(
+                BackendKind.Auto,
+                "Backend \"$backendStr\" is not available on Android.",
+            )
+
+        val cors: CorsConfig = opts.dynamicOrNull("corsOrigin")?.let { raw ->
+            when (raw) {
+                is String -> if (raw == "*") CorsConfig.Wildcard else CorsConfig.Exact(raw)
+                is ReadableArray -> CorsConfig.Allowlist(raw.toStringList())
+                else -> CorsConfig.Wildcard
+            }
+        } ?: CorsConfig.Wildcard
+
+        return StartOptions(
+            backend = backend,
+            modelPath = opts.getStringOrNull("modelPath"),
+            tokenizerPath = opts.getStringOrNull("tokenizerPath"),
+            mmprojPath = opts.getStringOrNull("mmprojPath"),
+            chatTemplate = opts.getStringOrNull("chatTemplate"),
+            modelId = opts.getStringOrNull("modelId"),
+            gpuLayers = opts.getIntOrNull("gpuLayers") ?: 99,
+            contextSize = opts.getIntOrNull("contextSize") ?: 2048,
+            threads = opts.getIntOrNull("threads") ?: 4,
+            embeddingMode = opts.getBooleanOrNull("embeddingMode") ?: false,
+            visionEnabled = opts.getBooleanOrNull("visionEnabled") ?: false,
+            temperature = opts.getDoubleOrNull("temperature")?.toFloat() ?: 0f,
+            topP = opts.getDoubleOrNull("topP")?.toFloat() ?: 1f,
+            topK = opts.getIntOrNull("topK") ?: 0,
+            maxNewTokens = opts.getIntOrNull("maxNewTokens") ?: 512,
+            httpBasePort = opts.getIntOrNull("httpBasePort") ?: 38883,
+            httpMaxPortAttempts = opts.getIntOrNull("httpMaxPortAttempts") ?: 16,
+            corsOrigin = cors,
+        )
+    }
+}
+
+// MARK: - Conversions
+
+/** Convert a Kotlin `BackendKind` to the lowercase JS-facing name. */
+internal fun BackendKind.toJsName(): String = when (this) {
+    BackendKind.Auto -> "auto"
+    BackendKind.Llama -> "llama"
+    BackendKind.MediaPipe -> "mediapipe"
+    BackendKind.LiteRT -> "litert"
+}
+
+/** Convert v3.2 PrecheckMode → kebab-case JS-facing string. */
+internal fun co.deepvoiceai.bridge.shared.core.capability.PrecheckMode.toJsName(): String = when (this) {
+    co.deepvoiceai.bridge.shared.core.capability.PrecheckMode.OK -> "ok"
+    co.deepvoiceai.bridge.shared.core.capability.PrecheckMode.OFFLOAD_ONLY -> "offload-only"
+    co.deepvoiceai.bridge.shared.core.capability.PrecheckMode.TOO_WEAK -> "too-weak"
+}
+
+/** Convert v3.2 GpuClass → kebab-case JS-facing string. */
+internal fun co.deepvoiceai.bridge.shared.core.capability.GpuClass.toJsName(): String = when (this) {
+    co.deepvoiceai.bridge.shared.core.capability.GpuClass.NONE -> "none"
+    co.deepvoiceai.bridge.shared.core.capability.GpuClass.INTEGRATED -> "integrated"
+    co.deepvoiceai.bridge.shared.core.capability.GpuClass.DISCRETE -> "discrete"
+    co.deepvoiceai.bridge.shared.core.capability.GpuClass.APPLE_SILICON -> "apple-silicon"
+}
+
+/** Convert v3.2 CpuClass → JS-facing string. */
+internal fun co.deepvoiceai.bridge.shared.core.capability.CpuClass.toJsName(): String = when (this) {
+    co.deepvoiceai.bridge.shared.core.capability.CpuClass.LOW -> "low"
+    co.deepvoiceai.bridge.shared.core.capability.CpuClass.MID -> "mid"
+    co.deepvoiceai.bridge.shared.core.capability.CpuClass.HIGH -> "high"
+}
+
+/**
+ * Look up the Kotlin `BackendKind` for a JS-side backend string. Returns
+ * null for iOS-only kinds (`foundation`, `coreml`, `mlx`) — the caller
+ * raises a `BackendUnavailable` error in that case so the JS side gets
+ * a stable failure mode.
+ */
+internal fun BackendKind.Companion.fromJsName(name: String): BackendKind? = when (name) {
+    "auto" -> BackendKind.Auto
+    "llama" -> BackendKind.Llama
+    "mediapipe" -> BackendKind.MediaPipe
+    "litert" -> BackendKind.LiteRT
+    else -> null
+}
+
+/**
+ * Convert a Kotlin `ProgressEvent` into the JS event-emitter payload shape
+ * `{ kind, phase, percent?, message?, error? }`.
+ *
+ * The Android `ProgressEvent.phase` is a free-form string already (matches
+ * the JS-side `"start" | "stop" | "download"` discriminator), so this
+ * mostly just re-shapes the field set.
+ */
+internal fun ProgressEvent.toJsEvent(): WritableMap = Arguments.createMap().apply {
+    when (val ev = this@toJsEvent) {
+        is ProgressEvent.Started -> {
+            putString("kind", "started")
+            putString("phase", ev.phase)
+        }
+        is ProgressEvent.Progress -> {
+            putString("kind", "progress")
+            putString("phase", ev.phase)
+            // Android emits percent as 0..1 float (with -1 for indeterminate);
+            // JS expects 0..100 with omission for indeterminate.
+            if (ev.percent >= 0f) {
+                putDouble("percent", (ev.percent * 100.0).coerceIn(0.0, 100.0))
+            }
+            if (ev.message.isNotEmpty()) putString("message", ev.message)
+        }
+        is ProgressEvent.Completed -> {
+            putString("kind", "completed")
+            putString("phase", ev.phase)
+        }
+        is ProgressEvent.Failed -> {
+            putString("kind", "failed")
+            putString("phase", ev.phase)
+            val errMap = Arguments.createMap().apply {
+                putString("kind", ev.error.toErrorKind())
+                putString("message", ev.error.message ?: ev.error::class.simpleName.orEmpty())
+            }
+            putMap("error", errMap)
+        }
+    }
+}
+
+/**
+ * Stable JS-side `kind` discriminator for a `DVAIBridgeError` instance.
+ * Mirrors `DVAIBridgeErrorKind` in `src/types.ts`.
+ */
+internal fun DVAIBridgeError.toErrorKind(): String = when (this) {
+    is DVAIBridgeError.AlreadyStarted -> "alreadyStarted"
+    is DVAIBridgeError.ConfigurationInvalid -> "configurationInvalid"
+    is DVAIBridgeError.ModelLoadFailed -> "modelLoadFailed"
+    is DVAIBridgeError.BackendUnavailable -> "backendUnavailable"
+    is DVAIBridgeError.BackendError -> "backendError"
+    is DVAIBridgeError.ChecksumMismatch -> "checksumMismatch"
+    is DVAIBridgeError.DownloadFailed -> "downloadFailed"
+}
+
+/** Reject a Promise with the canonical `DVAIBridgeError` shape. */
+internal fun Promise.rejectWith(err: DVAIBridgeError) {
+    val code = err.toErrorKind()
+    val message = err.message ?: err::class.simpleName.orEmpty()
+    val userInfo = Arguments.createMap().apply {
+        putString("kind", code)
+        when (err) {
+            is DVAIBridgeError.AlreadyStarted -> {
+                putString("currentBackend", err.currentBackend.toJsName())
+                putString("baseUrl", err.baseUrl)
+            }
+            is DVAIBridgeError.BackendUnavailable -> {
+                putString("backend", err.backend.toJsName())
+            }
+            else -> Unit
+        }
+    }
+    this.reject(code, message, err, userInfo)
+}
+
+// MARK: - ReadableMap convenience
+
+private fun ReadableMap.getStringOrNull(key: String): String? =
+    if (hasKey(key) && !isNull(key)) getString(key) else null
+
+private fun ReadableMap.getIntOrNull(key: String): Int? =
+    if (hasKey(key) && !isNull(key)) getInt(key) else null
+
+private fun ReadableMap.getBooleanOrNull(key: String): Boolean? =
+    if (hasKey(key) && !isNull(key)) getBoolean(key) else null
+
+private fun ReadableMap.getDoubleOrNull(key: String): Double? =
+    if (hasKey(key) && !isNull(key)) getDouble(key) else null
+
+/** Returns a Kotlin Any? for keys whose dynamic type isn't known up-front. */
+private fun ReadableMap.dynamicOrNull(key: String): Any? {
+    if (!hasKey(key) || isNull(key)) return null
+    return when (getType(key)) {
+        com.facebook.react.bridge.ReadableType.String -> getString(key)
+        com.facebook.react.bridge.ReadableType.Array -> getArray(key)
+        com.facebook.react.bridge.ReadableType.Map -> getMap(key)
+        com.facebook.react.bridge.ReadableType.Boolean -> getBoolean(key)
+        com.facebook.react.bridge.ReadableType.Number -> getDouble(key)
+        else -> null
+    }
+}
+
+private fun ReadableArray.toStringList(): List<String> {
+    val out = ArrayList<String>(size())
+    for (i in 0 until size()) {
+        out += getString(i)
+    }
+    return out
+}

package/android/src/main/java/co/deepvoiceai/bridge/rn/DVAIBridgePackage.kt

@@ -0,0 +1,42 @@
+package co.deepvoiceai.bridge.rn
+
+import com.facebook.react.TurboReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+/**
+ * `ReactPackage` registration for the DVAIBridge TurboModule. Picked up by
+ * RN's autolinking via `react-native.config.js` — the consumer's
+ * `MainApplication` doesn't need to add anything manually.
+ *
+ * `TurboReactPackage` (rather than the legacy `ReactPackage`) lets the
+ * package satisfy both old-arch and new-arch (TurboModule) registration
+ * paths from a single class.
+ */
+class DVAIBridgePackage : TurboReactPackage() {
+
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return if (name == DVAIBridgeNativeModule.NAME) {
+            DVAIBridgeNativeModule(reactContext)
+        } else {
+            null
+        }
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider {
+            mapOf(
+                DVAIBridgeNativeModule.NAME to ReactModuleInfo(
+                    DVAIBridgeNativeModule.NAME,
+                    DVAIBridgeNativeModule::class.java.name,
+                    /* canOverrideExistingModule = */ false,
+                    /* needsEagerInit = */ false,
+                    /* isCxxModule = */ false,
+                    /* isTurboModule = */ BuildConfig.IS_NEW_ARCHITECTURE_ENABLED,
+                ),
+            )
+        }
+    }
+}

package/android/src/newarch/java/co/deepvoiceai/bridge/rn/DVAIBridgeNativeModule.kt

@@ -0,0 +1,64 @@
+package co.deepvoiceai.bridge.rn
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * New Architecture (TurboModule) variant. Subclasses the codegen-generated
+ * `NativeDVAIBridgeSpec` (emitted at Gradle sync from
+ * `src/NativeDVAIBridge.ts` via the `codegenConfig` block in `package.json`).
+ *
+ * All actual logic lives in [DVAIBridgeNativeModuleImpl] — this class is a
+ * thin forwarder so the impl is shared with the old-arch variant under
+ * `src/oldarch/`.
+ */
+class DVAIBridgeNativeModule(
+    reactContext: ReactApplicationContext,
+) : NativeDVAIBridgeSpec(reactContext) {
+
+    private val impl = DVAIBridgeNativeModuleImpl(reactContext)
+
+    override fun getName(): String = NAME
+
+    override fun startBridge(opts: ReadableMap, promise: Promise) {
+        impl.startBridge(opts, promise)
+    }
+
+    override fun stopBridge(promise: Promise) {
+        impl.stopBridge(promise)
+    }
+
+    override fun status(promise: Promise) {
+        impl.status(promise)
+    }
+
+    override fun downloadModel(opts: ReadableMap, promise: Promise) {
+        impl.downloadModel(opts, promise)
+    }
+
+    override fun assessHardware(
+        hardwareMinimum: Double,
+        minLocalCapability: Double,
+        promise: Promise,
+    ) {
+        impl.assessHardware(hardwareMinimum, minLocalCapability, promise)
+    }
+
+    override fun addListener(eventName: String) {
+        impl.addListener(eventName)
+    }
+
+    override fun removeListeners(count: Double) {
+        impl.removeListeners(count.toInt())
+    }
+
+    override fun invalidate() {
+        impl.invalidate()
+        super.invalidate()
+    }
+
+    companion object {
+        const val NAME = "DVAIBridge"
+    }
+}

package/android/src/oldarch/java/co/deepvoiceai/bridge/rn/DVAIBridgeNativeModule.kt

@@ -0,0 +1,70 @@
+package co.deepvoiceai.bridge.rn
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * Old Architecture (legacy bridge) variant of the DVAIBridge React Native
+ * module. Used when `newArchEnabled=false` (Bridgeless OFF). Picked up by
+ * the source-set switch in `android/build.gradle`.
+ *
+ * RN ≥ 0.77 ships with Bridgeless ON by default, so this class exists
+ * mainly as a safety net for downstream consumers temporarily forced onto
+ * the legacy bridge while migrating. All real logic lives in
+ * [DVAIBridgeNativeModuleImpl].
+ */
+class DVAIBridgeNativeModule(
+    reactContext: ReactApplicationContext,
+) : ReactContextBaseJavaModule(reactContext) {
+
+    private val impl = DVAIBridgeNativeModuleImpl(reactContext)
+
+    override fun getName(): String = NAME
+
+    @ReactMethod
+    fun startBridge(opts: ReadableMap, promise: Promise) {
+        impl.startBridge(opts, promise)
+    }
+
+    @ReactMethod
+    fun stopBridge(promise: Promise) {
+        impl.stopBridge(promise)
+    }
+
+    @ReactMethod
+    fun status(promise: Promise) {
+        impl.status(promise)
+    }
+
+    @ReactMethod
+    fun downloadModel(opts: ReadableMap, promise: Promise) {
+        impl.downloadModel(opts, promise)
+    }
+
+    @ReactMethod
+    fun assessHardware(hardwareMinimum: Double, minLocalCapability: Double, promise: Promise) {
+        impl.assessHardware(hardwareMinimum, minLocalCapability, promise)
+    }
+
+    @ReactMethod
+    fun addListener(eventName: String) {
+        impl.addListener(eventName)
+    }
+
+    @ReactMethod
+    fun removeListeners(count: Double) {
+        impl.removeListeners(count.toInt())
+    }
+
+    override fun invalidate() {
+        impl.invalidate()
+        super.invalidate()
+    }
+
+    companion object {
+        const val NAME = "DVAIBridge"
+    }
+}

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@dvai-bridge/react-native",
+  "version": "4.0.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "description": "React Native TurboModule wrapping the @dvai-bridge/ios + @dvai-bridge/android native SDKs behind a shared TS API.",
+  "main": "lib/commonjs/index",
+  "module": "lib/module/index",
+  "types": "lib/typescript/commonjs/src/index.d.ts",
+  "react-native": "src/index",
+  "source": "src/index",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/typescript/module/src/index.d.ts",
+        "default": "./lib/module/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "android/src",
+    "android/build.gradle",
+    "android/gradle.properties",
+    "android/settings.gradle",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dvai-bridge",
+    "react-native",
+    "turbomodule",
+    "llm",
+    "on-device",
+    "openai-compatible",
+    "llama-cpp",
+    "mediapipe",
+    "litert",
+    "mlx",
+    "coreml",
+    "foundation-models"
+  ],
+  "author": "Deep Chakraborty <https://github.com/dk013>",
+  "license": "Custom (See LICENSE)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/westenets/dvai-bridge.git"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.77.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "react-native": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@babel/preset-env": "^7.29.2",
+    "@babel/preset-react": "^7.28.5",
+    "@babel/preset-typescript": "^7.28.5",
+    "@react-native/babel-preset": "^0.85.2",
+    "@react-native/eslint-config": "^0.85.2",
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.14",
+    "babel-jest": "^30.3.0",
+    "del-cli": "^7.0.0",
+    "jest": "^30.3.0",
+    "jest-environment-jsdom": "^30.3.0",
+    "react": "^19.2.5",
+    "react-native": "^0.85.2",
+    "react-native-builder-bob": "^0.41.0",
+    "react-test-renderer": "^19.2.5",
+    "typescript": "^6.0.3"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "commonjs",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "RNDVAIBridgeSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "co.deepvoiceai.bridge.rn"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "bob build",
+    "clean": "del-cli lib",
+    "test": "jest",
+    "typecheck": "tsc --noEmit"
+  }
+}