react-native-image-stitcher 0.16.2 → 0.18.0

package/dist/stitching/ensureStitcherProxyInstalled.js

@@ -0,0 +1,81 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureStitcherProxyInstalled = ensureStitcherProxyInstalled;
+exports._resetStitcherProxyInstallStateForTests = _resetStitcherProxyInstallStateForTests;
+const react_native_1 = require("react-native");
+/**
+ * `__DEV__` is RN's global dev-flag.  Guard the read with `typeof`
+ * so the helper works in any environment that imports it without
+ * defining __DEV__ (jest, SSR, custom tooling).  Same pattern RN's
+ * own debug code uses.
+ */
+function isDev() {
+    return typeof __DEV__ !== 'undefined' && __DEV__;
+}
+let installed = false;
+function ensureStitcherProxyInstalled() {
+    if (installed)
+        return true;
+    // Already installed by an earlier hook mount.  Cheap fast-path.
+    if (typeof globalThis.__stitcherProxy !== 'undefined') {
+        installed = true;
+        return true;
+    }
+    const mod = react_native_1.NativeModules
+        .StitcherJsiInstaller;
+    if (mod == null || typeof mod.install !== 'function') {
+        // Module not present — Android until Phase 4b.ii lands, or
+        // an old iOS build.  Surface this once at debug-info level so
+        // the host can see "your worklets are JS-registered only" in
+        // logcat / Console.app without a noisy per-frame warning.
+        if (isDev() && !warnedAboutMissingModule) {
+            warnedAboutMissingModule = true;
+            console.info('[react-native-image-stitcher] StitcherJsiInstaller native ' +
+                'module not found; host worklets registered in JS-side ' +
+                'registry only.  AR-mode dispatch requires the native install ' +
+                '(iOS Phase 4b.i — included in v0.8.0; Android Phase 4b.ii ' +
+                '— follow-up release).');
+        }
+        return false;
+    }
+    try {
+        const ok = mod.install();
+        if (!ok) {
+            // Native module ran but couldn't install (JSI runtime
+            // unreachable).  Same fallback as the missing-module case.
+            if (isDev() && !warnedAboutFailedInstall) {
+                warnedAboutFailedInstall = true;
+                console.info('[react-native-image-stitcher] StitcherJsiInstaller.install() ' +
+                    'returned false (JSI runtime unreachable — remote debug ' +
+                    'mode?).  Falling back to JS-side host worklet registry.');
+            }
+            return false;
+        }
+        installed = true;
+        return true;
+    }
+    catch (err) {
+        if (isDev() && !warnedAboutFailedInstall) {
+            warnedAboutFailedInstall = true;
+            console.info('[react-native-image-stitcher] StitcherJsiInstaller.install() ' +
+                'threw: ' +
+                String(err) +
+                '.  Falling back to JS-side host worklet registry.');
+        }
+        return false;
+    }
+}
+let warnedAboutMissingModule = false;
+let warnedAboutFailedInstall = false;
+/**
+ * Test-only — reset module-internal state.  Used by jest to allow
+ * multiple test cases to re-trigger the install path independently.
+ * NOT exported from `src/index.ts`.
+ */
+function _resetStitcherProxyInstallStateForTests() {
+    installed = false;
+    warnedAboutMissingModule = false;
+    warnedAboutFailedInstall = false;
+}
+//# sourceMappingURL=ensureStitcherProxyInstalled.js.map

package/dist/stitching/useStitcherWorklet.d.ts

@@ -106,17 +106,17 @@
  *   their own worklet via this hook must do the wiring themselves.
  */
 import type { Frame } from 'react-native-vision-camera';
-import type { StitcherFrame } from './StitcherFrame';
+import type { CameraFrame } from './CameraFrame';
 /**
  * Frames the lib's stitching worklet accepts.  Accepting either a
  * vc `Frame` (what the host's `useFrameProcessor` body sees) or the
- * lib's `StitcherFrame` (what the lib's `useFrameProcessor` body
+ * lib's `CameraFrame` (what the lib's `useFrameProcessor` body
  * sees) keeps the same `useStitcherWorklet` usable from both kinds
  * of host worklet bodies without a cast on the call site.  The
  * worklet only reads `width` / `height`; the rest of the frame
  * object is forwarded verbatim to the native plugin.
  */
-export type StitcherWorkletInput = Frame | StitcherFrame;
+export type StitcherWorkletInput = Frame | CameraFrame;
 export interface UseStitcherWorkletOptions {
     /**
      * Gyro sample interval in ms (~30 Hz default).  Drives the JS-
@@ -145,7 +145,7 @@ export interface UseStitcherWorkletOptions {
 }
 export interface StitcherWorkletHandle {
     /**
-     * Worklet function: pass a `StitcherFrame` to perform one frame of
+     * Worklet function: pass a `CameraFrame` to perform one frame of
      * the lib's first-party stitching (throttle + pose synthesis +
      * native plugin call).  Safe to call from inside another
      * `'worklet'`-prefixed function (this is the canonical

package/dist/stitching/useStitcherWorklet.js

@@ -228,7 +228,7 @@ function useStitcherWorklet(options = {}) {
         // party callback installed in `RNSARWorkletRuntime`).  Calling
         // the vc Frame Processor plugin here would throw
         // `getPropertyAsObject: property '__frame' is undefined`
-        // because AR frames are `StitcherFrameHostObject` instances
+        // because AR frames are `CameraFrameHostObject` instances
         // and don't carry the vc `Frame` proxy's JSI marker.  The
         // throw is caught silently by the per-worklet error handler
         // (`RNSARWorkletRuntime.mm:284-301`) and bubbles up only to
@@ -240,12 +240,12 @@ function useStitcherWorklet(options = {}) {
         // hook (the AR-side stitching path runs natively, independent
         // of the composed worklet body).
         //
-        // The `(frame as StitcherFrame).source` cast is safe: vc
+        // The `(frame as CameraFrame).source` cast is safe: vc
         // `Frame` doesn't carry a `source` property so the check
         // returns `undefined !== 'ar'` → `true`, and the worklet
         // proceeds normally.  Only frames that explicitly tag
         // themselves as AR-source (which our native AR dispatcher
-        // does — see `StitcherFrameHostObject.mm`) get short-circuited.
+        // does — see `CameraFrameHostObject.mm`) get short-circuited.
         if (frame.source === 'ar')
             return;
         // Throttle (verbatim from useFrameProcessorDriver).
@@ -273,7 +273,7 @@ function useStitcherWorklet(options = {}) {
         const fx = w * sharedFxNumerator.value;
         const fy = h * sharedFyNumerator.value;
         // vc's `plugin.call` is typed against vc's `Frame`.  The worklet
-        // accepts the union (`Frame | StitcherFrame`); cast through
+        // accepts the union (`Frame | CameraFrame`); cast through
         // `unknown` because the union doesn't satisfy vc's interface
         // even though structurally both members do.
         plugin.call(frame, {

package/ios/Sources/RNImageStitcher/ARSessionBridge.m

@@ -5,6 +5,7 @@
 // imports as `NativeModules.RNSARSession`.
 
 #import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
 
 // REMAP form, NOT EXTERN_MODULE.  The Swift singleton in
 // RNSARSession.swift takes the @objc name "RNSARSession"
@@ -20,7 +21,14 @@
 // `RNSARSessionBridge` and dispatch methods against THAT
 // class — where takePhoto / startRecording / stopRecording etc.
 // actually live.
-@interface RCT_EXTERN_REMAP_MODULE(RNSARSession, RNSARSessionBridge, NSObject)
+//
+// v0.18.0 — base class is now `RCTEventEmitter` (was `NSObject`) so the
+// "RNSARSession" module can emit the `RNImageStitcherARFrame` device
+// event for the `onArFrame` channel.  RN auto-provides the
+// `addListener:` / `removeListeners:` emitter selectors for a module
+// whose remap base is RCTEventEmitter; the Swift class supplies
+// `supportedEvents` / `startObserving` / `stopObserving`.
+@interface RCT_EXTERN_REMAP_MODULE(RNSARSession, RNSARSessionBridge, RCTEventEmitter)
 
 RCT_EXTERN_METHOD(isSupported:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
@@ -34,6 +42,20 @@ RCT_EXTERN_METHOD(stop:(RCTPromiseResolveBlock)resolver
 RCT_EXTERN_METHOD(getState:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 
+RCT_EXTERN_METHOD(setSceneReconstructionEnabled:(nonnull NSNumber *)enabled
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+RCT_EXTERN_METHOD(setPlaneDetection:(nonnull NSString *)mode
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+// v0.18.0 — toggle the onArFrame LIGHT-metadata channel + its throttle.
+RCT_EXTERN_METHOD(setArFrameMetaEnabled:(nonnull NSNumber *)enabled
+                  intervalMs:(nonnull NSNumber *)intervalMs
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
 RCT_EXTERN_METHOD(snapshotPoseLog:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 

package/ios/Sources/RNImageStitcher/ARSessionBridge.swift

@@ -17,15 +17,109 @@
 import Foundation
 import React
 
+// v0.18.0 — `RNSARSessionBridge` is now an `RCTEventEmitter` (was a
+// plain `NSObject`) so it can deliver the `onArFrame` LIGHT-metadata
+// channel as the JS `RNImageStitcherARFrame` device event.  The JS side
+// subscribes via `new NativeEventEmitter(NativeModules.RNSARSession)` —
+// the same module name this bridge is remapped to (see ARSessionBridge.m).
+//
+// Pattern mirrors `IncrementalStitcherBridge`: observe a NotificationCenter
+// post from the framework-free `RNSARSession` engine, then re-emit on the
+// main queue via `bridge.enqueueJSCall("RCTDeviceEventEmitter", "emit", …)`
+// rather than `RCTEventEmitter.sendEvent(…)`, because under RN bridgeless
+// interop `sendEvent` silently no-ops for some event-body shapes (see the
+// IncrementalStitcherBridge.handleStateUpdate docstring).
 @objc(RNSARSessionBridge)
-public final class RNSARSessionBridge: NSObject {
+public final class RNSARSessionBridge: RCTEventEmitter {
+
+    /// Whether at least one JS listener is attached to the AR-frame event.
+    /// RN's EventEmitter contract: don't emit when no listeners are
+    /// registered.  Toggled by `startObserving` / `stopObserving`.
+    private var hasListeners: Bool = false
+
+    private static let arFrameEvent = "RNImageStitcherARFrame"
+
+    public override init() {
+        super.init()
+        // Defensively de-dupe the observer: under RN bridgeless interop a
+        // bridge's init() can run twice on the same instance.  Remove any
+        // prior registration for this notification before adding, so the
+        // observer fires at most once per post regardless.
+        NotificationCenter.default.removeObserver(
+            self,
+            name: .retailensARFrameMeta,
+            object: nil
+        )
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleArFrameMeta(_:)),
+            name: .retailensARFrameMeta,
+            object: nil
+        )
+    }
 
-    @objc public static func requiresMainQueueSetup() -> Bool {
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    // MARK: - RCTEventEmitter protocol
+
+    public override static func requiresMainQueueSetup() -> Bool {
         // ARSession.start() must be called on the main thread —
         // ARKit needs to attach to the active CVDisplayLink.
         return true
     }
 
+    public override func supportedEvents() -> [String]! {
+        return [Self.arFrameEvent]
+    }
+
+    public override func startObserving() {
+        hasListeners = true
+    }
+
+    public override func stopObserving() {
+        hasListeners = false
+    }
+
+    /// Forward a posted `ARFrameMeta` dictionary to JS as the
+    /// `RNImageStitcherARFrame` device event.  Dropped when no JS listener
+    /// is attached.  Emits via `enqueueJSCall` on the main queue (see the
+    /// class docstring for why not `sendEvent`).
+    @objc private func handleArFrameMeta(_ notification: Notification) {
+        guard hasListeners else { return }
+        guard let userInfo = notification.userInfo else { return }
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self, let bridge = self.bridge else { return }
+            bridge.enqueueJSCall(
+                "RCTDeviceEventEmitter",
+                method: "emit",
+                args: [Self.arFrameEvent, userInfo],
+                completion: nil
+            )
+        }
+    }
+
+    // MARK: - Module methods
+
+    /// v0.18.0 — toggle the `onArFrame` LIGHT-metadata channel.  Called
+    /// from JS with `true` + the throttle interval (ms) when a host
+    /// supplies `<Camera onArFrame={...}>`, and `false` on
+    /// unmount / prop-removal.  Resolves with no value.
+    @objc(setArFrameMetaEnabled:intervalMs:resolver:rejecter:)
+    public func setArFrameMetaEnabled(
+        enabled: NSNumber,
+        intervalMs: NSNumber,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        RNSARSession.shared.setArFrameMetaEnabled(
+            enabled.boolValue,
+            intervalMs: intervalMs.doubleValue
+        )
+        resolver(nil)
+    }
+
     @objc(isSupported:rejecter:)
     public func isSupported(
         resolver: @escaping RCTPromiseResolveBlock,
@@ -68,6 +162,47 @@ public final class RNSARSessionBridge: NSObject {
         ])
     }
 
+    /// Toggle ARKit scene reconstruction (LiDAR mesh / `ARMeshAnchor`s).
+    /// Driven by the <Camera> `enableMesh` prop; gates the
+    /// StitcherFrame `meshGeometry` extraction at the SESSION level
+    /// (the per-frame `__stitcherProxy.setExtractionConfig(...mesh)`
+    /// gates the marshaling — both must be on for a host to receive
+    /// mesh).  Resolves with no value.
+    ///
+    /// Hops to the main queue: `setSceneReconstructionEnabled` may call
+    /// `arSession.run(config)` to reconfigure a live session, and
+    /// ARKit session lifecycle must run on the main thread (same
+    /// constraint as `start`).
+    @objc(setSceneReconstructionEnabled:resolver:rejecter:)
+    public func setSceneReconstructionEnabled(
+        enabled: NSNumber,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        let on = enabled.boolValue
+        DispatchQueue.main.async {
+            RNSARSession.shared.setSceneReconstructionEnabled(on)
+            resolver(nil)
+        }
+    }
+
+    /// Hops to the main queue: `setPlaneDetection` may call
+    /// `arSession.run(config)` to reconfigure a live session, and ARKit
+    /// session lifecycle must run on the main thread (same constraint as
+    /// `start` / `setSceneReconstructionEnabled`).
+    @objc(setPlaneDetection:resolver:rejecter:)
+    public func setPlaneDetection(
+        mode: NSString,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        let m = mode as String
+        DispatchQueue.main.async {
+            RNSARSession.shared.setPlaneDetection(m)
+            resolver(nil)
+        }
+    }
+
     @objc(snapshotPoseLog:rejecter:)
     public func snapshotPoseLog(
         resolver: @escaping RCTPromiseResolveBlock,

package/ios/Sources/RNImageStitcher/CameraFrameHostObject.h

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// CameraFrameHostObject.h — Obj-C facade for the v0.8.0
+// `StitcherFrame` JSI host object.  Header is intentionally
+// Obj-C-only (no `<jsi/jsi.h>` import) so this can land in the
+// public CocoaPods umbrella without breaking `use_frameworks!` hosts
+// (same rationale as `KeyframeGateBridge.h`).
+//
+// The C++ JSI host object class lives in the .mm; this facade
+// exposes only what cross-module callers need:
+//
+//   - Factory `+ fromARFrame:pose:` that the AR worklet runtime
+//     calls per ARFrame to construct a host object backed by the
+//     current AR session's frame.
+//   - Opaque accessor `- (void *)jsiHostObjectPtr` returning the
+//     `std::shared_ptr<facebook::jsi::HostObject> *` (boxed) that
+//     the worklet runtime hands to `jsi::Object::createFromHostObject`.
+//
+// Lifetime: the Obj-C wrapper holds the C++ shared_ptr; ARC frees
+// the wrapper when nothing references it.  Worklet runtime
+// invalidates the underlying ARFrame retain when the dispatch
+// returns; after invalidation, JSI access throws.
+
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import <ARKit/ARKit.h>
+
+@class RNSARFramePose;
+
+NS_ASSUME_NONNULL_BEGIN
+
+NS_SWIFT_NAME(CameraFrameHostObject)
+@interface CameraFrameHostObject : NSObject
+
+/// Construct a host object backed by the supplied ARFrame + pose.
+/// Retains the ARFrame for the host object's lifetime — caller can
+/// safely release their reference.
+///
+/// Thread: safe to call from the ARSession delegate queue; the
+/// resulting host object's JSI access must happen on the worklet
+/// runtime's thread (separate queue).
++ (instancetype)fromARFrame:(ARFrame *)arFrame pose:(RNSARFramePose *)pose;
+
+/// Mark the host object's underlying ARFrame as no longer accessible.
+/// Subsequent JSI property reads return `undefined` or throw,
+/// depending on the property.  Idempotent.
+- (void)invalidate;
+
+/// Opaque pointer to a `std::shared_ptr<facebook::jsi::HostObject>`.
+/// The worklet runtime (Obj-C++ context with JSI available) casts
+/// this back via `*reinterpret_cast<std::shared_ptr<facebook::jsi::HostObject>*>(ptr)`
+/// to hand to `jsi::Object::createFromHostObject`.
+///
+/// Returns `NULL` if the host object has been invalidated.
+- (nullable void *)jsiHostObjectPtr;
+
+/// Build the LIGHT per-frame AR metadata dictionary for the `onArFrame`
+/// callback (the `ARFrameMeta` TS shape).  Distinct from the full
+/// host-object factory above: this copies NO pixel / vertex / face bytes
+/// — only scalars, dimensions, anchor transforms, and mesh COUNTS — so
+/// it's cheap enough to run at the throttled `onArFrame` cadence.
+///
+/// Gating mirrors the full extraction path: `depth` only when the JS
+/// `enableDepth` flag is on (read from the shared C++ extraction config),
+/// `anchors` only when `enableAnchors`, `mesh` (counts) only when
+/// `enableMesh`.  `intrinsics` / `pose` / `trackingState` / `timestamp`
+/// are always populated.  `intrinsics` is `NSNull` only when the frame
+/// reported a degenerate (zero) resolution.
+///
+/// Returns a JSON-safe `NSDictionary` (NSNumber / NSString / NSArray /
+/// NSDictionary / NSNull leaves) ready to hand to
+/// `bridge.enqueueJSCall("RCTDeviceEventEmitter", "emit", ...)`.
+///
+/// Thread: safe to call from the ARSession delegate queue (reads the
+/// frame synchronously; copies nothing that outlives the call).
++ (NSDictionary *)lightArFrameMetaFromARFrame:(ARFrame *)arFrame
+                                         pose:(RNSARFramePose *)pose
+    NS_SWIFT_NAME(lightArFrameMeta(from:pose:));
+
+@end
+
+NS_ASSUME_NONNULL_END