diff --git a/.gitignore b/.gitignore
index b5028c58..71d825fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,3 +27,4 @@ skills-lock.json
 
 # Swift / SwiftPM build artifacts
 .build/
+.smoke-expo-moss/
diff --git a/AGENTS.md b/AGENTS.md
index c2cbc8e9..895a91bf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,10 +15,13 @@ sdks/
   python/sdk/      — Python SDK (PyPI: moss), Python 3.10+
   javascript/sdk/  — JS/TS SDK (npm: @moss-dev/moss), ESM-only
   elixir/sdk/      — Elixir SDK (Hex: moss)
+  swift/           — Swift SDK for iOS (wraps Moss.xcframework)
+  react-native/    — Expo / React Native module (@moss-dev/moss-react-native); iOS native, Android stub
 examples/
   python/          — Standalone Python usage examples
   javascript/      — Standalone TS usage examples
   javascript-web/  — Browser/Vite examples (no Node runtime)
+  react-native/    — Expo usage sketch for @moss-dev/moss-react-native
   c/               — C binding examples
   go/              — Standalone Go SDK usage examples
   bun/             — Bun runtime example
@@ -223,6 +226,17 @@ mix deps.get
 mix test
 ```
 
+### React Native / Expo module (`sdks/react-native/`)
+
+```bash
+cd sdks/react-native
+npm install
+npm run build      # tsc → build/
+```
+
+iOS links `Moss.xcframework` (downloaded at `pod install` via `ios/scripts/download-moss-xcframework.sh`).
+Android is a stub until [#411](https://github.com/usemoss/moss/issues/411). Requires Expo prebuild / a dev client — not Expo Go.
+
 ## Architecture: Two-Layer Design
 
 Every SDK has the same two-layer structure:
diff --git a/README.md b/README.md
index 4281a692..55e09b8f 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@
 
 Moss is a sub-10 ms semantic search runtime built for Conversational AI agents. Hybrid retrieval (semantic + Keyword Search), built-in embeddings, metadata filtering, and a WebAssembly build that runs in the browser - all from a single SDK that embeds in your application.
 
-No network hop on the hot path. No clusters to tune. Point the SDK at Moss Cloud, load your index, and query it in **under 10 ms**. Python, TypeScript, Elixir, and C.
+No network hop on the hot path. No clusters to tune. Point the SDK at Moss Cloud, load your index, and query it in **under 10 ms**. Python, TypeScript, Elixir, C, Swift, and React Native / Expo.
 
 ![Moss Python walkthrough](https://github.com/user-attachments/assets/d826023d-92d6-49ac-8e5e-81cf04d409c5)
 
@@ -116,7 +116,7 @@ Moss isn't a database! It's a **search runtime**. You don't manage clusters, tun
 - **Runs in the browser too** - separate WebAssembly SDK ([`@moss-dev/moss-web`](https://www.npmjs.com/package/@moss-dev/moss-web)) for client-side semantic search with no server
 - **Database connectors** - ingest directly from SQLite, MongoDB, MySQL, and Supabase ([`packages/moss-data-connector/`](packages/moss-data-connector/))
 - **CLI** - manage indexes and query from the terminal ([`packages/moss-cli/`](packages/moss-cli/))
-- **SDKs** - Python (3.10+), TypeScript / Node.js (20+), Elixir, and C ([`libmoss`](https://github.com/usemoss/moss/releases))
+- **SDKs** - Python (3.10+), TypeScript / Node.js (20+), Elixir, C ([`libmoss`](https://github.com/usemoss/moss/releases)), Swift (iOS), and React Native / Expo (`@moss-dev/moss-react-native`)
 - **Framework integrations** - LangChain, DSPy, LlamaIndex, Pipecat, LiveKit, Vapi, ElevenLabs, Strands Agents
 
 ## Examples
@@ -274,7 +274,7 @@ Full Python SDK source code is available at [`sdks/python/`](sdks/python/).
 
 Here's where the community can have the most impact:
 
-- **New SDK bindings** — Swift, Go, Elixir,...
+- **New SDK bindings** — Kotlin/Android, Rust,… React Native / Expo module shipped under `sdks/react-native/`
 - **Framework integrations** — CrewAI, Haystack, AutoGen
 - **Reranking support** — plug in cross-encoder rerankers
 - **Doc-parsing connectors** — PDF, DOCX, HTML, Markdown ingestion
diff --git a/ROADMAP.md b/ROADMAP.md
index 3b116e40..21be99b4 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -92,6 +92,7 @@ These are well-scoped and ready for contributors. Each one has (or will have) a
 - [ ] **Swift bindings** — for iOS/macOS apps with on-device retrieval ([`good first issue`](https://github.com/usemoss/moss/labels/good%20first%20issue))
 - [ ] **Rust bindings** — for performance-critical pipelines ([`good first issue`](https://github.com/usemoss/moss/labels/good%20first%20issue))
 - [ ] **Kotlin bindings** — for Android apps and Spring Boot backend services ([`good first issue`](https://github.com/usemoss/moss/labels/good%20first%20issue))
+- [x] **React Native / Expo module** — iOS via `Moss.xcframework` + Expo config plugin (`sdks/react-native/`, `@moss-dev/moss-react-native`); Android pending [#411](https://github.com/usemoss/moss/issues/411) ([#432](https://github.com/usemoss/moss/issues/432))
 
 ### Voice AI Ecosystem
 
diff --git a/examples/react-native/README.md b/examples/react-native/README.md
new file mode 100644
index 00000000..cdffedda
--- /dev/null
+++ b/examples/react-native/README.md
@@ -0,0 +1,93 @@
+# React Native / Expo example (Moss)
+
+Minimal usage sketch for [`@moss-dev/moss-react-native`](../../sdks/react-native/).
+
+This is not a full Expo app (no `node_modules` committed). Scaffold your own with:
+
+```bash
+npx create-expo-app moss-rn-demo
+cd moss-rn-demo
+npx expo install @moss-dev/moss-react-native
+```
+
+Add the plugin in `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": ["@moss-dev/moss-react-native"]
+  }
+}
+```
+
+Then:
+
+```bash
+npx expo prebuild
+npx expo run:ios
+```
+
+## Example screen
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, ScrollView, Text, View } from 'react-native';
+import { MossClient, type SearchResult } from '@moss-dev/moss-react-native';
+
+// Development build only. `EXPO_PUBLIC_*` values are inlined into the shipped JS
+// bundle, so a project key set this way is readable by anyone with the app and
+// grants mutating access (createIndex / addDocs / deleteIndex). Do not ship it
+// in a production app — see the package README's "Credentials" section.
+const PROJECT_ID = process.env.EXPO_PUBLIC_MOSS_PROJECT_ID!;
+const PROJECT_KEY = process.env.EXPO_PUBLIC_MOSS_PROJECT_KEY!;
+
+export default function App() {
+  const [result, setResult] = useState<SearchResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const client = new MossClient(PROJECT_ID, PROJECT_KEY);
+    let cancelled = false;
+
+    (async () => {
+      try {
+        await client.createIndex('rn-demo', [
+          { id: '1', text: 'Refunds are processed within 3-5 business days.' },
+          { id: '2', text: 'Shipping usually takes 2 business days.' },
+        ]);
+        await client.loadIndex('rn-demo');
+        const search = await client.query('rn-demo', 'how long do refunds take?');
+        if (!cancelled) setResult(search);
+      } catch (e) {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
+      } finally {
+        client.close();
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return (
+    <ScrollView contentContainerStyle={{ padding: 24, gap: 12 }}>
+      <Text style={{ fontSize: 22, fontWeight: '600' }}>Moss RN demo</Text>
+      {error ? <Text style={{ color: 'crimson' }}>{error}</Text> : null}
+      {result?.docs.map((doc) => (
+        <View key={doc.id}>
+          <Text>
+            [{doc.score.toFixed(3)}] {doc.text}
+          </Text>
+        </View>
+      ))}
+      <Button title={`SDK ${MossClient.sdkVersion}`} onPress={() => {}} />
+    </ScrollView>
+  );
+}
+```
+
+## Notes
+
+- iOS only for on-device query today. Android throws until [#411](https://github.com/usemoss/moss/issues/411) lands.
+- Requires a development build — Expo Go cannot load custom native modules.
diff --git a/sdks/react-native/.gitignore b/sdks/react-native/.gitignore
new file mode 100644
index 00000000..ace0dc83
--- /dev/null
+++ b/sdks/react-native/.gitignore
@@ -0,0 +1,9 @@
+node_modules/
+build/
+.DS_Store
+*.tgz
+ios/Frameworks/
+ios/Moss.xcframework/
+*.xcframework/
+.expo/
+package-lock.json
diff --git a/sdks/react-native/.npmignore b/sdks/react-native/.npmignore
new file mode 100644
index 00000000..a6bc692b
--- /dev/null
+++ b/sdks/react-native/.npmignore
@@ -0,0 +1,7 @@
+node_modules/
+ios/Frameworks/
+ios/Moss.xcframework/
+*.tgz
+.DS_Store
+tsconfig.json
+.gitignore
diff --git a/sdks/react-native/LICENSE b/sdks/react-native/LICENSE
new file mode 100644
index 00000000..372ad0ad
--- /dev/null
+++ b/sdks/react-native/LICENSE
@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Moss Team
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/sdks/react-native/README.md b/sdks/react-native/README.md
new file mode 100644
index 00000000..7b82e7cc
--- /dev/null
+++ b/sdks/react-native/README.md
@@ -0,0 +1,182 @@
+# @moss-dev/moss-react-native
+
+React Native / Expo module for [Moss](https://github.com/usemoss/moss) — on-device semantic search.
+
+Closes the gap described in [usemoss/moss#432](https://github.com/usemoss/moss/issues/432).
+
+## Status
+
+| Platform | Support |
+|----------|---------|
+| **iOS** | Native via `Moss.xcframework` (same binary as the Swift SDK, release `v0.6.2`) |
+| **Android** | Stub — throws until Android native builds land ([#411](https://github.com/usemoss/moss/issues/411)) |
+| **Expo Go** | Not supported (custom native code; use a [dev client](https://docs.expo.dev/develop/development-builds/introduction/) / `expo prebuild`) |
+
+## Install
+
+```bash
+npx expo install @moss-dev/moss-react-native
+```
+
+Add the config plugin in `app.json` / `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": ["@moss-dev/moss-react-native"]
+  }
+}
+```
+
+Then regenerate native projects:
+
+```bash
+npx expo prebuild
+npx pod-install
+```
+
+CocoaPods downloads `Moss.xcframework` during `pod install` (checksum-verified against the Swift SDK release).
+
+## Quick start
+
+> [!WARNING]
+> The snippet below reads the project key from `EXPO_PUBLIC_*`, which is fine
+> for a local dev build but **must not ship in a production app**. See
+> [Credentials](#credentials) before you release.
+
+```tsx
+import { MossClient } from '@moss-dev/moss-react-native';
+
+// Development builds only — see the Credentials section below.
+const client = new MossClient(process.env.EXPO_PUBLIC_MOSS_PROJECT_ID!, process.env.EXPO_PUBLIC_MOSS_PROJECT_KEY!);
+
+await client.createIndex('support-docs', [
+  { id: '1', text: 'Refunds are processed within 3-5 business days.' },
+  { id: '2', text: 'You can track your order on the dashboard.' },
+]);
+
+await client.loadIndex('support-docs');
+const result = await client.query('support-docs', 'how long do refunds take?');
+for (const doc of result.docs) {
+  console.log(`[${doc.score.toFixed(3)}] ${doc.text}`);
+}
+
+client.close();
+```
+
+## Credentials
+
+Anything in an `EXPO_PUBLIC_*` variable is **inlined into the JS bundle at build
+time**. It is shipped to every user and can be read straight out of the app —
+it is not a secret. A project key exposed that way is usable by anyone who
+extracts it, and `MossClient` also exposes mutating calls (`createIndex`,
+`addDocs`, `deleteIndex`), so a leaked key is not merely read access to your
+project.
+
+So:
+
+- **Development / internal builds** — `EXPO_PUBLIC_MOSS_PROJECT_KEY` is fine.
+- **Production apps** — do not embed a project key. Use the token form below.
+
+### Short-lived tokens (production)
+
+Pass `getAuthToken` instead of a project key. It is called whenever the native
+runtime needs a bearer token, so your backend mints a short-lived, scoped one
+and nothing long-lived is ever in the bundle:
+
+```ts
+const client = new MossClient({
+  projectId: process.env.EXPO_PUBLIC_MOSS_PROJECT_ID!,
+  getAuthToken: async () => {
+    const res = await fetch('https://api.example.com/moss-token', {
+      headers: { Authorization: `Bearer ${await mySessionToken()}` },
+    });
+    const { token } = await res.json();
+    return token; // raw token — do NOT prefix with "Bearer "
+  },
+});
+```
+
+Notes:
+
+- Return the **raw token**. The native side builds the
+  `Authorization: Bearer <token>` header itself.
+- `getAuthToken` may be called from a background thread and more than once —
+  cache until expiry if the round trip is expensive.
+- Throwing (or returning a non-string / empty string) fails the in-flight
+  request with your error rather than hanging it.
+- `projectId` is not a secret; only the key is.
+
+This is the same mechanism as the Swift SDK's `Authenticator`, wired through
+`moss_client_new_with_authenticator` in the native ABI.
+
+## API
+
+Mirrors the Node `@moss-dev/moss` client for the core cloud + local query loop:
+
+- `new MossClient(projectId, projectKey)` (development builds)
+- `new MossClient({ projectId, getAuthToken, baseUrl? })` (short-lived tokens; see [Credentials](#credentials))
+- `createIndex(name, docs, options?)`
+- `addDocs(name, docs, options?)`
+- `loadIndex(name, options?)` / `unloadIndex(name)`
+- `query(name, query, options?)`
+- `listIndexes()` / `getIndex(name)` / `deleteIndex(name)`
+- `close()`
+- `MossClient.sdkVersion`
+- `MossClient.setModelCacheDir(path)` (optional; iOS defaults to `Library/Caches/moss-models`)
+
+The Swift SDK's `Authenticator` is bridged (see [Credentials](#credentials)).
+Session APIs remain out of scope for this first release.
+
+### Metadata filters
+
+`query` takes the same `filter` shape as `@moss-dev/moss`:
+
+```ts
+await client.query('support-docs', 'refund timing', {
+  filter: { field: 'locale', condition: { $eq: 'en-US' } },
+});
+```
+
+Pass `filterJson` instead if you already hold the engine's serialized form.
+Supplying both is an error rather than a silent precedence rule.
+
+### Custom embeddings
+
+Passing documents with an `embedding` makes `createIndex` select `modelId: 'custom'`,
+which means there is no on-device model to embed query text with. Supply the query
+vector yourself:
+
+```ts
+await client.createIndex('vectors', [
+  { id: '1', text: 'Refunds take 3-5 business days.', embedding: myVector },
+]);
+await client.loadIndex('vectors');
+
+const result = await client.query('vectors', 'refund timing', {
+  embedding: myQueryVector, // must match the index dimensionality
+});
+```
+
+## Requirements
+
+- Expo SDK 54+ (or a React Native app with Expo Modules)
+- iOS 16.4+ (Expo SDK 54+ baseline)
+- Xcode 15+
+- Apple Silicon Mac for the iOS Simulator (the Moss.xcframework simulator slice is arm64-only)
+- A development build / `expo prebuild` — Expo Go is not supported
+- Until this package is published to npm, install from a local path or git checkout (`file:…` / `github:…`)
+
+## Development (this monorepo)
+
+```bash
+cd sdks/react-native
+npm install
+npm run build
+```
+
+See [`examples/react-native/`](../../examples/react-native/) for a minimal usage sketch.
+
+## License
+
+[BSD 2-Clause](./LICENSE)
diff --git a/sdks/react-native/android/build.gradle b/sdks/react-native/android/build.gradle
new file mode 100644
index 00000000..7b02231c
--- /dev/null
+++ b/sdks/react-native/android/build.gradle
@@ -0,0 +1,37 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'maven-publish'
+
+group = 'dev.moss'
+version = '0.1.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+if (expoModulesCorePlugin.exists()) {
+  apply from: expoModulesCorePlugin
+  applyKotlinExpoModulesCorePlugin()
+  safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+  useExpoPublishing()
+  useCoreDependencies()
+}
+
+android {
+  namespace "dev.moss.reactnative"
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 35)
+  }
+
+  lintOptions {
+    abortOnError false
+  }
+
+  publishing {
+    singleVariant("release") {
+      withSourcesJar()
+    }
+  }
+}
diff --git a/sdks/react-native/android/src/main/AndroidManifest.xml b/sdks/react-native/android/src/main/AndroidManifest.xml
new file mode 100644
index 00000000..a2f47b60
--- /dev/null
+++ b/sdks/react-native/android/src/main/AndroidManifest.xml
@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>
diff --git a/sdks/react-native/android/src/main/java/dev/moss/reactnative/MossModule.kt b/sdks/react-native/android/src/main/java/dev/moss/reactnative/MossModule.kt
new file mode 100644
index 00000000..8e41beb5
--- /dev/null
+++ b/sdks/react-native/android/src/main/java/dev/moss/reactnative/MossModule.kt
@@ -0,0 +1,39 @@
+package dev.moss.reactnative
+
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.sharedobjects.SharedObject
+import expo.modules.kotlin.AppContext
+
+/**
+ * Android native builds of Moss are tracked in
+ * https://github.com/usemoss/moss/issues/411. Until a published Android
+ * artifact exists, constructing a client fails with a clear error so apps
+ * can feature-detect.
+ */
+class MossModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("Moss")
+
+    Constant("sdkVersion") { "android-unavailable" }
+
+    AsyncFunction("setModelCacheDir") { _: String ->
+      throw AndroidUnavailableException()
+    }
+
+    Class("MossClient", MossClientSharedObject::class) {
+      Constructor { _: String, _: String ->
+        throw AndroidUnavailableException()
+      }
+
+      Function("close") { _: MossClientSharedObject -> }
+    }
+  }
+}
+
+class MossClientSharedObject(appContext: AppContext) : SharedObject(appContext)
+
+class AndroidUnavailableException : CodedException(
+  "Moss Android native builds are not published yet. Track progress in https://github.com/usemoss/moss/issues/411"
+)
diff --git a/sdks/react-native/app.plugin.js b/sdks/react-native/app.plugin.js
new file mode 100644
index 00000000..3d8d22c0
--- /dev/null
+++ b/sdks/react-native/app.plugin.js
@@ -0,0 +1,65 @@
+const {
+  createRunOncePlugin,
+  withPodfileProperties,
+} = require('@expo/config-plugins');
+
+const pkg = require('./package.json');
+
+/** Must stay in sync with `s.platforms` in ios/MossReactNative.podspec. */
+const MIN_IOS_DEPLOYMENT_TARGET = '16.4';
+
+/**
+ * Compares dotted version strings numerically ("15.10" > "15.9").
+ * @returns {number} negative if `a < b`, 0 if equal, positive if `a > b`
+ */
+const compareVersions = (a, b) => {
+  const pa = String(a).split('.');
+  const pb = String(b).split('.');
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const na = Number.parseInt(pa[i], 10) || 0;
+    const nb = Number.parseInt(pb[i], 10) || 0;
+    if (na !== nb) {
+      return na - nb;
+    }
+  }
+  return 0;
+};
+
+/**
+ * True when the existing target is unset, unparseable, or older than the
+ * minimum Moss.xcframework supports.
+ */
+const needsBump = (current) => {
+  if (current === undefined || current === null || String(current).trim() === '') {
+    return true;
+  }
+  if (!/^\d+(\.\d+)*$/.test(String(current).trim())) {
+    return true;
+  }
+  return compareVersions(current, MIN_IOS_DEPLOYMENT_TARGET) < 0;
+};
+
+/**
+ * Expo config plugin for `@moss-dev/moss-react-native`.
+ *
+ * Raises the iOS deployment target to what Moss.xcframework requires and
+ * documents that a development build / prebuild is required (Expo Go is not
+ * supported because this module ships custom native code).
+ *
+ * An app that already pins a lower target (say `15.1`) is bumped rather than
+ * left alone — CocoaPods rejects the pod otherwise.
+ *
+ * @param {import('@expo/config-plugins').ConfigPlugin} config
+ */
+const withMoss = (config) => {
+  config = withPodfileProperties(config, (cfg) => {
+    const current = cfg.modResults['ios.deploymentTarget'];
+    if (needsBump(current)) {
+      cfg.modResults['ios.deploymentTarget'] = MIN_IOS_DEPLOYMENT_TARGET;
+    }
+    return cfg;
+  });
+  return config;
+};
+
+module.exports = createRunOncePlugin(withMoss, pkg.name, pkg.version);
diff --git a/sdks/react-native/expo-module.config.json b/sdks/react-native/expo-module.config.json
new file mode 100644
index 00000000..6bd334f5
--- /dev/null
+++ b/sdks/react-native/expo-module.config.json
@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["MossModule"]
+  },
+  "android": {
+    "modules": ["dev.moss.reactnative.MossModule"]
+  }
+}
diff --git a/sdks/react-native/ios/.npmignore b/sdks/react-native/ios/.npmignore
new file mode 100644
index 00000000..97aa0333
--- /dev/null
+++ b/sdks/react-native/ios/.npmignore
@@ -0,0 +1,9 @@
+# Moss.xcframework is fetched and checksum-verified at `pod install` time (see
+# MossReactNative.podspec). It must never be published: a packed copy would be
+# used as-is, and the download script skips verification when the directory
+# already exists — so a stale or unverified binary would ship silently.
+#
+# The `files` allow-list in package.json already enumerates only the sources,
+# podspec and scripts. This is the second line of defence if that list is ever
+# widened back to the whole `ios` directory.
+Frameworks/
diff --git a/sdks/react-native/ios/MossClientSharedObject.swift b/sdks/react-native/ios/MossClientSharedObject.swift
new file mode 100644
index 00000000..d351daf5
--- /dev/null
+++ b/sdks/react-native/ios/MossClientSharedObject.swift
@@ -0,0 +1,636 @@
+import ExpoModulesCore
+import Foundation
+import MossC
+import UIKit
+
+/**
+ * SharedObject wrapping a native MossClient handle.
+ * Methods return dictionaries / arrays that map cleanly across the JSI bridge.
+ */
+/// Holds the closure that forwards a native auth-token request to JS.
+///
+/// A pointer to this box is handed to the native side as `user_data` and must
+/// stay valid for the whole life of the client, so it is retained manually and
+/// released only after `moss_client_free`.
+final class AuthBridgeBox {
+  let emit: (UInt32) -> Void
+  init(emit: @escaping (UInt32) -> Void) { self.emit = emit }
+}
+
+/// C trampoline registered as `MossAuthNotifyFn`.
+///
+/// The native runtime calls this from an arbitrary Rust thread, possibly
+/// concurrently, whenever it needs a bearer token. It must not block: it only
+/// forwards the request id to JS, which answers later via
+/// `moss_resolve_auth_request` / `moss_reject_auth_request`.
+@_cdecl("_moss_rn_auth_notify")
+func mossRNAuthNotify(requestId: UInt32, userData: UnsafeMutableRawPointer?) {
+  guard let userData else { return }
+  let box = Unmanaged<AuthBridgeBox>.fromOpaque(userData).takeUnretainedValue()
+  box.emit(requestId)
+}
+
+public final class MossClientSharedObject: SharedObject {
+  private var handle: OpaquePointer?
+  private var closed = false
+  private var inFlight = 0
+  /// Retained `AuthBridgeBox` pointer for authenticator-backed clients, or nil
+  /// for project-key clients. Released exactly once, after the handle is freed.
+  private var authUserData: UnsafeMutableRawPointer?
+  /// Guards `handle` / `closed` / `inFlight`.
+  ///
+  /// The operations are `AsyncFunction`s that run off the JS thread while
+  /// `close()` is a synchronous `Function` on it, so freeing the handle
+  /// eagerly would be a use-after-free. Ownership of the free is therefore
+  /// handed to whoever is last out — see `close()` and `release()`.
+  private let state = NSLock()
+
+  public init(projectId: String, projectKey: String) throws {
+    try Self.ensureModelCacheDir()
+    let deviceId = Self.stableDeviceId()
+    var raw: OpaquePointer?
+    let status = projectId.withCString { pid in
+      projectKey.withCString { pkey in
+        deviceId.withCString { did in
+          moss_client_new_with_device_id(pid, pkey, did, &raw)
+        }
+      }
+    }
+    try Self.throwIfErr(status)
+    guard let raw else {
+      throw Self.mossError(code: -7)
+    }
+    self.handle = raw
+    self.authUserData = nil
+    super.init()
+  }
+
+  /// Construct a client that asks the host for a short-lived bearer token
+  /// instead of embedding a long-lived project key.
+  ///
+  /// `emit` is invoked from an arbitrary native thread whenever a token is
+  /// needed; it must not block. The host answers out-of-band with
+  /// `resolveAuthRequest` / `rejectAuthRequest`.
+  public init(projectId: String, baseUrl: String?, emit: @escaping (UInt32) -> Void) throws {
+    try Self.ensureModelCacheDir()
+    let deviceId = Self.stableDeviceId()
+    // Retained deliberately: the native side keeps this pointer for the
+    // client's lifetime. Ownership comes back to us on every error path below,
+    // and otherwise transfers to close()/release().
+    let userData = Unmanaged.passRetained(AuthBridgeBox(emit: emit)).toOpaque()
+
+    var raw: OpaquePointer?
+    let status = projectId.withCString { pid in
+      withOptionalCString(baseUrl) { base in
+        deviceId.withCString { did in
+          moss_client_new_with_authenticator_and_device_id(
+            pid,
+            mossRNAuthNotify,
+            userData,
+            base,
+            did,
+            &raw
+          )
+        }
+      }
+    }
+    if status != 0 {
+      Unmanaged<AuthBridgeBox>.fromOpaque(userData).release()
+      try Self.throwIfErr(status)
+    }
+    guard let raw else {
+      Unmanaged<AuthBridgeBox>.fromOpaque(userData).release()
+      throw Self.mossError(code: -7)
+    }
+    self.handle = raw
+    self.authUserData = userData
+    super.init()
+  }
+
+  /// Answer a pending auth request with a bearer token (no `Bearer ` prefix —
+  /// the native side builds the header). Unknown ids are no-ops natively.
+  static func resolveAuthRequest(requestId: UInt32, token: String) throws {
+    let status = token.withCString { moss_resolve_auth_request(requestId, $0) }
+    try throwIfErr(status)
+  }
+
+  /// Fail a pending auth request so the in-flight native call errors out
+  /// instead of hanging.
+  static func rejectAuthRequest(requestId: UInt32, message: String?) {
+    _ = withOptionalCString(message) { moss_reject_auth_request(requestId, $0) }
+  }
+
+  deinit {
+    close()
+  }
+
+  /// Marks the client closed and frees the handle once nothing is using it.
+  ///
+  /// Never blocks: this is a synchronous `Function` on the JS thread, so
+  /// waiting here would freeze the UI for as long as an in-flight
+  /// `loadIndex` / query / mutation takes. If calls are still running the
+  /// handle is left for the last `release()` to free instead. Either way no
+  /// new work can start, since `acquire()` refuses once `closed` is set.
+  ///
+  /// Safe to call while operations are running, and safe to call twice.
+  public func close() {
+    state.lock()
+    if closed {
+      state.unlock()
+      return
+    }
+    closed = true
+    guard inFlight == 0 else {
+      // Still in use — the last one out owns the teardown.
+      state.unlock()
+      return
+    }
+    let doomed = handle
+    let doomedAuth = authUserData
+    handle = nil
+    authUserData = nil
+    state.unlock()
+
+    Self.teardown(doomed, doomedAuth)
+  }
+
+  /// Frees the native handle, then releases the auth box.
+  ///
+  /// Order matters: the native side can invoke the notify callback — and so
+  /// dereference `user_data` — right up until the client is freed.
+  private static func teardown(_ doomed: OpaquePointer?, _ auth: UnsafeMutableRawPointer?) {
+    if let doomed {
+      moss_client_free(doomed)
+    }
+    if let auth {
+      Unmanaged<AuthBridgeBox>.fromOpaque(auth).release()
+    }
+  }
+
+  public func createIndex(name: String, docsJson: String, modelId: String?) throws -> [String: Any] {
+    try withHandle { h in
+      var out: UnsafeMutablePointer<CChar>?
+      let status = name.withCString { cname in
+        docsJson.withCString { cdocs in
+          withOptionalCString(modelId) { cmodel in
+            moss_client_create_index_from_json(h, cname, cdocs, cmodel, &out)
+          }
+        }
+      }
+      try Self.throwIfErr(status)
+      guard let out else {
+        throw Self.mossError(code: -7)
+      }
+      defer { moss_free_string(out) }
+      return try Self.decodeJsonObject(String(cString: out))
+    }
+  }
+
+  public func loadIndex(name: String, options: [String: Any]) throws {
+    try withHandle { h in
+      let autoRefresh = (options["autoRefresh"] as? Bool) ?? false
+      let intervalSeconds = try Self.integerOption(
+        options,
+        "pollingIntervalSeconds",
+        default: 600,
+        minimum: 1,
+        maximum: Self.maxPollingIntervalSeconds
+      )
+      let interval = UInt64(intervalSeconds)
+      let cachePath = options["cachePath"] as? String
+
+      let status = name.withCString { cname in
+        withOptionalCString(cachePath) { cache in
+          var nativeOpts = MossLoadIndexOptions(
+            auto_refresh: autoRefresh,
+            polling_interval_secs: interval,
+            cache_path: cache
+          )
+          var info: UnsafeMutablePointer<MossIndexInfo>?
+          let r = moss_client_load_index(h, cname, &nativeOpts, &info)
+          if let info { moss_free_index_info(info) }
+          return r
+        }
+      }
+      try Self.throwIfErr(status)
+    }
+  }
+
+  public func unloadIndex(name: String) throws {
+    try withHandle { h in
+      let status = name.withCString { cname in moss_client_unload_index(h, cname) }
+      try Self.throwIfErr(status)
+    }
+  }
+
+  public func query(name: String, query: String, options: [String: Any]) throws -> [String: Any] {
+    try withHandle { h in
+      let topK = try Self.integerOption(
+        options,
+        "topK",
+        default: 5,
+        minimum: 0,
+        maximum: Self.maxTopK
+      )
+      let alpha = try Self.unitIntervalOption(options, "alpha", default: 0.8)
+      let filterJson = options["filterJson"] as? String
+      let embedding = try Self.embeddingOption(options, "embedding")
+
+      return try name.withCString { iname in
+        try query.withCString { q in
+          try withOptionalCString(filterJson) { filter in
+            // `embedding` must stay alive for the duration of the call, so the
+            // buffer pointer is taken around `invoke` rather than escaping it.
+            var result: UnsafeMutablePointer<MossSearchResult>?
+            let invoke: (UnsafePointer<Float>?, Int) -> Int32 = { embPtr, embLen in
+              var nativeOpts = MossQueryOptions(
+                top_k: UInt(topK),
+                alpha: alpha,
+                filter_json: filter,
+                embedding: embPtr,
+                embedding_dim: UInt(embLen)
+              )
+              return moss_client_query(h, iname, q, &nativeOpts, &result)
+            }
+            let status: Int32 = if let embedding {
+              embedding.withUnsafeBufferPointer { bp in invoke(bp.baseAddress, bp.count) }
+            } else {
+              invoke(nil, 0)
+            }
+            try Self.throwIfErr(status)
+            guard let result else {
+              throw Self.mossError(code: -7)
+            }
+            defer { moss_free_search_result(result) }
+            return Self.parseSearchResult(result.pointee)
+          }
+        }
+      }
+    }
+  }
+
+  public func listIndexes() throws -> [[String: Any]] {
+    try withHandle { h in
+      var infos: UnsafeMutablePointer<MossIndexInfo>?
+      var count: UInt = 0
+      let status = moss_client_list_indexes(h, &infos, &count)
+      try Self.throwIfErr(status)
+      guard let infos else { return [] }
+      defer { moss_free_index_info_list(infos, count) }
+      var out: [[String: Any]] = []
+      out.reserveCapacity(Int(count))
+      for i in 0..<Int(count) {
+        out.append(Self.parseIndexInfo(infos.advanced(by: i).pointee))
+      }
+      return out
+    }
+  }
+
+  public func getIndex(name: String) throws -> [String: Any] {
+    try withHandle { h in
+      try name.withCString { cname in
+        var info: UnsafeMutablePointer<MossIndexInfo>?
+        let status = moss_client_get_index(h, cname, &info)
+        try Self.throwIfErr(status)
+        guard let info else {
+          throw Self.mossError(code: -7)
+        }
+        defer { moss_free_index_info(info) }
+        return Self.parseIndexInfo(info.pointee)
+      }
+    }
+  }
+
+  public func deleteIndex(name: String) throws -> Bool {
+    try withHandle { h in
+      try name.withCString { cname in
+        var deleted = false
+        let status = moss_client_delete_index(h, cname, &deleted)
+        try Self.throwIfErr(status)
+        return deleted
+      }
+    }
+  }
+
+  public func addDocs(name: String, docsJson: String, upsert: Bool) throws -> [String: Any] {
+    try withHandle { h in
+      var out: UnsafeMutablePointer<CChar>?
+      let status = name.withCString { cname in
+        docsJson.withCString { cdocs in
+          moss_client_add_docs_from_json(h, cname, cdocs, upsert, &out)
+        }
+      }
+      try Self.throwIfErr(status)
+      guard let out else {
+        throw Self.mossError(code: -7)
+      }
+      defer { moss_free_string(out) }
+      return try Self.decodeJsonObject(String(cString: out))
+    }
+  }
+
+  // MARK: - Internals
+
+  /// Runs `body` with the native handle held open. The handle is not freed
+  /// while any such call is in flight, so the pointer stays valid for the whole
+  /// call even if `close()` arrives mid-flight. Concurrent operations are still
+  /// allowed — the native client is thread-safe.
+  private func withHandle<R>(_ body: (OpaquePointer) throws -> R) throws -> R {
+    let h = try acquire()
+    defer { release() }
+    return try body(h)
+  }
+
+  private func acquire() throws -> OpaquePointer {
+    state.lock()
+    defer { state.unlock() }
+    guard !closed, let handle else {
+      throw Self.mossError(code: -1, message: "MossClient already closed")
+    }
+    inFlight += 1
+    return handle
+  }
+
+  private func release() {
+    state.lock()
+    inFlight -= 1
+    // If close() landed while this call was running it deferred teardown to
+    // whoever finished last. That is us.
+    var doomed: OpaquePointer?
+    var doomedAuth: UnsafeMutableRawPointer?
+    if inFlight == 0, closed {
+      doomed = handle
+      doomedAuth = authUserData
+      handle = nil
+      authUserData = nil
+    }
+    state.unlock()
+
+    Self.teardown(doomed, doomedAuth)
+  }
+
+  /// Upper bound for `topK`. Far above any sane result count, but small enough
+  /// that `UInt(_:)` and the engine's own allocation stay well-defined.
+  private static let maxTopK = 100_000
+
+  /// Upper bound for `pollingIntervalSeconds` (~136 years). Exactly
+  /// representable as a `Double` and safely inside `UInt64`.
+  private static let maxPollingIntervalSeconds = Int(UInt32.max)
+
+  private static let cacheDirLock = NSLock()
+  private static var cacheDirConfigured = false
+
+  static func setModelCacheDir(_ path: String) throws {
+    cacheDirLock.lock()
+    defer { cacheDirLock.unlock() }
+    let status = path.withCString { moss_set_model_cache_dir($0) }
+    try throwIfErr(status)
+    cacheDirConfigured = true
+  }
+
+  private static func ensureModelCacheDir() throws {
+    cacheDirLock.lock()
+    defer { cacheDirLock.unlock() }
+    if cacheDirConfigured { return }
+    guard let cacheRoot = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else {
+      throw mossError(code: -7, message: "could not locate Library/Caches for model cache")
+    }
+    let dir = cacheRoot.appendingPathComponent("moss-models", isDirectory: true)
+    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    let status = dir.path.withCString { moss_set_model_cache_dir($0) }
+    try throwIfErr(status)
+    cacheDirConfigured = true
+  }
+
+  private static func stableDeviceId() -> String {
+    if let idfv = UIDevice.current.identifierForVendor?.uuidString {
+      return idfv
+    }
+    return UUID().uuidString
+  }
+
+  // MARK: - Option decoding
+  //
+  // JS numbers reach us as `Double`, so NaN, ±Infinity, negatives and huge
+  // magnitudes are all reachable from user code. `Int(_:)` and `UInt64(_:)`
+  // *trap* on those, which kills the app process outright — there is no error
+  // to bridge back. Validate first and throw a MossError instead.
+
+  private static func doubleValue(_ raw: Any) -> Double? {
+    if let d = raw as? Double { return d }
+    if let n = raw as? NSNumber { return n.doubleValue }
+    if let i = raw as? Int { return Double(i) }
+    return nil
+  }
+
+  /// Reads a whole-number option, rejecting anything `Int(_:)` would trap on.
+  /// Bounds stay well inside 2^53 so the `Double` comparisons are exact.
+  private static func integerOption(
+    _ options: [String: Any],
+    _ key: String,
+    default defaultValue: Int,
+    minimum: Int,
+    maximum: Int
+  ) throws -> Int {
+    guard let raw = options[key], !(raw is NSNull) else { return defaultValue }
+    guard let value = doubleValue(raw) else {
+      throw mossError(code: -2, message: "\(key) must be a number")
+    }
+    guard value.isFinite else {
+      throw mossError(code: -2, message: "\(key) must be a finite number")
+    }
+    let truncated = value.rounded(.towardZero)
+    guard truncated >= Double(minimum), truncated <= Double(maximum) else {
+      throw mossError(
+        code: -2,
+        message: "\(key) must be between \(minimum) and \(maximum), got \(value)"
+      )
+    }
+    return Int(truncated)
+  }
+
+  /// Reads a 0...1 weight. `Float(_:)` does not trap on NaN/Infinity, but
+  /// forwarding either into the engine is meaningless — reject them here.
+  private static func unitIntervalOption(
+    _ options: [String: Any],
+    _ key: String,
+    default defaultValue: Float
+  ) throws -> Float {
+    guard let raw = options[key], !(raw is NSNull) else { return defaultValue }
+    guard let value = doubleValue(raw) else {
+      throw mossError(code: -2, message: "\(key) must be a number")
+    }
+    guard value.isFinite else {
+      throw mossError(code: -2, message: "\(key) must be a finite number")
+    }
+    guard value >= 0, value <= 1 else {
+      throw mossError(code: -2, message: "\(key) must be between 0 and 1, got \(value)")
+    }
+    return Float(value)
+  }
+
+  /// Reads a query embedding, rejecting non-finite components before they reach
+  /// the engine.
+  private static func embeddingOption(_ options: [String: Any], _ key: String) throws -> [Float]? {
+    guard let raw = options[key], !(raw is NSNull) else { return nil }
+    guard let values = raw as? [Any] else {
+      throw mossError(code: -2, message: "\(key) must be an array of numbers")
+    }
+    if values.isEmpty { return nil }
+    var out: [Float] = []
+    out.reserveCapacity(values.count)
+    for element in values {
+      guard let value = doubleValue(element) else {
+        throw mossError(code: -2, message: "\(key) must contain only finite numbers")
+      }
+      // Check finiteness *after* narrowing: a finite Double beyond
+      // Float.greatestFiniteMagnitude (~3.4e38) rounds to Float.infinity, so
+      // testing the Double alone would still let a non-finite value through.
+      let narrowed = Float(value)
+      guard narrowed.isFinite else {
+        throw mossError(
+          code: -2,
+          message: "\(key) must contain only values representable as 32-bit floats, got \(value)"
+        )
+      }
+      out.append(narrowed)
+    }
+    return out
+  }
+
+  /// Narrows a bridged JS number to the native request-id type. `UInt32(_:)`
+  /// would trap on a negative or oversized value.
+  static func authRequestId(_ raw: Int) throws -> UInt32 {
+    guard raw >= 0, raw <= Int(UInt32.max) else {
+      throw mossError(code: -2, message: "requestId out of range: \(raw)")
+    }
+    return UInt32(raw)
+  }
+
+  static func argumentError(_ message: String) -> NSError {
+    mossError(code: -2, message: message)
+  }
+
+  private static func throwIfErr(_ status: Int32) throws {
+    if status != 0 {
+      throw mossError(code: status)
+    }
+  }
+
+  private static func mossError(code: Int32, message: String? = nil) -> NSError {
+    let msg: String
+    if let message {
+      msg = message
+    } else if let ptr = moss_last_error() {
+      msg = String(cString: ptr)
+    } else {
+      msg = "moss native error code \(code)"
+    }
+    return NSError(
+      domain: "dev.moss",
+      code: Int(code),
+      userInfo: [NSLocalizedDescriptionKey: msg]
+    )
+  }
+
+  private static func decodeJsonObject(_ json: String) throws -> [String: Any] {
+    guard let data = json.data(using: .utf8),
+          let obj = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+      throw mossError(code: -7, message: "failed to decode Moss JSON response")
+    }
+    return [
+      "jobId": obj["jobId"] as? String ?? "",
+      "indexName": obj["indexName"] as? String ?? "",
+      "docCount": obj["docCount"] as? Int ?? 0,
+    ]
+  }
+
+  /// Nullable C strings are omitted rather than boxed with `as Any` — that
+  /// would put an `Optional.none` into the dictionary and hand a non-JSON value
+  /// to the bridge. Absent keys read as `undefined` in JS, which the optional
+  /// fields on `IndexInfo` / `ModelRef` already allow.
+  private static func parseIndexInfo(_ info: MossIndexInfo) -> [String: Any] {
+    var model: [String: Any] = ["id": cstr(info.model.id)]
+    if let version = cstrOpt(info.model.version) {
+      model["version"] = version
+    }
+
+    var out: [String: Any] = [
+      "id": cstr(info.id),
+      "name": cstr(info.name),
+      "status": cstr(info.status),
+      "docCount": Int(info.doc_count),
+      "model": model,
+    ]
+    if let version = cstrOpt(info.version) {
+      out["version"] = version
+    }
+    if let createdAt = cstrOpt(info.created_at) {
+      out["createdAt"] = createdAt
+    }
+    if let updatedAt = cstrOpt(info.updated_at) {
+      out["updatedAt"] = updatedAt
+    }
+    return out
+  }
+
+  private static func parseSearchResult(_ result: MossSearchResult) -> [String: Any] {
+    let count = Int(result.doc_count)
+    var docs: [[String: Any]] = []
+    docs.reserveCapacity(count)
+    if let buf = result.docs {
+      for i in 0..<count {
+        let d = buf.advanced(by: i).pointee
+        var row: [String: Any] = [
+          "id": cstr(d.id),
+          "text": cstr(d.text),
+          "score": d.score,
+        ]
+        if let metadata = parseMetadata(d.metadata, count: d.metadata_count) {
+          row["metadata"] = metadata
+        }
+        if let payload = d.payload {
+          row["payload"] = String(cString: payload)
+        }
+        docs.append(row)
+      }
+    }
+    return [
+      "docs": docs,
+      "query": cstr(result.query),
+      "timeMs": result.time_taken_ms,
+    ]
+  }
+
+  private static func parseMetadata(
+    _ entries: UnsafeMutablePointer<MossMetadataEntry>?,
+    count: UInt
+  ) -> [String: String]? {
+    guard let entries, count > 0 else { return nil }
+    var out: [String: String] = [:]
+    for i in 0..<Int(count) {
+      let e = entries.advanced(by: i).pointee
+      guard let keyPtr = e.key else { continue }
+      out[String(cString: keyPtr)] = cstr(e.value)
+    }
+    return out.isEmpty ? nil : out
+  }
+}
+
+@inline(__always)
+func withOptionalCString<R>(_ value: String?, _ body: (UnsafePointer<CChar>?) throws -> R) rethrows -> R {
+  if let value {
+    return try value.withCString { try body($0) }
+  }
+  return try body(nil)
+}
+
+@inline(__always)
+func cstr(_ ptr: UnsafeMutablePointer<CChar>?) -> String {
+  ptr.flatMap { String(cString: $0) } ?? ""
+}
+
+@inline(__always)
+func cstrOpt(_ ptr: UnsafeMutablePointer<CChar>?) -> String? {
+  ptr.flatMap { String(cString: $0) }
+}
diff --git a/sdks/react-native/ios/MossModule.swift b/sdks/react-native/ios/MossModule.swift
new file mode 100644
index 00000000..d879b2e4
--- /dev/null
+++ b/sdks/react-native/ios/MossModule.swift
@@ -0,0 +1,94 @@
+import ExpoModulesCore
+import MossC
+
+public class MossModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("Moss")
+
+    Constant("sdkVersion") {
+      String(cString: moss_sdk_version())
+    }
+
+    // Emitted when an authenticator-backed client needs a bearer token. The JS
+    // side answers with resolveAuthRequest / rejectAuthRequest.
+    Events("onMossAuthRequest")
+
+    AsyncFunction("setModelCacheDir") { (path: String) in
+      try MossClientSharedObject.setModelCacheDir(path)
+    }
+
+    AsyncFunction("resolveAuthRequest") { (requestId: Int, token: String) in
+      try MossClientSharedObject.resolveAuthRequest(
+        requestId: try MossClientSharedObject.authRequestId(requestId),
+        token: token
+      )
+    }
+
+    AsyncFunction("rejectAuthRequest") { (requestId: Int, message: String?) in
+      MossClientSharedObject.rejectAuthRequest(
+        requestId: try MossClientSharedObject.authRequestId(requestId),
+        message: message
+      )
+    }
+
+    Class("MossClient", MossClientSharedObject.self) {
+      Constructor { [weak self] (
+        projectId: String,
+        projectKey: String?,
+        useAuthenticator: Bool,
+        baseUrl: String?,
+        clientId: Int
+      ) -> MossClientSharedObject in
+        guard useAuthenticator else {
+          guard let projectKey, !projectKey.isEmpty else {
+            throw MossClientSharedObject.argumentError("projectKey is required")
+          }
+          return try MossClientSharedObject(projectId: projectId, projectKey: projectKey)
+        }
+        // Called from an arbitrary native thread; just hands the request to JS.
+        return try MossClientSharedObject(projectId: projectId, baseUrl: baseUrl) { requestId in
+          self?.sendEvent(
+            "onMossAuthRequest",
+            ["clientId": clientId, "requestId": Int(requestId)]
+          )
+        }
+      }
+
+      AsyncFunction("createIndex") { (client: MossClientSharedObject, name: String, docsJson: String, modelId: String?) -> [String: Any] in
+        try client.createIndex(name: name, docsJson: docsJson, modelId: modelId)
+      }
+
+      AsyncFunction("loadIndex") { (client: MossClientSharedObject, name: String, options: [String: Any]) in
+        try client.loadIndex(name: name, options: options)
+      }
+
+      AsyncFunction("unloadIndex") { (client: MossClientSharedObject, name: String) in
+        try client.unloadIndex(name: name)
+      }
+
+      AsyncFunction("query") { (client: MossClientSharedObject, name: String, query: String, options: [String: Any]) -> [String: Any] in
+        try client.query(name: name, query: query, options: options)
+      }
+
+      AsyncFunction("listIndexes") { (client: MossClientSharedObject) -> [[String: Any]] in
+        try client.listIndexes()
+      }
+
+      AsyncFunction("getIndex") { (client: MossClientSharedObject, name: String) -> [String: Any] in
+        try client.getIndex(name: name)
+      }
+
+      AsyncFunction("deleteIndex") { (client: MossClientSharedObject, name: String) -> Bool in
+        try client.deleteIndex(name: name)
+      }
+
+      AsyncFunction("addDocs") { (client: MossClientSharedObject, name: String, docsJson: String, upsert: Bool) -> [String: Any] in
+        try client.addDocs(name: name, docsJson: docsJson, upsert: upsert)
+      }
+
+      Function("close") { (client: MossClientSharedObject) in
+        client.close()
+      }
+    }
+  }
+}
diff --git a/sdks/react-native/ios/MossReactNative.podspec b/sdks/react-native/ios/MossReactNative.podspec
new file mode 100644
index 00000000..3164ee57
--- /dev/null
+++ b/sdks/react-native/ios/MossReactNative.podspec
@@ -0,0 +1,77 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+# Fetch Moss.xcframework now, while this podspec is being evaluated.
+#
+# It cannot be done from `prepare_command`: Expo/RN autolinking installs this
+# pod from node_modules as a *development* pod (`:path => ...`), and CocoaPods
+# only runs `prepare_command` for pods it downloads into `Pods/` — development
+# pods skip it entirely. The npm tarball also excludes `ios/Frameworks/` (see
+# .npmignore) to keep the package small, so nothing would have created the
+# directory that `vendored_frameworks` points at.
+#
+# Podspec evaluation happens before CocoaPods resolves `vendored_frameworks`,
+# which makes this the earliest hook that runs on every install path. The
+# script is a no-op once the framework is present, so repeat `pod install`s
+# do not re-download.
+download_script = File.join(__dir__, 'scripts', 'download-moss-xcframework.sh')
+unless system('bash', download_script)
+  raise <<~MSG
+    [MossReactNative] Could not fetch Moss.xcframework.
+
+    Tried: bash #{download_script}
+
+    This needs network access on the first `pod install`. To use a locally
+    built binary instead, place it at #{File.join(__dir__, 'Frameworks', 'Moss.xcframework')}
+    and re-run `pod install` — the script skips the download when it exists.
+  MSG
+end
+
+Pod::Spec.new do |s|
+  s.name           = 'MossReactNative'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '16.4' }
+  s.swift_version  = '5.9'
+  s.source         = { git: 'https://github.com/usemoss/moss.git' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  # System frameworks used by libmoss (see examples/c + Swift SDK)
+  s.frameworks = 'Security', 'SystemConfiguration', 'UIKit'
+
+  # NB: no `prepare_command` — see the download block above for why it cannot
+  # be relied on here. By this point Frameworks/Moss.xcframework exists.
+  s.vendored_frameworks = 'Frameworks/Moss.xcframework'
+  s.preserve_paths = [
+    'Frameworks/Moss.xcframework',
+    'scripts',
+  ]
+
+  # Keep Frameworks/ out of the source glob (Expo third-party library guidance)
+  s.source_files = '*.{h,m,mm,swift}'
+
+  xc_headers = '"${PODS_XCFRAMEWORKS_BUILD_DIR}/MossReactNative/Headers"'
+  xc_libdir  = '"${PODS_XCFRAMEWORKS_BUILD_DIR}/MossReactNative"'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'OTHER_SWIFT_FLAGS' => '$(inherited) -D EXPO_CONFIGURATION_$(CONFIGURATION:upper)',
+    # Make `import MossC` resolve the Headers/module.modulemap from the xcframework
+    'HEADER_SEARCH_PATHS' => "$(inherited) #{xc_headers}",
+    'SWIFT_INCLUDE_PATHS' => "$(inherited) #{xc_headers}",
+    'LIBRARY_SEARCH_PATHS' => "$(inherited) #{xc_libdir}",
+    # Simulator binary is arm64-only (Apple Silicon)
+    'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'x86_64',
+  }
+
+  s.user_target_xcconfig = {
+    'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'x86_64',
+  }
+end
diff --git a/sdks/react-native/ios/scripts/download-moss-xcframework.sh b/sdks/react-native/ios/scripts/download-moss-xcframework.sh
new file mode 100755
index 00000000..9058a83d
--- /dev/null
+++ b/sdks/react-native/ios/scripts/download-moss-xcframework.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Downloads Moss.xcframework (MossC) used by the Expo iOS module.
+# Invoked while MossReactNative.podspec is evaluated (not from prepare_command,
+# which CocoaPods skips for development pods) so the binary is not committed.
+# Idempotent: exits early when the framework is already in place.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+FRAMEWORKS_DIR="${ROOT_DIR}/Frameworks"
+XCFRAMEWORK="${FRAMEWORKS_DIR}/Moss.xcframework"
+VERSION="${MOSS_XCFRAMEWORK_VERSION:-v0.6.2}"
+URL="https://github.com/usemoss/moss/releases/download/${VERSION}/Moss.xcframework.zip"
+EXPECTED_SHA256="${MOSS_XCFRAMEWORK_SHA256:-db6bffcd27fec51ad275e27777f2037746a173c5c3e05f1b8d67981229b9e7d1}"
+
+if [[ -d "${XCFRAMEWORK}" ]]; then
+  echo "Moss.xcframework already present at ${XCFRAMEWORK}"
+  exit 0
+fi
+
+mkdir -p "${FRAMEWORKS_DIR}"
+TMP_ZIP="$(mktemp -t Moss.xcframework.XXXXXX.zip)"
+cleanup() { rm -f "${TMP_ZIP}"; }
+trap cleanup EXIT
+
+echo "Downloading Moss.xcframework ${VERSION}…"
+curl -fsSL -o "${TMP_ZIP}" "${URL}"
+
+ACTUAL_SHA256="$(shasum -a 256 "${TMP_ZIP}" | awk '{print $1}')"
+if [[ "${ACTUAL_SHA256}" != "${EXPECTED_SHA256}" ]]; then
+  echo "error: Moss.xcframework.zip checksum mismatch" >&2
+  echo "  expected: ${EXPECTED_SHA256}" >&2
+  echo "  actual:   ${ACTUAL_SHA256}" >&2
+  exit 1
+fi
+
+unzip -qo "${TMP_ZIP}" -d "${FRAMEWORKS_DIR}"
+if [[ ! -d "${XCFRAMEWORK}" ]]; then
+  echo "error: unzip did not produce ${XCFRAMEWORK}" >&2
+  exit 1
+fi
+
+echo "Installed Moss.xcframework → ${XCFRAMEWORK}"
diff --git a/sdks/react-native/package.json b/sdks/react-native/package.json
new file mode 100644
index 00000000..de340618
--- /dev/null
+++ b/sdks/react-native/package.json
@@ -0,0 +1,60 @@
+{
+  "name": "@moss-dev/moss-react-native",
+  "version": "0.1.0",
+  "description": "React Native and Expo module for on-device Moss semantic search",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf build",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "moss",
+    "usemoss",
+    "semantic-search",
+    "react-native",
+    "expo",
+    "embeddings",
+    "vector-search"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usemoss/moss.git",
+    "directory": "sdks/react-native"
+  },
+  "bugs": {
+    "url": "https://github.com/usemoss/moss/issues"
+  },
+  "author": "InferEdge Inc. <contact@moss.dev>",
+  "license": "BSD-2-Clause",
+  "homepage": "https://github.com/usemoss/moss/tree/main/sdks/react-native#readme",
+  "files": [
+    "build",
+    "ios/*.swift",
+    "ios/*.podspec",
+    "ios/scripts",
+    "android",
+    "app.plugin.js",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@expo/config-plugins": "^54.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "expo-modules-core": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    }
+  }
+}
diff --git a/sdks/react-native/src/MossClient.ts b/sdks/react-native/src/MossClient.ts
new file mode 100644
index 00000000..d7bc1148
--- /dev/null
+++ b/sdks/react-native/src/MossClient.ts
@@ -0,0 +1,402 @@
+import { SharedObject } from 'expo-modules-core';
+
+import MossModule from './MossModule';
+import type {
+  AuthTokenProvider,
+  CreateIndexOptions,
+  DocumentInfo,
+  IndexInfo,
+  LoadIndexOptions,
+  MutationOptions,
+  MossClientAuthOptions,
+  MutationResult,
+  QueryOptions,
+  SearchResult,
+} from './types';
+import { MossError } from './types';
+
+type NativeClient = SharedObject & {
+  createIndex(name: string, docsJson: string, modelId: string | null): Promise<MutationResult>;
+  loadIndex(name: string, options: Record<string, unknown>): Promise<void>;
+  unloadIndex(name: string): Promise<void>;
+  query(name: string, query: string, options: Record<string, unknown>): Promise<SearchResult>;
+  listIndexes(): Promise<IndexInfo[]>;
+  getIndex(name: string): Promise<IndexInfo>;
+  deleteIndex(name: string): Promise<boolean>;
+  addDocs(name: string, docsJson: string, upsert: boolean): Promise<MutationResult>;
+  close(): void;
+};
+
+declare class NativeMossClient extends SharedObject {
+  constructor(
+    projectId: string,
+    projectKey: string | null,
+    useAuthenticator: boolean,
+    baseUrl: string | null,
+    clientId: number,
+  );
+}
+
+const NativeMossClientCtor = (MossModule as { MossClient: typeof NativeMossClient }).MossClient;
+
+const DEFAULT_MODEL_ID = 'moss-minilm';
+
+type AuthNative = {
+  addListener(
+    name: string,
+    listener: (event: { clientId: number; requestId: number }) => void,
+  ): { remove(): void };
+  resolveAuthRequest(requestId: number, token: string): Promise<void>;
+  rejectAuthRequest(requestId: number, message: string | null): Promise<void>;
+};
+
+const authNative = MossModule as unknown as AuthNative;
+
+/** Token providers by client id, for clients constructed with an authenticator. */
+const authProviders = new Map<number, AuthTokenProvider>();
+let nextAuthClientId = 1;
+let authSubscription: { remove(): void } | null = null;
+
+/**
+ * Answers a native auth request.
+ *
+ * Always responds, on every path: an unanswered request leaves the native call
+ * that triggered it waiting indefinitely, so a throwing or missing provider
+ * must still produce a rejection.
+ */
+async function handleAuthRequest(event: { clientId: number; requestId: number }): Promise<void> {
+  const reject = async (message: string) => {
+    try {
+      await authNative.rejectAuthRequest(event.requestId, message);
+    } catch {
+      // The request was already answered, or the client is gone.
+    }
+  };
+
+  const provider = authProviders.get(event.clientId);
+  if (!provider) {
+    await reject('MossClient was closed before an auth token could be provided');
+    return;
+  }
+  try {
+    const token = await provider();
+    if (typeof token !== 'string' || token.length === 0) {
+      await reject('getAuthToken must resolve to a non-empty string');
+      return;
+    }
+    await authNative.resolveAuthRequest(event.requestId, token);
+  } catch (err) {
+    await reject(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/** Subscribes once, on first authenticator-backed client. */
+function ensureAuthListener(): void {
+  if (authSubscription) return;
+  authSubscription = authNative.addListener('onMossAuthRequest', (event) => {
+    void handleAuthRequest(event);
+  });
+}
+
+/**
+ * On-device Moss client for React Native / Expo.
+ *
+ * iOS uses the native `Moss.xcframework` (same binary as the Swift SDK).
+ * Android support is tracked in https://github.com/usemoss/moss/issues/411 —
+ * constructing a client on Android throws until a native Android build ships.
+ *
+ * Requires a development build or Expo prebuild — custom native code does not
+ * run in Expo Go.
+ *
+ * @example
+ * ```ts
+ * import { MossClient } from '@moss-dev/moss-react-native';
+ *
+ * const client = new MossClient(projectId, projectKey);
+ * try {
+ *   await client.createIndex('docs', [
+ *     { id: '1', text: 'Refunds take 3-5 business days.' },
+ *   ]);
+ *   await client.loadIndex('docs');
+ *   const result = await client.query('docs', 'how long do refunds take?');
+ *   console.log(result.docs);
+ * } finally {
+ *   client.close();
+ * }
+ * ```
+ */
+export class MossClient {
+  readonly #native: NativeClient;
+  /** Non-zero only for authenticator-backed clients. */
+  readonly #authClientId: number;
+
+  /**
+   * Construct with a long-lived project key.
+   *
+   * Only suitable for development and internal builds — the key ends up in the
+   * shipped JS bundle. Use the authenticator form for production.
+   */
+  constructor(projectId: string, projectKey: string);
+  /**
+   * Construct with a token callback, so no long-lived secret is embedded in
+   * the app. `getAuthToken` is invoked whenever the native runtime needs a
+   * bearer token and should fetch a short-lived one from your backend.
+   */
+  constructor(init: MossClientAuthOptions);
+  constructor(projectIdOrInit: string | MossClientAuthOptions, projectKey?: string) {
+    if (typeof projectIdOrInit === 'string') {
+      if (!projectIdOrInit || !projectKey) {
+        throw new MossError(-2, 'projectId and projectKey are required');
+      }
+      this.#authClientId = 0;
+      try {
+        this.#native = new NativeMossClientCtor(
+          projectIdOrInit,
+          projectKey,
+          false,
+          null,
+          0,
+        ) as unknown as NativeClient;
+      } catch (err) {
+        throw wrapNativeError(err);
+      }
+      return;
+    }
+
+    const { projectId, getAuthToken, baseUrl } = projectIdOrInit;
+    if (!projectId) {
+      throw new MossError(-2, 'projectId is required');
+    }
+    if (typeof getAuthToken !== 'function') {
+      throw new MossError(-2, 'getAuthToken must be a function');
+    }
+
+    const clientId = nextAuthClientId++;
+    // Register before constructing: the native side may request a token as
+    // soon as the client exists.
+    authProviders.set(clientId, getAuthToken);
+    ensureAuthListener();
+    this.#authClientId = clientId;
+    try {
+      this.#native = new NativeMossClientCtor(
+        projectId,
+        null,
+        true,
+        baseUrl ?? null,
+        clientId,
+      ) as unknown as NativeClient;
+    } catch (err) {
+      authProviders.delete(clientId);
+      throw wrapNativeError(err);
+    }
+  }
+
+  /** Native SDK version string from `moss_sdk_version()`. */
+  static get sdkVersion(): string {
+    return String((MossModule as { sdkVersion?: string }).sdkVersion ?? 'unknown');
+  }
+
+  /**
+   * Override the embedding-model cache directory.
+   * Call before constructing any `MossClient` if you need a custom location
+   * (e.g. an App Group container). iOS defaults to Library/Caches/moss-models.
+   */
+  static async setModelCacheDir(path: string): Promise<void> {
+    try {
+      await (MossModule as { setModelCacheDir(path: string): Promise<void> }).setModelCacheDir(path);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  async createIndex(
+    indexName: string,
+    docs: DocumentInfo[],
+    options?: CreateIndexOptions,
+  ): Promise<MutationResult> {
+    const hasEmbeddings = docs.some((d) => Array.isArray(d.embedding) && d.embedding.length > 0);
+    const modelId = options?.modelId ?? (hasEmbeddings ? 'custom' : DEFAULT_MODEL_ID);
+    const docsJson = serializeDocs(docs);
+    try {
+      return await this.#native.createIndex(indexName, docsJson, modelId);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  async loadIndex(indexName: string, options?: LoadIndexOptions): Promise<void> {
+    try {
+      await this.#native.loadIndex(indexName, {
+        autoRefresh: options?.autoRefresh ?? false,
+        pollingIntervalSeconds: options?.pollingIntervalSeconds ?? 600,
+        cachePath: options?.cachePath ?? null,
+      });
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  async unloadIndex(indexName: string): Promise<void> {
+    try {
+      await this.#native.unloadIndex(indexName);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  /**
+   * Search a loaded index.
+   *
+   * Indexes built from custom document embeddings have no on-device model to
+   * embed `query` with — pass `options.embedding` with a matching query vector
+   * for those. Text-model indexes ignore it.
+   */
+  async query(indexName: string, query: string, options?: QueryOptions): Promise<SearchResult> {
+    const filterJson = resolveFilterJson(options);
+    try {
+      return await this.#native.query(indexName, query, {
+        topK: options?.topK ?? 5,
+        alpha: options?.alpha ?? 0.8,
+        filterJson,
+        embedding: options?.embedding ?? null,
+      });
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  async listIndexes(): Promise<IndexInfo[]> {
+    try {
+      return await this.#native.listIndexes();
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  async getIndex(indexName: string): Promise<IndexInfo> {
+    try {
+      return await this.#native.getIndex(indexName);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  async deleteIndex(indexName: string): Promise<boolean> {
+    try {
+      return await this.#native.deleteIndex(indexName);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  async addDocs(
+    indexName: string,
+    docs: DocumentInfo[],
+    options?: MutationOptions,
+  ): Promise<MutationResult> {
+    const docsJson = serializeDocs(docs);
+    try {
+      return await this.#native.addDocs(indexName, docsJson, options?.upsert ?? true);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  /** Release the native client. Safe to call more than once. */
+  close(): void {
+    if (this.#authClientId !== 0) {
+      authProviders.delete(this.#authClientId);
+    }
+    try {
+      this.#native.close();
+    } catch {
+      // already closed
+    }
+  }
+}
+
+/** Largest finite 32-bit float; the native side stores embeddings as `Float`. */
+const MAX_FLOAT32 = 3.4028234663852886e38;
+
+/**
+ * Serializes documents for the native layer.
+ *
+ * `JSON.stringify` turns `NaN` / `±Infinity` into `null`, so an embedding
+ * containing either would reach the engine silently corrupted rather than
+ * rejected. Values beyond the 32-bit float range are also refused, since the
+ * native side narrows to `Float` and would round them to infinity.
+ */
+function serializeDocs(docs: DocumentInfo[]): string {
+  if (!Array.isArray(docs)) {
+    throw new MossError(-2, 'docs must be an array');
+  }
+  for (const doc of docs) {
+    const embedding = doc?.embedding;
+    if (embedding === undefined) continue;
+    if (!Array.isArray(embedding)) {
+      throw new MossError(-2, `embedding for doc "${doc?.id}" must be an array of numbers`);
+    }
+    for (const value of embedding) {
+      if (typeof value !== 'number' || !Number.isFinite(value) || Math.abs(value) > MAX_FLOAT32) {
+        throw new MossError(
+          -2,
+          `embedding for doc "${doc?.id}" must contain only finite 32-bit-float values`,
+        );
+      }
+    }
+  }
+  try {
+    return JSON.stringify(docs);
+  } catch (err) {
+    throw new MossError(-2, `docs are not JSON-serializable: ${String(err)}`);
+  }
+}
+
+/**
+ * Resolves the metadata filter to the engine's JSON form.
+ *
+ * `filter` is the shape `@moss-dev/moss` uses, so callers migrating from the
+ * Node SDK reach for it first. Silently ignoring it would run the query
+ * unfiltered and return documents outside the intended scope, so an
+ * unserializable filter is an error rather than a fallback to `null`.
+ */
+function resolveFilterJson(options?: QueryOptions): string | null {
+  if (options?.filter !== undefined && options?.filterJson !== undefined) {
+    throw new MossError(-2, 'Pass either `filter` or `filterJson`, not both');
+  }
+  if (options?.filter !== undefined) {
+    let encoded: string;
+    try {
+      encoded = JSON.stringify(options.filter);
+    } catch (err) {
+      throw new MossError(-2, `filter is not JSON-serializable: ${String(err)}`);
+    }
+    if (typeof encoded !== 'string') {
+      throw new MossError(-2, 'filter is not JSON-serializable');
+    }
+    return encoded;
+  }
+  const filterJson = options?.filterJson;
+  if (filterJson === undefined || filterJson === null) {
+    return null;
+  }
+  // Plain-JS callers are not bound by the type. A non-string would arrive at
+  // the Swift side, fail its `as? String` cast, and silently run the query
+  // unfiltered — which for a tenant- or user-scoping filter means returning
+  // documents the caller never intended to expose.
+  if (typeof filterJson !== 'string') {
+    throw new MossError(-2, 'filterJson must be a string');
+  }
+  return filterJson;
+}
+
+function wrapNativeError(err: unknown): Error {
+  if (err instanceof MossError) return err;
+  if (err && typeof err === 'object') {
+    const e = err as { code?: number; message?: string };
+    const message = typeof e.message === 'string' ? e.message : String(err);
+    const code = typeof e.code === 'number' ? e.code : -1;
+    return new MossError(code, message);
+  }
+  return new MossError(-1, String(err));
+}
diff --git a/sdks/react-native/src/MossModule.ts b/sdks/react-native/src/MossModule.ts
new file mode 100644
index 00000000..41ec6f48
--- /dev/null
+++ b/sdks/react-native/src/MossModule.ts
@@ -0,0 +1,7 @@
+import { requireNativeModule } from 'expo-modules-core';
+
+/**
+ * Low-level Expo native module handle.
+ * Prefer the idiomatic {@link MossClient} wrapper exported from the package root.
+ */
+export default requireNativeModule('Moss');
diff --git a/sdks/react-native/src/index.ts b/sdks/react-native/src/index.ts
new file mode 100644
index 00000000..76bb839b
--- /dev/null
+++ b/sdks/react-native/src/index.ts
@@ -0,0 +1,17 @@
+export { MossClient } from './MossClient';
+export type {
+  AuthTokenProvider,
+  CreateIndexOptions,
+  DocumentInfo,
+  IndexInfo,
+  LoadIndexOptions,
+  ModelRef,
+  MossClientAuthOptions,
+  MossModel,
+  MutationOptions,
+  MutationResult,
+  QueryOptions,
+  QueryResultDocumentInfo,
+  SearchResult,
+} from './types';
+export { MossError } from './types';
diff --git a/sdks/react-native/src/types.ts b/sdks/react-native/src/types.ts
new file mode 100644
index 00000000..27c5ae30
--- /dev/null
+++ b/sdks/react-native/src/types.ts
@@ -0,0 +1,123 @@
+/**
+ * Shared types for the Moss React Native / Expo module.
+ * Mirrors the public surface of `@moss-dev/moss` closely enough that
+ * examples transfer across runtimes.
+ */
+
+export type MossModel = 'moss-minilm' | 'moss-mediumlm' | 'moss-litelm' | 'custom' | (string & {});
+
+export interface DocumentInfo {
+  id: string;
+  text: string;
+  metadata?: Record<string, string>;
+  embedding?: number[];
+  /** Opaque structured payload (e.g. JSON string). Not embedded or searched. */
+  payload?: string;
+}
+
+export interface QueryResultDocumentInfo {
+  id: string;
+  text: string;
+  score: number;
+  metadata?: Record<string, string>;
+  payload?: string;
+}
+
+export interface SearchResult {
+  docs: QueryResultDocumentInfo[];
+  query: string;
+  /** Wall-clock query time in milliseconds. */
+  timeMs: number;
+}
+
+export interface QueryOptions {
+  topK?: number;
+  /** Hybrid weight: 1.0 = dense only, 0.0 = sparse only. Default 0.8. */
+  alpha?: number;
+  /**
+   * Metadata filter, same shape as `@moss-dev/moss`:
+   * - Field: `{ field: 'city', condition: { $eq: 'NYC' } }`
+   * - And: `{ $and: [filter, filter, ...] }`
+   * - Or: `{ $or: [filter, filter, ...] }`
+   *
+   * Operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$near`.
+   */
+  filter?: Record<string, unknown>;
+  /**
+   * Pre-serialized metadata filter, for callers that already hold the engine's
+   * JSON form. Mutually exclusive with `filter`.
+   */
+  filterJson?: string;
+  /**
+   * Precomputed query vector. Required for indexes built from custom document
+   * embeddings (`modelId: 'custom'`), which have no on-device model to embed
+   * the query text with. Must match the index's dimensionality.
+   */
+  embedding?: number[];
+}
+
+export interface ModelRef {
+  id: string;
+  version?: string | null;
+}
+
+export interface IndexInfo {
+  id: string;
+  name: string;
+  status: string;
+  docCount: number;
+  model: ModelRef;
+  version?: string | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+}
+
+export interface MutationResult {
+  jobId: string;
+  indexName: string;
+  docCount: number;
+}
+
+export interface CreateIndexOptions {
+  modelId?: MossModel;
+}
+
+export interface LoadIndexOptions {
+  autoRefresh?: boolean;
+  /** Poll interval in seconds when `autoRefresh` is true. Default 600. */
+  pollingIntervalSeconds?: number;
+  /** Sandbox path used to cache the index on disk across launches. */
+  cachePath?: string;
+}
+
+export interface MutationOptions {
+  upsert?: boolean;
+}
+
+/**
+ * Supplies a short-lived bearer token.
+ *
+ * Return the raw token only — the native side builds the
+ * `Authorization: Bearer <token>` header itself, so do not include the
+ * `Bearer ` prefix. Called whenever the runtime needs a token, so cache until
+ * expiry on your side if the round trip is expensive.
+ */
+export type AuthTokenProvider = () => Promise<string> | string;
+
+/** Options for constructing a client that authenticates with short-lived tokens. */
+export interface MossClientAuthOptions {
+  projectId: string;
+  getAuthToken: AuthTokenProvider;
+  /** Override the cloud endpoint. Defaults to the standard Moss endpoint. */
+  baseUrl?: string;
+}
+
+export class MossError extends Error {
+  readonly code: number;
+
+  constructor(code: number, message: string) {
+    super(message);
+    this.name = 'MossError';
+    this.code = code;
+  }
+}
diff --git a/sdks/react-native/tsconfig.json b/sdks/react-native/tsconfig.json
new file mode 100644
index 00000000..a9adf0a6
--- /dev/null
+++ b/sdks/react-native/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "build",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "build", "android", "ios", "example"]
+}