react-native-image-stitcher 0.9.0 → 0.10.0

package/cpp/tests/stitcher_frame_data_test.cpp

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_frame_data_test.cpp — v0.10.0 audit #9A
+//
+// Sanity coverage for the `StitcherFrameData` POD payload + the
+// `PixelBufferReader` interface contract.  The shared C++
+// `StitcherFrameData` is constructed by both the iOS Obj-C++ side
+// (`StitcherFrameHostObject.mm`) and the Android JNI side
+// (`stitcher_frame_jni.cpp`); these tests pin the default-construction
+// invariants both sides depend on (e.g. `hasTranslation=false`,
+// `qw=1.0`).
+//
+// The `PixelBufferReader` tests use a fake-buffer implementation
+// (`FakePixelBufferReader`) to validate the `copyTo` clipping
+// behaviour the docstring promises.
+
+#include "stitcher_frame_data.hpp"
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <vector>
+
+using retailens::PixelBufferReader;
+using retailens::StitcherFrameData;
+
+namespace {
+
+/// Minimal fake reader — backs a fixed byte vector.  Used by the
+/// `PixelBufferReader` contract tests below to verify
+/// `copyTo` clips at the smaller of (maxBytes, byteSize).
+class FakePixelBufferReader : public PixelBufferReader {
+ public:
+  explicit FakePixelBufferReader(std::vector<uint8_t> bytes)
+      : _bytes(std::move(bytes)) {}
+
+  std::size_t byteSize() const override { return _bytes.size(); }
+
+  std::size_t copyTo(uint8_t* dst, std::size_t maxBytes) override {
+    const std::size_t n =
+        maxBytes < _bytes.size() ? maxBytes : _bytes.size();
+    std::memcpy(dst, _bytes.data(), n);
+    return n;
+  }
+
+ private:
+  std::vector<uint8_t> _bytes;
+};
+
+}  // namespace
+
+// ─── StitcherFrameData default-construction invariants ─────────────
+
+TEST(StitcherFrameDataTest, DefaultsAreSafeForJSIDispatch) {
+  // The JSI host object's `get()` dispatch keys off these defaults to
+  // expose `undefined` for unset fields.  In particular:
+  //   - `hasTranslation == false`  →  pose.translation === undefined
+  //   - `arTrackingState.empty()`  →  arTrackingState === undefined
+  //   - `qw == 1.0` with rest zero →  identity rotation (safe default
+  //     for non-AR mode where rotation is unknown)
+  StitcherFrameData d;
+  EXPECT_EQ(d.width, 0);
+  EXPECT_EQ(d.height, 0);
+  EXPECT_TRUE(d.source.empty());
+  EXPECT_TRUE(d.pixelFormat.empty());
+  EXPECT_TRUE(d.orientation.empty());
+  EXPECT_DOUBLE_EQ(d.timestampNs, 0.0);
+  EXPECT_DOUBLE_EQ(d.qx, 0.0);
+  EXPECT_DOUBLE_EQ(d.qy, 0.0);
+  EXPECT_DOUBLE_EQ(d.qz, 0.0);
+  EXPECT_DOUBLE_EQ(d.qw, 1.0);  // identity rotation
+  EXPECT_DOUBLE_EQ(d.tx, 0.0);
+  EXPECT_DOUBLE_EQ(d.ty, 0.0);
+  EXPECT_DOUBLE_EQ(d.tz, 0.0);
+  EXPECT_FALSE(d.hasTranslation);
+  EXPECT_TRUE(d.arTrackingState.empty());
+  EXPECT_EQ(d.pixelReader, nullptr);
+}
+
+TEST(StitcherFrameDataTest, IsCopyable) {
+  // `StitcherFrameData` is documented as "value-typed (cheap to copy;
+  // ~100 bytes)".  Copy needs to deep-copy the strings + bump the
+  // pixelReader shared_ptr refcount.
+  StitcherFrameData a;
+  a.source = "ar";
+  a.width = 1920;
+  a.height = 1080;
+  a.pixelReader = std::make_shared<FakePixelBufferReader>(
+      std::vector<uint8_t>{1, 2, 3});
+
+  StitcherFrameData b = a;
+  EXPECT_EQ(b.source, "ar");
+  EXPECT_EQ(b.width, 1920);
+  EXPECT_EQ(b.height, 1080);
+  ASSERT_NE(b.pixelReader, nullptr);
+  EXPECT_EQ(b.pixelReader.use_count(), 2);  // both a and b hold a ref
+  EXPECT_EQ(b.pixelReader->byteSize(), 3u);
+}
+
+// ─── PixelBufferReader contract ────────────────────────────────────
+
+TEST(PixelBufferReaderTest, CopyToReturnsAllBytesWhenMaxBytesExceedsSize) {
+  FakePixelBufferReader reader({0x11, 0x22, 0x33});
+  uint8_t buf[8] = {0};
+  const std::size_t written = reader.copyTo(buf, sizeof(buf));
+  EXPECT_EQ(written, 3u);
+  EXPECT_EQ(buf[0], 0x11);
+  EXPECT_EQ(buf[1], 0x22);
+  EXPECT_EQ(buf[2], 0x33);
+  EXPECT_EQ(buf[3], 0u);  // untouched tail
+}
+
+TEST(PixelBufferReaderTest, CopyToClipsWhenMaxBytesIsSmaller) {
+  // Contract per stitcher_frame_data.hpp: "Implementations MUST handle
+  // the case where maxBytes < byteSize() (clip silently)."
+  FakePixelBufferReader reader({0xAA, 0xBB, 0xCC, 0xDD});
+  uint8_t buf[2] = {0};
+  const std::size_t written = reader.copyTo(buf, sizeof(buf));
+  EXPECT_EQ(written, 2u);
+  EXPECT_EQ(buf[0], 0xAA);
+  EXPECT_EQ(buf[1], 0xBB);
+}
+
+TEST(PixelBufferReaderTest, CopyToWithZeroMaxBytesReturnsZero) {
+  FakePixelBufferReader reader({0x01, 0x02, 0x03});
+  uint8_t dummy = 0xFF;
+  const std::size_t written = reader.copyTo(&dummy, 0);
+  EXPECT_EQ(written, 0u);
+  EXPECT_EQ(dummy, 0xFF);  // dst untouched when maxBytes == 0
+}

package/cpp/tests/stitcher_worklet_registry_test.cpp

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_worklet_registry_test.cpp — v0.10.0 audit #9A
+//
+// Lifecycle + concurrency coverage for the process-scope native
+// `StitcherWorkletRegistry` introduced in v0.8.0 Phase 4b.  See
+// `cpp/stitcher_worklet_registry.hpp` for the public contract.
+//
+// The registry's production `install(runtime, workletValue)` path
+// constructs an `RNWorklet::WorkletInvoker` from a JSI `Runtime` and
+// `Value`.  Standing up a real worklets-core runtime under gtest would
+// pull in Hermes + JSI + the whole worklets-core library — too heavy
+// for these scope-limited storage tests.  Instead we exercise the
+// equivalent `_installEntryForTests(invoker)` test seam (mirrors
+// `_resetForTests` in pattern) with `nullptr` invokers.  The registry
+// never dereferences the pointer — it only stores the shared_ptr and
+// hands it back via `snapshot` — so nullptr is safe.
+//
+// What this covers (lifting from the production `install`/`uninstall`/
+// `snapshot`/`count` contract):
+//   - shared() returns the same instance across calls
+//   - count/snapshot start empty after _resetForTests
+//   - install assigns monotonically increasing host-N IDs
+//   - count tracks installs / uninstalls
+//   - uninstall of an unknown ID is a no-op (matches JS side)
+//   - snapshot returns an independent copy (mutations after snapshot
+//     don't affect the snapshot's view)
+//   - concurrent installs from many threads serialise correctly and
+//     yield unique IDs (no double-issue under contention)
+
+#include "stitcher_worklet_registry.hpp"
+#include <react-native-worklets-core/WKTJsiWorklet.h>
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <set>
+#include <string>
+#include <thread>
+#include <vector>
+
+using retailens::StitcherWorkletEntry;
+using retailens::StitcherWorkletRegistry;
+
+namespace {
+
+/// Test fixture — resets the singleton before each test so cases
+/// don't leak state into each other.  Without this every test would
+/// see the cumulative entries from prior tests in the run.
+class StitcherWorkletRegistryTest : public ::testing::Test {
+ protected:
+  void SetUp() override {
+    StitcherWorkletRegistry::shared()._resetForTests();
+  }
+  void TearDown() override {
+    StitcherWorkletRegistry::shared()._resetForTests();
+  }
+};
+
+}  // namespace
+
+TEST_F(StitcherWorkletRegistryTest, SharedReturnsSameInstance) {
+  // The singleton invariant is load-bearing for the JS-side mental
+  // model: `useFrameProcessor` mounts on one component and unmounts
+  // from another but the registry stays.
+  StitcherWorkletRegistry& a = StitcherWorkletRegistry::shared();
+  StitcherWorkletRegistry& b = StitcherWorkletRegistry::shared();
+  EXPECT_EQ(&a, &b);
+}
+
+TEST_F(StitcherWorkletRegistryTest, StartsEmptyAfterReset) {
+  auto& r = StitcherWorkletRegistry::shared();
+  EXPECT_EQ(r.count(), 0u);
+  EXPECT_TRUE(r.snapshot().empty());
+}
+
+TEST_F(StitcherWorkletRegistryTest, InstallAssignsHostPrefixedIncrementingIds) {
+  auto& r = StitcherWorkletRegistry::shared();
+  const std::string id0 = r._installEntryForTests(nullptr);
+  const std::string id1 = r._installEntryForTests(nullptr);
+  const std::string id2 = r._installEntryForTests(nullptr);
+
+  // IDs are "host-N" with N monotonically increasing from 0 after a
+  // reset.  The format is part of the public contract — uninstall
+  // callers store these IDs verbatim.
+  EXPECT_EQ(id0, "host-0");
+  EXPECT_EQ(id1, "host-1");
+  EXPECT_EQ(id2, "host-2");
+  EXPECT_EQ(r.count(), 3u);
+}
+
+TEST_F(StitcherWorkletRegistryTest, UninstallRemovesByIdAndUpdatesCount) {
+  auto& r = StitcherWorkletRegistry::shared();
+  const std::string id0 = r._installEntryForTests(nullptr);
+  const std::string id1 = r._installEntryForTests(nullptr);
+  const std::string id2 = r._installEntryForTests(nullptr);
+  EXPECT_EQ(r.count(), 3u);
+
+  r.uninstall(id1);  // remove the middle entry
+  EXPECT_EQ(r.count(), 2u);
+
+  // Snapshot should contain only id0 and id2, in some order — the
+  // contract doesn't promise insertion order survives uninstall
+  // (the erase-remove pattern is stable in practice but we don't
+  // pin that publicly).
+  const auto snap = r.snapshot();
+  std::vector<std::string> remainingIds;
+  remainingIds.reserve(snap.size());
+  for (const auto& entry : snap) {
+    remainingIds.push_back(entry.id);
+  }
+  std::sort(remainingIds.begin(), remainingIds.end());
+  EXPECT_EQ(remainingIds, (std::vector<std::string>{id0, id2}));
+}
+
+TEST_F(StitcherWorkletRegistryTest, UninstallOfUnknownIdIsNoop) {
+  // Matches the JS-side `StitcherWorkletRegistry.uninstall` semantics
+  // (idempotent, no throw on unknown).  Critical because the JS
+  // useEffect cleanup can fire after an unmount/remount race where the
+  // ID has already been removed.
+  auto& r = StitcherWorkletRegistry::shared();
+  r._installEntryForTests(nullptr);
+  EXPECT_EQ(r.count(), 1u);
+  EXPECT_NO_THROW(r.uninstall("host-does-not-exist"));
+  EXPECT_NO_THROW(r.uninstall(""));
+  EXPECT_EQ(r.count(), 1u);  // existing entry untouched
+}
+
+TEST_F(StitcherWorkletRegistryTest, SnapshotIsIndependentOfFutureMutations) {
+  // Per header docstring: "mutations against the registry after
+  // `snapshot` returns do not affect the snapshot."  This matters for
+  // the AR-session dispatch path, which snapshots and then iterates
+  // without holding the registry lock — concurrent uninstall on the
+  // JS thread must NOT invalidate the snapshot.
+  auto& r = StitcherWorkletRegistry::shared();
+  const std::string id0 = r._installEntryForTests(nullptr);
+  const std::string id1 = r._installEntryForTests(nullptr);
+
+  const auto snap = r.snapshot();
+  ASSERT_EQ(snap.size(), 2u);
+
+  r.uninstall(id0);
+  r.uninstall(id1);
+  EXPECT_EQ(r.count(), 0u);
+
+  // Snapshot still has both entries.
+  EXPECT_EQ(snap.size(), 2u);
+  EXPECT_EQ(snap[0].id, id0);
+  EXPECT_EQ(snap[1].id, id1);
+}
+
+TEST_F(StitcherWorkletRegistryTest, ConcurrentInstallsYieldUniqueIds) {
+  // Many threads racing `_installEntryForTests` simultaneously must
+  // not see duplicate IDs (would indicate the mutex around _nextId is
+  // missing or broken).  This is the per-instance equivalent of
+  // TransferredNV21Test's "only one of N concurrent callers wins"
+  // pattern, adapted for "all N callers succeed but produce distinct
+  // IDs".
+  auto& r = StitcherWorkletRegistry::shared();
+  constexpr int kThreads = 16;
+  constexpr int kPerThread = 32;  // 512 total installs
+
+  std::vector<std::thread> workers;
+  workers.reserve(kThreads);
+  std::vector<std::vector<std::string>> idsPerThread(kThreads);
+
+  std::atomic<bool> go{false};
+  for (int t = 0; t < kThreads; ++t) {
+    workers.emplace_back([&, t]() {
+      while (!go.load(std::memory_order_acquire)) {
+        std::this_thread::yield();
+      }
+      for (int i = 0; i < kPerThread; ++i) {
+        idsPerThread[t].push_back(r._installEntryForTests(nullptr));
+      }
+    });
+  }
+  go.store(true, std::memory_order_release);
+  for (auto& w : workers) w.join();
+
+  // Aggregate every ID issued.  Total count = kThreads * kPerThread;
+  // uniqueness = the set size matches.
+  std::set<std::string> allIds;
+  for (const auto& v : idsPerThread) {
+    for (const auto& id : v) {
+      allIds.insert(id);
+    }
+  }
+  EXPECT_EQ(allIds.size(),
+            static_cast<std::size_t>(kThreads * kPerThread));
+  EXPECT_EQ(r.count(),
+            static_cast<std::size_t>(kThreads * kPerThread));
+}

package/cpp/tests/stubs/jsi/jsi.h

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// jsi.h — TEST-ONLY stub of facebook::jsi types.
+//
+// The real jsi.h ships with React Native and pulls in a large surface
+// area (Runtime, Value, Object, Function, HostObject, HostFunction,
+// Array, ArrayBuffer, PropNameID, …) along with the build infra to
+// link them.  For pure-C++ unit tests that exercise data-structure
+// invariants of code that REFERENCES jsi types but never CALLS into
+// them (e.g. `StitcherWorkletRegistry` storing a `shared_ptr` and
+// forwarding `Runtime&` to a constructor stub), we only need the
+// types to be NAMED so headers compile.
+//
+// Pattern: this stub is placed first on the test target's include
+// path so `#include <jsi/jsi.h>` resolves here instead of to RN's
+// real header.  Production builds NEVER see this file — it lives
+// only under `cpp/tests/stubs/`, which is referenced exclusively by
+// `cpp/tests/CMakeLists.txt`.
+//
+// Tests that need to actually CONSTRUCT or CALL into JSI types should
+// not use this stub — they should run against a real JSI runtime (a
+// future v0.11.0+ test target that links Hermes).
+
+#pragma once
+
+namespace facebook {
+namespace jsi {
+
+class Runtime {};
+class Value {};
+
+}  // namespace jsi
+}  // namespace facebook

package/cpp/tests/stubs/react-native-worklets-core/WKTJsiWorklet.h

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// WKTJsiWorklet.h — TEST-ONLY stub of RNWorklet::WorkletInvoker.
+//
+// `cpp/stitcher_worklet_registry.cpp` constructs a
+// `std::make_shared<RNWorklet::WorkletInvoker>(runtime, value)` inside
+// `install`.  The real WorkletInvoker (from react-native-worklets-core)
+// captures the worklet's source / closure / runtime affinity and is
+// non-trivial to stand up in a unit-test context.
+//
+// This stub provides JUST the symbols needed for the registry to
+// compile and link.  The constructor and destructor are no-ops; calling
+// methods on a stub invoker is undefined behaviour, but the registry
+// itself never does (it only stores the shared_ptr and hands it out
+// via `snapshot`).  Tests construct entries directly via
+// `_installEntryForTests(nullptr)` to avoid even the trivial
+// allocation.
+//
+// See cpp/tests/stubs/jsi/jsi.h for the parallel stub of facebook::jsi.
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+namespace RNWorklet {
+
+class WorkletInvoker {
+ public:
+  WorkletInvoker(facebook::jsi::Runtime& /*runtime*/,
+                 const facebook::jsi::Value& /*workletValue*/) {}
+  ~WorkletInvoker() = default;
+};
+
+}  // namespace RNWorklet

package/dist/camera/useCapture.d.ts

@@ -17,7 +17,7 @@
  *   - This hook does NOT persist captures.  Host apps hand the
  *     returned CaptureResult to their own storage layer (WatermelonDB
  *     insert, Redux dispatch, whatever).
- *   - Video recording lives in useVideoCapture (TODO).
+ *   - Video recording lives in useVideoCapture.
  *
  * The public API is designed to be minimal and replaceable: host apps
  * that prefer the raw vision-camera API can opt out of this hook and

package/dist/camera/useCapture.js

@@ -19,7 +19,7 @@
  *   - This hook does NOT persist captures.  Host apps hand the
  *     returned CaptureResult to their own storage layer (WatermelonDB
  *     insert, Redux dispatch, whatever).
- *   - Video recording lives in useVideoCapture (TODO).
+ *   - Video recording lives in useVideoCapture.
  *
  * The public API is designed to be minimal and replaceable: host apps
  * that prefer the raw vision-camera API can opt out of this hook and

package/dist/stitching/incremental.d.ts

@@ -249,6 +249,47 @@ export interface IncrementalState {
      * keyframes on disk.
      */
     refinedPanoramaPath?: string;
+    /**
+     * v0.10.0 (#15A) — current phase of an in-flight `refinePanorama`
+     * call.  Fires from both the explicit `module.refinePanorama(...)`
+     * JS API path AND the hybrid-engine auto-refine path (which calls
+     * the same native refinePanorama internally).
+     *
+     * Lifecycle:
+     *   - `"validating"` (fraction 0.05) — synchronous input checks
+     *   - `"stitching"`  (fraction 0.10) — OpenCV stitch in flight
+     *   - `"writing"`    (fraction 0.90) — stitch done, JPEG written
+     *   - `"done"`       (fraction 1.00) — success
+     *   - `"error"`      (fraction 1.00) — failure; `refineError` is set
+     *
+     * Coarse on purpose: OpenCV's Stitcher doesn't expose mid-pipeline
+     * progress, so the 0.10 → 0.90 jump is one opaque step.  Use
+     * `refineStage` for a stage label; use `refineProgress` purely for
+     * spinner progress.
+     *
+     * Undefined when no refinement is in flight.
+     */
+    refineStage?: 'validating' | 'stitching' | 'writing' | 'done' | 'error';
+    /**
+     * v0.10.0 (#15A) — coarse progress fraction in `[0, 1]` aligned
+     * with `refineStage`.  See `refineStage` for the per-stage value
+     * mapping.  Undefined when no refinement is in flight.
+     */
+    refineProgress?: number;
+    /**
+     * v0.10.0 (#15A) — number of input frames the in-flight refine is
+     * processing.  Useful for the UI label
+     * (`Stitching 6 frames…`).  Mirrors the `framesRequested` field
+     * returned in the explicit refinePanorama resolution.  Undefined
+     * when no refinement is in flight.
+     */
+    refineFrames?: number;
+    /**
+     * v0.10.0 (#15A) — present only when `refineStage === 'error'`.
+     * Human-readable error message; the same text the rejected promise
+     * carries.  Use to render a one-line failure pill.
+     */
+    refineError?: string;
 }
 export interface IncrementalStartOptions {
     /**

package/dist/stitching/useFrameStream.js

@@ -61,10 +61,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useFrameStream = useFrameStream;
 const react_1 = require("react");
-const react_native_1 = require("react-native");
 const react_native_vision_camera_1 = require("react-native-vision-camera");
 const react_native_worklets_core_1 = require("react-native-worklets-core");
 const useThrottledFrameProcessor_1 = require("./useThrottledFrameProcessor");
+const files_1 = require("../utils/files");
 /**
  * `useFrameStream` — Layer 3.  See module docstring for the full
  * design + use-case mapping.  Quick start:
@@ -98,37 +98,38 @@ const useThrottledFrameProcessor_1 = require("./useThrottledFrameProcessor");
 function useFrameStream(options, handler) {
     const sampleHz = Math.max(0.5, Math.min(10, options.sampleHz));
     const quality = options.quality ?? 75;
-    // Default output dir: a per-app cache subdirectory.  Hosts that
-    // want a known path supply their own via `options.outputDir`.
-    // `Platform.OS`-specific cache paths are read once at hook mount.
-    const outputDir = (0, react_1.useMemo)(() => {
+    // Default output dir: the lib's canonical capture dir resolved
+    // via `FileBridge.defaultCaptureDir()`.  Same dir the lib uses
+    // for panorama JPEGs / keyframe JPEGs — guaranteed writable on
+    // both platforms (iOS NSCachesDirectory + Android Context.cacheDir),
+    // created if missing.  Resolved async on first mount; until
+    // resolution completes the worklet's `outputDir` is empty and
+    // the plugin call no-ops silently (a few frames missed at most;
+    // typical resolution time is <50ms).
+    //
+    // Hosts that want a specific path supply `options.outputDir`
+    // and skip the resolution entirely.
+    const [resolvedDefaultDir, setResolvedDefaultDir] = (0, react_1.useState)('');
+    (0, react_1.useEffect)(() => {
         if (options.outputDir != null)
-            return options.outputDir;
-        // Both platforms expose a cache directory at a predictable path
-        // via React Native APIs; we use a small inline computation to
-        // avoid pulling `react-native-fs` as a hard dep.  The lib's
-        // existing JPEG encode targets the app's data dir via similar
-        // logic in `RNSARCameraView.kt` / `IncrementalStitcher.swift`.
-        //
-        // We just generate a relative-ish path under /tmp/ for cross-
-        // platform simplicity; the native plugin writes wherever it's
-        // told to (absolute path), so as long as the directory exists
-        // the encode succeeds.  Hosts that care about file lifecycle
-        // should supply `outputDir` explicitly.
-        return react_native_1.Platform.OS === 'ios'
-            ? '/tmp/rnis-frame-stream'
-            : '/data/local/tmp/rnis-frame-stream';
+            return;
+        let cancelled = false;
+        (0, files_1.getDefaultCaptureDir)()
+            .then((dir) => {
+            if (!cancelled)
+                setResolvedDefaultDir(dir);
+        })
+            .catch((err) => {
+            // eslint-disable-next-line no-console
+            console.warn('[useFrameStream] FileBridge.defaultCaptureDir() failed; ' +
+                'samples will not fire until `options.outputDir` is supplied. ' +
+                String(err));
+        });
+        return () => {
+            cancelled = true;
+        };
     }, [options.outputDir]);
-    // Ensure outputDir exists on the native side.  We could use
-    // react-native-fs but to keep the dep surface minimal, we just
-    // attempt to create via a tiny native call — or, simpler, accept
-    // that the plugin's write call will fail if the dir doesn't
-    // exist + log a clear error.  For v0.9.0 baseline we defer
-    // mkdir to the host (document it in the option's JSDoc) OR fall
-    // back to the platform's tmpdir which already exists.
-    //
-    // The tmpdir defaults above always exist on iOS + Android, so
-    // the common case "host doesn't supply outputDir" Just Works.
+    const outputDir = options.outputDir ?? resolvedDefaultDir;
     // Stable JS-side handler reference for `runOnJS`.  The hook re-
     // captures `handler` on every render but the ref keeps the
     // worklet closure pointing at the latest callback (avoid stale
@@ -152,18 +153,33 @@ function useFrameStream(options, handler) {
     // registry hasn't initialised yet (rare race on app start).  We
     // retry every 16ms (one display frame) until success — matches
     // the pattern in `useFrameProcessorDriver`.
-    const pluginRef = (0, react_1.useRef)(null);
+    //
+    // Use `useState` (not `useRef`) so the eventual non-null value
+    // triggers a re-render — the worklet closure below captures
+    // `plugin` by value at render time, so without state we'd
+    // capture `null` forever.
+    const [plugin, setPlugin] = (0, react_1.useState)(null);
     (0, react_1.useEffect)(() => {
         let cancelled = false;
         let timerId = null;
+        let attempts = 0;
         const tryAcquire = () => {
             if (cancelled)
                 return;
+            attempts += 1;
             const p = react_native_vision_camera_1.VisionCameraProxy.initFrameProcessorPlugin('save_frame_as_jpeg', {});
             if (p != null) {
-                pluginRef.current = p;
+                setPlugin(p);
                 return;
             }
+            // After ~1s of failed retries, warn once — the plugin should
+            // be registered by then; persistent failure means the host's
+            // native bundle doesn't include `save_frame_as_jpeg`.
+            if (attempts === 60) {
+                // eslint-disable-next-line no-console
+                console.warn('[useFrameStream] save_frame_as_jpeg plugin not found after 1s of retries. ' +
+                    'Verify react-native-image-stitcher native module is installed in your host app.');
+            }
             timerId = setTimeout(tryAcquire, 16);
         };
         tryAcquire();
@@ -173,15 +189,14 @@ function useFrameStream(options, handler) {
                 clearTimeout(timerId);
         };
     }, []);
-    // The worklet body — fires at sampleHz, calls the JPEG plugin,
-    // bridges the result to JS.  Note we read `pluginRef.current`
-    // inside the worklet via the captured `plugin` value below;
-    // worklets-core handles the JS↔worklet reference.
-    const plugin = pluginRef.current;
     return (0, useThrottledFrameProcessor_1.useThrottledFrameProcessor)((frame) => {
         'worklet';
         if (plugin == null)
             return;
+        // Async outputDir resolution may not have completed yet on
+        // the first few frames after mount — bail until it does.
+        if (outputDir === '')
+            return;
         // Slot rotation: compute slot from frame timestamp.  At
         // sampleHz=2 (500ms interval), the slot index changes every
         // ~1s, giving each slot ~2 samples before being overwritten.