react-native-image-stitcher 0.9.0 → 0.11.0

package/cpp/tests/pose_test.cpp

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// pose_test.cpp — v0.10.0 audit #9A
+//
+// Layout / size invariants for the cross-platform POD structs that
+// marshal AR-frame pose data between Swift/Kotlin and shared C++.
+// The Pose / PlaneTransform structs MUST stay binary-compatible
+// across iOS (Swift → C++) and Android (Kotlin → JNI → C++) — any
+// silent field reorder, padding shift, or size change would diverge
+// gate decisions between platforms.
+//
+// These are pinned to the contract in `cpp/ar_frame_pose.h`'s
+// docstring; if the struct shape evolves intentionally, update both
+// the docstring and these tests in the same commit.
+
+#include "ar_frame_pose.h"
+
+#include <gtest/gtest.h>
+
+#include <cstddef>
+#include <type_traits>
+
+using retailens::Pose;
+using retailens::PlaneTransform;
+
+TEST(PoseLayoutTest, IsStandardLayoutPod) {
+  // Required for `memcpy` marshalling and for the iOS Obj-C++ /
+  // Android JNI bridges to write into the struct directly.
+  EXPECT_TRUE(std::is_standard_layout<Pose>::value);
+  EXPECT_TRUE(std::is_trivially_copyable<Pose>::value);
+}
+
+TEST(PoseLayoutTest, SizeMatchesExpectedFields) {
+  // 11 floats (tx, ty, tz, qx, qy, qz, qw, fx, fy, cx, cy) + 2 int32_t
+  // (imageWidth, imageHeight) = 11*4 + 2*4 = 52 bytes.  No padding
+  // expected: every field is 4-byte aligned and the struct contains
+  // only 4-byte primitives.
+  EXPECT_EQ(sizeof(Pose), static_cast<std::size_t>(11 * 4 + 2 * 4));
+}
+
+TEST(PoseLayoutTest, FieldOrderMatchesContract) {
+  // Translation comes before rotation; rotation before intrinsics;
+  // intrinsics before image dimensions.  Swift / Kotlin marshallers
+  // assume this order — flipping any pair silently breaks the
+  // memcpy-based bridge.
+  EXPECT_EQ(offsetof(Pose, tx), 0u);
+  EXPECT_EQ(offsetof(Pose, ty), sizeof(float) * 1);
+  EXPECT_EQ(offsetof(Pose, tz), sizeof(float) * 2);
+  EXPECT_EQ(offsetof(Pose, qx), sizeof(float) * 3);
+  EXPECT_EQ(offsetof(Pose, qy), sizeof(float) * 4);
+  EXPECT_EQ(offsetof(Pose, qz), sizeof(float) * 5);
+  EXPECT_EQ(offsetof(Pose, qw), sizeof(float) * 6);
+  EXPECT_EQ(offsetof(Pose, fx), sizeof(float) * 7);
+  EXPECT_EQ(offsetof(Pose, fy), sizeof(float) * 8);
+  EXPECT_EQ(offsetof(Pose, cx), sizeof(float) * 9);
+  EXPECT_EQ(offsetof(Pose, cy), sizeof(float) * 10);
+  EXPECT_EQ(offsetof(Pose, imageWidth), sizeof(float) * 11);
+  EXPECT_EQ(offsetof(Pose, imageHeight),
+            sizeof(float) * 11 + sizeof(int32_t));
+}
+
+TEST(PlaneTransformLayoutTest, IsStandardLayoutPod) {
+  EXPECT_TRUE(std::is_standard_layout<PlaneTransform>::value);
+  EXPECT_TRUE(std::is_trivially_copyable<PlaneTransform>::value);
+}
+
+TEST(PlaneTransformLayoutTest, SixteenFloatsContiguous) {
+  // The `m[16]` array MUST be a contiguous 64-byte block — both
+  // bridges call `memcpy(planeTransform.m, source, 64)`.  No leading
+  // padding, no field reorder (there's only one field, but pinning the
+  // size catches any accidental wrapper/struct change).
+  EXPECT_EQ(sizeof(PlaneTransform), static_cast<std::size_t>(16 * 4));
+  EXPECT_EQ(offsetof(PlaneTransform, m), 0u);
+}

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/Camera.d.ts

@@ -221,26 +221,42 @@ export interface CameraProps {
      * }
      * ```
      *
-     * ## Non-AR mode tradeoff (HONEST)
+     * ## Non-AR mode composition (v0.11.0+)
      *
      * vision-camera's `<Camera>` accepts ONLY ONE frame processor.
      * The lib's internal `useFrameProcessorDriver` produces the
      * processor that drives first-party panorama stitching in non-AR
-     * mode.  If you supply your own via this prop, **the lib's
-     * first-party stitching is replaced** — panorama capture in
-     * non-AR mode will not produce stitched output until you remove
-     * the prop or fork the SDK to compose both worklets manually.
+     * mode.  If you supply your own via this prop, the lib's
+     * default processor is REPLACED — but as of v0.11.0 you can
+     * COMPOSE first-party stitching back into your worklet body
+     * using `useStitcherWorklet`:
      *
-     * For the common case (host wants worklet + lib wants stitching
-     * concurrently), prefer AR mode: the AR-mode path natively fans
-     * out to both the lib's first-party stitching AND every
-     * registered host worklet on every frame, with per-worklet
-     * failure isolation.
+     * ```tsx
+     * import {
+     *   Camera, useFrameProcessor, useStitcherWorklet,
+     *   type StitcherFrame,
+     * } from 'react-native-image-stitcher';
+     *
+     * function MyScreen() {
+     *   const stitcher = useStitcherWorklet();
+     *   const fp = useFrameProcessor((frame: StitcherFrame) => {
+     *     'worklet';
+     *     hostPreLogic(frame);
+     *     stitcher.call(frame);   // ← first-party stitching
+     *     hostPostLogic(frame);
+     *   }, [stitcher.call]);
+     *   return <Camera frameProcessor={fp} ... />;
+     * }
+     * ```
      *
-     * Composition for non-AR mode (lib stitching + host worklet on
-     * the same vc processor) is tracked as a v0.9+ follow-up;
-     * needs the lib's first-party logic exposed as a vc Frame
-     * Processor plugin the host's worklet can call.
+     * Hosts that DON'T call `useStitcherWorklet` from their worklet
+     * body replace first-party stitching for non-AR captures (a
+     * one-shot console.info documents this when the prop is first
+     * supplied).  AR mode is unaffected either way — the AR-mode
+     * dispatch path (v0.8.0 Phase 4b.i / 4b.iii) natively fans out
+     * to both the lib's first-party stitching AND every registered
+     * host worklet on every frame, with per-worklet failure
+     * isolation.
      *
      * ## AR mode behaviour
      *

package/dist/camera/Camera.js

@@ -435,36 +435,36 @@ function Camera(props) {
     // Safety: stop the driver if the component unmounts mid-recording.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     (0, react_1.useEffect)(() => () => { fpDriver.stop(); }, []);
-    // v0.8.0 Phase 5 — frameProcessor prop semantics:
+    // v0.8.0 Phase 5 / v0.11.0 — frameProcessor prop semantics:
     //
-    //   - Host supplied? → use host's processor; lib's first-party
-    //     stitching is DISABLED in non-AR mode (vc accepts only one
-    //     processor).  One-shot console.info documents the tradeoff
-    //     so the host isn't surprised by "panorama capture stopped
-    //     producing output" in non-AR mode.  AR-mode capture is
-    //     unaffected — the AR-session dispatch path fans out to BOTH
-    //     first-party and host worklets independently.
+    //   - Host supplied? → use host's processor.  The host's worklet
+    //     body controls whether first-party stitching also fires:
+    //     call `stitcher.call(frame)` (from `useStitcherWorklet`)
+    //     inside the body to compose; omit to replace.  One-shot
+    //     console.info documents the choice so the host can spot a
+    //     missing `useStitcherWorklet` call before they go hunting
+    //     for "why is non-AR panorama capture not producing output".
+    //     AR-mode capture is unaffected either way — the AR-session
+    //     dispatch path fans out to BOTH first-party stitching AND
+    //     every host worklet independently.
     //
     //   - No host processor? → use `fpDriver.frameProcessor` which is
     //     the lib's internal worklet driving first-party stitching
     //     via `useFrameProcessorDriver`.  Default behaviour for the
     //     common "I just want panorama capture" case.
-    //
-    // The pre-v0.8.0 behaviour (host's prop silently ignored with
-    // a warning) is gone — Phase 5 plumbs the prop through.  The
-    // tradeoff is honestly documented in the CameraProps docstring.
     const hostFrameProcessorAcceptedWarnedRef = (0, react_1.useRef)(false);
     if (hostFrameProcessor != null
         && !hostFrameProcessorAcceptedWarnedRef.current) {
         hostFrameProcessorAcceptedWarnedRef.current = true;
         // eslint-disable-next-line no-console
         console.info('[react-native-image-stitcher] Host frameProcessor supplied — '
-            + 'non-AR mode will run YOUR worklet instead of the lib\'s '
-            + 'first-party stitching plugin (vc accepts only one frame '
-            + 'processor).  Non-AR panorama capture will not produce '
-            + 'stitched output until this prop is removed.  AR-mode '
-            + 'capture is unaffected (AR-session dispatch fans out to '
-            + 'both first-party and host worklets independently).');
+            + 'non-AR mode will run YOUR composed worklet.  If you want '
+            + 'first-party panorama stitching alongside your own logic, '
+            + 'call `useStitcherWorklet()` and invoke `stitcher.call(frame)` '
+            + 'from your worklet body (see `<Camera>` `frameProcessor` '
+            + 'JSDoc for the composition pattern).  AR-mode capture is '
+            + 'unaffected (AR-session dispatch fans out to both '
+            + 'first-party and host worklets independently).');
     }
     // The Frame Processor worklet bound to vision-camera's Camera.
     // Host's wins if supplied; lib's internal driver otherwise.

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/index.d.ts

@@ -73,5 +73,7 @@ export { useFrameStream } from './stitching/useFrameStream';
 export type { FrameStreamOptions, SampledFrame } from './types';
 export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
 export type { UseFrameProcessorDriverOptions, FrameProcessorDriverHandle, } from './stitching/useFrameProcessorDriver';
+export { useStitcherWorklet } from './stitching/useStitcherWorklet';
+export type { UseStitcherWorkletOptions, StitcherWorkletHandle, StitcherWorkletInput, } from './stitching/useStitcherWorklet';
 export { stitchVideo } from './stitching/stitchVideo';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,7 +22,7 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stitchVideo = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
+exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
 // ─────────────────────────────────────────────────────────────────────
 // Layer 1 — the high-level <Camera> component
 // ─────────────────────────────────────────────────────────────────────
@@ -179,6 +179,14 @@ Object.defineProperty(exports, "useFrameStream", { enumerable: true, get: functi
 // `useIncrementalJSDriver` was removed; was deprecated in v0.5).
 var useFrameProcessorDriver_1 = require("./stitching/useFrameProcessorDriver");
 Object.defineProperty(exports, "useFrameProcessorDriver", { enumerable: true, get: function () { return useFrameProcessorDriver_1.useFrameProcessorDriver; } });
+// v0.11.0 — composable first-party stitching as a worklet function.
+// Hosts that want to COMPOSE their own per-frame logic with the
+// lib's stitching (instead of REPLACING it via the <Camera>
+// `frameProcessor` prop) call this hook + invoke `stitcher.call`
+// inside their own `useFrameProcessor` body.  See
+// `docs/host-app-integration.md` § Tier 3 for the full pattern.
+var useStitcherWorklet_1 = require("./stitching/useStitcherWorklet");
+Object.defineProperty(exports, "useStitcherWorklet", { enumerable: true, get: function () { return useStitcherWorklet_1.useStitcherWorklet; } });
 // ── Batch stitching ───────────────────────────────────────────────────
 // Feed a video file straight to OpenCV's cv::Stitcher, bypassing the
 // incremental pipeline.  Useful when you have content captured