react-native-image-stitcher 0.14.2 → 0.15.0

package/ios/Sources/RNImageStitcher/RNSARSession.swift

@@ -485,40 +485,14 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         isRunning = true
         currentTrackingState = .initialising
 
-        // v0.8.0 Phase 3c — install the worklet runtime + register
-        // the first-party stitching callback.  The delegate's
-        // per-frame ingest now routes through
-        // `RNSARWorkletRuntime.dispatchFrame` (see
-        // `session(_:didUpdate:)` below) which invokes this
-        // callback synchronously.  Net behavior is byte-identical
-        // to the pre-Phase-3c direct `consumer.consumeFrame(...)`
-        // call.  The indirection sets up the seam where Phase 4
-        // will fan out to host worklets without touching this
-        // first-party path.
-        RNSARWorkletRuntime.shared().installIfNeeded()
-        RNSARWorkletRuntime.shared().setFirstPartyCallback {
-            [weak self] arFrame, pose in
-            // ARKit pool reuse contract: must consume the pixel
-            // buffer before returning.  The consumer's
-            // `consumeFrame` does that synchronously inside the
-            // call (NV12 → cv::Mat sync, then heavy work on its
-            // own queue).  We're on the same thread as the
-            // delegate (ARSession.delegateQueue), so the contract
-            // holds end-to-end.
-            guard let self = self else { return }
-            guard let consumer = self.incrementalConsumer else { return }
-            consumer.consumeFrame(pixelBuffer: arFrame.capturedImage,
-                                  pose: pose)
-        }
+        // Per-frame ingest calls `incrementalConsumer.consumeFrame`
+        // directly from `session(_:didUpdate:)` below. (The v0.8
+        // worklet-runtime indirection that used to live here was archived
+        // in the batch-keyframe cleanup — see archive/.)
     }
 
     @objc public func stop() {
         guard isRunning else { return }
-        // v0.8.0 Phase 3c — drop the first-party callback so the
-        // closure's `[weak self]` reference can be released
-        // immediately + no in-flight delegate frame re-enters the
-        // engine after stop.  Idempotent.
-        RNSARWorkletRuntime.shared().setFirstPartyCallback(nil)
         arSession.pause()
         isRunning = false
         currentTrackingState = .notAvailable
@@ -602,11 +576,12 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         // `useFrameProcessor` TS hook + a JSI plugin entry point)
         // without changing this first-party path.
         //
-        // ARKit pool reuse contract: still satisfied — the runtime
-        // invokes the callback synchronously on the delegate
-        // thread, and the callback's `consumer.consumeFrame(...)`
-        // does the same NV12 → cv::Mat sync conversion as before.
-        RNSARWorkletRuntime.shared().dispatchFrame(frame, pose: pose)
+        // ARKit pool reuse contract: consumeFrame does the NV12 →
+        // cv::Mat sync conversion synchronously on the delegate thread
+        // before returning, so the captured pixel buffer is safe for
+        // ARKit to recycle after this call.
+        incrementalConsumer?.consumeFrame(pixelBuffer: frame.capturedImage,
+                                          pose: pose)
 
         // If recording is in flight, append this frame to the
         // asset writer DIRECTLY — no queue hop.

package/ios/Sources/RNImageStitcher/Stitcher.swift

@@ -151,11 +151,11 @@ public enum Stitcher {
         // IncrementalStitcher) hit the method directly with
         // the right value.
         captureOrientation: nil,
-        // V16 Phase 1b.fix5c — generic Stitcher API defaults the
-        // crop strategy to bbox-only (matches the operator-default
-        // in the panorama settings modal).  Callers that want
-        // inscribed-rect can use IncrementalStitcher with
-        // the toggle on.
+        // V16 Phase 1b.fix5c — generic Stitcher API keeps the crop
+        // strategy at bbox-only (conservative; the panorama-capture
+        // path now defaults to inscribed-rect via the settings).
+        // Callers that want inscribed-rect can use IncrementalStitcher
+        // with the toggle on.
         useInscribedRectCrop: false,
         // 2026-05-22 (audit F2) — legacy video-stitch API doesn't
         // expose stitchMode in its options dict yet.  nil falls
@@ -193,6 +193,72 @@ public enum Stitcher {
     }
   }
 
+  /// v0.15 debug — compute the max-inscribed rectangle of the image
+  /// (no file change), for the example app's crop-visualisation harness.
+  public static func computeInscribedRect(
+    imagePath: String
+  ) throws -> (x: Int, y: Int, width: Int, height: Int, imageWidth: Int, imageHeight: Int) {
+    do {
+      let d = try OpenCVStitcher.computeInscribedRect(atPath: imagePath)
+      return (
+        x: d["x"]?.intValue ?? 0,
+        y: d["y"]?.intValue ?? 0,
+        width: d["width"]?.intValue ?? 0,
+        height: d["height"]?.intValue ?? 0,
+        imageWidth: d["imageWidth"]?.intValue ?? 0,
+        imageHeight: d["imageHeight"]?.intValue ?? 0
+      )
+    } catch let nsError as NSError {
+      throw StitcherError.fromNSError(nsError)
+    }
+  }
+
+  /// v0.15 debug — crop the image to an explicit rectangle (overwrite
+  /// in place) and re-encode at `quality`.  Pairs with the
+  /// computeInscribedRect debug harness.
+  public static func cropToRect(
+    imagePath: String,
+    x: Int,
+    y: Int,
+    width: Int,
+    height: Int,
+    quality: Int
+  ) throws -> (width: Int, height: Int) {
+    do {
+      let d = try OpenCVStitcher.cropToRect(
+        atPath: imagePath,
+        x: x,
+        y: y,
+        width: width,
+        height: height,
+        quality: quality
+      )
+      return (width: d["width"]?.intValue ?? 0, height: d["height"]?.intValue ?? 0)
+    } catch let nsError as NSError {
+      throw StitcherError.fromNSError(nsError)
+    }
+  }
+
+  /// v0.15 debug — write a red-tinted mask overlay (excluded pixels =
+  /// red) next to the image and report what fraction the brightness mask
+  /// drops. Pairs with the inscribed-rect debug harness.
+  public static func debugMaskOverlay(
+    imagePath: String,
+    threshold: Int
+  ) throws -> (maskPath: String, width: Int, height: Int, excludedPercent: Int) {
+    do {
+      let d = try OpenCVStitcher.debugMaskOverlay(atPath: imagePath, threshold: threshold)
+      return (
+        maskPath: d["maskPath"] as? String ?? "",
+        width: (d["width"] as? NSNumber)?.intValue ?? 0,
+        height: (d["height"] as? NSNumber)?.intValue ?? 0,
+        excludedPercent: (d["excludedPercent"] as? NSNumber)?.intValue ?? 0
+      )
+    } catch let nsError as NSError {
+      throw StitcherError.fromNSError(nsError)
+    }
+  }
+
   /// Combined pipeline: extract frames from a recorded video,
   /// stitch them into a panorama, write the result to
   /// `options.outputPath`.  Used by the host app's tap-and-hold
@@ -202,38 +268,21 @@ public enum Stitcher {
   /// All temp frame extraction lives in /tmp and is torn down by
   /// the ObjC layer regardless of success or failure.
   public static func stitchVideo(
-    _ options: StitchVideoOptions,
-    poses: [[String: Any]]? = nil
+    _ options: StitchVideoOptions
   ) throws -> StitchResult {
     do {
-      let result: RNStitchResult
-      if let poses = poses, !poses.isEmpty {
-        // Phase 5: pose-driven path.  Skips features → matching →
-        // BundleAdjuster on the native side; cv::detail::CameraParams
-        // come straight from the ARKit poses with the appropriate
-        // coordinate-system flip (Y-up → Y-down, -Z → +Z).
-        result = try OpenCVStitcher.stitchVideo(
-          atPath: options.videoPath,
-          outputPath: options.outputPath,
-          maxFrames: options.maxFrames,
-          jpegQuality: options.jpegQuality,
-          warperType: options.warperType,
-          blenderType: options.blenderType,
-          seamFinderType: options.seamFinderType,
-          poses: poses
-        )
-      } else {
-        // Existing feature-matched path.
-        result = try OpenCVStitcher.stitchVideo(
-          atPath: options.videoPath,
-          outputPath: options.outputPath,
-          maxFrames: options.maxFrames,
-          jpegQuality: options.jpegQuality,
-          warperType: options.warperType,
-          blenderType: options.blenderType,
-          seamFinderType: options.seamFinderType
-        )
-      }
+      // The pose-driven video stitch (the old native `withPoses:`
+      // path) was archived in the 2026-06 batch-keyframe cleanup;
+      // this now always runs the feature-matched compose.
+      let result = try OpenCVStitcher.stitchVideo(
+        atPath: options.videoPath,
+        outputPath: options.outputPath,
+        maxFrames: options.maxFrames,
+        jpegQuality: options.jpegQuality,
+        warperType: options.warperType,
+        blenderType: options.blenderType,
+        seamFinderType: options.seamFinderType
+      )
       return StitchResult(
         outputPath: result.outputPath,
         width: result.width,

package/ios/Sources/RNImageStitcher/StitcherBridge.m

@@ -25,4 +25,17 @@ RCT_EXTERN_METHOD(normaliseOrientation:(NSDictionary *)options
                   resolver:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 
+// v0.15 debug harness (inscribed-rect visualisation in the example app).
+RCT_EXTERN_METHOD(computeInscribedRect:(NSDictionary *)options
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+RCT_EXTERN_METHOD(cropToRect:(NSDictionary *)options
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+RCT_EXTERN_METHOD(debugMaskOverlay:(NSDictionary *)options
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
 @end

package/ios/Sources/RNImageStitcher/StitcherBridge.swift

@@ -95,10 +95,6 @@ public class StitcherBridge: NSObject {
     let warperType = (options["warperType"] as? String) ?? "plane"
     let blenderType = (options["blenderType"] as? String) ?? "multiband"
     let seamFinderType = (options["seamFinderType"] as? String) ?? "graphcut"
-    // Optional pose log from the host's RNSARSession snapshot.
-    // When present and non-empty, the native stitcher routes to the
-    // pose-driven path (skips features → matching → BA).
-    let poses = options["poses"] as? [[String: Any]]
 
     let stitchOpts = StitchVideoOptions(
       videoPath: videoPath,
@@ -112,7 +108,7 @@ public class StitcherBridge: NSObject {
 
     DispatchQueue.global(qos: .userInitiated).async {
       do {
-        let result = try Stitcher.stitchVideo(stitchOpts, poses: poses)
+        let result = try Stitcher.stitchVideo(stitchOpts)
         resolver([
           "outputPath": result.outputPath,
           "width": result.width,
@@ -179,6 +175,137 @@ public class StitcherBridge: NSObject {
     }
   }
 
+  /// v0.15 debug — compute the max-inscribed rectangle of `imagePath`
+  /// without modifying it.  Resolves
+  /// `{ x, y, width, height, imageWidth, imageHeight }`.
+  @objc(computeInscribedRect:resolver:rejecter:)
+  public func computeInscribedRect(
+    options: NSDictionary,
+    resolver: @escaping RCTPromiseResolveBlock,
+    rejecter: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let imagePath = options["imagePath"] as? String else {
+      rejecter("invalid-options", "imagePath must be a string", nil)
+      return
+    }
+    DispatchQueue.global(qos: .userInitiated).async {
+      do {
+        let r = try Stitcher.computeInscribedRect(imagePath: imagePath)
+        resolver([
+          "x": r.x,
+          "y": r.y,
+          "width": r.width,
+          "height": r.height,
+          "imageWidth": r.imageWidth,
+          "imageHeight": r.imageHeight,
+        ])
+      } catch let err as StitcherError {
+        switch err {
+        case .insufficientFrames(let count):
+          rejecter("insufficient-frames", "(unexpected for computeInscribedRect) frames=\(count)", err)
+        case .readFailed(let path):
+          rejecter("read-failed", "Could not read image: \(path)", err)
+        case .writeFailed(let path):
+          rejecter("write-failed", "Could not write image: \(path)", err)
+        case .opencvFailed(let code, let message):
+          rejecter("opencv-failed-\(code)", message, err)
+        }
+      } catch {
+        rejecter("unknown", "Unexpected computeInscribedRect failure: \(error)", error)
+      }
+    }
+  }
+
+  /// v0.15 debug — crop `imagePath` to the rectangle in `options`
+  /// (`x`, `y`, `width`, `height`) at `quality` (default 90), overwriting
+  /// in place.  Resolves the final `{ width, height }`.
+  @objc(cropToRect:resolver:rejecter:)
+  public func cropToRect(
+    options: NSDictionary,
+    resolver: @escaping RCTPromiseResolveBlock,
+    rejecter: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let imagePath = options["imagePath"] as? String else {
+      rejecter("invalid-options", "imagePath must be a string", nil)
+      return
+    }
+    let x = (options["x"] as? NSNumber)?.intValue ?? 0
+    let y = (options["y"] as? NSNumber)?.intValue ?? 0
+    let width = (options["width"] as? NSNumber)?.intValue ?? 0
+    let height = (options["height"] as? NSNumber)?.intValue ?? 0
+    let quality = (options["quality"] as? NSNumber)?.intValue ?? 90
+    DispatchQueue.global(qos: .userInitiated).async {
+      do {
+        let dims = try Stitcher.cropToRect(
+          imagePath: imagePath,
+          x: x,
+          y: y,
+          width: width,
+          height: height,
+          quality: quality
+        )
+        resolver([
+          "width": dims.width,
+          "height": dims.height,
+        ])
+      } catch let err as StitcherError {
+        switch err {
+        case .insufficientFrames(let count):
+          rejecter("insufficient-frames", "(unexpected for cropToRect) frames=\(count)", err)
+        case .readFailed(let path):
+          rejecter("read-failed", "Could not read image: \(path)", err)
+        case .writeFailed(let path):
+          rejecter("write-failed", "Could not write image: \(path)", err)
+        case .opencvFailed(let code, let message):
+          rejecter("opencv-failed-\(code)", message, err)
+        }
+      } catch {
+        rejecter("unknown", "Unexpected cropToRect failure: \(error)", error)
+      }
+    }
+  }
+
+  /// v0.15 debug — write a red-tinted mask overlay for `imagePath`
+  /// (excluded pixels red). `threshold` optional (default 1, matching the
+  /// inscribed-rect mask). Resolves
+  /// `{ maskPath, width, height, excludedPercent }`.
+  @objc(debugMaskOverlay:resolver:rejecter:)
+  public func debugMaskOverlay(
+    options: NSDictionary,
+    resolver: @escaping RCTPromiseResolveBlock,
+    rejecter: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let imagePath = options["imagePath"] as? String else {
+      rejecter("invalid-options", "imagePath must be a string", nil)
+      return
+    }
+    let threshold = (options["threshold"] as? NSNumber)?.intValue ?? 1
+    DispatchQueue.global(qos: .userInitiated).async {
+      do {
+        let r = try Stitcher.debugMaskOverlay(imagePath: imagePath, threshold: threshold)
+        resolver([
+          "maskPath": r.maskPath,
+          "width": r.width,
+          "height": r.height,
+          "excludedPercent": r.excludedPercent,
+        ])
+      } catch let err as StitcherError {
+        switch err {
+        case .insufficientFrames(let count):
+          rejecter("insufficient-frames", "(unexpected for debugMaskOverlay) frames=\(count)", err)
+        case .readFailed(let path):
+          rejecter("read-failed", "Could not read image: \(path)", err)
+        case .writeFailed(let path):
+          rejecter("write-failed", "Could not write image: \(path)", err)
+        case .opencvFailed(let code, let message):
+          rejecter("opencv-failed-\(code)", message, err)
+        }
+      } catch {
+        rejecter("unknown", "Unexpected debugMaskOverlay failure: \(error)", error)
+      }
+    }
+  }
+
   @objc(stitch:resolver:rejecter:)
   public func stitch(
     options: NSDictionary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,10 +25,11 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "jest",
     "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test",
     "postinstall": "node scripts/postinstall-fetch-binaries.js"
   },
   "keywords": [

package/src/camera/Camera.tsx

@@ -242,6 +242,11 @@ export interface CameraProps {
   defaultFlowMaxTranslationCm?: number;
   defaultKeyframeMaxCount?: number;
   defaultKeyframeOverlapThreshold?: number;
+  /** Time-budget force-accept (ms) for the keyframe gate — accept a
+   *  keyframe at least this often during a pan even if novelty is low,
+   *  so slow / static pans don't leave temporal gaps.  `0` disables it.
+   *  Default 2000 (2 s).  Applies to both AR and non-AR captures. */
+  defaultMaxKeyframeIntervalMs?: number;
   /** Forward-looking — wires through to cv::Stitcher's compositingResol
    *  once PanoramaSettings exposes the field (currently a no-op). */
   defaultCompositingResolMP?: number;
@@ -250,6 +255,28 @@ export interface CameraProps {
   /** Forward-looking — see above. */
   defaultSeamEstimationResolMP?: number;
 
+  // ── Inscribed-rect crop (v0.15) ───────────────────────────────────
+  /**
+   * Crop strategy for the stitched panorama. `false` (default) keeps the
+   * bounding-rect of non-black pixels, which preserves all stitched
+   * content but may leave black corners. `true` crops to the maximum
+   * axis-aligned rectangle inscribed in the coverage mask — clean edges,
+   * no black corners (slightly more CPU at finalize) — but it can shrink
+   * the output substantially on lopsided / ultra-wide masks, which is why
+   * it's opt-in.
+   *
+   * Implemented as a start-time stitcher config (like the other
+   * stitcher settings), so this value is read once at mount to seed the
+   * initial setting; the in-app settings modal can override it at
+   * runtime. It changes image geometry (the crop), not encoding.
+   *
+   * Since the default is `false`, only pass this prop to opt in:
+   * @example
+   * // Crop to a clean inscribed rectangle (no black corners):
+   * <Camera maxInscribedRectCrop={true} />
+   */
+  maxInscribedRectCrop?: boolean;
+
   // ── UI knobs ──────────────────────────────────────────────────────
   enablePhotoMode?: boolean;
   enablePanoramaMode?: boolean;
@@ -270,27 +297,13 @@ export interface CameraProps {
   style?: StyleProp<ViewStyle>;
 
   /**
-   * Which incremental stitcher engine to drive.  Default
-   * `'batch-keyframe'` — collects accepted JPEGs and runs
-   * `cv::Stitcher` once at finalize time.  This is the v0.4+
-   * production default and what the v0.5 Frame Processor migration
-   * exercises.
-   *
-   * Switch to a live engine (`'firstwins-rectilinear'` or
-   * `'hybrid'`) for low-latency in-flight stitching.  Live engines
-   * exercise the F8.6 pixel-buffer ingest path (skipping the JPEG
-   * encode/decode round-trip; ~30–50 ms saved per accept) when the
-   * Frame Processor driver is active.
-   *
-   * See `docs/f8-frame-processor-plan.md` and the v0.5.0
-   * CHANGELOG for the trade-offs between batch-keyframe and live
-   * engines.
+   * Which stitcher engine to drive.  Only `'batch-keyframe'` is
+   * supported (and the default): it collects accepted keyframe JPEGs
+   * during the hold-pan-release capture and runs the stitch once at
+   * finalize.  The live engines (hybrid / slit-scan / firstwins) were
+   * archived in the batch-keyframe cleanup — see `archive/`.
    */
-  engine?: 'batch-keyframe'
-    | 'hybrid'
-    | 'slitscan-rotate' | 'slitscan-both'
-    | 'firstwins' | 'firstwins-zoomed' | 'firstwins-rectilinear'
-    | 'slitscan';
+  engine?: 'batch-keyframe';
 
   /**
    * Optional destination directory for captures.  When set, the lib
@@ -865,6 +878,8 @@ function extractPanoramaOverrides(props: CameraProps): PanoramaPropOverrides {
     defaultFlowMaxTranslationCm: props.defaultFlowMaxTranslationCm,
     defaultKeyframeMaxCount: props.defaultKeyframeMaxCount,
     defaultKeyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold,
+    defaultMaxKeyframeIntervalMs: props.defaultMaxKeyframeIntervalMs,
+    maxInscribedRectCrop: props.maxInscribedRectCrop,
   };
 }
 
@@ -1433,6 +1448,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         width = result.width;
         height = result.height;
       }
+
       onCapture?.({ type: 'photo', uri, width, height });
     } catch (err) {
       const e = err instanceof CameraError
@@ -1576,7 +1592,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         isNonAR ? imuGate.getTotalAbsMetres() : 0;
       const result = await incremental.finalize(
         panoOutputPath,
-        90,
+        90, // default JPEG quality
         deviceOrientation,
         imuTotalTranslationM,
       );
@@ -1590,6 +1606,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
           included: result.framesIncluded,
         });
       }
+
       onCapture?.({
         type: 'panorama',
         // Native finalize() returns a bare `/data/.../foo.jpg` path;
@@ -1615,7 +1632,11 @@ export function Camera(props: CameraProps): React.JSX.Element {
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       const code: CameraErrorCode =
-        /need more images/i.test(message) ? 'STITCH_NEED_MORE_IMGS'
+        // Insufficient overlap surfaces two ways: cv::Stitcher's
+        // ERR_NEED_MORE_IMGS ("need more images") and the manual
+        // pipeline's "0 valid pairwise matches / frames may not overlap
+        // enough" — both are the same recoverable "pan more slowly" case.
+        /need more images|pairwise match|overlap enough/i.test(message) ? 'STITCH_NEED_MORE_IMGS'
         : /homography/i.test(message) ? 'STITCH_HOMOGRAPHY_FAIL'
         : /camera params/i.test(message) ? 'STITCH_CAMERA_PARAMS_FAIL'
         : /out of memory|oom/i.test(message) ? 'STITCH_OOM'

package/src/camera/CaptureStitchStatsToast.tsx

@@ -23,28 +23,47 @@ import type { IncrementalFinalizeResult } from '../stitching/incremental';
 export interface CaptureStitchStatsToastProps {
   /** Toast message to show.  Pass null to hide. */
   message: string | null;
+  /**
+   * Optional bold title rendered above the message (e.g. an action ask
+   * like "Pan more slowly").  Omit for a plain single-line toast.
+   */
+  title?: string | null;
   /** Top inset for safe-area placement.  Toast pinned `topInset + 12`. */
   topInset?: number;
+  /**
+   * Vertical placement.  'top' (default) pins it `topInset + 12` from the
+   * top; 'center' vertically centers it — more prominent, and dodges the
+   * notch / Dynamic Island entirely.
+   */
+  placement?: 'top' | 'center';
 }
 
 export function CaptureStitchStatsToast({
   message,
+  title = null,
   topInset = 0,
+  placement = 'top',
 }: CaptureStitchStatsToastProps): React.JSX.Element | null {
   if (message === null) return null;
   return (
     <View
       pointerEvents="none"
-      style={[
-        styles.wrap,
-        { top: topInset + 12 },
-      ]}
+      style={
+        placement === 'center'
+          ? styles.wrapCenter
+          : [styles.wrap, { top: topInset + 12 }]
+      }
     >
       <View
         style={styles.capsule}
         accessibilityRole="alert"
         accessibilityLiveRegion="polite"
       >
+        {title ? (
+          <Text style={styles.title} numberOfLines={2}>
+            {title}
+          </Text>
+        ) : null}
         <Text style={styles.text} numberOfLines={3}>
           {message}
         </Text>
@@ -61,6 +80,16 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     zIndex: 110,
   },
+  wrapCenter: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    left: 24,
+    right: 24,
+    alignItems: 'center',
+    justifyContent: 'center',
+    zIndex: 110,
+  },
   capsule: {
     paddingHorizontal: 16,
     paddingVertical: 10,
@@ -68,6 +97,13 @@ const styles = StyleSheet.create({
     backgroundColor: 'rgba(15, 23, 42, 0.92)',
     maxWidth: '100%',
   },
+  title: {
+    color: '#ffffff',
+    fontSize: 14,
+    fontWeight: '700',
+    textAlign: 'center',
+    marginBottom: 3,
+  },
   text: {
     color: '#ffffff',
     fontSize: 13,
@@ -93,7 +129,9 @@ const styles = StyleSheet.create({
  */
 export interface UseStitchStatsToastReturn {
   message: string | null;
-  showFor: (msg: string, ms?: number) => void;
+  /** Optional bold title shown above `message` (pass to the toast). */
+  title: string | null;
+  showFor: (msg: string, ms?: number, title?: string) => void;
   showResult: (result: IncrementalFinalizeResult, ms?: number) => void;
 }
 
@@ -101,16 +139,22 @@ const DEFAULT_DISMISS_MS = 4500;
 
 export function useStitchStatsToast(): UseStitchStatsToastReturn {
   const [message, setMessage] = useState<string | null>(null);
+  const [title, setTitle] = useState<string | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const showFor = useCallback((msg: string, ms = DEFAULT_DISMISS_MS) => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    setMessage(msg);
-    timerRef.current = setTimeout(() => {
-      setMessage(null);
-      timerRef.current = null;
-    }, ms);
-  }, []);
+  const showFor = useCallback(
+    (msg: string, ms = DEFAULT_DISMISS_MS, titleText?: string) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      setTitle(titleText ?? null);
+      setMessage(msg);
+      timerRef.current = setTimeout(() => {
+        setMessage(null);
+        setTitle(null);
+        timerRef.current = null;
+      }, ms);
+    },
+    [],
+  );
 
   const showResult = useCallback(
     (result: IncrementalFinalizeResult, ms = DEFAULT_DISMISS_MS) => {
@@ -151,5 +195,5 @@ export function useStitchStatsToast(): UseStitchStatsToastReturn {
     if (timerRef.current) clearTimeout(timerRef.current);
   }, []);
 
-  return { message, showFor, showResult };
+  return { message, title, showFor, showResult };
 }