react-native-image-stitcher 0.15.2 → 0.16.1

package/src/index.ts

@@ -28,6 +28,7 @@ export { Camera, CameraError } from './camera/Camera';
 export type {
   CameraProps,
   CameraCaptureResult,
+  PanoramaCaptureResult,
   CameraErrorCode,
   CaptureSource,
   CaptureSourcesMode,
@@ -38,12 +39,29 @@ export type {
   Warper,
   FramesDroppedInfo,
 } from './camera/Camera';
+// Non-fatal capture quality signals carried on `CameraCaptureResult.warnings`.
+export type {
+  CaptureWarning,
+  CaptureWarningCode,
+  CaptureWarningCopy,
+} from './camera/captureWarnings';
+// Default English warning templates (single source of truth; re-used by
+// `DEFAULT_GUIDANCE_COPY`).  Exposed so a host can diff / extend them.
+export { DEFAULT_CAPTURE_WARNING_COPY } from './camera/captureWarnings';
 
 // Recoverable-stitch-failure → friendly Alert copy.  Hosts call this in
 // their onError handler to surface actionable guidance ("pan more slowly",
-// "pivot in place") instead of the raw cv::Stitcher diagnostic.
-export { userFacingStitchError } from './camera/cameraErrorMessages';
-export type { UserFacingStitchError } from './camera/cameraErrorMessages';
+// "pivot in place") instead of the raw cv::Stitcher diagnostic.  Pass an
+// `overrides` map (keyed by `RECOVERABLE_STITCH_CODES`) to localise it.
+export {
+  userFacingStitchError,
+  RECOVERABLE_STITCH_GUIDANCE,
+  RECOVERABLE_STITCH_CODES,
+} from './camera/cameraErrorMessages';
+export type {
+  UserFacingStitchError,
+  UserFacingStitchErrorOverrides,
+} from './camera/cameraErrorMessages';
 
 // ─────────────────────────────────────────────────────────────────────
 // AR foundation (public since 0.1.0)
@@ -174,6 +192,51 @@ export type { UseOrientationDriftReturn } from './camera/useOrientationDrift';
 export { OrientationDriftModal } from './camera/OrientationDriftModal';
 export type { OrientationDriftModalProps } from './camera/OrientationDriftModal';
 
+// ── Panorama capture GUIDANCE (feature/pano-ux-guidance) ──────────────
+// The first-time-user pan-capture guidance surfaces, wired into Layer-1
+// <Camera> automatically (panMode / panGuidance / maxPanDurationMs /
+// lateralBudgetCm / rectCrop / showPreview / guidanceCopy props).  Exported for
+// Layer-2 hosts composing their own capture UX on CameraView + the
+// incremental engine.
+//
+// `PanMode` is the landscape-only-vs-both flag; `GuidanceCopy` +
+// `DEFAULT_GUIDANCE_COPY` are the overridable copy surface.
+export type { PanMode } from './camera/panModeGate';
+export {
+  DEFAULT_GUIDANCE_COPY,
+} from './camera/cameraGuidanceCopy';
+export type { GuidanceCopy } from './camera/cameraGuidanceCopy';
+// Shared motion hook — one gyro + one accelerometer subscription feeding
+// the pan-speed bucket (item 4) and the lateral-drift latch (item 6).
+export { usePanMotion } from './camera/usePanMotion';
+export type {
+  UsePanMotionOptions,
+  UsePanMotionReturn,
+  PanSpeedBucket,
+  PanAxis,
+} from './camera/usePanMotion';
+// Presentational guidance surfaces (each renders null when not visible).
+export { RotateToLandscapePrompt } from './camera/RotateToLandscapePrompt';
+export type { RotateToLandscapePromptProps } from './camera/RotateToLandscapePrompt';
+export { PanHowToOverlay } from './camera/PanHowToOverlay';
+export type { PanHowToOverlayProps } from './camera/PanHowToOverlay';
+export { CaptureCountdownOverlay } from './camera/CaptureCountdownOverlay';
+export type { CaptureCountdownOverlayProps } from './camera/CaptureCountdownOverlay';
+export { CaptureFrameCounterOverlay } from './camera/CaptureFrameCounterOverlay';
+export type { CaptureFrameCounterOverlayProps } from './camera/CaptureFrameCounterOverlay';
+export { LateralMotionModal } from './camera/LateralMotionModal';
+export type { LateralMotionModalProps } from './camera/LateralMotionModal';
+export { RectCropPreview } from './camera/RectCropPreview';
+export type {
+  RectCropPreviewProps,
+  RectCropResult,
+  ImageRect,
+} from './camera/RectCropPreview';
+// Native perspective-rectify crop used by RectCropPreview's confirm
+// path; hosts driving their own crop UI call it directly.
+export { cropQuad } from './stitching/cropQuad';
+export type { CropQuadOptions, CropQuadResult } from './stitching/cropQuad';
+
 // ── Incremental stitching engine ──────────────────────────────────────
 // JS bindings around the native `IncrementalStitcher` module.  Use
 // these when you need finer control than <Camera>'s built-in

package/src/stitching/computeInscribedRect.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * computeInscribedRect — resolve the largest axis-aligned rectangle that
+ * fits entirely inside the non-black (coverage) region of a stitched
+ * panorama, via native `BatchStitcher.computeInscribedRect`.
+ *
+ * Used to SEED the post-capture crop editor (`RectCropPreview`): instead of
+ * a blind 8 %-inset rectangle, the editor opens on the max-inscribed rect —
+ * the tightest clean rectangle with no black corners — which the user then
+ * fine-tunes.  Best-effort: callers fall back to the default inset seed if
+ * the native module is absent or the call rejects.
+ *
+ * Same native module + defensive-availability posture as
+ * `src/stitching/cropQuad.ts` and `src/quality/normaliseOrientation.ts`.
+ * The native side (Android `BatchStitcher.computeInscribedRect`, iOS
+ * `OpenCVStitcher.computeInscribedRect`) is the exact `maxInscribedRectFromMask`
+ * port used by the opt-in auto-crop, so the seed matches what that crop would
+ * pick — only here the user can then drag outward to keep more content.
+ */
+
+import { NativeModules } from 'react-native';
+
+
+/** Resolved max-inscribed rectangle, in image-pixel coords. */
+export interface InscribedRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Intrinsic dimensions of the source image the rect was computed on. */
+  imageWidth: number;
+  imageHeight: number;
+}
+
+/** The shape of the native module method we call. */
+interface InscribedRectNativeModule {
+  computeInscribedRect: (options: {
+    imagePath: string;
+  }) => Promise<InscribedRect>;
+}
+
+
+/**
+ * Resolve the native `computeInscribedRect` function off
+ * `NativeModules.BatchStitcher`, or `null` when the module / method isn't
+ * registered (e.g. an older native build).
+ */
+function resolveComputeInscribedRect():
+  | InscribedRectNativeModule['computeInscribedRect']
+  | null {
+  const native: unknown =
+    (NativeModules as Record<string, unknown>)['BatchStitcher'];
+  if (
+    native
+    && typeof native === 'object'
+    && typeof (native as { computeInscribedRect?: unknown })
+      .computeInscribedRect === 'function'
+  ) {
+    return (native as InscribedRectNativeModule).computeInscribedRect;
+  }
+  return null;
+}
+
+
+/**
+ * Compute the max-inscribed rectangle of `imagePath`'s coverage mask.
+ *
+ * @param imagePath  file:// URI or bare path of the stitched image (the
+ *                   native side strips the scheme).
+ * @returns the inscribed rect, or `null` when the native module isn't
+ *   registered (older native build) — callers then fall back to the default
+ *   seed.  REJECTS only if the native call itself errors (decode / read
+ *   failure); callers should catch and treat the rejection as "no seed".
+ */
+export async function computeInscribedRect(
+  imagePath: string,
+): Promise<InscribedRect | null> {
+  const fn = resolveComputeInscribedRect();
+  if (!fn) return null;
+  return fn({ imagePath });
+}

package/src/stitching/cropQuad.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * cropQuad — item-7 perspective crop: rectify a user-dragged
+ * quadrilateral to an upright rectangle.
+ *
+ * The post-capture crop editor (`src/camera/RectCropPreview.tsx`) lets the
+ * user drag 4 independent corners over the stitched result.  When that
+ * quad isn't ~axis-aligned, the host calls THIS wrapper instead of the
+ * cheap `cropToRect`: it hands the 4 IMAGE-PIXEL corners to the native
+ * `BatchStitcher.cropToQuad`, which runs
+ * `cv::getPerspectiveTransform` + `cv::warpPerspective` to produce an
+ * upright rectangle (averaged opposite-edge dimensions) and overwrites the
+ * file in place.
+ *
+ * This is the typed twin of the `cropToRect` call in
+ * `example/InscribedRectDebug.tsx` — same native module (`BatchStitcher`),
+ * same in-place overwrite + `{ width, height }` result contract, same
+ * platform-availability fallback posture as
+ * `src/quality/normaliseOrientation.ts`.
+ *
+ * Corner-order contract: `quadImagePoints` MUST be in canonical
+ * [TL, TR, BR, BL] (clockwise from top-left) order — exactly what
+ * `cropGeometry.ts:orderQuadCorners` produces and `RectCropResult.quad`
+ * carries.  The native side rectifies into a rectangle whose corners map
+ * TL→(0,0), TR→(w,0), BR→(w,h), BL→(0,h); pass un-ordered points and the
+ * output is mirrored / rotated.
+ */
+
+import { NativeModules, Platform } from 'react-native';
+
+import type { Point, Quad } from '../camera/cropGeometry';
+
+
+/** Options for {@link cropQuad}. */
+export interface CropQuadOptions {
+  /**
+   * JPEG quality for the re-encoded output, 1–100.  Defaults to 90 (the
+   * native default, matching `cropToRect`).
+   */
+  quality?: number;
+}
+
+/** Resolved result of a successful {@link cropQuad}. */
+export interface CropQuadResult {
+  /**
+   * The file the rectified image was written to.  Equals the input
+   * `imagePath` (the native crop overwrites in place) — surfaced
+   * explicitly so callers don't have to assume the in-place contract.
+   */
+  outputPath: string;
+  /** Width of the rectified rectangle, in pixels. */
+  width: number;
+  /** Height of the rectified rectangle, in pixels. */
+  height: number;
+}
+
+
+/** The shape of the native module method we call. */
+interface CropQuadNativeModule {
+  cropToQuad: (options: {
+    imagePath: string;
+    quad: number[];
+    quality: number;
+  }) => Promise<{ width: number; height: number }>;
+}
+
+
+/**
+ * Resolve the native `cropToQuad` function off `NativeModules.BatchStitcher`,
+ * or `null` when the module / method isn't registered (e.g. an older native
+ * build).  Same defensive lookup as `normaliseOrientation`.
+ */
+function resolveCropToQuad(): CropQuadNativeModule['cropToQuad'] | null {
+  const native: unknown =
+    (NativeModules as Record<string, unknown>)['BatchStitcher'];
+  if (
+    native
+    && typeof native === 'object'
+    && typeof (native as { cropToQuad?: unknown }).cropToQuad === 'function'
+  ) {
+    return (native as CropQuadNativeModule).cropToQuad;
+  }
+  return null;
+}
+
+
+/**
+ * Flatten the 4 ordered ([TL, TR, BR, BL]) image-pixel corners into the
+ * `[tlX, tlY, trX, trY, brX, brY, blX, blY]` array the native module
+ * expects.  Exported for unit tests + reuse.
+ */
+export function flattenQuad(quad: Quad): number[] {
+  const out: number[] = [];
+  for (const p of quad as ReadonlyArray<Point>) {
+    out.push(p.x, p.y);
+  }
+  return out;
+}
+
+
+/**
+ * Perspective-rectify `quadImagePoints` out of `imagePath` into an upright
+ * rectangle, overwriting the file in place, and resolve the output path +
+ * rectified dimensions.
+ *
+ * @param imagePath        file:// URI (or bare path) of the image to crop.
+ * @param quadImagePoints  the 4 corners in IMAGE-PIXEL space, canonically
+ *                         ordered [TL, TR, BR, BL] (use
+ *                         `orderQuadCorners`).  This is exactly
+ *                         `RectCropResult.quad`.
+ * @param outPath          where to write the result.  The native crop
+ *                         OVERWRITES IN PLACE, so this currently MUST equal
+ *                         `imagePath` (or be omitted — defaults to it).
+ *                         Passing a different path throws, surfacing the
+ *                         limitation rather than silently ignoring it; see
+ *                         the integrator note in the item-7 handoff.
+ * @param opts             optional `{ quality }`.
+ *
+ * @throws if the native module isn't registered, if `outPath` differs from
+ *         `imagePath`, or if the native crop rejects (degenerate quad,
+ *         canvas guard, write failure).
+ */
+export async function cropQuad(
+  imagePath: string,
+  quadImagePoints: Quad,
+  outPath?: string,
+  opts?: CropQuadOptions,
+): Promise<CropQuadResult> {
+  if (outPath !== undefined && outPath !== imagePath) {
+    // The native cropToQuad (like cropToRect) only overwrites in place.
+    // Fail loudly rather than silently writing to imagePath and returning
+    // a path the file isn't at.
+    throw new Error(
+      '[capture-sdk] cropQuad: native crop overwrites in place; '
+      + 'outPath must equal imagePath (or be omitted).',
+    );
+  }
+
+  const fn = resolveCropToQuad();
+  if (!fn) {
+    throw new Error(
+      `[capture-sdk] cropQuad: native module BatchStitcher.cropToQuad not `
+      + `available on ${Platform.OS}.  Ensure the native module is registered.`,
+    );
+  }
+
+  const quality = clampQuality(opts?.quality);
+  const dims = await fn({
+    imagePath,
+    quad: flattenQuad(quadImagePoints),
+    quality,
+  });
+  return {
+    outputPath: imagePath,
+    width: dims.width,
+    height: dims.height,
+  };
+}
+
+
+/** Clamp the requested JPEG quality into [1, 100]; default 90. */
+function clampQuality(quality?: number): number {
+  if (quality === undefined || Number.isNaN(quality)) return 90;
+  if (quality < 1) return 1;
+  if (quality > 100) return 100;
+  return Math.round(quality);
+}

package/src/stitching/incremental.ts

@@ -682,6 +682,50 @@ export interface IncrementalFinalizeResult {
    * on the just-completed capture.
    */
   stitchModeResolved?: 'panorama' | 'scans';
+  /**
+   * 2026-06-15 (DEV) — gyro rotation magnitude of the capture, in RADIANS
+   * (angle between the first and last accepted keyframe camera-forward vectors).
+   * Surfaced so a dev tool can display it and tune the panorama-vs-SCANS
+   * rotation threshold from real captures. `0` when there is no pose-derived
+   * rotation signal (non-AR with no poses) — not necessarily "no rotation".
+   */
+  rRadians?: number;
+  /**
+   * 2026-06-16 (DEV) — translation magnitude (metres) and the auto decision
+   * ratio (`tScore/(tScore+rScore)`, `>=0.55` → SCANS) that drove the
+   * panorama-vs-SCANS choice. Surfaced alongside `rRadians` so a dev tool can
+   * display the full decision inputs and tune the threshold from real captures.
+   * `0` when there is no motion signal (non-AR with no poses / no movement).
+   */
+  tMeters?: number;
+  decisionRatio?: number;
+  /**
+   * 2026-06-14 (DEV overlay) — a semicolon-separated `key=value` trace of the
+   * stitcher's RUNTIME choices for this output, e.g.
+   * `"pipe=manual;warp=spherical;route=batch;seam=graphcut;blend=multiband"`.
+   *   pipe:  `manual` (cv::detail) | `highlevel` (cv::Stitcher)
+   *   warp:  `plane` | `cylindrical` | `spherical`
+   *   route: `batch` (warp-all + seam) | `stream` (low-memory per-frame)
+   *   seam:  `graphcut` | `none`
+   *   blend: `multiband` | `feather`
+   * Intended for a __DEV__-only overlay so the operator can see HOW the
+   * panorama was built (which warper, whether the low-memory stream/feather
+   * fallback kicked in, etc.).  iOS only for now; undefined elsewhere.
+   */
+  debugSummary?: string;
+  /**
+   * 2026-06-15 (iOS) — the exact keyframe JPEG paths used for this stitch.
+   * Lets the host re-stitch the SAME frames on demand via `refinePanorama`
+   * (e.g. the high-level preview tab) without re-running the capture or
+   * enumerating the session directory.  iOS only; undefined elsewhere.
+   */
+  batchKeyframePaths?: string[];
+  /**
+   * 2026-06-15 (iOS) — the capture orientation this stitch baked into the
+   * output.  An on-demand re-stitch (refinePanorama) MUST pass this back or the
+   * result comes out in the raw sensor landscape (sideways).  iOS only.
+   */
+  captureOrientation?: string;
 }
 
 
@@ -750,6 +794,15 @@ export interface IncrementalRefineOptions {
   stitchMode?: 'auto' | 'panorama' | 'scans';
   /** JPEG quality 1..100, default 90. */
   jpegQuality?: number;
+  /**
+   * 2026-06-15 (iOS) — which stitch pipeline to run.  `true` = the manual
+   * `cv::detail` pipeline (the default batch-capture output); `false` = stock
+   * high-level `cv::Stitcher`.  Default `false` on the refine path.  This is
+   * how the on-demand "high-level" preview tab re-stitches the captured
+   * keyframes via cv::Stitcher without re-running the whole capture.  iOS only
+   * (Android refine is always cv::Stitcher).
+   */
+  useManualPipeline?: boolean;
 }
 
 
@@ -771,6 +824,15 @@ export interface IncrementalRefineResult {
   framesDropped: number;
   /** The confidence threshold that succeeded.  -1 when not applicable. */
   finalConfidenceThresh: number;
+  /**
+   * 2026-06-15 (DEV overlay A/B-aware) — the stitcher's own semicolon-separated
+   * `key=value` runtime recipe for THIS refined output, e.g.
+   * `"pipe=highlevel;warp=spherical;route=batch;seam=graphcut;blend=multiband"`.
+   * Mirrors `IncrementalFinalizeResult.debugSummary`.  Lets the on-demand
+   * high-level preview tab show its OWN recipe in the __DEV__ overlay pill
+   * instead of the manual primary's recipe.  iOS only; undefined elsewhere.
+   */
+  debugSummary?: string;
 }
 
 
@@ -852,6 +914,14 @@ interface NativeIncrementalModule {
      * are zero, matching legacy behaviour.
      */
     imuTranslationMetres?: number;
+    /**
+     * 2026-06-16 — the explicit lens the user selected (`'1x'` | `'0.5x'`).
+     * The reliable zoom signal for the high-level warper tree: `'0.5x'`
+     * (ultra-wide) → spherical warper.  Replaces deriving zoom from the
+     * intrinsics FOV (unreliable on multi-cam 0.5x / non-AR fx=0).  Omitted →
+     * treated as `'1x'`.
+     */
+    lens?: string;
   }): Promise<IncrementalFinalizeResult>;
   cancel(): Promise<{ ok: true }>;
   getState(): Promise<IncrementalState | null>;
@@ -877,6 +947,10 @@ interface NativeIncrementalModule {
    *  one-true-number for "how close are we to OOM?".  Returns -1
    *  on task_info failure (very rare).  Resolves immediately. */
   getMemoryFootprintMB(): Promise<number>;
+  /** 2026-06-16 — total physical RAM in MB.  Lets the DEV memory pill derive
+   *  RAM-aware pressure bands instead of iPhone-fixed thresholds.  -1 on
+   *  failure.  Resolves immediately. */
+  getDeviceTotalRamMB?(): Promise<number>;
   /**
    * 2026-05-16 — realtime+batch fusion API foundation.  Run the
    * shared C++ `cv::Stitcher` pipeline over a caller-supplied list

package/src/stitching/useIncrementalStitcher.ts

@@ -85,6 +85,12 @@ export interface UseIncrementalStitcherReturn {
      * translation magnitude and prefers that).
      */
     imuTranslationMetres?: number,
+    /**
+     * 2026-06-16 — the EXPLICIT lens the user selected (`'1x'` | `'0.5x'`).
+     * The reliable zoom signal for the high-level warper tree (`'0.5x'`
+     * ultra-wide → spherical).  Omit ⇒ treated as `'1x'`.
+     */
+    lens?: string,
   ) => Promise<IncrementalFinalizeResult>;
   /** Abort the capture without producing output. */
   cancel: () => Promise<void>;
@@ -198,6 +204,7 @@ export function useIncrementalStitcher(): UseIncrementalStitcherReturn {
       quality = 90,
       captureOrientation?: string,
       imuTranslationMetres?: number,
+      lens?: string,
     ): Promise<IncrementalFinalizeResult> => {
       if (!native) {
         throw new Error('useIncrementalStitcher: native module unavailable');
@@ -216,6 +223,12 @@ export function useIncrementalStitcher(): UseIncrementalStitcherReturn {
         // doesn't carry tx/ty/tz, so pose-derived translation is 0).
         // Native side treats it as a magnitude (always ≥ 0).
         imuTranslationMetres: Math.max(0, imuTranslationMetres ?? 0),
+        // 2026-06-16 — the EXPLICIT lens the user selected ('1x' | '0.5x').
+        // This is the reliable zoom signal for the high-level warper tree
+        // (0.5x ultra-wide → spherical); deriving zoom from intrinsics FOV was
+        // unreliable (multi-cam 0.5x reaches the ultra-wide by zoom without
+        // changing the reported fx, and the non-AR path may supply fx=0).
+        lens,
       });
       setIsRunning(false);
       // Clear React state on finalize so the next start doesn't

package/android/src/main/java/io/imagestitcher/rn/TransferredNV21.kt

@@ -1,100 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-package io.imagestitcher.rn
-
-/**
- * v0.10.0 (audit #4A) — single-use NV21 byte-array handle that
- * enforces the engine's pixel-data ownership contract at runtime.
- *
- * ## Why this exists
- *
- * `IncrementalStitcher.ingestFromARCameraView` accepts an
- * `nv21PixelData` parameter that the engine retains for ~50 ms
- * after the producer thread returns (until the `workScope`
- * coroutine consumes it).  The documented contract is
- * "callers MUST treat the array as transferred — do not mutate it
- * or return it to a buffer pool after calling this method."
- *
- * The v0.10.0 audit (`docs/plans/handoff/2026-05-26-autonomous-run-handoff.md`
- * finding #4A) noted this is by-convention only.  The current AR
- * caller (`RNSARCameraView`) passes the same `packed.nv21` array
- * as BOTH `grayData` (consumed synchronously inside the gate)
- * AND `nv21PixelData` (consumed asynchronously).  Today no race
- * because the sync read finishes before the async coroutine reads,
- * but a future refactor that reorders consumption would silently
- * corrupt frames.
- *
- * Wrapping the bytes in `TransferredNV21` turns the documentation
- * contract into a runtime contract: callers can only extract the
- * bytes once via `takeOnce()`; the second call throws.  The
- * misuse is caught at the call site, not at the engine.
- *
- * ## Cost
- *
- * Construction: tens of ns (one heap allocation for the wrapper +
- * one volatile write of the bytes reference).  `takeOnce()`: tens
- * of ns (one synchronized read + one null-out).  Negligible vs the
- * underlying NV21 array's KB-scale memory footprint and the
- * ms-scale frame-processing cost — but not a free pointer hop.
- *
- * ## Thread-safety
- *
- * `takeOnce()` and `available` are `synchronized` on the wrapper
- * itself.  Producers should still extract on a single thread (the
- * frame producer); the synchronization defends against the
- * pathological case where two threads race to extract.
- */
-class TransferredNV21(bytes: ByteArray) {
-    init {
-        // Empty arrays would propagate as "0 bytes of pixel data with
-        // a non-zero width/height" downstream and crash inside the
-        // C++ ingest with a far less actionable error.  Catch at
-        // construction.  Critic-finding [MAJOR][B].
-        require(bytes.isNotEmpty()) {
-            "TransferredNV21 requires a non-empty byte array " +
-                "(received zero-length)"
-        }
-    }
-
-    @Volatile
-    private var bytes: ByteArray? = bytes
-
-    /**
-     * Take the wrapped bytes.  Throws on second call.
-     *
-     * Consumers should call this exactly once — typically once per
-     * frame, on the producer thread, immediately before handing
-     * the bytes to the async work queue:
-     *
-     * ```kotlin
-     * val pixelBytes: ByteArray? = if (hasPixelData) nv21PixelData!!.takeOnce() else null
-     * workScope.launch {
-     *     // pixelBytes is captured by value; no race.
-     *     engine.addFramePixelData(nv21 = pixelBytes!!, ...)
-     * }
-     * ```
-     *
-     * Concurrency note: `@Volatile` on the bytes field plus the
-     * `synchronized(this)` block here together guarantee both
-     * visibility AND atomicity across threads.  The `@Volatile` is
-     * defensive for any future non-synchronized read; today every
-     * accessor goes through the synchronized block.
-     */
-    fun takeOnce(): ByteArray = synchronized(this) {
-        val b = bytes ?: error(
-            "TransferredNV21.takeOnce() called twice — bytes already transferred. " +
-                "Check that you're not passing the same TransferredNV21 instance to " +
-                "two consumers (e.g., a sync gate-eval call AND an async workScope.launch)."
-        )
-        bytes = null
-        b
-    }
-
-    // Note: an `available` property was considered and removed in
-    // pre-merge review (critic-finding [MAJOR][B]).  Any
-    // `if (handle.available) handle.takeOnce()` pattern is
-    // inherently TOCTOU-racy — another thread could win the
-    // takeOnce() between the check and the use.  Consumers should
-    // call `takeOnce()` directly and catch the `IllegalStateException`
-    // if they need recovery semantics.  No internal caller used
-    // `available`; YAGNI removed it.
-}