react-native-image-stitcher 0.3.0 → 0.4.0

package/src/camera/PanoramaSettingsModal.tsx

@@ -1,26 +1,61 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * PanoramaSettingsModal — runtime A/B testing surface for the
- * stitcher pipeline.  Operators in the field can toggle warper,
- * blender, and tuning constants between captures to see what
- * looks best on real shelf scenes.
+ * PanoramaSettingsModal — runtime tuning surface for <Camera>'s
+ * batch-keyframe panorama capture.
  *
- * The modal is presentational: the host owns the settings state
- * (typically `useState<PanoramaSettings>`) and renders the modal
- * with `visible` toggled by a gear-icon press in the capture
- * header.  Settings flow OUT via `onChange` for each tweak.
+ * v0.4 rewrite (Phase 2 of F10):
+ * ──────────────────────────────
  *
- * Why expose this as an SDK component instead of leaving it to
- * each host?  The set of tunable knobs IS the SDK's contract —
- * if a new setting is added (e.g. registration MP) the SDK ships
- * the UI for it in lockstep with the param itself, instead of
- * forcing every host app to update its settings screen.
+ * The v0.3 modal exposed a flat 45-field surface that mixed
+ * batch-keyframe knobs with slit-scan, hybrid, and video-recording
+ * fallback fields the engine never reads in <Camera>'s
+ * `engine: 'batch-keyframe'` path.  The 2026-05-22 audit (v0.3.0
+ * CHANGELOG) traced every field's native consumer and proved most of
+ * the cross-engine fields were dead surface in this modal.
+ *
+ * v0.4 narrows the modal to exactly the surface <Camera> consumes:
+ * the `PanoramaSettings` type defined in `./PanoramaSettings.ts`.  Each
+ * section in the modal mirrors a sub-tree of that type — operators see
+ * the same shape in the UI as the code, and host apps that want to
+ * tune slit-scan or hybrid engines build their own analogous
+ * SlitscanSettingsModal / HybridSettingsModal on top of those types.
+ *
+ * UI structure (matches the type tree):
+ *
+ *   - Debug                       (top-level, `debug`)
+ *   - Frame selection             (`frameSelection`, closed by default)
+ *       - Mode
+ *       - Max keyframes
+ *       - Overlap threshold
+ *       - Flow tunables           (`frameSelection.flow`, only when
+ *                                  mode === 'flow-based')
+ *           - Max corners
+ *           - Quality level
+ *           - Min distance
+ *           - Max translation cm
+ *           - Novelty percentile
+ *           - Eval every N frames
+ *   - Stitcher                    (`stitcher`, closed by default)
+ *       - Stitch mode
+ *       - Warper type
+ *       - Blender
+ *       - Seam finder
+ *       - Inscribed-rect crop
+ *   - Reset to defaults           (button)
+ *
+ * Note: `captureSource` (AR vs non-AR) is NOT surfaced here.  The
+ * camera-screen AR toggle owns that state — Camera.tsx overrides the
+ * native bridge's `captureSource` with the derived
+ * `effectiveCaptureSource` so settings and runtime stay in sync.
+ *
+ * The reusable `Accordion` + `SectionHeader` + `SegmentedControl` +
+ * `Tag` helpers from the v0.3 modal are preserved verbatim — only the
+ * data-binding layer changed.
  */
 
 import React, { useState } from 'react';
 import {
   Modal,
-  NativeModules,
   Pressable,
   ScrollView,
   StyleSheet,
@@ -28,490 +63,32 @@ import {
   View,
 } from 'react-native';
 
-
-export interface PanoramaSettings {
-  warperType: 'plane' | 'cylindrical' | 'spherical';
-  blenderType: 'multiband' | 'feather';
-  /**
-   * Seam finder strategy.  "graphcut" finds optimal seams before
-   * blending (cleaner output, pairs with multiband, more memory).
-   * "skip" streams warp+feed (lower peak memory, fine with feather).
-   */
-  seamFinderType: 'graphcut' | 'skip';
-  /**
-   * V16 Phase 1b.fix5c (Ram's call 2026-05-10) — toggle the
-   * max-inscribed-rectangle crop on the batch-keyframe output
-   * panorama.  When false (default), the output is cropped to the
-   * bounding rectangle of non-black pixels only (cv::boundingRect)
-   * — preserves all stitched content at the cost of some black
-   * corners where cv::Stitcher's projection didn't fill.  When
-   * true, the post-stitch pipeline additionally runs
-   * `MaxInscribedRectFromMask` to find the largest axis-aligned
-   * rectangle entirely inside content, followed by the
-   * column-projection second-pass.  Inscribed-rect can be
-   * over-aggressive on lopsided masks (field log showed a
-   * 1146×1102 bbox shrinking to a 602×1102 strip), so default OFF
-   * lets the operator see the full stitched scene; flip ON to
-   * A/B against the cleaner-but-smaller output.
-   */
-  enableMaxInscribedRectCrop: boolean;
-  /**
-   * Phase 4.4 EXPERIMENTAL: when true, the host swaps the
-   * vision-camera-backed CameraView for an ARKit-backed ARCameraView
-   * during panorama capture.  Default false (keeps the existing
-   * stitcher flow untouched).  Phase 5 will add AR-backed photo /
-   * video capture and pose-driven stitching; until then this is
-   * preview-only — useful for verifying the AR session renders
-   * cleanly on the operator's device before we cut over.
-   */
-  useARPreview: boolean;
-  /**
-   * V15 — Incremental engine choice for live realtime stitching.
-   *   'hybrid'           — Whole-frame projection + feature matching;
-   *                        planar by default (was cylindrical).
-   *   'slitscan-rotate'  — V13.0a baseline + 1D NCC for rotation
-   *                        wobble correction.
-   *   'slitscan-both'    — DEFAULT.  V13.0a + no accept gate +
-   *                        feather blend.  Iterate via per-stage
-   *                        toggles below.
-   *
-   * All three are A/B-comparable on the same scene by toggling here
-   * without restarting the app.
-   */
-  incrementalEngine:
-    | 'batch-keyframe'
-    | 'hybrid'
-    | 'slitscan-rotate'
-    | 'slitscan-both';
-
-  /**
-   * V15 — Slit-scan slit width (fraction of pan-axis retained per
-   * frame).  Range 0.10 – 0.70.  Smaller = less within-slit multi-
-   * depth disagreement but tighter overlap budget at fast pans.
-   * Default 0.30.  Only applied to slitscan-* engines.
-   */
-  slitWidthFraction: number;
-
-  /**
-   * V15 — Per-stage correction toggles for slitscan-both.  Settings
-   * UI exposes these so iteration happens via toggles, not rebuilds.
-   */
-  acceptGate: 0 | 50;
-  enableTriangulation: boolean;
-  enableTriAccumulator: boolean;
-  enable2dNcc: boolean;
-  enableRansacHomography: boolean;
-  paintMode: 'FirstPaintedWins' | 'FeatherBlend';
-  hybridProjection: 'Cylindrical' | 'Planar';
-  /** 1D NCC search radius (slitscan-rotate only). */
-  nccSearchRadius1d: number;
-  /** **DEPRECATED in V15.0d** — see `planeSource`.  Kept on the type
-   *  for backward compat with stored settings.  When `planeSource`
-   *  is 'Disabled' (default) and this is true, the engine treats it
-   *  as 'ARKitDetected'. */
-  useDetectedPlane: boolean;
-  /** V15.0d — source of the plane used by the V15.0b plane-projected
-   *  stitch path.  Slit-scan modes only.
-   *
-   *  - 'Disabled': no plane projection (plain slit-scan).
-   *  - 'ARKitDetected': use ARKit's first vertical plane that aligns
-   *    with the camera's view direction.  Falls back to slit-scan
-   *    silently when no aligned plane is found.
-   *  - 'Virtual': synthesize a plane perpendicular to the camera at
-   *    `virtualPlaneDepthMeters` distance.  Always works; loses
-   *    "real depth" advantage but immune to ARKit picking the wrong
-   *    surface (which is the common failure mode for ARKitDetected). */
-  planeSource: 'Disabled' | 'ARKitDetected' | 'Virtual';
-  /** V15.0d — depth (m) of the synthetic plane in front of the camera
-   *  when `planeSource = 'Virtual'`.  0.3 – 5.0 m.  Default 1.5 m. */
-  virtualPlaneDepthMeters: number;
-  /** V15.0d — alignment threshold (cosine) for ARKit-detected planes.
-   *  Higher = stricter (fewer planes accepted).  0.0 – 1.0.
-   *  Default 0.6 (≈53° max angle off-camera). */
-  arkitPlaneAlignmentThreshold: number;
-  /** V15.0g — plane-projection rendering style.  Trapezoidal is the
-   *  V15.0b legacy 3D-correct mapping; Rectified is V15.0g's clean-
-   *  rectangle paste that eliminates tilt-induced trapezoidal
-   *  distortion.  Default Rectified.  Ignored when planeSource =
-   *  Disabled. */
-  planeProjectionStyle: 'Trapezoidal' | 'Rectified';
-  /** V15.0d — 2D NCC search half-window in pixels.  4 – 30.
-   *  Default 12. */
-  nccSearchMargin2d: number;
-  /** V15.0d — 2D NCC confidence threshold below which corrections
-   *  are rejected.  0.30 – 0.99.  Default 0.75. */
-  nccConfidenceThreshold2d: number;
-  /** V15.0d (1B) — EMA smoothing on 2D NCC corrections to damp
-   *  single-frame snaps.  Default false. */
-  enableNcc2dEmaSmoothing: boolean;
-  /** V15.0d — EMA weight on the CURRENT-frame correction.  0.05 – 0.95.
-   *  Default 0.4 (60% prev / 40% current). */
-  ncc2dEmaAlpha: number;
-  /** V15.0d (1C) — pan-axis-aware 2D NCC: clamp the cross-axis
-   *  correction tighter than the pan-axis.  Default false. */
-  enableNcc2dPanAxisLock: boolean;
-  /** V15.0d — cross-axis clamp (px) when pan-axis lock is on.
-   *  0 – 30.  Default 5. */
-  ncc2dCrossAxisLockPx: number;
-
-  /** V16 — frame-selection mode for the live engine.
-   *
-   *  - 'time-based' (default): every ARFrame is forwarded to the
-   *    engine; the engine's own gate (kMinAcceptDeltaPx etc.) decides.
-   *    Backward-compatible with all prior versions.
-   *  - 'pose-based': frames are pre-filtered by a KeyframeGate that
-   *    projects each onto the latched ARKit plane and accepts only
-   *    when overlap with the previous keyframe is < 1 −
-   *    overlapThreshold.  Bounded to keyframeMaxCount frames per
-   *    capture (matches iOS Camera / Samsung Pano architecture).
-   *    Requires planeSource != 'Disabled' to engage.
-   *  - 'flow-based' (V16 A2, DEFAULT): same KeyframeGate cap +
-   *    threshold but the novelty metric is sparse-Lucas-Kanade
-   *    optical flow on full-frame content instead of plane-projected
-   *    polygon overlap.  Plane-independent (scale-invariant — works
-   *    regardless of latched plane size); the metric is "median
-   *    pan-axis feature displacement / pan-axis frame dim", which is
-   *    a direct measure of % new content on the leading edge.  Falls
-   *    back to angular delta when feature tracking fails (texture-
-   *    poor scene / motion exceeds KLT pyramid window). */
-  frameSelectionMode: 'time-based' | 'pose-based' | 'flow-based';
-  /** V16 — required NEW-content fraction for a keyframe to be
-   *  accepted (pose-based AND flow-based modes share this knob;
-   *  both interpret 0.40 as "40 % new content").  Tuneable from
-   *  0.20 to 0.60 in the modal. */
-  keyframeOverlapThreshold: number;
-  /** V16 — hard cap on keyframes per capture (pose-based + flow-
-   *  based modes).  Default 6.  Once reached, all further frames are
-   *  rejected and the host should auto-finalize. */
-  keyframeMaxCount: number;
-  /** V16 A2 — flow-based mode: max Shi-Tomasi corners to detect per
-   *  accepted keyframe.  More = more robust median pan-axis
-   *  displacement but slower detect (~15-25 ms at 150 on iPhone 13
-   *  Pro).  Range 50 – 300, default 150. */
-  flowMaxCorners: number;
-  /** V16 A2 — flow-based mode: Shi-Tomasi quality level (0, 1].
-   *  Lower = more (weaker) corners detected; higher = fewer
-   *  (stronger) corners.  Default 0.01.  Range 0.005 – 0.05 in the
-   *  modal. */
-  flowQualityLevel: number;
-  /** V16 A2 — flow-based mode: minimum pixel distance between
-   *  detected corners at WORKING resolution (the gate internally
-   *  downscales the frame to 720 px longest side for KLT).  Higher
-   *  = more spatially-spread features.  Default 10. */
-  flowMinDistance: number;
-  /** V16 — flow-based mode: translation budget in CENTIMETRES.
-   *  When > 0, the gate force-accepts a frame if the camera has
-   *  translated more than this distance (3D Euclidean) since the
-   *  last accepted keyframe — even when novelty < threshold.
-   *  Bounds the parallax between adjacent keyframes so the
-   *  downstream affine stitcher matcher can fit a homography.
-   *  Range 0 – 100 cm in the modal, default 0 = disabled.
-   *  Recommended starting value once enabled: 8 cm. */
-  flowMaxTranslationCm: number;
-  /** V16 — flow-based mode: percentile used to aggregate tracked-
-   *  feature absolute displacements into the novelty estimate.
-   *  Pre-V16 used median (0.50); 0.85 picks up leading-edge
-   *  motion sooner — matches user perception of "new content
-   *  visible" better.  Range 0.50 – 0.99, default 0.85. */
-  flowNoveltyPercentile: number;
-  /** V16 — flow-based mode: eval-throttle.  Gate evaluation runs
-   *  every Nth consumeFrame from the AR delegate instead of every
-   *  frame.  Pure CPU/battery savings — doesn't change WHICH
-   *  frames are accepted, just samples less frequently.  Range
-   *  1 – 10, default 1 (every frame). */
-  flowEvalEveryNFrames: number;
-
-  /** V15.0c — sliver position within the camera frame.  'Center' is
-   *  V13.x default.  'Bottom' takes leading-edge content for top-to-
-   *  bottom pan; 'Top' for bottom-to-top pan. */
-  sliverPosition: 'Center' | 'Bottom' | 'Top';
-  /** V15.0c — paint full first frame, then add slivers as user pans.
-   *  Useful with 'Bottom' or 'Top' sliverPosition. */
-  firstFrameFullFrame: boolean;
-  /** Hard cap on hold duration (ms).  0 disables auto-stop. */
-  maxRecordingMs: number;
-  /** Frames per second of recording to sample for stitching. */
-  framesPerSecond: number;
-  /** Floor / ceiling on extracted frame count. */
-  minFrames: number;
-  maxFrames: number;
-  /** JPEG quality (0-100) for output panorama. */
-  quality: number;
-
-  // ── 2026-05-14: capture-source + stitch-mode axes ─────────────────
-  //
-  // These two settings are independent from the existing
-  // `incrementalEngine` / `useARPreview` axes; together they decide
-  // (a) which camera + tracking the capture screen uses, and (b)
-  // which OpenCV pipeline mode the batch stitcher uses at finalize.
-
-  /**
-   * 2026-05-14 (revised) — capture-source picker for the panorama
-   * camera screen.  Two options after the 2026-05-14 user-reported
-   * Galaxy A35 crash + simplification request:
-   *
-   *   'ar' (DEFAULT) — Use the AR stack (ARKit on iOS, ARCore on
-   *                    Android).  Plane detection, pose-aware
-   *                    capture, pose-driven gate.  Falls back to
-   *                    non-AR silently if the device doesn't
-   *                    support AR.
-   *   'non-ar'      — Use vision-camera.  Disables all AR-based
-   *                    services (planeSource=Disabled, no plane
-   *                    polling, no AR session, frameSelectionMode
-   *                    flipped to flow-based).  Lens-switcher chip
-   *                    on the capture screen lets the operator
-   *                    toggle 0.5× / 1× without re-opening Settings.
-   *                    The chip is hidden if the device has only
-   *                    one physical back lens.
-   *
-   * Cascade: switching from 'ar' → 'non-ar' triggers a useEffect
-   * in `AuditCaptureScreen` that patches dependent settings
-   * (planeSource, frameSelectionMode, useARPreview) to a coherent
-   * non-AR state.  Operators don't have to know which other
-   * settings to flip.
-   *
-   * Earlier draft (replaced 2026-05-14) had 4 values:
-   * 'auto' | 'ar' | 'wide' | 'ultrawide'.  The pre-mount
-   * physical-lens selection ('wide' / 'ultrawide') crashed the
-   * Galaxy A35 vision-camera CameraCaptureSession with a Parcel
-   * exception (physical_camera_id=null in AidlCamera3-Device
-   * configureStreams) — Camera2 can't be reliably steered to a
-   * specific physical lens via vision-camera's `physicalDevices`
-   * filter on this hardware.  The post-mount on-screen chip path
-   * works because vision-camera selects the safe multi-lens
-   * virtual device first, and the lens swap happens against an
-   * already-open camera.
-   */
-  captureSource: 'ar' | 'non-ar';
-
-  /**
-   * 2026-05-16 (Issue 5) — diagnostic toast on every successful
-   * finalize.  When `true`, the host renders a transient toast
-   * summarising the C+D progressive-confidence retry telemetry:
-   *
-   *   "Stitch: 6/6 frames retained at thresh 1.00 (1 attempt)"
-   *
-   * Defaults to `false` so end-users don't see it.  Toggle from the
-   * Settings modal under "Debug".  Independent from any log-level
-   * controls — purely a UI affordance for field testing.
-   */
-  debug: boolean;
-
-  /**
-   * 2026-05-14 — `cv::Stitcher` pipeline mode for the batch stitch.
-   *
-   *   'auto' (DEFAULT)
-   *     The capture engine looks at the accumulated translation vs
-   *     rotation magnitudes between first and last accepted keyframe
-   *     poses (AR-mode) or the windowed IMU integration (non-AR
-   *     mode) and picks PANORAMA or SCANS at finalize time.
-   *
-   *   'panorama'
-   *     `cv::Stitcher::PANORAMA` — rotation-only pipeline.  Best for
-   *     "rotate phone in place to capture a wide field of view"
-   *     captures.  ORB feature matching + global BundleAdjusterRay +
-   *     SphericalWarper.  Sharp seams, expensive memory.  WARNING:
-   *     on translation-heavy input the rotation-only homography fit
-   *     diverges and the canvas can blow up to multi-GB on Android
-   *     (2026-05-14 lmkd kill observed).  Pick this only for genuine
-   *     rotation panoramas.
-   *
-   *   'scans'
-   *     `cv::Stitcher::SCANS` — translational pipeline.  Best for
-   *     "walk past a shelf and pan sideways" captures.  Affine
-   *     matcher + AffineBasedEstimator + BundleAdjusterAffine +
-   *     PlaneWarper.  Canvas size bounded by sum of frame areas.
-   *     Slight quality drop on pure rotations but works for them too.
-   *
-   * Both platforms honour this as of 2026-05-22 (audit F2).  Android
-   * routes through `image_stitcher_jni.cpp` → `cpp/stitcher.cpp`;
-   * iOS routes through `OpenCVStitcher.stitchFramePaths(stitchMode:)`
-   * → `cpp/stitcher.cpp`.  Both 'auto' resolutions use the same
-   * translation/rotation ratio heuristic
-   * (`resolveStitchModeAuto` on each side).
-   */
-  stitchMode: 'auto' | 'panorama' | 'scans';
-}
-
-
-// Per-device default selection.  We read the iPhone's physical
-// RAM at SDK module load (exposed by `BatchStitcher`'s
-// `constantsToExport`) and pick the heaviest blender + seam
-// finder combo that fits.  Threshold (2 GB) is conservative —
-// iPhone 6s through iPhone X have 2 GB exactly; below that
-// (iPhone 6 / 5s) is unsupported by RN 0.84 anyway.  The user
-// can still flip ANY of these in the settings modal at runtime;
-// this only chooses the INITIAL default.
-const _physicalMemoryBytes: number = (() => {
-  const m = (NativeModules as Record<string, unknown>).BatchStitcher;
-  const bytes =
-    m && typeof m === 'object'
-      ? (m as { physicalMemoryBytes?: number }).physicalMemoryBytes
-      : undefined;
-  return typeof bytes === 'number' ? bytes : 0;
-})();
-
-const _isLowMem = _physicalMemoryBytes > 0
-  && _physicalMemoryBytes < 2 * 1024 * 1024 * 1024;
-
-// One-line diagnostic so the host's Metro console shows what the
-// SDK saw at module load.  If `physicalMemoryBytes=0` here, the
-// native bridge's `constantsToExport` isn't being picked up by
-// React Native and we should investigate the @objc registration.
-// The defaults always pick the SAFE fallback (multiband+graphcut)
-// when the value is 0 — this log is the only signal we have.
-// eslint-disable-next-line no-console
-console.log(
-  '[capture-sdk] PanoramaSettings defaults: '
-  + `physicalMemoryBytes=${_physicalMemoryBytes} `
-  + `isLowMem=${_isLowMem} `
-  + `→ blender=${_isLowMem ? 'feather' : 'multiband'} `
-  + `seam=${_isLowMem ? 'skip' : 'graphcut'}`,
-);
+import {
+  DEFAULT_FLOW_GATE_SETTINGS,
+  DEFAULT_PANORAMA_SETTINGS,
+  type BatchStitcherSettings,
+  type CaptureBaseSettings,
+  type FlowGateSettings,
+  type FrameSelectionSettings,
+  type PanoramaSettings,
+} from './PanoramaSettings';
+import {
+  getPhysicalMemoryBytes,
+  isLowMemDevice,
+} from './lowMemDevice';
 
 
-export const DEFAULT_PANORAMA_SETTINGS: PanoramaSettings = {
-  warperType: 'plane',
-  // High-quality defaults on devices with ≥2 GB RAM (iPhone X+):
-  // MultiBandBlender + GraphCutSeamFinder, the same combo
-  // cv::Stitcher::PANORAMA uses internally and what produced the
-  // sharpest output during iteration.
-  // Low-memory devices (<2 GB) fall back to FeatherBlender + skip
-  // seam (streams warp+feed) so peak memory stays under the
-  // tighter jetsam threshold.  Either way, the user can switch
-  // both in the settings modal.
-  blenderType: _isLowMem ? 'feather' : 'multiband',
-  seamFinderType: _isLowMem ? 'skip' : 'graphcut',
-  // V16 Phase 1b.fix5c — default OFF.  See PanoramaSettings.enableMaxInscribedRectCrop.
-  enableMaxInscribedRectCrop: false,
-  // AR-backed capture is the default — vision-camera path is kept as
-  // a fallback while we shake out edge cases.
-  useARPreview: true,
-  // V16 Phase 1 — batch-keyframe is the new default-recommended
-  // engine: KeyframeGate caps input at ≤ keyframeMaxCount frames,
-  // OpenCVStitcher's BA + GraphCut + ExposureCompensator +
-  // MultiBandBlender runs once on shutter release.  Existing
-  // slitscan-* engines remain available for wide-pan fallback.
-  incrementalEngine: 'batch-keyframe',
-  slitWidthFraction: 0.30,
-  acceptGate: 0,
-  enableTriangulation: false,
-  enableTriAccumulator: false,
-  enable2dNcc: false,
-  enableRansacHomography: false,
-  // V15.0c — Ram observation: FirstPaintedWins is consistently the best
-  // output across all combinations.  Default switched from FeatherBlend.
-  paintMode: 'FirstPaintedWins',
-  hybridProjection: 'Planar',
-  nccSearchRadius1d: 15,
-  useDetectedPlane: false,
-  // V16 Phase 1 — Virtual plane is the default since batch-keyframe
-  // is the recommended engine and the gate needs a plane to compute
-  // polygon overlap.  Virtual works without ARKit-detected planes (a
-  // synthesized plane perpendicular to the first-frame camera at
-  // virtualPlaneDepthMeters); operators can flip to ARKitDetected
-  // when in a controlled scene with a clearly-visible wall.  Disabled
-  // is still selectable for the older slit-scan paths that don't
-  // need a plane.
-  // V16 Phase 1b.fix5c (Ram's call 2026-05-10): switched default
-  // from 'Virtual' to 'ARKitDetected'.  ARKit's real plane gives
-  // better intrinsics-to-pixel alignment than a synthesised plane
-  // at a fixed depth, when ARKit can find a vertical plane.  Falls
-  // back to slit-scan when no plane latches.
-  planeSource: 'ARKitDetected',
-  virtualPlaneDepthMeters: 1.5,
-  arkitPlaneAlignmentThreshold: 0.6,
-  // V15.0g — Rectified is the default (Trapezoidal had the tilt-
-  // induced bottom-wider-than-top distortion that was the field
-  // blocker on V15.0e/f).  Trapezoidal stays available for
-  // operator A/B comparison.
-  planeProjectionStyle: 'Rectified',
-  // V15.0d — NCC 2D defaults match V15.0c.4's hardcoded values, now
-  // tunable via the settings UI.  EMA smoothing and pan-axis lock are
-  // off by default so the V15.0c.4 baseline behaviour is preserved
-  // until the operator explicitly opts in.
-  nccSearchMargin2d: 12,
-  // V15.0i.1 — default raised to 0.99 per Ram (only apply on near-
-  // perfect overlap matches; reject ambiguous matches that snap to
-  // wrong patterns on repetitive textures like shelf rails).
-  nccConfidenceThreshold2d: 0.99,
-  enableNcc2dEmaSmoothing: false,
-  ncc2dEmaAlpha: 0.4,
-  enableNcc2dPanAxisLock: false,
-  ncc2dCrossAxisLockPx: 5,
-  // V16 A2 (2026-05-13) — flow-based is now the default.  Ram report
-  // 2026-05-13 13:05 showed that pose-based on a small latched plane
-  // produces "bursts" of accepts on small physical motion: a 0.64 m²
-  // plane at 2.7 m perpDist gave 6 accepts in 1 s over 12 cm of
-  // translation because the plane-projected polygon covers only a
-  // sliver of the frame, hyperinflating newContent.  Flow-based
-  // measures novelty from real image content (sparse KLT), is
-  // plane-independent, and is invariant to plane size.  Operators
-  // can still flip back to 'pose-based' or 'time-based' in the modal
-  // for A/B testing or low-texture scenes.  Same defaults shared
-  // between pose-based and flow-based (40 % new content per
-  // keyframe, ≤ 6 keyframes per capture).
-  frameSelectionMode: 'flow-based',
-  // 2026-05-15 (U4) — flow-based default novelty 0.40 → 0.20.
-  // Accept frames with 20 % new content (was 40 %).  More inclusive
-  // selection for shelf-pan captures where panning slowly produces
-  // gradual content reveal.  Operator can still bump via Settings.
-  keyframeOverlapThreshold: 0.20,
-  keyframeMaxCount: 6,
-  // V16 A2 — flow-based mode tuning.  Defaults are the values that
-  // tested cleanly on iPhone 13 Pro / 14 Pro: 150 corners give a
-  // stable median across the frame; quality=0.01 + minDistance=10
-  // give spatially-spread, repeatable detection.  All three are
-  // tunable in the modal under "Flow tuning".
-  flowMaxCorners: 150,
-  flowQualityLevel: 0.01,
-  flowMinDistance: 10,
-  // V16 — translation-budget force-accept (Flow strategy only).
-  // 2026-05-16 (Issue 4a fix) — default flipped from 0 (disabled) to
-  // 25 cm so the "Rotate the camera instead of moving it sideways"
-  // warning fires out-of-the-box.  Set to 0 in Settings to disable
-  // both the warning AND the gate's force-accept on budget crossing.
-  // 2026-05-17 (Issue 4-A v2) — raised 25 → 50 cm.  The 25-cm budget
-  // was too tight given IMU double-integration drift (the
-  // accelerometer's noise floor accumulates several cm of bogus
-  // "translation" per second even when the phone is held still).
-  // Combined with the new `resetAnchor` at handleHoldStart (so drift
-  // doesn't compound across captures), 50 cm gives the warning real
-  // headroom for genuine sideways motion without false positives.
-  flowMaxTranslationCm: 50,
-  // V16 — novelty aggregation percentile.  0.85 picks up leading-
-  // edge motion sooner than the pre-V16 median (0.50).  Operator
-  // can dial down toward 0.5 for more-conservative captures or up
-  // toward 0.99 for more-aggressive.
-  flowNoveltyPercentile: 0.85,
-  // V16 — every-Nth-frame eval throttle.  2026-05-15 (U4): default
-  // 1 → 5 to reduce per-frame KeyframeGate CPU cost (Shi-Tomasi +
-  // calcOpticalFlowPyrLK is ~3-5 ms per ARFrame on Galaxy A35; at
-  // 30 fps that's ~15 % CPU on flow alone).  Evaluating every 5th
-  // frame yields novelty samples at ~6 Hz which is still well above
-  // the 1-2 Hz keyframe-accept cadence.
-  // matches pre-V16 behaviour).  Set higher to cut CPU on long
-  // captures at the cost of acceptance latency.
-  flowEvalEveryNFrames: 5,
-  // V15.0c — sliver tweaks: leading-edge sliver from BOTTOM for typical
-  // top-to-bottom pan + full first-frame anchor produced the best
-  // outputs in early iteration.
-  sliverPosition: 'Bottom',
-  firstFrameFullFrame: true,
-  maxRecordingMs: 8000,
-  framesPerSecond: 3,
-  minFrames: 6,
-  maxFrames: 16,
-  quality: 85,
+// ─── Device-memory diagnostic (informational only) ─────────────────
+//
+// Read once at module load via the shared `lowMemDevice` helper.  We
+// surface this as a single Menlo-monospace line at the top of the
+// modal body so operators can see what the SDK detected — useful for
+// diagnosing "why am I OOMing on this device?" questions.  The same
+// helper feeds <Camera>'s initial-settings device adaptation; they
+// were duplicated implementations pre-Phase-2-fix.
 
-  // 2026-05-14 (revised) — capture source defaults to 'ar' (AR-backed
-  // is the recommended path; non-AR is the explicit opt-out).  Stitch
-  // mode stays 'auto' — the auto-resolution heuristic between PANORAMA
-  // and SCANS is per-capture, not per-mode, so it's safe to leave on.
-  captureSource: 'ar',
-  stitchMode: 'auto',
-  debug: false,
-};
+const _physicalMemoryBytes = getPhysicalMemoryBytes();
+const _isLowMem = isLowMemDevice();
 
 
 export interface PanoramaSettingsModalProps {
@@ -528,42 +105,57 @@ export function PanoramaSettingsModal({
   onChange,
   onClose,
 }: PanoramaSettingsModalProps): React.JSX.Element {
-  const update = (patch: Partial<PanoramaSettings>) =>
-    onChange({ ...settings, ...patch });
-
-  // V16 Phase 1b — derive the 2-axis (timing × algorithm) UI state
-  // from the underlying single `incrementalEngine` field.  Storage
-  // shape is unchanged; the modal just presents it in two segmented
-  // controls so the user's mental model matches the system's actual
-  // primary axis (batch vs realtime).
+  // ─── Sub-tree update helpers ─────────────────────────────────────
+  //
+  // Each settings sub-tree has its own update helper that
+  // non-destructively patches that branch and re-emits the whole
+  // settings object via `onChange`.  Call sites stay short
+  // (`updateStitcher({ stitchMode: 'scans' })`) and avoid the
+  // nested-spread boilerplate the hierarchical shape would otherwise
+  // require at every callsite.
   //
-  // Mapping:
-  //   incrementalEngine === 'batch-keyframe'  → timing='batch'
-  //   incrementalEngine === 'hybrid'          → timing='realtime', algo='hybrid'
-  //   incrementalEngine === 'slitscan-rotate' → timing='realtime', algo='slitscan-rotate'
-  //   incrementalEngine === 'slitscan-both'   → timing='realtime', algo='slitscan-both'
-  const timing: 'batch' | 'realtime' =
-    settings.incrementalEngine === 'batch-keyframe' ? 'batch' : 'realtime';
-  // When in batch mode, remember 'hybrid' as the realtime algorithm
-  // the user would land on if they flipped timing back.  When already
-  // in realtime, the engine field IS the algorithm.
-  const realtimeAlgorithm:
-    'hybrid' | 'slitscan-rotate' | 'slitscan-both' =
-      settings.incrementalEngine === 'batch-keyframe'
-        ? 'hybrid'
-        : settings.incrementalEngine;
-  const setTiming = (t: 'batch' | 'realtime') => {
-    if (t === 'batch') {
-      update({ incrementalEngine: 'batch-keyframe' });
-    } else {
-      update({ incrementalEngine: realtimeAlgorithm });
-    }
-  };
+  // Why not a generic deep-merge?  Type-safety: each helper takes
+  // exactly the `Partial<SubTree>` the section it backs can patch.
+  // A generic helper would accept arbitrary nested keys and break the
+  // type-level guarantee that the modal only mutates what its
+  // matching settings type defines.
 
-  // Frame Selection only makes sense for batch and hybrid engines —
-  // slit-scan needs dense input and the gate would starve it.
-  const showFrameSelection =
-    timing === 'batch' || realtimeAlgorithm === 'hybrid';
+  const updateBase = (patch: Partial<CaptureBaseSettings>) =>
+    onChange({ ...settings, ...patch });
+
+  const updateStitcher = (patch: Partial<BatchStitcherSettings>) =>
+    onChange({
+      ...settings,
+      stitcher: { ...settings.stitcher, ...patch },
+    });
+
+  const updateFrameSelection = (patch: Partial<FrameSelectionSettings>) =>
+    onChange({
+      ...settings,
+      frameSelection: { ...settings.frameSelection, ...patch },
+    });
+
+  // Flow has an extra wrinkle: `frameSelection.flow` is optional.
+  // We materialise it from `DEFAULT_FLOW_GATE_SETTINGS` (the
+  // canonical FlowGateSettings defaults — see PanoramaSettings.ts)
+  // when patching from "undefined" — happens if a host starts with
+  // a custom settings literal that omits the sub-tree.
+  const updateFlow = (patch: Partial<FlowGateSettings>) =>
+    onChange({
+      ...settings,
+      frameSelection: {
+        ...settings.frameSelection,
+        flow: {
+          ...(settings.frameSelection.flow ?? DEFAULT_FLOW_GATE_SETTINGS),
+          ...patch,
+        },
+      },
+    });
+
+  // Frame-selection mode controls the visibility of the nested
+  // Flow-tunables section.  Mirrors the type-level optionality of
+  // `frameSelection.flow`.
+  const showFlowTunables = settings.frameSelection.mode === 'flow-based';
 
   return (
     <Modal
@@ -593,463 +185,187 @@ export function PanoramaSettingsModal({
               {`device: physicalMemoryBytes=${_physicalMemoryBytes} `
                 + `(${(_physicalMemoryBytes / (1024 ** 3)).toFixed(2)} GB) · `
                 + `isLowMem=${_isLowMem ? 'yes' : 'no'} · `
-                + `default blender=${_isLowMem ? 'feather' : 'multiband'}`}
+                + `current blender=${settings.stitcher.blenderType} `
+                + `(low-mem fallback=${_isLowMem ? 'feather' : 'multiband'})`}
             </Text>
 
             {/* ──────────────────────────────────────────────
-             *  2026-05-14 (revised) — CAPTURE SOURCE picker.
-             *  Two options after the Galaxy A35 vision-camera
-             *  CameraCaptureSession crash on pre-mount physical-
-             *  lens selection: 'ar' (AR-backed, default) and
-             *  'non-ar' (vision-camera + lens-switcher chip on
-             *  the capture screen).  Switching to 'non-ar'
-             *  cascades to disable plane detection, flip frame-
-             *  selection to flow-based, and turn off useARPreview
-             *  (see useEffect in AuditCaptureScreen.tsx).
+             *  DEBUG (top-level, `debug`)
+             *
+             *  Note: `captureSource` (AR vs non-AR) is intentionally
+             *  NOT surfaced here — the camera-screen AR toggle is the
+             *  sole source of truth.  Camera.tsx computes
+             *  `effectiveCaptureSource` from `arPreference + lens +
+             *  AR-device-support` and overrides `settings.captureSource`
+             *  on the bridge call, so the native engine always agrees
+             *  with the runtime preview.  Exposing a second control
+             *  here led to silent split-state where the modal value
+             *  disagreed with the on-screen toggle.
              * ────────────────────────────────────────────── */}
-            <SectionHeader title="Capture source" />
-            <SegmentedControl
-              options={['ar', 'non-ar']}
-              value={settings.captureSource}
-              onChange={(v) => update({ captureSource: v as PanoramaSettings['captureSource'] })}
-              caption="ar (default): ARKit / ARCore — plane detection, pose-aware capture, full AR stack.  non-ar: vision-camera only — disables AR plane detection, flips frame-selection to flow-based, runs IMU translation gate.  In non-ar mode, the on-screen lens-switcher chip lets you toggle 0.5× / 1× lens during capture (only shown when the device has both lenses)."
-            />
-
-            {/* 2026-05-14 — Stitch-mode picker.  THE 2026-05-14 OOM
-             *  root cause: cv::Stitcher PANORAMA mode breaks down
-             *  on translation-heavy input.  'auto' (DEFAULT) routes
-             *  between PANORAMA and SCANS based on accumulated
-             *  translation vs rotation magnitudes at finalize time.
-             *  Lifted to the top of the modal alongside captureSource
-             *  for the same reason: it's a top-level pipeline
-             *  decision, not a per-engine tuning. */}
-            <SectionHeader title="Stitch mode" />
-            <SegmentedControl
-              options={['auto', 'panorama', 'scans']}
-              value={settings.stitchMode}
-              onChange={(v) => update({ stitchMode: v as PanoramaSettings['stitchMode'] })}
-              caption="auto (default): pick PANORAMA or SCANS based on translation/rotation totals at finalize. panorama: cv::Stitcher::PANORAMA — rotation-only (spherical warper, BA-ray); best for rotate-in-place captures, BAD on translation. scans: cv::Stitcher::SCANS — affine pipeline (plane warper, BA-affine); best for shelf-pan captures."
-            />
-
-            {/* ──────────────────────────────────────────────
-             *  STITCH TIMING — top-level decision.  Maps to the
-             *  `incrementalEngine` storage field via setTiming().
-             * ────────────────────────────────────────────── */}
-            <SectionHeader title="Stitch timing" />
-            <SegmentedControl
-              options={['batch', 'realtime']}
-              value={timing}
-              onChange={(v) => setTiming(v as 'batch' | 'realtime')}
-              caption="batch (recommended): full cv::Stitcher pipeline at shutter release. Highest quality. ~1–2 s post-release. realtime: incremental during pan; lower latency, fewer quality stages."
-            />
-
-            {/* ──────────────────────────────────────────────
-             *  FRAME SELECTION (V16) — only for batch + hybrid.
-             *  Slit-scan needs dense input; gate would starve it.
-             * ────────────────────────────────────────────── */}
-            {showFrameSelection && (
-              <>
-                <SectionHeader title="Frame selection (V16)" />
-                <SegmentedControl
-                  options={['time-based', 'pose-based', 'flow-based']}
-                  value={settings.frameSelectionMode}
-                  onChange={(v) => update({ frameSelectionMode: v as PanoramaSettings['frameSelectionMode'] })}
-                  caption="flow-based (V16 A2, default): KeyframeGate uses sparse-Lucas-Kanade optical flow on full frame — plane-independent, invariant to plane size. pose-based: plane-polygon overlap (oversensitive on small latched planes). time-based: every ARFrame goes to the engine."
-                />
-                {(settings.frameSelectionMode === 'pose-based' ||
-                  settings.frameSelectionMode === 'flow-based') && (
-                  <>
-                    <SectionHeader title="Overlap threshold (new content per keyframe)" />
-                    <SegmentedControl
-                      options={['20%', '30%', '40%', '50%', '60%']}
-                      value={`${Math.round(settings.keyframeOverlapThreshold * 100)}%`}
-                      onChange={(v) => update({ keyframeOverlapThreshold: parseInt(v, 10) / 100 })}
-                      caption="Required NEW content per keyframe. 40% (default) ≈ 4–5 keyframes for a 90° pan. Same threshold semantics for both pose-based and flow-based."
-                    />
-                    <SectionHeader title="Max keyframes per capture" />
-                    <SegmentedControl
-                      options={['3', '4', '5', '6', '8', '10']}
-                      value={String(settings.keyframeMaxCount)}
-                      onChange={(v) => update({ keyframeMaxCount: parseInt(v, 10) })}
-                      caption="Hard cap. 6 (default) matches Samsung's behaviour. Once reached, host auto-finalizes."
-                    />
-                  </>
-                )}
-                {settings.frameSelectionMode === 'flow-based' && (
-                  <>
-                    <SectionHeader title="Flow tuning — max corners" />
-                    <SegmentedControl
-                      options={['50', '100', '150', '200', '300']}
-                      value={String(settings.flowMaxCorners)}
-                      onChange={(v) => update({ flowMaxCorners: parseInt(v, 10) })}
-                      caption="Max Shi-Tomasi corners detected per accepted keyframe. More = more robust median, slower detect. 150 = default."
-                    />
-                    <SectionHeader title="Flow tuning — quality level" />
-                    <SegmentedControl
-                      options={['0.005', '0.01', '0.02', '0.03', '0.05']}
-                      value={String(settings.flowQualityLevel)}
-                      onChange={(v) => update({ flowQualityLevel: parseFloat(v) })}
-                      caption="Shi-Tomasi corner quality threshold. Lower = more (weaker) corners; higher = fewer (stronger) corners. 0.01 = default."
-                    />
-                    <SectionHeader title="Flow tuning — min distance" />
-                    <SegmentedControl
-                      options={['5', '8', '10', '15', '20']}
-                      value={String(settings.flowMinDistance)}
-                      onChange={(v) => update({ flowMinDistance: parseInt(v, 10) })}
-                      caption="Min pixel distance between detected corners (working resolution = 720 px longest side). Higher = more spatially-spread features. 10 = default."
-                    />
-                    <SectionHeader title="Flow tuning — translation budget (cm)" />
-                    <SegmentedControl
-                      options={['0', '5', '8', '12', '20', '50']}
-                      value={String(settings.flowMaxTranslationCm)}
-                      onChange={(v) => update({ flowMaxTranslationCm: parseInt(v, 10) })}
-                      caption="Force-accept when camera has moved this many cm since last keyframe, even if novelty < overlap threshold. Bounds parallax so the stitcher can match. 0 = disabled (default). 8 = recommended starting value."
-                    />
-                    <SectionHeader title="Flow tuning — novelty percentile" />
-                    <SegmentedControl
-                      options={['0.50', '0.70', '0.85', '0.95', '0.99']}
-                      value={settings.flowNoveltyPercentile.toFixed(2)}
-                      onChange={(v) => update({ flowNoveltyPercentile: parseFloat(v) })}
-                      caption="How tracked-feature displacements are aggregated into novelty. 0.50 = pre-V16 median behaviour (conservative). 0.85 = picks up leading-edge motion sooner (default, matches user perception). 0.99 = near-max, very aggressive."
-                    />
-                    <SectionHeader title="Flow tuning — eval every N frames" />
-                    <SegmentedControl
-                      options={['1', '2', '3', '5', '10']}
-                      value={String(settings.flowEvalEveryNFrames)}
-                      onChange={(v) => update({ flowEvalEveryNFrames: parseInt(v, 10) })}
-                      caption="Throttle gate evaluation to every Nth AR frame. 1 = every frame (default, no throttle). 3-5 = noticeable CPU/battery savings on long captures, up to N-1 frames of acceptance latency."
-                    />
-                  </>
-                )}
-              </>
-            )}
-
-            {/* ──────────────────────────────────────────────
-             *  AR PLANE PROJECTION — used by KeyframeGate's overlap
-             *  calculation, slit-scan plane-projection, and (future)
-             *  pose-driven batch.  Sub-fields reveal based on source.
-             * ────────────────────────────────────────────── */}
-            <SectionHeader title="AR plane projection" />
+            <SectionHeader title="Debug" />
             <SegmentedControl
-              options={['Disabled', 'ARKitDetected', 'Virtual']}
-              value={settings.planeSource}
-              onChange={(v) => update({ planeSource: v as PanoramaSettings['planeSource'] })}
-              caption="Disabled: no plane (gate falls back to angular delta). ARKitDetected: latch ARKit's vertical plane (best fidelity, picky). Virtual: synthesise plane perpendicular to camera at a fixed depth (always works)."
+              options={['off', 'on']}
+              value={settings.debug ? 'on' : 'off'}
+              onChange={(v) => updateBase({ debug: v === 'on' })}
+              caption="When ON, <Camera> mounts the diagnostic pills (memory, keyframes, orientation), the detailed metrics overlay, and the stitch-stats toast on every successful finalize.  OFF (default) — production end-user UI."
             />
-            {settings.planeSource === 'ARKitDetected' && (
-              <>
-                <SectionHeader title="ARKit alignment threshold" />
-                <SegmentedControl
-                  options={['0.3', '0.5', '0.6', '0.7', '0.85']}
-                  value={settings.arkitPlaneAlignmentThreshold.toFixed(2)}
-                  onChange={(v) => update({ arkitPlaneAlignmentThreshold: parseFloat(v) })}
-                  caption="Min dot product between candidate plane normal and camera facing. 0.6 (default) = ~53° max angle off-camera. Higher = stricter."
-                />
-              </>
-            )}
-            {settings.planeSource === 'Virtual' && (
-              <>
-                <SectionHeader title="Virtual plane depth" />
-                <SegmentedControl
-                  options={['0.5m', '1.0m', '1.5m', '2.0m', '3.0m']}
-                  value={`${settings.virtualPlaneDepthMeters.toFixed(1)}m`}
-                  onChange={(v) => update({ virtualPlaneDepthMeters: parseFloat(v) })}
-                  caption="Synthetic plane depth at first frame. Set to your typical scan distance."
-                />
-              </>
-            )}
-            {settings.planeSource !== 'Disabled' && (
-              <>
-                <SectionHeader title="Plane projection style" />
-                <SegmentedControl
-                  options={['Rectified', 'Trapezoidal']}
-                  value={settings.planeProjectionStyle}
-                  onChange={(v) => update({ planeProjectionStyle: v as PanoramaSettings['planeProjectionStyle'] })}
-                  caption="Rectified (default): clean rectangle paste, no tilt distortion. Trapezoidal: V15.0b legacy 3D-correct raycast — geometric purity at the cost of tilt artifacts."
-                />
-              </>
-            )}
 
             {/* ──────────────────────────────────────────────
-             *  ALGORITHM — what runs at stitch time.  In batch mode
-             *  there's no choice (cv::Stitcher feature-matched
-             *  pipeline).  In realtime, three live engines.
+             *  FRAME SELECTION (`frameSelection` sub-tree, closed by default)
+             *
+             *  Placed above Stitcher because keyframe-gate tuning is
+             *  the more frequently touched control surface during
+             *  capture-quality troubleshooting.  Stitcher knobs are
+             *  rarely changed at runtime.
+             *
+             *  Nested Flow-tunables section reveals when mode is
+             *  flow-based (mirrors the `frameSelection.flow` optional
+             *  on the type).
              * ────────────────────────────────────────────── */}
-            <SectionHeader title="Algorithm" />
-            {timing === 'batch' ? (
-              <View style={styles.infoBox}>
-                <Text style={styles.infoText}>
-                  Full feature-matched pipeline:
-                  ORB → BFMatcher → RANSAC → BundleAdjusterRay →
-                  waveCorrect → Warper → GraphCutSeamFinder →
-                  ExposureCompensator → MultiBandBlender. No engine
-                  choice in batch mode.
-                </Text>
-              </View>
-            ) : (
+            <Accordion title="Frame selection (KeyframeGate)">
+              <SectionHeader title="Mode" />
               <SegmentedControl
-                options={['hybrid', 'slitscan-rotate', 'slitscan-both']}
-                value={realtimeAlgorithm}
-                onChange={(v) => update({ incrementalEngine: v as PanoramaSettings['incrementalEngine'] })}
-                caption="hybrid: streaming planar projection + feature matching. slitscan-rotate: V13.0a + 1D NCC. slitscan-both: V13.0a + no accept gate + feather blend (iteration playground)."
+                options={['time-based', 'pose-based', 'flow-based']}
+                value={settings.frameSelection.mode}
+                onChange={(v) => updateFrameSelection({
+                  mode: v as FrameSelectionSettings['mode'],
+                })}
+                caption="flow-based (default): sparse Shi-Tomasi + KLT optical flow.  Plane-independent.  pose-based: plane-overlap when a plane is latched, angular fallback otherwise — cheap but conservative.  time-based: gate disabled; every frame accepted up to maxKeyframes."
               />
-            )}
-
-            {/* ──────────────────────────────────────────────
-             *  ALGORITHM TUNING — engine-specific knobs revealed
-             *  by current Algorithm choice.
-             * ────────────────────────────────────────────── */}
-            {timing === 'batch' && (
-              <>
-                {/* Capture source + stitch mode were lifted to the
-                 * TOP of the modal (above the timing picker) on
-                 * 2026-05-14 since they're pipeline-level decisions,
-                 * not batch-tuning knobs.  See the top of the
-                 * ScrollView for those controls. */}
-                <SectionHeader title="Batch tuning — Warper" />
-                <SegmentedControl
-                  options={['plane', 'cylindrical', 'spherical']}
-                  value={settings.warperType}
-                  onChange={(v) => update({ warperType: v as PanoramaSettings['warperType'] })}
-                  caption="plane (default, recommended for retail shelves): flat rectangular output. cylindrical: rotational mid-arc, gentle curvature. spherical: wide pans (180°+) but always-curved."
-                />
-                <SectionHeader title="Batch tuning — Blender" />
-                <SegmentedControl
-                  options={['multiband', 'feather']}
-                  value={settings.blenderType}
-                  onChange={(v) => update({ blenderType: v as PanoramaSettings['blenderType'] })}
-                  caption="multiband (default): Laplacian-pyramid blending; cleanest seams. feather: faster, no halo when exposure varies."
-                />
-                <SectionHeader title="Batch tuning — Seam finder" />
-                <SegmentedControl
-                  options={['graphcut', 'skip']}
-                  value={settings.seamFinderType}
-                  onChange={(v) => update({ seamFinderType: v as PanoramaSettings['seamFinderType'] })}
-                  caption="graphcut (default): cv::detail::GraphCutSeamFinder; optimal seams, pairs with multiband, holds all warps in memory. skip: stream warp+feed (lower peak memory)."
-                />
-                <SectionHeader title="Batch tuning — Inscribed-rect crop" />
-                <SegmentedControl
-                  options={['off', 'on']}
-                  value={settings.enableMaxInscribedRectCrop ? 'on' : 'off'}
-                  onChange={(v) => update({ enableMaxInscribedRectCrop: v === 'on' })}
-                  caption="off (default): final crop is just cv::boundingRect of non-black pixels — preserves all stitched content; may have black corners. on: additionally run MaxInscribedRectFromMask + column-projection second-pass for a clean-cornered rectangle — can shrink the output if the panorama mask is lopsided. A/B against the bbox crop on real scenes."
-                />
-              </>
-            )}
-            {timing === 'realtime' && realtimeAlgorithm === 'hybrid' && (
-              <>
-                <SectionHeader title="Hybrid tuning — Projection" />
-                <SegmentedControl
-                  options={['Planar', 'Cylindrical']}
-                  value={settings.hybridProjection}
-                  onChange={(v) => update({ hybridProjection: v as PanoramaSettings['hybridProjection'] })}
-                  caption="Planar (default): cv::detail::PlaneWarper. Cylindrical: V12.x – V14.0a behaviour (legacy)."
-                />
-              </>
-            )}
-            {timing === 'realtime' && realtimeAlgorithm.startsWith('slitscan') && (
-              <>
-                <SectionHeader title="Slit-scan tuning — Slit width" />
-                <SegmentedControl
-                  options={['0.01', '0.05', '0.10', '0.20', '0.30', '0.50']}
-                  value={settings.slitWidthFraction.toFixed(2)}
-                  onChange={(v) => update({ slitWidthFraction: parseFloat(v) })}
-                  caption="Fraction of pan-axis retained per sliver. 0.30 (V15 default) ≈ 324 px. Smaller = less within-slit depth disagreement."
-                />
-                <SectionHeader title="Slit-scan tuning — Sliver position" />
-                <SegmentedControl
-                  options={['Center', 'Bottom', 'Top']}
-                  value={settings.sliverPosition}
-                  onChange={(v) => update({ sliverPosition: v as PanoramaSettings['sliverPosition'] })}
-                  caption="Where on the camera sensor frame the sliver is taken."
-                />
-                <SectionHeader title="Slit-scan tuning — Full first-frame" />
-                <SegmentedControl
-                  options={['off', 'on']}
-                  value={settings.firstFrameFullFrame ? 'on' : 'off'}
-                  onChange={(v) => update({ firstFrameFullFrame: v === 'on' })}
-                  caption="ON: first accepted frame paints the full camera frame at the canvas anchor; subsequent frames use sliver clip."
-                />
-                <SectionHeader title="Slit-scan tuning — Paint mode" />
-                <SegmentedControl
-                  options={['FirstPaintedWins', 'FeatherBlend']}
-                  value={settings.paintMode}
-                  onChange={(v) => update({ paintMode: v as PanoramaSettings['paintMode'] })}
-                  caption="FirstPaintedWins (default): protect already-painted pixels. FeatherBlend: alpha-blend new content into overlap."
-                />
-              </>
-            )}
-
-            {/* ──────────────────────────────────────────────
-             *  ADVANCED — 2D NCC fine-alignment (closed by default).
-             *  Used by slit-scan plane mode and any 2D NCC stage.
-             * ────────────────────────────────────────────── */}
-            <Accordion title="Advanced — 2D NCC fine-alignment" badge="advanced">
-              <SectionHeader title="Enable 2D NCC" />
+              <SectionHeader title="Max keyframes per capture" />
               <SegmentedControl
-                options={['off', 'on']}
-                value={settings.enable2dNcc ? 'on' : 'off'}
-                onChange={(v) => update({ enable2dNcc: v === 'on' })}
-                caption="V13.0g 2D NCC fine-alignment after pose-driven projection. Refines (Δx, Δy) translation via cv::matchTemplate."
+                options={['3', '4', '5', '6', '8', '10']}
+                value={String(settings.frameSelection.maxKeyframes)}
+                onChange={(v) => updateFrameSelection({
+                  maxKeyframes: parseInt(v, 10),
+                })}
+                caption="Hard cap on accepted keyframes; native clamps to [3, 10].  6 (default) matches Samsung Pano's behaviour and is the sweet spot for cv::Stitcher BA convergence."
+              />
+              <SectionHeader title="Overlap threshold (new content per keyframe)" />
+              <SegmentedControl
+                options={['20%', '30%', '40%', '50%', '60%']}
+                value={`${Math.round(settings.frameSelection.overlapThreshold * 100)}%`}
+                onChange={(v) => updateFrameSelection({
+                  overlapThreshold: parseInt(v, 10) / 100,
+                })}
+                caption="Required NEW-content fraction.  20% (default): generous, ~5–6 keyframes for a 90° pan.  Native clamps to [10%, 80%]."
               />
-              {settings.enable2dNcc && (
-                <>
-                  <SectionHeader title="Confidence threshold" />
+
+              {showFlowTunables && (
+                <View style={styles.nested}>
+                  <Text style={styles.nestedLabel}>Flow tuning</Text>
+                  <SectionHeader title="Max corners (Shi-Tomasi)" />
+                  <SegmentedControl
+                    options={['50', '100', '150', '200', '300']}
+                    value={String(settings.frameSelection.flow?.maxCorners
+                      ?? DEFAULT_FLOW_GATE_SETTINGS.maxCorners)}
+                    onChange={(v) => updateFlow({ maxCorners: parseInt(v, 10) })}
+                    caption="More corners = more robust median displacement, slower detect.  150 (default) ~ 15–25 ms / frame on Galaxy A35.  Native clamps to [50, 300]."
+                  />
+                  <SectionHeader title="Quality level (Shi-Tomasi)" />
                   <SegmentedControl
-                    options={['0.50', '0.65', '0.75', '0.85', '0.95', '0.99']}
-                    value={settings.nccConfidenceThreshold2d.toFixed(2)}
-                    onChange={(v) => update({ nccConfidenceThreshold2d: parseFloat(v) })}
-                    caption="Reject NCC corrections below this confidence. 0.99 = only apply on near-perfect overlap."
+                    options={['0.005', '0.01', '0.02', '0.03', '0.05']}
+                    value={String(settings.frameSelection.flow?.qualityLevel
+                      ?? DEFAULT_FLOW_GATE_SETTINGS.qualityLevel)}
+                    onChange={(v) => updateFlow({ qualityLevel: parseFloat(v) })}
+                    caption="Lower lets weaker corners in; higher demands stronger corners.  0.01 (default).  Clamped to [0.005, 0.05]."
                   />
-                  <SectionHeader title="Search half-window (px)" />
+                  <SectionHeader title="Min distance (working-resolution px)" />
                   <SegmentedControl
-                    options={['6', '10', '12', '20', '30']}
-                    value={String(settings.nccSearchMargin2d)}
-                    onChange={(v) => update({ nccSearchMargin2d: parseInt(v, 10) })}
-                    caption="Pixels: 2D NCC searches ±this around the pose-predicted match."
+                    options={['5', '8', '10', '15', '20']}
+                    value={String(settings.frameSelection.flow?.minDistance
+                      ?? DEFAULT_FLOW_GATE_SETTINGS.minDistance)}
+                    onChange={(v) => updateFlow({ minDistance: parseInt(v, 10) })}
+                    caption="Min pixel distance between detected corners (working res = 720 px longest side).  10 (default).  Clamped to [1, 50]."
                   />
-                  <SectionHeader title="EMA smoothing" />
+                  <SectionHeader title="Translation budget (cm)" />
                   <SegmentedControl
-                    options={['off', 'on']}
-                    value={settings.enableNcc2dEmaSmoothing ? 'on' : 'off'}
-                    onChange={(v) => update({ enableNcc2dEmaSmoothing: v === 'on' })}
-                    caption="Damp single-frame snaps to spurious peaks via EMA."
+                    options={['0', '5', '8', '12', '20', '50']}
+                    value={String(settings.frameSelection.flow?.maxTranslationCm
+                      ?? DEFAULT_FLOW_GATE_SETTINGS.maxTranslationCm)}
+                    onChange={(v) => updateFlow({
+                      maxTranslationCm: parseInt(v, 10),
+                    })}
+                    caption="Force-accept the next frame once the operator has translated this many cm since the last keyframe, even when novelty < threshold.  Bounds parallax so cv::Stitcher's matcher can handle the input.  50 (default).  0 disables.  Clamped to [0, 100]."
                   />
-                  {settings.enableNcc2dEmaSmoothing && (
-                    <>
-                      <SectionHeader title="EMA alpha (current-frame weight)" />
-                      <SegmentedControl
-                        options={['0.20', '0.30', '0.40', '0.60', '0.80']}
-                        value={settings.ncc2dEmaAlpha.toFixed(2)}
-                        onChange={(v) => update({ ncc2dEmaAlpha: parseFloat(v) })}
-                      />
-                    </>
-                  )}
-                  <SectionHeader title="Pan-axis lock" />
+                  <SectionHeader title="Novelty percentile" />
                   <SegmentedControl
-                    options={['off', 'on']}
-                    value={settings.enableNcc2dPanAxisLock ? 'on' : 'off'}
-                    onChange={(v) => update({ enableNcc2dPanAxisLock: v === 'on' })}
-                    caption="Clamp cross-axis correction tighter than pan-axis (pose + 1D NCC handle cross-axis already)."
+                    options={['0.50', '0.70', '0.85', '0.95', '0.99']}
+                    value={(settings.frameSelection.flow?.noveltyPercentile
+                      ?? DEFAULT_FLOW_GATE_SETTINGS.noveltyPercentile).toFixed(2)}
+                    onChange={(v) => updateFlow({
+                      noveltyPercentile: parseFloat(v),
+                    })}
+                    caption="How tracked-feature displacements aggregate into a per-axis novelty estimate.  0.85 (default): picks up leading-edge motion sooner — matches user perception.  0.50: pre-V16 median (conservative).  0.99: very aggressive.  Clamped to [0.50, 0.99]."
                   />
-                  {settings.enableNcc2dPanAxisLock && (
-                    <>
-                      <SectionHeader title="Cross-axis clamp (px)" />
-                      <SegmentedControl
-                        options={['2', '5', '10', '15']}
-                        value={String(settings.ncc2dCrossAxisLockPx)}
-                        onChange={(v) => update({ ncc2dCrossAxisLockPx: parseInt(v, 10) })}
-                      />
-                    </>
-                  )}
-                </>
+                  <SectionHeader title="Eval every N frames" />
+                  <SegmentedControl
+                    options={['1', '2', '3', '5', '10']}
+                    value={String(settings.frameSelection.flow?.evalEveryNFrames
+                      ?? DEFAULT_FLOW_GATE_SETTINGS.evalEveryNFrames)}
+                    onChange={(v) => updateFlow({
+                      evalEveryNFrames: parseInt(v, 10),
+                    })}
+                    caption="Throttle gate evaluation to every Nth frame for CPU savings.  5 (default) gives ~6 Hz novelty samples at 30 Hz ARCore.  Doesn't change WHICH frames are accepted; only the sample rate.  Clamped to [1, 10]."
+                  />
+                </View>
               )}
             </Accordion>
 
             {/* ──────────────────────────────────────────────
-             *  ADVANCED — Slit-scan experimental.  Only relevant
-             *  when slitscan-both is the active engine.
-             * ────────────────────────────────────────────── */}
-            {timing === 'realtime' && realtimeAlgorithm === 'slitscan-both' && (
-              <Accordion title="Advanced — Slit-scan experimental" badge="experimental">
-                <SectionHeader title="Triangulation parallax" />
-                <SegmentedControl
-                  options={['off', 'on']}
-                  value={settings.enableTriangulation ? 'on' : 'off'}
-                  onChange={(v) => update({ enableTriangulation: v === 'on' })}
-                  caption="V13.0e ORB triangulation + median-Z parallax correction. Adds ~10ms/accept."
-                />
-                <SectionHeader title="RANSAC homography" />
-                <SegmentedControl
-                  options={['off', 'on']}
-                  value={settings.enableRansacHomography ? 'on' : 'off'}
-                  onChange={(v) => update({ enableRansacHomography: v === 'on' })}
-                  caption="V14.0a RANSAC homography per slit + cv::warpPerspective. Known limitation: can absorb pan as scale, leaving gaps."
-                />
-                <SectionHeader title="Accept gate (px)" />
-                <SegmentedControl
-                  options={['0', '50']}
-                  value={String(settings.acceptGate)}
-                  onChange={(v) => update({ acceptGate: parseInt(v, 10) as PanoramaSettings['acceptGate'] })}
-                  caption="0 = accept on every frame (Apple-dense). 50 = V13.0g throttle."
-                />
-              </Accordion>
-            )}
-
-            {/* ──────────────────────────────────────────────
-             *  OUTPUT — always visible.
+             *  STITCHER (`stitcher` sub-tree, closed by default)
              * ────────────────────────────────────────────── */}
-            <SectionHeader title="Recording cap" />
-            <SegmentedControl
-              options={['4 s', '6 s', '8 s', '10 s']}
-              value={`${Math.round(settings.maxRecordingMs / 1000)} s`}
-              onChange={(v) => update({ maxRecordingMs: parseInt(v, 10) * 1000 })}
-              caption="Auto-stops the hold-recording at this duration."
-            />
-            <SectionHeader title="JPEG quality" />
-            <SegmentedControl
-              options={['70', '85', '92']}
-              value={String(settings.quality)}
-              onChange={(v) => update({ quality: parseInt(v, 10) })}
-              caption="Higher = bigger files, sharper detail. 85 is the recommended default."
-            />
-
-            {/* ──────────────────────────────────────────────
-             *  DEBUG — surfaces stitch telemetry to the operator on
-             *  every successful finalize.  See PanoramaSettings.debug.
-             * ────────────────────────────────────────────── */}
-            <SectionHeader title="Debug" />
-            <SegmentedControl
-              options={['off', 'on']}
-              value={settings.debug ? 'on' : 'off'}
-              onChange={(v) => update({ debug: v === 'on' })}
-              caption="When ON, every successful stitch shows a popup with the C+D progressive-confidence retry telemetry (frames included, final threshold, retry attempts). Off by default."
-            />
-
-            {/* ──────────────────────────────────────────────
-             *  DIAGNOSTICS / FALLBACKS — closed by default.  AR is
-             *  the active path for 99% of use; the vision-camera
-             *  fallback path lives here for emergencies.
-             * ────────────────────────────────────────────── */}
-            <Accordion title="Diagnostics / fallbacks" badge="rarely needed">
-              <View style={styles.infoBox}>
-                <Text style={styles.infoText}>
-                  AR-backed capture is the recommended path. Toggle off
-                  ONLY if ARKit fails on a specific device (very rare on
-                  modern iPhones). Doing so falls back to vision-camera
-                  video recording + post-stitch via cv::Stitcher.
-                </Text>
-              </View>
-              <SectionHeader title="AR-backed capture" />
+            <Accordion title="Stitcher (cv::Stitcher knobs)">
+              <SectionHeader title="Stitch mode" />
               <SegmentedControl
-                options={['on', 'off']}
-                value={settings.useARPreview ? 'on' : 'off'}
-                onChange={(v) => update({ useARPreview: v === 'on' })}
-                caption="Default ON. OFF only when ARKit is unavailable or for A/B testing."
+                options={['auto', 'panorama', 'scans']}
+                value={settings.stitcher.stitchMode}
+                onChange={(v) => updateStitcher({
+                  stitchMode: v as BatchStitcherSettings['stitchMode'],
+                })}
+                caption="auto (default): pick PANORAMA or SCANS based on translation/rotation totals at finalize.  panorama: rotation-only (spherical warper, BA-Ray) — best for rotate-in-place captures; BAD on translation.  scans: affine pipeline (plane warper, BA-affine) — best for shelf-pan captures; never diverges on rotation either.  Both modes auto-retry with the opposite if camera params come out degenerate."
+              />
+              <SectionHeader title="Warper" />
+              <SegmentedControl
+                options={['plane', 'cylindrical', 'spherical']}
+                value={settings.stitcher.warperType}
+                onChange={(v) => updateStitcher({
+                  warperType: v as BatchStitcherSettings['warperType'],
+                })}
+                caption="plane (default): flat rectangular output, best for retail shelves.  cylindrical: rotational mid-arc.  spherical: wide pans (180°+), always curved.  Only consulted in panorama mode; scans hardwires PlaneWarper."
+              />
+              <SectionHeader title="Blender" />
+              <SegmentedControl
+                options={['multiband', 'feather']}
+                value={settings.stitcher.blenderType}
+                onChange={(v) => updateStitcher({
+                  blenderType: v as BatchStitcherSettings['blenderType'],
+                })}
+                caption="multiband (default): Laplacian-pyramid blending; cleanest seams, holds all warped frames in memory.  feather: streams warp+feed (lower peak memory, no halo with varied exposure).  <Camera> auto-picks feather on low-memory devices."
+              />
+              <SectionHeader title="Seam finder" />
+              <SegmentedControl
+                options={['graphcut', 'skip']}
+                value={settings.stitcher.seamFinderType}
+                onChange={(v) => updateStitcher({
+                  seamFinderType: v as BatchStitcherSettings['seamFinderType'],
+                })}
+                caption="graphcut (default): cv::detail::GraphCutSeamFinder for optimal seams; pairs with multiband.  skip: stream warp+feed (lowest-memory configuration; pair with feather)."
+              />
+              <SectionHeader title="Inscribed-rect crop" />
+              <SegmentedControl
+                options={['off', 'on']}
+                value={settings.stitcher.enableMaxInscribedRectCrop ? 'on' : 'off'}
+                onChange={(v) => updateStitcher({
+                  enableMaxInscribedRectCrop: v === 'on',
+                })}
+                caption="off (default): crop to cv::boundingRect of non-black pixels — preserves all stitched content; may leave black corners.  on: run MaxInscribedRectFromMask + column-projection second-pass for a clean rectangle (can shrink output if mask is lopsided)."
               />
-              {!settings.useARPreview && (
-                <>
-                  <SectionHeader title="Frame extraction — Frames per second" />
-                  <SegmentedControl
-                    options={['2', '3', '4']}
-                    value={String(settings.framesPerSecond)}
-                    onChange={(v) => update({ framesPerSecond: parseInt(v, 10) })}
-                    caption="Frames/sec extracted from the recorded video. Lower = faster but riskier overlap."
-                  />
-                  <SectionHeader title="Frame extraction — Frame count clamp" />
-                  <SegmentedControl
-                    options={['4-12', '6-16', '8-20']}
-                    value={`${settings.minFrames}-${settings.maxFrames}`}
-                    onChange={(v) => {
-                      const [min, max] = v.split('-').map((n) => parseInt(n, 10));
-                      update({ minFrames: min, maxFrames: max });
-                    }}
-                    caption="Floor/ceiling for extracted frames."
-                  />
-                </>
-              )}
             </Accordion>
 
+            {/* ──────────────────────────────────────────────
+             *  RESET TO DEFAULTS
+             * ────────────────────────────────────────────── */}
             <Pressable
               onPress={() => onChange(DEFAULT_PANORAMA_SETTINGS)}
               style={styles.resetBtn}
@@ -1066,21 +382,20 @@ export function PanoramaSettingsModal({
 }
 
 
+// ════════════════════════════════════════════════════════════════════
+// Helpers (kept verbatim from v0.3 — presentational primitives the
+// modal composes; nothing in here depends on the settings shape).
+// ════════════════════════════════════════════════════════════════════
+
 function SectionHeader({ title }: { title: string }) {
   return <Text style={styles.sectionHeader}>{title}</Text>;
 }
 
 
 /**
- * Collapsible section.  Used for closed-by-default groupings
- * ("Advanced", "Diagnostics / fallbacks") so the modal's primary
- * surface stays focused on the controls operators actually touch
- * day-to-day.
- *
- * State is local — each Accordion instance manages its own open
- * flag.  The modal opens fresh-collapsed every mount which is what
- * we want for now; persisting open state across mounts (e.g. via
- * AsyncStorage) is a future enhancement.
+ * Collapsible section.  Each instance owns its open/closed state;
+ * the modal opens fresh-collapsed on every mount, which is what we
+ * want (no AsyncStorage roundtrip on every settings tweak).
  */
 function Accordion({
   title,
@@ -1114,9 +429,10 @@ function Accordion({
 
 
 /**
- * Small grey-text badge.  Marks sections / fields as "advanced",
- * "experimental", "legacy", or similar — quick visual signal that
- * the operator can usually ignore them.
+ * Small grey-text badge — marks sections as "advanced",
+ * "experimental", or similar.  No semantic effect; purely a quick
+ * visual signal.  Kept for future Layer-2 settings modals that may
+ * want to flag experimental sub-trees.
  */
 function Tag({ label }: { label: string }): React.JSX.Element {
   return (
@@ -1228,18 +544,21 @@ const styles = StyleSheet.create({
     marginTop: 18,
     marginBottom: 8,
   },
-  row: {
-    marginTop: 4,
+  // Nested-sub-section label inside an accordion body — used for the
+  // Flow-tunables sub-tree under Frame selection.
+  nested: {
+    marginTop: 12,
+    paddingTop: 12,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: 'rgba(255,255,255,0.08)',
   },
-  label: {
-    color: '#ffffff',
-    opacity: 0.85,
-    fontSize: 13,
+  nestedLabel: {
+    color: 'rgba(255,255,255,0.55)',
+    fontSize: 11,
     fontWeight: '600',
     textTransform: 'uppercase',
-    letterSpacing: 0.5,
-    marginTop: 18,
-    marginBottom: 8,
+    letterSpacing: 0.8,
+    marginBottom: 4,
   },
   segmentedRow: {
     flexDirection: 'row',
@@ -1299,7 +618,6 @@ const styles = StyleSheet.create({
     fontSize: 14,
     fontWeight: '500',
   },
-  // V16 Phase 1b — Accordion + Tag + InfoBox
   accordion: {
     marginTop: 18,
     backgroundColor: 'rgba(255,255,255,0.04)',
@@ -1344,15 +662,4 @@ const styles = StyleSheet.create({
     textTransform: 'uppercase',
     letterSpacing: 0.5,
   },
-  infoBox: {
-    backgroundColor: 'rgba(255,255,255,0.06)',
-    borderRadius: 8,
-    padding: 12,
-    marginTop: 4,
-  },
-  infoText: {
-    color: 'rgba(255,255,255,0.75)',
-    fontSize: 12,
-    lineHeight: 17,
-  },
 });