react-native-image-stitcher 0.14.2 → 0.15.0

package/ios/Sources/RNImageStitcher/RNSARWorkletRuntime.h

@@ -1,128 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// RNSARWorkletRuntime.h — Obj-C facade for the v0.8.0 AR-mode
-// worklet runtime.  Wraps `react-native-worklets-core`'s
-// `RNWorklet::JsiWorkletContext` (the same primitive vision-camera
-// uses for its Frame Processor runtime) so the lib can dispatch
-// per-ARFrame worklets on a thread we own — rather than ARKit's
-// delegate queue, where doing significant work would block the
-// AR session's update loop.
-//
-// ## Phase 3b scope (this commit)
-//
-// Owns:
-//   - The dispatch queue the worklet runtime pins to.
-//   - The underlying `JsiWorkletContext` (constructed lazily on
-//     `installIfNeeded`, lives for the singleton's lifetime).
-//
-// Exposes:
-//   - `+ shared` singleton accessor.
-//   - `- installIfNeeded` (idempotent runtime construction).
-//   - `- isInstalled` for diagnostics + tests.
-//   - `- dispatchFrame:pose:` — currently a no-op stub; Phase 3c
-//     fills in the actual host-object construction + worklet
-//     invocation + first-party stitching dispatch.
-//
-// Host-worklet registry is intentionally NOT in Phase 3b — Phase 4
-// lands the JSI plugin + TS-side hook that defines the storage
-// shape (NSMutableArray of boxed shared_ptrs vs a C++ vector ivar
-// vs something else).  Pre-committing the storage type here would
-// risk rework.  See
-// `docs/plans/handoff/2026-05-26-v0.8.0-phases-2-5-implementation-guide.md`
-// Phase 4 section for the planned API.
-//
-// ## Why Obj-C facade with `.mm` implementation
-//
-// The implementation needs to hold `std::shared_ptr<JsiWorkletContext>`
-// + run JSI value construction, which can't live in pure Swift.  Same
-// pattern as `KeyframeGateBridge.{h,mm}` + `StitcherFrameHostObject.{h,mm}`:
-// keep the header umbrella-safe (no JSI imports), put the C++ glue in
-// the .mm.
-//
-// ## Header umbrella safety
-//
-// This .h imports only Foundation + ARKit (both system frameworks).
-// Worklets-core types are confined to the .mm.
-
-#pragma once
-
-#import <Foundation/Foundation.h>
-#import <ARKit/ARKit.h>
-
-@class RNSARFramePose;
-
-NS_ASSUME_NONNULL_BEGIN
-
-NS_SWIFT_NAME(RNSARWorkletRuntime)
-@interface RNSARWorkletRuntime : NSObject
-
-/// Singleton accessor.  One AR worklet runtime per process; multiple
-/// `<Camera>` mounts share it.  Construction is cheap (just an Obj-C
-/// alloc + an `NSMutableArray`); the heavy JSI work happens in
-/// `-installIfNeeded`.
-+ (instancetype)shared;
-
-/// Construct the underlying `JsiWorkletContext` if not yet
-/// installed.  Idempotent — repeated calls are no-ops.  Called from
-/// `RNSARSession` at AR-mode start time (Phase 3c will wire this
-/// up; Phase 3b ships the method but no one calls it yet).
-///
-/// Threading: safe to call from any thread; internally serialised.
-/// The runtime's own dispatch queue starts running once installed.
-- (void)installIfNeeded;
-
-/// Diagnostics + tests.  Returns `YES` after a successful
-/// `-installIfNeeded`.
-- (BOOL)isInstalled;
-
-/// Phase 3c — type of the first-party stitching callback.  Invoked
-/// synchronously on the caller thread (`ARSession.delegateQueue` —
-/// typically main queue today) per AR frame.  Block must consume
-/// the pixel buffer before returning (ARKit pool reuse contract).
-typedef void (^RNSARFirstPartyCallback)(ARFrame *arFrame,
-                                         RNSARFramePose *pose);
-
-/// Phase 3c — install the closure that takes ownership of the
-/// per-frame first-party stitching dispatch.  Called from
-/// `RNSARSession.start()` after the incremental consumer is set;
-/// the block then routes `dispatchFrame:pose:` calls through to
-/// the existing `incrementalConsumer.consumeFrame(...)` path.
-///
-/// Pre-Phase-3c the delegate called the consumer directly.  After
-/// Phase 3c the delegate calls `dispatchFrame:pose:` (this class)
-/// which invokes the callback.  Net behavior is byte-identical;
-/// the indirection sets up the seam where Phase 4 will fan out to
-/// host worklets without changing the first-party path.
-///
-/// Pass `nil` to clear (e.g. on `RNSARSession.stop()`).  Idempotent.
-- (void)setFirstPartyCallback:(nullable RNSARFirstPartyCallback)callback;
-
-/// Dispatch one AR frame through the registered worklets.  Called
-/// per `ARFrame` by `RNSARSession.delegate` once Phase 3c lands the
-/// migration (Phase 3b ships this method as a no-op stub so the
-/// runtime can be built + linked + the API surface fixed).
-///
-/// The Phase 3c implementation will:
-///   1. Build a `StitcherFrameHostObject` from `arFrame` + `pose`.
-///   2. Run the first-party stitching synchronously on the caller
-///      thread (preserves today's `ingestFromARCameraView` cost
-///      envelope at the producer site).
-///   3. If any host worklets are registered, dispatch the host
-///      object onto the worklet runtime's thread + invoke each
-///      worklet via `RNWorklet::WorkletInvoker::call`.
-///   4. Invalidate the host object after all worklets return.
-///
-/// Phase 3c gate: install/idempotence tests + this method's
-/// integration test required before merge.  See
-/// `docs/plans/handoff/2026-05-26-v0.8.0-phases-2-5-implementation-guide.md`
-/// Phase 3c gate criteria.
-///
-/// Threading: typically called from `ARSession.delegateQueue` (main
-/// queue by default; Phase 3c will pin it explicitly to a
-/// dedicated queue).
-- (void)dispatchFrame:(ARFrame *)arFrame pose:(RNSARFramePose *)pose
-    NS_SWIFT_NAME(dispatchFrame(_:pose:));
-
-@end
-
-NS_ASSUME_NONNULL_END

package/ios/Sources/RNImageStitcher/RNSARWorkletRuntime.mm

@@ -1,313 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// RNSARWorkletRuntime.mm — Obj-C++ implementation.  See the header
-// for the API contract.  This file owns:
-//
-//   - The dispatch queue the worklet runtime is pinned to
-//   - The `std::shared_ptr<RNWorklet::JsiWorkletContext>` itself
-//   - The registry of host worklets (Phase 4 wiring will populate
-//     this via a JSI plugin entry point)
-//
-// Phase 3b scope: construct the context + expose the API.  No
-// dispatch logic yet — `dispatchFrame:pose:` is a stub.  Phase 3c
-// fills in (a) the host-object construction + worklet invocation,
-// (b) the first-party stitching callback, (c) the migration in
-// `RNSARSession.delegate`.
-//
-// ## Singleton lifetime note (for Leaks-tool readers)
-//
-// `+ shared` uses `dispatch_once`, so the singleton lives for the
-// process lifetime — same pattern as most Obj-C singletons.  This
-// means the dispatch queue (created in `init`) + the JsiWorkletContext
-// (constructed lazily in `installIfNeeded`) + the `workletCallInvoker`
-// lambda that captures the queue are ALL retained until process
-// termination.  Xcode Instruments → Leaks will flag this as "leaked
-// allocation rooted at the singleton" — that's noise, not a real leak
-// (process termination reclaims it).  Phase 3c will keep this shape.
-
-#import "RNSARWorkletRuntime.h"
-#import "StitcherFrameHostObject.h"
-
-#import <Foundation/Foundation.h>
-#import <os/log.h>
-
-#include <jsi/jsi.h>
-// worklets-core headers — use quotes-include since the pod
-// publishes them via HEADER_SEARCH_PATHS, not as a framework
-// module map.  Same pattern KeyframeGateFrameProcessor.mm uses
-// for vision-camera headers (which are reachable via <angle>
-// only because vc's podspec sets `define_module` differently).
-#include "WKTJsiWorkletContext.h"
-#include "WKTJsiWorklet.h"
-
-#include "stitcher_worklet_registry.hpp"
-
-#include <exception>
-#include <memory>
-#include <utility>
-#include <vector>
-
-// Forward-declare `RNSARFramePose` — same pattern as
-// StitcherFrameHostObject.mm.  We don't read its fields here in
-// Phase 3b (the stub doesn't unpack the pose), but Phase 3c will.
-@class RNSARFramePose;
-
-@implementation RNSARWorkletRuntime {
-    /// Dispatch queue the worklet runtime's `workletCallInvoker`
-    /// posts onto.  Serial; `DISPATCH_QUEUE_SERIAL` matches the
-    /// existing `IncrementalStitcher::workQueue` cost envelope
-    /// (one-at-a-time frame ingest).
-    ///
-    /// Phase 3c will configure `ARSession.delegateQueue` to point
-    /// at the same queue so the delegate fires on the worklet
-    /// thread — eliminates a thread hop per frame + makes the
-    /// "first-party first, host worklets after" ordering trivial
-    /// to enforce (all on one queue).
-    dispatch_queue_t _dispatchQueue;
-
-    /// The wrapped worklet-runtime context.  Constructed lazily on
-    /// `-installIfNeeded`; held for the singleton's lifetime
-    /// (process-wide).
-    std::shared_ptr<RNWorklet::JsiWorkletContext> _ctx;
-
-    /// Single-flight install guard.  `BOOL` is sufficient because
-    /// `-installIfNeeded` synchronises on `_installLock` below.
-    BOOL _installed;
-
-    /// Lock for `_installed` + `_ctx`.  Construction may race with
-    /// concurrent first-mount calls from multiple `<Camera>`
-    /// instances; serialise to ensure exactly-once init.
-    NSLock *_installLock;
-
-    // Phase 4 will add the host-worklet registry here.  Storage
-    // shape (NSMutableArray of boxed shared_ptrs vs C++ vector
-    // ivar) is intentionally NOT pre-committed in Phase 3b — let
-    // the JSI plugin's actual register/unregister implementation
-    // pick the natural shape.
-
-    /// Phase 3c — first-party callback installed by RNSARSession.
-    /// Invoked synchronously on the caller thread per AR frame.
-    /// Cleared on RNSARSession.stop() to avoid retain cycles.
-    ///
-    /// Atomic property protects against the delegate firing
-    /// concurrently with a setFirstPartyCallback: call on a
-    /// different thread (rare but possible: setter on main thread
-    /// from RNSARSession.start while a delayed delegate frame
-    /// arrives).
-    RNSARFirstPartyCallback _firstPartyCallback;
-
-    /// Lock for `_firstPartyCallback` reads + writes.  The
-    /// `_installLock` above is dispatch-queue-scoped (install);
-    /// callback rotation is a separate concern.
-    NSLock *_callbackLock;
-}
-
-+ (instancetype)shared {
-    static RNSARWorkletRuntime *sInstance;
-    static dispatch_once_t once;
-    dispatch_once(&once, ^{ sInstance = [[self alloc] init]; });
-    return sInstance;
-}
-
-- (instancetype)init {
-    if ((self = [super init])) {
-        _dispatchQueue = dispatch_queue_create(
-            "io.imagestitcher.ar-worklet-runtime", DISPATCH_QUEUE_SERIAL);
-        _installed = NO;
-        _installLock = [[NSLock alloc] init];
-        _callbackLock = [[NSLock alloc] init];
-        _firstPartyCallback = nil;
-    }
-    return self;
-}
-
-- (void)setFirstPartyCallback:(RNSARFirstPartyCallback)callback {
-    [_callbackLock lock];
-    // Copy the block to move it from stack to heap (ARC handles
-    // the copy semantics for blocks assigned to strong ivars).
-    _firstPartyCallback = [callback copy];
-    [_callbackLock unlock];
-}
-
-- (void)installIfNeeded {
-    [_installLock lock];
-    if (_installed) {
-        [_installLock unlock];
-        return;
-    }
-
-    // Build the `workletCallInvoker`.  `RNWorklet::JsiWorkletContext`
-    // accepts a `std::function<void(std::function<void()>&&)>` that
-    // posts a task onto whatever thread the runtime should execute
-    // on.  We post onto `_dispatchQueue` (a serial GCD queue).
-    //
-    // The captured `fp` is moved into a `std::shared_ptr` so the
-    // dispatch_async block (which can only capture copyable types)
-    // can hold + invoke it.  Without the shared_ptr indirection
-    // we'd hit `std::function` copy-construction on the
-    // non-copyable forward closure.
-    dispatch_queue_t queue = _dispatchQueue;
-    auto invoker = [queue](std::function<void()>&& fp) {
-        auto fpHolder = std::make_shared<std::function<void()>>(std::move(fp));
-        dispatch_async(queue, ^{ (*fpHolder)(); });
-    };
-
-    _ctx = std::make_shared<RNWorklet::JsiWorkletContext>(
-        "stitcher.ar", std::move(invoker));
-    _installed = YES;
-    [_installLock unlock];
-}
-
-- (BOOL)isInstalled {
-    [_installLock lock];
-    BOOL result = _installed;
-    [_installLock unlock];
-    return result;
-}
-
-- (void)dispatchFrame:(ARFrame *)arFrame pose:(RNSARFramePose *)pose {
-    // ── Phase 3c — first-party (synchronous on caller thread) ────
-    //
-    // The callback (installed by RNSARSession.start) wraps the
-    // existing `incrementalConsumer.consumeFrame(...)` call path,
-    // so net behavior is byte-identical to the v0.7.x direct call.
-    //
-    // **Why first-party runs on the CALLER thread (not the worklet
-    // thread):** ARKit's pool reuse contract requires the pixel
-    // buffer to be consumed before this method returns.  The Swift
-    // consumer does that synchronously inside `consumeFrame(...)`
-    // (converts NV12 → cv::Mat synchronously, then defers heavier
-    // work to its own queue).  If we posted the callback onto
-    // `_dispatchQueue`, the delegate would return before
-    // `consumeFrame` ran, ARKit could reclaim the buffer, and we'd
-    // get torn frames.
-    //
-    // Pull the callback under the lock so a concurrent
-    // `setFirstPartyCallback:` doesn't race with our invocation.
-    [_callbackLock lock];
-    RNSARFirstPartyCallback cb = _firstPartyCallback;
-    [_callbackLock unlock];
-    if (cb != nil) {
-        cb(arFrame, pose);
-    }
-
-    // ── Phase 4b — host-worklet fan-out (async on worklet thread) ──
-    //
-    // Snapshot the native registry.  Fast-path early-exit when no
-    // host worklets are registered — saves the host-object alloc
-    // + dispatch_async hop on every frame (the common case in
-    // first-party-only deployments).
-    auto invokers = retailens::StitcherWorkletRegistry::shared().snapshot();
-    if (invokers.empty()) {
-        return;
-    }
-
-    // Construction must happen on the caller thread.  The
-    // `IOSPixelBufferReader` ctor takes a `CFBridgingRetain(arFrame)`
-    // so the underlying CVPixelBuffer stays alive until the host
-    // object's `invalidate` runs.  ARKit's pool will throttle the
-    // *next* frame's delegate call while we hold this retain
-    // (acceptable for Phase 4b minimum-viable; a per-frame buffer
-    // copy is a known optimization for later if throughput
-    // suffers).
-    StitcherFrameHostObject *hostObj =
-        [StitcherFrameHostObject fromARFrame:arFrame pose:pose];
-
-    // Hand the host object's jsi::HostObject shared_ptr (boxed as
-    // void*) into the lambda.  The lambda will:
-    //   1. Cast back to `std::shared_ptr<jsi::HostObject>*`
-    //   2. Construct the JS-side `jsi::Object` from the host object
-    //   3. Invoke each registered WorkletInvoker with the JS-side
-    //      object as its single argument
-    //   4. Delete the boxed shared_ptr
-    //   5. Invalidate the host object on caller-side retained ref
-    //
-    // The dispatch is via worklets-core's `JsiWorkletContext::
-    // invokeOnWorkletThread` — internally posts onto our serial
-    // `_dispatchQueue` via the `workletCallInvoker` we set up in
-    // `installIfNeeded`.
-    //
-    // `hostObj` (the Obj-C facade) is captured by the block; ARC
-    // retains it for the block's lifetime, so the host object
-    // outlives the dispatch.  We invalidate AFTER all worklets
-    // return.
-    void *hostObjPtr = [hostObj jsiHostObjectPtr];
-    if (hostObjPtr == NULL) {
-        // Host object construction failed (e.g., ARFrame was nil).
-        // Skip fan-out.
-        os_log_error(OS_LOG_DEFAULT,
-            "[RNSARWorkletRuntime] host object jsiHostObjectPtr was NULL; "
-            "skipping host-worklet fan-out for this frame.");
-        return;
-    }
-
-    if (_ctx == nullptr) {
-        // installIfNeeded wasn't called.  This shouldn't happen
-        // because RNSARSession.start calls installIfNeeded before
-        // any frames arrive, but guard defensively.
-        os_log_error(OS_LOG_DEFAULT,
-            "[RNSARWorkletRuntime] _ctx is nullptr in dispatchFrame; "
-            "did installIfNeeded run?  Skipping host-worklet fan-out.");
-        // Leaked: hostObjPtr (boxed shared_ptr).  Reclaim it here so
-        // we don't leak even on the defensive path.
-        delete static_cast<std::shared_ptr<facebook::jsi::HostObject>*>(hostObjPtr);
-        return;
-    }
-
-    _ctx->invokeOnWorkletThread(
-        [invokers, hostObjPtr, hostObj](
-            RNWorklet::JsiWorkletContext* /*ctx*/,
-            facebook::jsi::Runtime& rt) {
-            // Reclaim the boxed shared_ptr.  After this scope the
-            // unique_ptr automatically deletes the heap allocation
-            // even if the JSI call below throws.
-            std::unique_ptr<std::shared_ptr<facebook::jsi::HostObject>> spBox(
-                static_cast<std::shared_ptr<facebook::jsi::HostObject>*>(
-                    hostObjPtr));
-
-            facebook::jsi::Object frameJsi =
-                facebook::jsi::Object::createFromHostObject(rt, *spBox);
-            // Pass the host object as a single argument.  The
-            // worklet's signature is `(frame: StitcherFrame) =>
-            // void` — matches.
-            //
-            // Construct the argument value as a copy of the
-            // Object (jsi::Value(rt, obj) makes a fresh Value
-            // wrapping the same host object — refcounted by JSI).
-            facebook::jsi::Value frameVal(rt, frameJsi);
-
-            for (const auto& entry : invokers) {
-                if (!entry.invoker) continue;
-                try {
-                    entry.invoker->call(rt, facebook::jsi::Value::undefined(),
-                                         &frameVal, 1);
-                } catch (const facebook::jsi::JSError& jsErr) {
-                    // Per-worklet failure isolation: one host
-                    // worklet throwing must NOT stop the lib's own
-                    // path or other host worklets.  Log + continue.
-                    os_log_error(OS_LOG_DEFAULT,
-                        "[RNSARWorkletRuntime] host worklet '%{public}s' "
-                        "threw JS error: %{public}s",
-                        entry.id.c_str(), jsErr.what());
-                } catch (const std::exception& e) {
-                    os_log_error(OS_LOG_DEFAULT,
-                        "[RNSARWorkletRuntime] host worklet '%{public}s' "
-                        "threw native exception: %{public}s",
-                        entry.id.c_str(), e.what());
-                } catch (...) {
-                    os_log_error(OS_LOG_DEFAULT,
-                        "[RNSARWorkletRuntime] host worklet '%{public}s' "
-                        "threw unknown exception", entry.id.c_str());
-                }
-            }
-
-            // Drop the JSI references BEFORE invalidating the host
-            // object — `frameJsi` / `frameVal` go out of scope at
-            // end of lambda anyway, but be explicit.  Then
-            // invalidate the Obj-C facade which releases the
-            // CFBridgingRetain'd ARFrame so ARKit's pool can recycle.
-            [hostObj invalidate];
-        });
-}
-
-@end

package/ios/Sources/RNImageStitcher/SaveFrameAsJpegPlugin.mm

@@ -1,185 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// SaveFrameAsJpegPlugin.mm — v0.9.0 Layer 1: vc Frame Processor plugin
-// that JPEG-encodes the supplied frame's pixel buffer to a host-
-// supplied path.  Worklet-callable; thin wrapper around the standard
-// iOS CIImage → CGImage → UIImage → UIImageJPEGRepresentation path.
-//
-// JS-side usage (from a worklet — typically inside `useFrameStream`
-// (Layer 3) or directly from a custom `useFrameProcessor` body):
-//
-//     const plugin = VisionCameraProxy.initFrameProcessorPlugin(
-//       'save_frame_as_jpeg', {},
-//     );
-//
-//     const fp = useFrameProcessor((frame) => {
-//       'worklet';
-//       if (plugin == null) return;
-//       const result = plugin.call(frame, {
-//         path: '/path/to/output.jpg',
-//         quality: 75,  // 0-100; defaults to 75
-//       });
-//       // result: { ok: true, path, width, height }  OR
-//       //         { ok: false, error: "..." }
-//     }, [plugin]);
-//
-// ## Why a separate plugin (not folded into KeyframeGateFrameProcessor)
-//
-// `cv_flow_gate_process_frame` (the existing plugin) drives the lib's
-// FIRST-PARTY stitching pipeline: it consumes the frame, evaluates
-// the keyframe gate, dispatches into `IncrementalStitcher`.  It owns
-// state.
-//
-// `save_frame_as_jpeg` is STATELESS — a pure encode-and-write function.
-// Mixing them would force every JS-side caller of either to pay both
-// codepaths' arg-parsing costs (and would confuse the use-case
-// boundary).  Two plugins, one job each.
-//
-// ## CONDITIONAL COMPILATION
-//
-// Same `__has_include` guard as `KeyframeGateFrameProcessor.mm` — if
-// vision-camera isn't on the host's classpath, this file is a no-op
-// translation unit.  See that file's header for the rationale.
-
-#import <Foundation/Foundation.h>
-
-#if __has_include(<VisionCamera/FrameProcessorPlugin.h>)
-
-#import <VisionCamera/Frame.h>
-#import <VisionCamera/FrameProcessorPlugin.h>
-#import <VisionCamera/FrameProcessorPluginRegistry.h>
-#import <VisionCamera/VisionCameraProxyHolder.h>
-#import <CoreVideo/CoreVideo.h>
-#import <CoreImage/CoreImage.h>
-#import <UIKit/UIKit.h>
-
-@interface SaveFrameAsJpegPlugin : FrameProcessorPlugin
-@end
-
-@implementation SaveFrameAsJpegPlugin
-
-- (instancetype)initWithProxy:(VisionCameraProxyHolder*)proxy
-                   withOptions:(NSDictionary* _Nullable)options {
-  return [super initWithProxy:proxy withOptions:options];
-}
-
-// Helper: read a string arg with a fallback.  Returns nil only when
-// the arg is missing AND no fallback was supplied.
-static NSString* sfj_argString(NSDictionary* args, NSString* key,
-                                NSString* _Nullable fallback) {
-  id v = args[key];
-  if ([v isKindOfClass:[NSString class]]) return (NSString*)v;
-  return fallback;
-}
-
-// Helper: read a numeric arg (NSNumber or NSString-parseable) with a
-// fallback.  Matches the pattern in KeyframeGateFrameProcessor.mm.
-static double sfj_argDouble(NSDictionary* args, NSString* key,
-                             double fallback) {
-  id v = args[key];
-  if ([v isKindOfClass:[NSNumber class]]) return [(NSNumber*)v doubleValue];
-  if ([v isKindOfClass:[NSString class]]) return [(NSString*)v doubleValue];
-  return fallback;
-}
-
-// The host-callable plugin entry point.  vc dispatches each
-// `plugin.call(frame, args)` from a worklet here.
-//
-// ## Arguments
-//
-//   - `path` (string, REQUIRED): absolute filesystem path to write
-//     the JPEG to.  Parent directory must exist (we don't `mkdir -p`).
-//     Existing file is overwritten atomically.
-//   - `quality` (number, optional): 0-100 JPEG quality.  Default 75
-//     (matches `KeyframeGate.onAccept`'s encoder).  Clamped silently
-//     to `[1, 100]`.
-//
-// ## Returns
-//
-//   - On success: `{ ok: YES, path: <path>, width: <px>, height: <px> }`
-//   - On failure: `{ ok: NO, error: "<reason>" }`
-//
-// Errors are surfaced via the result dict, NOT thrown as `JSError` —
-// host worklets that want to react to encoder failures (e.g., to
-// rotate slot paths, or to back off) can branch on `result.ok`
-// without try/catch boilerplate.  Throwing would break the
-// Layer 3 `useFrameStream` flow which only sees the result.
-- (id)callback:(Frame*)frame withArguments:(NSDictionary*)arguments {
-  NSString* path = sfj_argString(arguments, @"path", nil);
-  if (path == nil) {
-    return @{@"ok": @NO, @"error": @"missing required `path` argument"};
-  }
-  double q = sfj_argDouble(arguments, @"quality", 75.0);
-  if (q < 1.0) q = 1.0;
-  if (q > 100.0) q = 100.0;
-
-  CMSampleBufferRef sampleBuffer = frame.buffer;
-  if (sampleBuffer == NULL) {
-    return @{@"ok": @NO, @"error": @"frame.buffer was NULL"};
-  }
-  CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
-  if (pixelBuffer == NULL) {
-    return @{@"ok": @NO, @"error": @"CMSampleBufferGetImageBuffer returned NULL"};
-  }
-
-  // CIImage → CGImage → UIImage → JPEG.  Standard iOS path; the
-  // CIContext + colorSpace are cheap to construct per-call (CoreImage
-  // caches GPU resources internally).  If profiling shows this in
-  // the hot path, lift the context to a static; for v0.9.0 baseline,
-  // per-call construction is fine.
-  CIImage* ciImage = [CIImage imageWithCVPixelBuffer:pixelBuffer];
-  if (ciImage == nil) {
-    return @{@"ok": @NO, @"error": @"CIImage imageWithCVPixelBuffer returned nil"};
-  }
-  CIContext* ctx = [CIContext context];
-  CGImageRef cgImage = [ctx createCGImage:ciImage fromRect:ciImage.extent];
-  if (cgImage == NULL) {
-    return @{@"ok": @NO, @"error": @"CIContext createCGImage failed"};
-  }
-  UIImage* uiImage = [UIImage imageWithCGImage:cgImage];
-  size_t width = CGImageGetWidth(cgImage);
-  size_t height = CGImageGetHeight(cgImage);
-  CGImageRelease(cgImage);
-
-  NSData* jpegData = UIImageJPEGRepresentation(uiImage, (CGFloat)(q / 100.0));
-  if (jpegData == nil) {
-    return @{@"ok": @NO, @"error": @"UIImageJPEGRepresentation returned nil"};
-  }
-
-  // Atomic write — under the hood NSData writes to a temp file then
-  // renames.  Avoids torn writes if a reader tries to open the path
-  // mid-write (would otherwise see a partial JPEG and choke).
-  NSError* err = nil;
-  BOOL ok = [jpegData writeToFile:path
-                          options:NSDataWritingAtomic
-                            error:&err];
-  if (!ok) {
-    NSString* msg = err.localizedDescription ?: @"NSData writeToFile returned NO";
-    return @{@"ok": @NO, @"error": msg};
-  }
-
-  return @{
-    @"ok": @YES,
-    @"path": path,
-    @"width": @(width),
-    @"height": @(height),
-  };
-}
-
-// Auto-register the plugin at class-load time.  Name must match what
-// JS passes to `VisionCameraProxy.initFrameProcessorPlugin('save_frame_as_jpeg')`.
-// Same pattern as KeyframeGateFrameProcessor's +load.
-+ (void)load {
-  [FrameProcessorPluginRegistry
-    addFrameProcessorPlugin:@"save_frame_as_jpeg"
-            withInitializer:^FrameProcessorPlugin* _Nonnull(
-                VisionCameraProxyHolder* proxy,
-                NSDictionary* _Nullable options) {
-              return [[SaveFrameAsJpegPlugin alloc]
-                  initWithProxy:proxy withOptions:options];
-            }];
-}
-
-@end
-
-#endif // __has_include(<VisionCamera/FrameProcessorPlugin.h>)