react-native-image-stitcher 0.14.2 → 0.15.1

package/src/stitching/ensureStitcherProxyInstalled.ts

@@ -1,141 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-import { NativeModules } from 'react-native';
-
-/**
- * v0.8.0 Phase 4b — one-shot installer that asks the native side
- * to install `globalThis.__stitcherProxy` on the main JS runtime.
- *
- * ## When this runs
- *
- * The first call to `useFrameProcessor` triggers this.  Idempotent:
- * once the global is installed, subsequent calls short-circuit.
- *
- * ## What it does
- *
- * Calls into the platform-native `StitcherJsiInstaller` RN module
- * which is registered with a `RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(install)`
- * on iOS (see `ios/Sources/RNImageStitcher/StitcherJsiInstaller.mm`)
- * and — Phase 4b.ii — an analogous Kotlin TurboModule on Android.
- *
- * The native module reaches into the main JS runtime via
- * `RCTCxxBridge.runtime` (iOS) / the equivalent Android JSI access
- * pattern and installs a host object on `globalThis.__stitcherProxy`
- * exposing `install(workletFn)` / `uninstall(id)` / `count()`.
- *
- * ## Failure modes (and what happens then)
- *
- * 1. **Module not registered** (Android in Phase 4b.i; old iOS
- *    builds without the new pod files).  `NativeModules
- *    .StitcherJsiInstaller` is `undefined`.  This function returns
- *    `false` and the hook falls back to the JS-side
- *    `StitcherWorkletRegistry` — host worklets are registered
- *    on the JS side but never fan out to AR mode.  No crash, no
- *    regression vs. Phase 4a.
- *
- * 2. **JSI runtime unreachable** (e.g., remote debug mode).  The
- *    sync method returns `false`.  Same JS-side-registry fallback.
- *
- * 3. **Native install succeeds but global not yet visible.**
- *    The native call is SYNCHRONOUS (`BLOCKING_SYNCHRONOUS_METHOD`),
- *    so by the time the function returns the global is installed.
- *    No race here.
- *
- * ## Why a separate module
- *
- * The install method is a one-time runtime bootstrap, not a
- * per-call API.  Putting it on its own RN module (vs. on the
- * existing `StitcherBridge` / `IncrementalStitcherBridge`) keeps
- * the responsibility surface narrow and the failure mode easy
- * to diagnose ("`__stitcherProxy` not installed" → check
- * `StitcherJsiInstaller` module registration first).
- */
-
-interface StitcherJsiInstallerModule {
-  install(): boolean;
-}
-
-/**
- * `__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(): boolean {
-  return typeof __DEV__ !== 'undefined' && __DEV__;
-}
-
-let installed = false;
-
-export function ensureStitcherProxyInstalled(): boolean {
-  if (installed) return true;
-  // Already installed by an earlier hook mount.  Cheap fast-path.
-  if (typeof (globalThis as { __stitcherProxy?: unknown }).__stitcherProxy !== 'undefined') {
-    installed = true;
-    return true;
-  }
-
-  const mod = (NativeModules as { StitcherJsiInstaller?: StitcherJsiInstallerModule })
-    .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`.
- */
-export function _resetStitcherProxyInstallStateForTests(): void {
-  installed = false;
-  warnedAboutMissingModule = false;
-  warnedAboutFailedInstall = false;
-}

package/src/stitching/useFrameProcessor.ts

@@ -1,226 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-import { useEffect, type DependencyList } from 'react';
-import {
-  useFrameProcessor as visionCameraUseFrameProcessor,
-  type DrawableFrameProcessor,
-  type Frame,
-  type ReadonlyFrameProcessor,
-} from 'react-native-vision-camera';
-
-import { ensureStitcherProxyInstalled } from './ensureStitcherProxyInstalled';
-import { StitcherWorkletRegistry } from './StitcherWorkletRegistry';
-import type { StitcherFrameProcessor } from './StitcherFrame';
-
-/**
- * Shape of the native-installed `globalThis.__stitcherProxy` host
- * object (iOS Phase 4b.i; Android Phase 4b.ii).  When present, the
- * hook prefers the native registry over the JS-side mirror — the
- * native AR worklet runtime reads from the native side directly.
- */
-interface StitcherProxy {
-  install(workletFn: StitcherFrameProcessor): string;
-  uninstall(id: string): void;
-  count(): number;
-}
-
-/**
- * v0.8.0 Phase 4a — public hook for hosts to attach a per-frame
- * worklet that runs in BOTH AR and non-AR capture modes.
- *
- * ## Quick start
- *
- * ```tsx
- * import { useFrameProcessor, type StitcherFrame } from 'react-native-image-stitcher';
- *
- * function MyOcrOverlay() {
- *   const processor = useFrameProcessor((frame: StitcherFrame) => {
- *     'worklet';
- *     // Pixel data is in `frame.toArrayBuffer()`.
- *     // AR-only fields: `frame.arDepth`, `frame.arAnchors`, `frame.arTrackingState`.
- *     // Discriminate via `frame.source === 'ar'` / `'vc'`.
- *   }, []);
- *   return <Camera frameProcessor={processor} ... />;
- * }
- * ```
- *
- * ## Two behaviours, depending on mode
- *
- * **Non-AR mode (today, fully working):** the worklet runs on
- * vision-camera's Frame Processor runtime.  Same thread + same
- * cost envelope as a plain `useFrameProcessor` from
- * `react-native-vision-camera`.  The lib's own first-party
- * stitching plugin runs alongside on the same producer-thread
- * runtime (composition is handled by vision-camera's own dispatch
- * order).
- *
- * Your worklet receives whatever vision-camera delivers — vc's raw
- * `Frame`.  This is a structural subset of `StitcherFrame`: the
- * vc-shaped fields (`width`, `height`, `pixelFormat`, `orientation`,
- * `timestamp`, `toArrayBuffer`) are guaranteed; the
- * `StitcherFrame`-only fields (`source`, `pose`, `arDepth`,
- * `arAnchors`, `arTrackingState`) are **undefined** at runtime
- * because the lib does NOT wrap or augment vc's `Frame` in Phase 4a
- * (cross-worklet-boundary field injection is Phase 4b work).
- * Worklets that need to read `source` / `pose` MUST guard for
- * `undefined`:
- *
- * ```ts
- * if (frame.source === 'ar') { ... }   // false in non-AR mode
- * if (frame.pose) { ... }              // skipped in non-AR mode
- * ```
- *
- * **AR mode — iOS Phase 4b.i (this release):** the worklet is
- * installed into the native registry via
- * `globalThis.__stitcherProxy.install(workletFn)`, where
- * `__stitcherProxy` is a JSI host object installed at lib
- * bootstrap by the native `StitcherJsiInstaller` module.  The
- * AR worklet runtime (`RNSARWorkletRuntime`) reads from the
- * native registry on each `dispatchFrame:pose:` call and fans
- * out invocations — your worklet fires alongside the lib's
- * first-party stitching path.
- *
- * **AR mode — Android Phase 4b.ii (deferred):** the native
- * installer + JNI bridge from `StitcherWorkletRuntime.kt`'s
- * `runFirstParty {...}` path to a parallel C++ registry land in
- * a follow-up release.  Until then, on Android the hook falls
- * back to the JS-side `StitcherWorkletRegistry`; AR-mode host
- * worklets register but do not invoke.  No regression vs.
- * Phase 4a; iOS gets the API first.
- *
- * ### When Phase 4b.ii lands (Android)
- *
- * The hook's call signature does NOT change.  Android hosts that
- * write code today against this API will see their worklets
- * start firing in AR mode automatically when Phase 4b.ii is
- * merged.  No migration required.
- *
- * ## Frame contract
- *
- * The worklet receives a {@link StitcherFrame} (see
- * `src/stitching/StitcherFrame.ts` for the full contract +
- * lifecycle).  Highlights:
- *
- *   - **`source`** discriminator: `'vc'` or `'ar'`.  Branch on this
- *     before reading `arDepth` / `arAnchors` / `arTrackingState`
- *     so non-AR captures don't break.
- *   - **`pose`** always present.  `pose.translation` is `undefined`
- *     in non-AR mode (gyro provides only rotation; no spatial
- *     anchor).
- *   - **Buffer lifetime**: pixel data is valid only for the
- *     duration of the worklet call.  Worklets that need to retain
- *     data must `toArrayBuffer()` synchronously inside the
- *     worklet body — returning a reference and reading it later
- *     reads freed memory.
- *
- * ## Threading
- *
- * The worklet runs on the producer thread (vision-camera's
- * runtime in non-AR mode; the AR-session callback thread under
- * Phase 4b).  Worklets MUST NOT block the producer thread for
- * more than a few ms — the next frame's processing is gated on
- * the previous frame returning.  Long work belongs on a queue
- * crossed via Reanimated / worklets-core's `runOnJS`.
- *
- * @param worklet  The host's frame processor function.  Must be
- *                 `'worklet'`-prefixed at the call site.  TS
- *                 cannot enforce the prefix; the runtime will
- *                 throw at attempt to invoke a non-worklet
- *                 function.
- * @param deps     Standard React deps array.  When `deps` change,
- *                 the previous registration is removed and the
- *                 new worklet is registered.  Same semantics as
- *                 vision-camera's `useFrameProcessor`.
- *
- * @returns A vision-camera frame-processor object that
- *          `<Camera frameProcessor={...}>` accepts.  In non-AR
- *          mode this is what drives the per-frame worklet
- *          invocation; in AR mode it's currently a no-op (vc
- *          isn't mounted in AR mode anyway).
- */
-export function useFrameProcessor(
-  worklet: StitcherFrameProcessor,
-  deps: DependencyList,
-): ReadonlyFrameProcessor | DrawableFrameProcessor {
-  // Non-AR path: delegate to vision-camera's hook.  The returned
-  // processor object is what `<Camera>` hands to vc.  Worklet
-  // fires on vc's producer-thread runtime.
-  //
-  // Cast rationale: vc's hook expects `(frame: Frame) => void`.
-  // Our worklet is typed `(frame: StitcherFrame) => void`.
-  // `StitcherFrame` is a structural superset of `Frame` (it adds
-  // required `source` + `pose` and the optional AR fields), so
-  // assigning a function that consumes `StitcherFrame` to a
-  // `Frame`-consuming slot is unsound at the type level — TS is
-  // right to reject the direct assignment.  At RUNTIME the worklet
-  // will see vc's raw `Frame`; the `source` / `pose` / AR fields
-  // are undefined (the hook's docstring above documents this and
-  // tells hosts to guard).  We double-cast through `unknown` to
-  // suppress, accepting the explicit type-system gap as the price
-  // of Phase 4a's pre-Phase-4b deferral on cross-runtime frame
-  // wrapping.
-  const vcProcessor = visionCameraUseFrameProcessor(
-    worklet as unknown as (frame: Frame) => void,
-    deps,
-  );
-
-  // AR path: install into the native registry if available (iOS
-  // Phase 4b.i — and Android Phase 4b.ii once it lands).  Falls
-  // back to the JS-side `StitcherWorkletRegistry` when the native
-  // installer isn't present (Android in 4b.i; remote debug mode;
-  // unit tests).  The fallback path matches Phase 4a's
-  // register-but-not-invoke semantics.
-  //
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  useEffect(() => {
-    const nativeReady = ensureStitcherProxyInstalled();
-    if (
-      nativeReady &&
-      typeof (globalThis as { __stitcherProxy?: StitcherProxy }).__stitcherProxy !== 'undefined'
-    ) {
-      // Native path — install through the JSI proxy.  Errors here
-      // most commonly mean the worklet doesn't have the
-      // `'worklet'` directive at the call site (the worklets-core
-      // babel plugin didn't transform it).  Surface them via the
-      // proxy's own throw with a host-side log so the failure is
-      // obvious.
-      let id: string | undefined;
-      try {
-        id = (globalThis as unknown as { __stitcherProxy: StitcherProxy }).__stitcherProxy.install(
-          worklet,
-        );
-      } catch (err) {
-        // Guard `__DEV__` read so the hook works in any environment
-        // that imports it without defining the flag (jest, SSR,
-        // custom tooling).
-        if (typeof __DEV__ !== 'undefined' && __DEV__) {
-          console.error(
-            '[react-native-image-stitcher] __stitcherProxy.install ' +
-              'threw — is the worklet function decorated with ' +
-              "`'worklet';` and processed by react-native-worklets-core's " +
-              'babel plugin?  Original error: ' +
-              String(err),
-          );
-        }
-        return; // No cleanup needed — nothing was installed.
-      }
-      return () => {
-        try {
-          (globalThis as unknown as { __stitcherProxy: StitcherProxy }).__stitcherProxy.uninstall(id!);
-        } catch {
-          // Uninstall is best-effort; an exception here means the
-          // proxy was already gone (e.g., app reload mid-cleanup).
-        }
-      };
-    }
-
-    // Fallback — JS-side registry.  Same as Phase 4a.
-    const jsId = StitcherWorkletRegistry.register({
-      worklet,
-      isFirstParty: false,
-    });
-    return () => StitcherWorkletRegistry.unregister(jsId);
-  }, deps);
-
-  return vcProcessor;
-}

package/src/stitching/useFrameStream.ts

@@ -1,271 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// v0.9.0 Layer 3 — JS-thread sampled-frame stream over Layer 1 +
-// Layer 2.
-//
-// ## What this is
-//
-// A hook that:
-//   1. Throttles a worklet via `useThrottledFrameProcessor` (Layer 2)
-//      to fire at `sampleHz` Hz.
-//   2. Inside the worklet, calls the `save_frame_as_jpeg` vc Frame
-//      Processor plugin (Layer 1) to JPEG-encode the frame to a
-//      bounded-rotation slot on disk.
-//   3. Bridges the resulting `SampledFrame` (file path + pose +
-//      dims) to a JS-thread callback via `runOnJS`.
-//
-// The host gets a per-sample callback on the JS thread with a file
-// path they can pass to `<Image>`, an OCR RN module, a cloud-upload
-// library, etc.  Zero worklet boilerplate.
-//
-// ## When to use this (vs alternatives)
-//
-//   - **`useFrameStream`** (this hook) — JS-thread consumers.  File-
-//     path OCR libraries, cloud upload, thumbnail UI, sampled
-//     server-side analysis.
-//   - **`useThrottledFrameProcessor`** (Layer 2) — worklet-native
-//     consumers.  Native OCR (Vision.framework / ML Kit) wrapped as
-//     vc plugins, TFLite ML inference, LiDAR depth processing.
-//     Lower latency; no JPEG roundtrip.
-//   - **`useFrameProcessor`** — every camera frame; full control.
-//
-// ## Slot reuse / disk usage
-//
-// JPEG files are written to `<outputDir>/stream-<N>.jpg` where N
-// cycles 0..3 based on `frame.timestamp / 1000`.  At most 4 stale
-// JPEGs ever exist on disk; the same file is rewritten on each
-// rotation, so disk usage is bounded.
-//
-// Hosts that need long-term retention (e.g., archive each sample
-// for later upload) MUST copy the file synchronously inside the
-// handler — the slot may be overwritten by the next sample.
-//
-// ## Backpressure
-//
-// If the JS handler returns slower than `1/sampleHz`, subsequent
-// ticks DO still fire (the throttle is time-based, not handler-
-// completion-based).  This means multiple handler invocations can
-// be in flight simultaneously.  For most use cases that's fine
-// (the handlers are pure or commute).  Hosts that need serialised
-// handling should track in-flight state themselves and early-return.
-//
-// ## AR vs non-AR
-//
-// Works in both modes because it composes over
-// `useThrottledFrameProcessor` → `useFrameProcessor`.  In AR mode
-// the worklet auto-registers via `__stitcherProxy` (v0.8.0 Phase
-// 4b.i/iii); in non-AR mode the returned processor object is
-// passed to `<Camera frameProcessor={...}>`.  The hook returns
-// the processor object so hosts can wire it up either way.
-
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import {
-  VisionCameraProxy,
-  type Frame,
-  type FrameProcessorPlugin,
-} from 'react-native-vision-camera';
-import { Worklets } from 'react-native-worklets-core';
-
-import { useThrottledFrameProcessor } from './useThrottledFrameProcessor';
-import type { StitcherFrame } from './StitcherFrame';
-import type {
-  FrameStreamOptions,
-  SampledFrame,
-} from '../types';
-import { getDefaultCaptureDir } from '../utils/files';
-
-/**
- * `useFrameStream` — Layer 3.  See module docstring for the full
- * design + use-case mapping.  Quick start:
- *
- * ```tsx
- * import { Camera, useFrameStream } from 'react-native-image-stitcher';
- *
- * function MyScreen() {
- *   const fp = useFrameStream(
- *     { sampleHz: 2, quality: 75 },
- *     (sample) => {
- *       setThumbnail(sample.jpegPath);
- *     },
- *   );
- *   return <Camera frameProcessor={fp} ... />;
- * }
- * ```
- *
- * @param options  `{ sampleHz, quality?, outputDir? }`.  `sampleHz`
- *                 clamped to `[0.5, 10]`.
- * @param handler  JS-thread callback fired per sample.  Receives a
- *                 `SampledFrame`.  May return a Promise; rejections
- *                 are caught + logged (not re-thrown) so one
- *                 misbehaving handler doesn't break the stream.
- *
- * @returns A `useFrameProcessor`-shaped processor object — pass to
- *          `<Camera frameProcessor={...}>` for non-AR mode wiring.
- *          (AR mode auto-registration via `__stitcherProxy` is
- *          handled inside `useFrameProcessor`.)
- */
-export function useFrameStream(
-  options: FrameStreamOptions,
-  handler: (sample: SampledFrame) => void | Promise<void>,
-): ReturnType<typeof useThrottledFrameProcessor> {
-  const sampleHz = Math.max(0.5, Math.min(10, options.sampleHz));
-  const quality = options.quality ?? 75;
-
-  // 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] = useState<string>('');
-  useEffect(() => {
-    if (options.outputDir != null) return;
-    let cancelled = false;
-    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]);
-
-  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
-  // captures).
-  const handlerRef = useRef(handler);
-  handlerRef.current = handler;
-
-  const onSampleJS = useCallback((sample: SampledFrame) => {
-    const result = handlerRef.current(sample);
-    if (
-      result != null &&
-      typeof (result as Promise<void>).catch === 'function'
-    ) {
-      (result as Promise<void>).catch((err) => {
-        // eslint-disable-next-line no-console
-        console.error('[useFrameStream] handler threw:', err);
-      });
-    }
-  }, []);
-
-  const onSampleOnJS = useMemo(
-    () => Worklets.createRunOnJS(onSampleJS),
-    [onSampleJS],
-  );
-
-  // ── Plugin acquisition (Layer 1) ─────────────────────────────────
-  //
-  // `initFrameProcessorPlugin` can return `undefined` if the native
-  // registry hasn't initialised yet (rare race on app start).  We
-  // retry every 16ms (one display frame) until success — matches
-  // the pattern in `useFrameProcessorDriver`.
-  //
-  // 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] = useState<FrameProcessorPlugin | null>(null);
-  useEffect(() => {
-    let cancelled = false;
-    let timerId: ReturnType<typeof setTimeout> | null = null;
-    let attempts = 0;
-    const tryAcquire = () => {
-      if (cancelled) return;
-      attempts += 1;
-      const p = VisionCameraProxy.initFrameProcessorPlugin(
-        'save_frame_as_jpeg',
-        {},
-      );
-      if (p != null) {
-        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();
-    return () => {
-      cancelled = true;
-      if (timerId != null) clearTimeout(timerId);
-    };
-  }, []);
-
-  return useThrottledFrameProcessor(
-    (frame: StitcherFrame) => {
-      '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.
-      // That's overkill for the "stream-of-samples" use case but
-      // matches the docstring's "at most 4 stale JPEGs" guarantee.
-      const slot = Math.floor(frame.timestamp / 1000) % 4;
-      const path = `${outputDir}/stream-${slot}.jpg`;
-
-      // vc's `FrameProcessorPlugin.call` expects vc's `Frame` type.
-      // `StitcherFrame` is structurally a superset (it adds `source`,
-      // `pose`, AR-only fields).  Cast through `unknown` — same
-      // pattern v0.8.0's `useFrameProcessor` uses when handing a
-      // StitcherFrame-typed worklet to vc.
-      const result = plugin.call(frame as unknown as Frame, {
-        path,
-        quality,
-      });
-      if (
-        result == null ||
-        (result as { ok?: boolean }).ok !== true
-      ) {
-        // Native side reported an error (path not writable, format
-        // wrong, etc.).  Silently skip this sample — the next tick
-        // will retry.  The plugin already logs the specific reason
-        // on the native side.
-        return;
-      }
-      const r = result as {
-        path: string;
-        width: number;
-        height: number;
-      };
-
-      onSampleOnJS({
-        jpegPath: r.path,
-        pose: frame.pose,
-        timestamp: frame.timestamp,
-        width: r.width,
-        height: r.height,
-      });
-    },
-    { sampleHz },
-    [plugin, outputDir, quality, onSampleOnJS],
-  );
-}