react-native-facefusion 0.1.0

package/lib/typescript/src/probeDevice.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probeDevice.native.d.ts","sourceRoot":"","sources":["../../../src/probeDevice.native.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAoB,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAExD"}

package/lib/typescript/src/saveToGallery.d.ts

@@ -0,0 +1,2 @@
+export declare function saveToGallery(_path: string, _mimeType: string, _displayName?: string): Promise<string>;
+//# sourceMappingURL=saveToGallery.d.ts.map

package/lib/typescript/src/saveToGallery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saveToGallery.d.ts","sourceRoot":"","sources":["../../../src/saveToGallery.tsx"],"names":[],"mappings":"AAAA,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/lib/typescript/src/saveToGallery.native.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copies a `swapPhoto`/`swapVideo` output into the system's Photos/Gallery app, so it
+ * survives beyond this app's own private storage. Returns the resulting `content://` URI.
+ *
+ * `mimeType` must be `image/*` or `video/*` — pass the real one, there's no safe way to
+ * guess it from a path alone. No storage permission is needed on Android.
+ */
+export declare function saveToGallery(path: string, mimeType: string, displayName?: string): Promise<string>;
+//# sourceMappingURL=saveToGallery.native.d.ts.map

package/lib/typescript/src/saveToGallery.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saveToGallery.native.d.ts","sourceRoot":"","sources":["../../../src/saveToGallery.native.tsx"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAEjB"}

package/lib/typescript/src/swapPhoto.d.ts

@@ -0,0 +1,3 @@
+import type { SwapOptions, SwapPhotoResult } from './NativeFacefusion.js';
+export declare function swapPhoto(_sourcePath: string, _targetPath: string, _outputPath: string, _options?: SwapOptions): Promise<SwapPhotoResult>;
+//# sourceMappingURL=swapPhoto.d.ts.map

package/lib/typescript/src/swapPhoto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swapPhoto.d.ts","sourceRoot":"","sources":["../../../src/swapPhoto.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAoB,CAAC;AAEvE,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,eAAe,CAAC,CAI1B"}

package/lib/typescript/src/swapPhoto.native.d.ts

@@ -0,0 +1,12 @@
+import type { SwapOptions, SwapPhotoResult } from './NativeFacefusion.js';
+/**
+ * Swaps the face from `sourcePath` into every face found in `targetPath`, writing the
+ * result to `outputPath`.
+ *
+ * Both images are decoded and re-encoded natively — nothing but paths and options crosses
+ * the JS bridge. Rejects with `E_BUSY` if another swap (or, from Phase 7, a video job) is
+ * already running, `E_MODELS` if the required models are not downloaded yet, and `E_SWAP`
+ * for anything else, naming what failed.
+ */
+export declare function swapPhoto(sourcePath: string, targetPath: string, outputPath: string, options?: SwapOptions): Promise<SwapPhotoResult>;
+//# sourceMappingURL=swapPhoto.native.d.ts.map

package/lib/typescript/src/swapPhoto.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swapPhoto.native.d.ts","sourceRoot":"","sources":["../../../src/swapPhoto.native.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAoB,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/lib/typescript/src/swapVideo.d.ts

@@ -0,0 +1,6 @@
+import type { EventSubscription } from 'react-native';
+import type { SwapOptions, SwapVideoResult, VideoSwapProgress } from './NativeFacefusion.js';
+export declare function swapVideo(_sourcePath: string, _targetPath: string, _outputPath: string, _options?: SwapOptions): Promise<SwapVideoResult>;
+export declare function cancelVideoSwap(): void;
+export declare function onVideoSwapProgress(_listener: (progress: VideoSwapProgress) => void): EventSubscription;
+//# sourceMappingURL=swapVideo.d.ts.map

package/lib/typescript/src/swapVideo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swapVideo.d.ts","sourceRoot":"","sources":["../../../src/swapVideo.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EAClB,MAAM,uBAAoB,CAAC;AAE5B,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,eAAe,CAAC,CAI1B;AAED,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,GAC/C,iBAAiB,CAInB"}

package/lib/typescript/src/swapVideo.native.d.ts

@@ -0,0 +1,20 @@
+import type { EventSubscription } from 'react-native';
+import type { SwapOptions, SwapVideoResult, VideoSwapProgress } from './NativeFacefusion.js';
+/**
+ * Swaps the face from `sourcePath` into every frame of the video at `targetPath`, writing
+ * the result to `outputPath`.
+ *
+ * Runs behind a foreground service — Android kills a plain background process partway
+ * through a job this long. Rejects with `E_BUSY` if a photo or another video swap is
+ * already running, `E_MODELS` if the required models are not downloaded yet, `E_CANCELLED`
+ * if `cancelVideoSwap()` was called, and `E_SWAP` for anything else, naming what failed.
+ */
+export declare function swapVideo(sourcePath: string, targetPath: string, outputPath: string, options?: SwapOptions): Promise<SwapVideoResult>;
+/** Asks the video swap in flight to stop. Fire-and-forget — see `swapVideo`'s doc. */
+export declare function cancelVideoSwap(): void;
+/**
+ * Subscribe to video swap progress. Returns the subscription — call `.remove()` on
+ * unmount.
+ */
+export declare function onVideoSwapProgress(listener: (progress: VideoSwapProgress) => void): EventSubscription;
+//# sourceMappingURL=swapVideo.native.d.ts.map

package/lib/typescript/src/swapVideo.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swapVideo.native.d.ts","sourceRoot":"","sources":["../../../src/swapVideo.native.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EAClB,MAAM,uBAAoB,CAAC;AAE5B;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED,sFAAsF;AACtF,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,GAC9C,iBAAiB,CAEnB"}

package/package.json

@@ -0,0 +1,132 @@
+{
+  "name": "react-native-facefusion",
+  "version": "0.1.0",
+  "description": "React Native TurboModule for on-device face swapping on Qualcomm Hexagon NPUs. Runs fully offline on the phone, no server and no uploads.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-facefusion-source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "scripts/fetch-upstream.sh",
+    "scripts/check-tarball.sh",
+    "patches",
+    "third_party/facefusion-mobile/NOTICE",
+    "!android/src/main/jniLibs",
+    "!android/src/main/cpp/include/QNN",
+    "!third_party/facefusion-mobile/cpp",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "npm run --workspace=example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "prepublishOnly": "./scripts/check-tarball.sh"
+  },
+  "keywords": [
+    "react-native",
+    "android",
+    "face-swap",
+    "npu",
+    "qualcomm",
+    "on-device-ml"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shipitsaad/facefusion-rn.git"
+  },
+  "author": "Saad <saad.saad737@gmail.com> (https://github.com/shipitsaad)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/shipitsaad/facefusion-rn/issues"
+  },
+  "homepage": "https://github.com/shipitsaad/facefusion-rn#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^9.39.5",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "prettier": "^3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.43.0",
+    "turbo": "^2.9.16",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "FacefusionSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.facefusion"
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint"
+    ],
+    "version": "0.63.0"
+  }
+}

package/patches/ffjni-analyse-faces.patch

@@ -0,0 +1,63 @@
+--- ffjni.cpp
++++ ffjni.cpp
+@@ -236,6 +236,60 @@
+   if (!faces.empty())
+     env->SetByteArrayRegion(jBgr, 0, (jsize)img.data.size(), (const jbyte*)img.data.data());
+   return (jint)faces.size();
++}
++
++// Ours, not upstream's -- see third_party/facefusion-mobile/NOTICE and
++// docs/02-upstream.md "Patches". Applied by scripts/fetch-upstream.sh from
++// patches/ffjni-analyse-faces.patch after every re-sync.
++//
++// Detects every face in an image without swapping: box + confidence only, no
++// embeddings.  Reuses the already-public Pipeline::analyse() and the already-warm
++// g_pipe -- no new pipeline state, no change to any existing function.  Lets a
++// caller with a multi-face source photo see what's in it before deciding which one
++// becomes the identity; the caller commits a choice by cropping to that face's box
++// and calling the existing, unmodified setSource() on the crop, not by any new
++// entry point here.
++JNIEXPORT jfloatArray JNICALL
++Java_com_facefusion_mobile_NativePipe_analyseFaces(JNIEnv* env, jclass, jbyteArray jBgr,
++                                                   jint w, jint h) {
++  if (!g_pipe) { g_err = "pipeline not initialised"; return nullptr; }
++  ffcv::Image img(w, h, 3);
++  if ((size_t)env->GetArrayLength(jBgr) != img.data.size()) {
++    g_err = "analyseFaces: frame is not w*h*3 bytes";
++    return nullptr;
++  }
++  env->GetByteArrayRegion(jBgr, 0, (jsize)img.data.size(), (jbyte*)img.data.data());
++
++  // A detector graph that FAILED TO EXECUTE and a frame with genuinely no face both
++  // come back as an empty vector.  Pipeline::setSource carries a comment saying exactly
++  // that -- "reporting the second when it was the first sends the next hour in the wrong
++  // place" -- and the first version of this export ignored it, returning an empty array
++  // either way.  A real detector failure therefore reached the user as "no faces found",
++  // with nothing in logcat, which is precisely what happened on a v69 phone on
++  // 2026-09-14 and cost a remote debugging round trip.
++  //
++  // analyse() does not clear error() on entry, so a non-empty string is not on its own
++  // proof that THIS call failed; compare against what was already there.
++  const std::string errBefore = g_pipe->error();
++  auto faces = g_pipe->analyse(img);
++  const std::string& errAfter = g_pipe->error();
++  if (faces.empty() && !errAfter.empty() && errAfter != errBefore) {
++    g_err = errAfter;
++    return nullptr;
++  }
++
++  std::vector<float> out;
++  out.reserve(faces.size() * 5);
++  for (auto& f : faces) {
++    out.push_back(f.box[0]);
++    out.push_back(f.box[1]);
++    out.push_back(f.box[2]);
++    out.push_back(f.box[3]);
++    out.push_back(f.detScore);
++  }
++  jfloatArray arr = env->NewFloatArray((jsize)out.size());
++  env->SetFloatArrayRegion(arr, 0, (jsize)out.size(), out.data());
++  return arr;
+ }
+ 
+ /** Bitmap ARGB_8888 ints -> packed BGR bytes. */

package/scripts/check-tarball.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# Refuses to publish a tarball containing Qualcomm's QAIRT runtime, its proprietary
+# headers, upstream's unlicensed C++, or a model binary.
+#
+# This runs as `prepublishOnly`, ON THE PUBLISHING MACHINE, and that placement is the
+# whole point. CI has a step that greps the packed tarball too -- but a CI checkout
+# cannot contain any of these files in the first place (they are gitignored and fetched
+# separately), so the grep there passes trivially and proves nothing. The only machine
+# where the bytes actually exist is a developer's, which is the only machine that ever
+# runs `npm publish`. A guard that cannot fire where the risk lives is decoration.
+#
+# See docs/05-licensing.md: redistribution of the QAIRT runtime is permitted only "as
+# incorporated in Your software application", never "on a standalone basis" -- an APK
+# may ship it, an npm package may not.
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+echo "prepublish: auditing the tarball..."
+
+# Build the real tarball and read it with tar, rather than parsing `npm pack --json`:
+# `npm pack` re-runs `prepare` (bob build), which prints lines like
+# "[typescript] Cleaning up previous build" to STDOUT, ahead of the JSON. Any attempt to
+# slice the JSON out of that stream picks up bob's bracket instead of the array's.
+# The bytes on disk are the thing being audited anyway.
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+npm pack --pack-destination "$tmp" >/dev/null 2>&1
+tgz="$(ls "$tmp"/*.tgz 2>/dev/null | head -1)"
+if [ -z "$tgz" ]; then
+  echo "prepublish: npm pack produced no tarball" >&2
+  exit 1
+fi
+files="$(tar -tzf "$tgz" | sed 's|^package/||' | grep -v '/$')"
+
+banned="$(printf '%s\n' "$files" | grep -Ei 'libQnn|\.so$|\.bin$|include/QNN/|hexagon|third_party/facefusion-mobile/cpp/' || true)"
+if [ -n "$banned" ]; then
+  echo >&2
+  echo "PUBLISH BLOCKED -- the tarball contains files that must never be redistributed:" >&2
+  printf '  %s\n' $banned >&2
+  echo >&2
+  echo "See docs/05-licensing.md. Check the \"files\" array in package.json:" >&2
+  echo "npm's files list OVERRIDES .gitignore, so being gitignored is not protection." >&2
+  exit 1
+fi
+
+# Clean is not enough; it also has to be complete. These are what the README's install
+# steps and the build actually need -- all four were missing once, which made the
+# published package impossible to install.
+required=(
+  package.json README.md LICENSE
+  scripts/fetch-upstream.sh
+  patches/ffjni-analyse-faces.patch
+  third_party/facefusion-mobile/NOTICE
+  lib/module/index.js
+  lib/typescript/src/index.d.ts
+  android/build.gradle
+  android/src/main/AndroidManifest.xml
+  android/src/main/cpp/CMakeLists.txt
+)
+missing=0
+for f in "${required[@]}"; do
+  printf '%s\n' "$files" | grep -qxF "$f" || { echo "PUBLISH BLOCKED -- missing: $f" >&2; missing=1; }
+done
+[ "$missing" -eq 0 ] || exit 1
+
+echo "prepublish: OK -- $(printf '%s\n' "$files" | wc -l | tr -d ' ') files, nothing proprietary, nothing missing."

package/scripts/fetch-upstream.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+#
+# Places the upstream C++ engine into third_party/facefusion-mobile/cpp/.
+#
+# The files are NOT in this repository: upstream ships no LICENSE, so redistributing
+# them is not permitted (docs/05-licensing.md §1). Cloning their public repo yourself
+# is, which is all this script does.
+#
+# Pinned to a commit on purpose. Upstream moves daily, and a re-sync must be a
+# deliberate act with a diff review, not something a build silently picks up.
+set -euo pipefail
+
+REPO="https://github.com/AbrahamPaulJ/facefusion-mobile.git"
+COMMIT="bf633acee030772deb2f2068866c0c0a17de24ba"
+SRC_SUBDIR="work/android/app/src/main/cpp"
+FILES=(ffjni.cpp ffpipe.cpp ffpipe.h ffcv.cpp ffcv.h ffqnn.cpp ffqnn.h)
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DEST="$ROOT/third_party/facefusion-mobile/cpp"
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+echo "Cloning $REPO @ ${COMMIT:0:7} ..."
+git init -q "$TMP"
+git -C "$TMP" remote add origin "$REPO"
+git -C "$TMP" fetch -q --depth 1 origin "$COMMIT"
+git -C "$TMP" checkout -q FETCH_HEAD
+
+mkdir -p "$DEST"
+for f in "${FILES[@]}"; do
+  cp "$TMP/$SRC_SUBDIR/$f" "$DEST/$f"
+  echo "  $f"
+done
+
+# Verify against NOTICE, and FAIL on a mismatch. This used to print the hashes and tell
+# the reader to compare them by eye, while the comment below claimed a check had happened
+# -- a promise the script did not keep, found by installing the npm tarball into a clean
+# app and reading what actually ran. A check nobody performs is not a check.
+NOTICE="$ROOT/third_party/facefusion-mobile/NOTICE"
+echo
+if ! command -v shasum >/dev/null; then
+  echo "WARNING: shasum not found -- cannot verify the fetch against NOTICE." >&2
+elif [ ! -f "$NOTICE" ]; then
+  echo "WARNING: $NOTICE is missing -- cannot verify the fetch." >&2
+else
+  echo "Verifying against third_party/facefusion-mobile/NOTICE ..."
+  fail=0
+  for f in "${FILES[@]}"; do
+    got="$(shasum -a 256 "$DEST/$f" | cut -d' ' -f1)"
+    # NOTICE records each hash in a markdown table row naming the file: `cpp/ffjni.cpp`.
+    want="$(grep -F "cpp/$f\`" "$NOTICE" | grep -oE '[0-9a-f]{64}' | head -1)"
+    if [ -z "$want" ]; then
+      echo "  ?? $f -- no hash recorded in NOTICE" >&2; fail=1
+    elif [ "$got" != "$want" ]; then
+      echo "  !! $f -- MISMATCH" >&2
+      echo "       expected $want" >&2
+      echo "       got      $got" >&2
+      fail=1
+    else
+      echo "  ok $f"
+    fi
+  done
+  if [ "$fail" -ne 0 ]; then
+    echo >&2
+    echo "Upstream bytes do not match NOTICE. Refusing to patch or continue: a patch" >&2
+    echo "applied to unexpected sources would mask exactly this. If upstream moved on" >&2
+    echo "purpose, re-pin COMMIT and update NOTICE deliberately, with a diff review." >&2
+    exit 1
+  fi
+fi
+
+# Patches, applied AFTER the hash check above -- that check verifies we got upstream's
+# actual, unmodified bytes; patching is a separate, deliberate step on top of a known-
+# good base, not something that should ever be allowed to mask a bad fetch.
+#
+# One patch exists today: patches/ffjni-analyse-faces.patch adds a single new JNI
+# export to ffjni.cpp (Java_com_facefusion_mobile_NativePipe_analyseFaces) so a
+# multi-face source photo can be shown to the user before a swap picks one. It changes
+# no existing function. See docs/02-upstream.md "Patches" and NOTICE for why this is
+# tracked here instead of edited in place: this script overwrites cpp/ from upstream
+# every time it runs, so an in-place edit would not survive a re-fetch.
+PATCH_DIR="$ROOT/patches"
+if [ -d "$PATCH_DIR" ] && [ -n "$(ls -A "$PATCH_DIR"/*.patch 2>/dev/null)" ]; then
+  echo
+  echo "Applying patches..."
+  for p in "$PATCH_DIR"/*.patch; do
+    echo "  $(basename "$p")"
+    patch "$DEST/ffjni.cpp" < "$p"
+  done
+fi

package/src/FacefusionPreview.native.tsx

@@ -0,0 +1,18 @@
+import { requireNativeComponent } from 'react-native';
+import type { ViewProps } from 'react-native';
+
+export type FacefusionPreviewProps = ViewProps;
+
+/**
+ * A live view of the frame [swapPhoto]/[swapVideo] just produced — the result the instant
+ * it's ready for a photo, and one frame at a time while a video swap is running.
+ *
+ * No prop carries pixels and none of this crosses the JS bridge: the native side
+ * (`PreviewSurfaceHolder.kt`) draws straight into this view's own `Surface` from whichever
+ * swap is running. Mount it, give it a size with `style`, and it shows whatever the native
+ * layer is currently drawing — there is nothing else to wire up. At most one swap runs at a
+ * time (`PipeGuard`), so at most one `<FacefusionPreview />` needs to be mounted to see it.
+ */
+export const FacefusionPreview = requireNativeComponent<FacefusionPreviewProps>(
+  'FacefusionPreviewView'
+);

package/src/FacefusionPreview.tsx

@@ -0,0 +1,9 @@
+import type { ViewProps } from 'react-native';
+
+export type FacefusionPreviewProps = ViewProps;
+
+export function FacefusionPreview(_props: FacefusionPreviewProps): never {
+  throw new Error(
+    "'react-native-facefusion' is only supported on native platforms."
+  );
+}