react-native-image-stitcher 0.15.2 → 0.16.1

package/dist/camera/usePanMotion.js

@@ -0,0 +1,451 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * usePanMotion — one sensor-fed hook that exposes the three motion
+ * signals the first-time-user GUIDANCE surfaces share, so the screen
+ * spins up ONE gyroscope + ONE accelerometer subscription instead of
+ * three independent ones.
+ *
+ * Consumers
+ *   - Item 3 (pan how-to / direction arrow) wants `resolvedAxis` to
+ *     know whether the user is panning horizontally or vertically.
+ *   - Item 4 ("Moving too fast, slow down") wants `panSpeedBucket`.
+ *   - Item 6 (lateral-drift → finalize + popup) wants `lateralCm` /
+ *     `lateralExceeded`.
+ *
+ * Why one hook (and not three components each subscribing)
+ *   `react-native-sensors` is global: every `gyroscope.subscribe` /
+ *   `accelerometer.subscribe` adds a listener to the same underlying
+ *   native sensor, and `setUpdateIntervalForType` is process-wide.
+ *   Three subscribers means three JS callbacks per native sample +
+ *   three teardown paths to get right.  Funnelling the shared signals
+ *   through one hook keeps the sensor wiring in a single place.
+ *
+ * ── Speed bucket (Item 4) ────────────────────────────────────────
+ * Reuses `PanoramaGuidance`'s gyro logic verbatim (see `bucketFor`
+ * below, lifted from that file): take the dominant rotation axis for
+ * the current pan direction and map |rad/s| onto good / warn / bad.
+ *   horizontal pan (portrait, Mode B)  → gyro Y dominates.
+ *   vertical   pan (landscape, Mode A) → gyro X dominates.
+ * Defaults 0.5 / 1.0 rad/s match `PanoramaGuidance`'s SCANS tuning.
+ *
+ * ── Lateral drift (Item 6) ───────────────────────────────────────
+ * This is the subtle part.  `useIMUTranslationGate` integrates the
+ * accelerometer along **device-X**, because in BOTH pan modes the
+ * pan axis maps to device-X (portrait: user left/right; landscape:
+ * device-X has rotated 90° into user up/down).  That gate's X
+ * integrator RESETS at every accepted keyframe (and auto-rearms on
+ * each budget fire) — see its header — because it measures
+ * translation-*along*-the-pan between keyframes.
+ *
+ * Lateral drift is the ORTHOGONAL motion: the operator sliding the
+ * phone sideways out of the pan plane.  Orthogonal to device-X is
+ * **device-Y**, in both modes.  So we integrate device-Y here.
+ *
+ * Crucially this accumulator must measure drift over the WHOLE
+ * capture, not per-keyframe — a slow continuous sideways creep would
+ * never trip a per-keyframe-reset budget.  So unlike the gate's
+ * `posX`, our `posY` resets ONLY on `active` false → true (capture
+ * start).  It is never reset by keyframe accepts (this hook doesn't
+ * even know about them).
+ *
+ * We borrow the gate's drift-mitigation recipe (per-axis IIR gravity
+ * estimate + per-sample velocity damping + iOS G→m/s² scaling) so the
+ * lateral integrator has the same noise floor characteristics.
+ *
+ * Grace window
+ *   A short slide as the operator settles their grip at capture start
+ *   shouldn't fire the "you drifted" popup.  `lateralExceeded` only
+ *   latches once the budget has been *continuously* exceeded for
+ *   `LATERAL_GRACE_MS` (default 500 ms).  A dip back under budget
+ *   resets the grace timer, so a single wobble that crosses and
+ *   immediately recrosses the threshold never latches.  Once latched
+ *   it STAYS latched until the next capture (matches Item 6's
+ *   product decision: finalize what's captured, then show the popup —
+ *   we don't un-finalize if the phone wobbles back).
+ *
+ * Performance
+ *   Gyro at ~30 Hz, accel at ~50 Hz, all integrator state in refs.
+ *   `setState` fires only on a *qualitative* change (bucket flips, or
+ *   the exceeded latch trips) — never per sample.  `lateralCm` is the
+ *   one exception consumers may want live; it's exposed via the
+ *   returned object but only re-rendered on the throttled tick (see
+ *   `LATERAL_EMIT_INTERVAL_MS`) so a debug/HUD readout updates without
+ *   a 50 Hz re-render storm.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._bucketForRate = _bucketForRate;
+exports._gyroRateForAxis = _gyroRateForAxis;
+exports._resolvePanAxis = _resolvePanAxis;
+exports._evalGraceLatch = _evalGraceLatch;
+exports._freshLateralState = _freshLateralState;
+exports._resetLateralState = _resetLateralState;
+exports._integrateLateralSample = _integrateLateralSample;
+exports.usePanMotion = usePanMotion;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const react_native_sensors_1 = require("react-native-sensors");
+const useDeviceOrientation_1 = require("./useDeviceOrientation");
+// ── Speed-bucket constants ────────────────────────────────────────
+// v0.16: lowered from 0.5 / 1.0.  On-device the old 1.0 rad/s (~57°/s)
+// "bad" trip point almost never fired for a hand pan that's genuinely too
+// fast for good keyframe overlap — a brisk-but-too-fast sweep sits around
+// 0.5–0.8 rad/s.  0.6 rad/s (~34°/s) is the new "too fast" line; tune via
+// the `panTooFastThreshold` prop (or the __DEV__ [panMotion] gyro logs).
+const DEFAULT_GOOD_RAD_PER_SEC = 0.4;
+const DEFAULT_WARN_RAD_PER_SEC = 0.6;
+// ── Lateral-drift constants ───────────────────────────────────────
+// v0.16: lowered 5 → 4 cm so a deliberate sideways slide trips sooner.
+// NOTE: the cm budget now only feeds the (secondary) accel readout; the
+// PRIMARY lateral trigger is the gyro cross-axis below.
+const DEFAULT_LATERAL_BUDGET_CM = 4;
+/**
+ * Lateral-drift trip point on the SMOOTHED cross-pan gyro rate (EMA of
+ * `|gyro.x|`), in rad/s.
+ *
+ * v0.16 — on-device traces showed a user "moving perpendicular to the arrow"
+ * is really a ROTATION about the cross-pan axis (gyro X), not a sideways
+ * translation — so the old accel double-integration never saw it.  But the
+ * raw cross rate is NOISY (dips between samples), so a continuous-over-
+ * threshold dwell reset on every dip and never latched.  We instead smooth
+ * `|gyro.x|` with an EMA (rides the dips, gives a ~0.4 s natural dwell) and
+ * latch when the SMOOTHED rate stays above this line.  A clean pan smooths
+ * to ~0.04; the user's two cross-turns smoothed to ~0.3 and ~0.7 — so 0.15
+ * separates them with a comfortable margin.
+ */
+const DEFAULT_LATERAL_TURN_RAD_PER_SEC = 0.15;
+/**
+ * EMA smoothing factor for the cross-pan gyro rate (per ~33 ms gyro sample).
+ * ~0.08 gives a time constant of ~12 samples (~0.4 s) — enough to ride
+ * through the inter-sample noise yet still respond within ~0.4 s of a
+ * sustained cross-turn.
+ */
+const LATERAL_CROSS_EMA_ALPHA = 0.08;
+/**
+ * Continuous-over-budget dwell before `lateralExceeded` latches.
+ * Filters out a settle-the-grip slide at capture start + single
+ * wobbles that cross and recross the threshold.  Documented in the
+ * task as a permitted design decision.
+ */
+const LATERAL_GRACE_MS = 500;
+/**
+ * Accelerometer sample interval (≈50 Hz).  Matches
+ * `useIMUTranslationGate` so the integration math + drift profile are
+ * identical.
+ */
+const ACCEL_SAMPLE_INTERVAL_MS = 20;
+/**
+ * Gyro sample interval (≈30 Hz).  Matches `PanoramaGuidance` so each
+ * sample maps to roughly one recording frame's pan.
+ */
+const GYRO_SAMPLE_INTERVAL_MS = 33;
+/**
+ * How often the throttled `lateralCm` React value is emitted.  The
+ * integrator runs at 50 Hz but we don't want 50 re-renders/sec for a
+ * cosmetic readout, so we coalesce to ~10 Hz.
+ */
+const LATERAL_EMIT_INTERVAL_MS = 100;
+// ── Drift-mitigation constants (lifted from useIMUTranslationGate) ─
+/// Per-sample multiplicative damping on the velocity integrator.
+const VELOCITY_DAMPING_PER_SAMPLE = 0.05;
+/// IIR low-pass coefficient for the per-axis gravity estimate.
+const GRAVITY_IIR_ALPHA = 0.9;
+/// 1 G in m/s².  `react-native-sensors` reports iOS accel in G's,
+/// Android in m/s²; we scale iOS into m/s² so the integrator is in
+/// standard units.
+const G_TO_MPS2 = 9.81;
+/// 1 metre = 100 centimetres.  The integrator works in metres; the
+/// public API is centimetres (matches the design copy + budget unit).
+const M_TO_CM = 100;
+/**
+ * Map a signed rotation rate (rad/s) onto the qualitative speed
+ * bucket.  Pure — exported for tests.  Lifted verbatim from
+ * `PanoramaGuidance.bucketFor` so the two surfaces never diverge.
+ *
+ * Thresholds are INCLUSIVE of the lower band: `|rate| <= good` is
+ * 'good', `|rate| <= warn` is 'warn', otherwise 'bad'.
+ */
+function _bucketForRate(rate, good, warn) {
+    const abs = Math.abs(rate);
+    if (abs <= good)
+        return 'good';
+    if (abs <= warn)
+        return 'warn';
+    return 'bad';
+}
+/**
+ * Pick the dominant gyro axis value for a pan direction.  Mirrors
+ * `PanoramaGuidance`'s `resolvedAxis === 'horizontal' ? y : x`:
+ *   horizontal pan (portrait)  → gyro Y dominates.
+ *   vertical   pan (landscape) → gyro X dominates.
+ * Pure — exported for tests.
+ */
+function _gyroRateForAxis(axis, gyro) {
+    return axis === 'horizontal' ? gyro.y : gyro.x;
+}
+/**
+ * Resolve the pan axis the same way `PanoramaGuidance` does:
+ *   explicit `axis` override wins; otherwise portrait → 'horizontal',
+ *   landscape → 'vertical'.  Pure — exported for tests.
+ */
+function _resolvePanAxis(orientation, override) {
+    if (override)
+        return override;
+    const isPortrait = orientation === 'portrait' || orientation === 'portrait-upside-down';
+    return isPortrait ? 'horizontal' : 'vertical';
+}
+/**
+ * Pure grace-window latch decision, factored out of the integrator so
+ * the debounce is testable without constructing a physical
+ * acceleration profile.  Given whether |pos| is currently over budget,
+ * the clock, and the prior latch/timer state, decide the next state:
+ *
+ *   - under budget          → clear the timer; never un-latch.
+ *   - over budget, no timer  → start the timer (note: NOT yet latched).
+ *   - over budget, timer old  → latch once `now - since >= graceMs`.
+ *   - already latched        → stays latched forever (one-shot
+ *                              finalize; see header).
+ *
+ * @param overBudget  is |pos| currently over the budget?
+ * @param nowMs       monotonic clock, ms
+ * @param prevSinceMs timestamp |pos| first went over in the current
+ *                    continuous run, or `null` if previously under
+ * @param prevExceeded already-latched flag from the prior sample
+ * @param graceMs     continuous dwell required before latching
+ */
+function _evalGraceLatch(overBudget, nowMs, prevSinceMs, prevExceeded, graceMs) {
+    // One-shot: once latched, stay latched (don't even touch the timer).
+    if (prevExceeded) {
+        return { exceeded: true, overBudgetSinceMs: prevSinceMs };
+    }
+    if (!overBudget) {
+        // Dipped back under budget — reset the dwell timer so a wobble
+        // that crosses and recrosses never accumulates grace.
+        return { exceeded: false, overBudgetSinceMs: null };
+    }
+    // Over budget, not yet latched.
+    if (prevSinceMs === null) {
+        // First sample of a new over-budget run — start the clock.
+        return { exceeded: false, overBudgetSinceMs: nowMs };
+    }
+    // Continuous over-budget run in progress — latch once it's old
+    // enough.
+    if (nowMs - prevSinceMs >= graceMs) {
+        return { exceeded: true, overBudgetSinceMs: prevSinceMs };
+    }
+    return { exceeded: false, overBudgetSinceMs: prevSinceMs };
+}
+/** A fresh integrator, as seeded at every capture start. */
+function _freshLateralState() {
+    return {
+        pos: 0,
+        vel: 0,
+        // NaN = uninitialised; the first sample seeds gravity from itself
+        // (same convention as useIMUTranslationGate).
+        gravity: NaN,
+        exceeded: false,
+        overBudgetSinceMs: null,
+    };
+}
+/**
+ * Reset the integrator in place for a new capture.  Zeroes position,
+ * velocity, the latch, and the grace timer, and re-arms gravity
+ * seeding.  Pure (mutates the passed object, returns it) — exported so
+ * tests can assert the "resets only at capture start" contract.
+ */
+function _resetLateralState(s) {
+    s.pos = 0;
+    s.vel = 0;
+    s.gravity = NaN;
+    s.exceeded = false;
+    s.overBudgetSinceMs = null;
+    return s;
+}
+/**
+ * Advance the lateral integrator by one accelerometer sample.  Pure
+ * (mutates + returns the passed state) so the integration math is
+ * unit-testable without a sensor or a React render.
+ *
+ * @param s         running integrator state (mutated in place)
+ * @param rawAxis   raw cross-pan accel reading for this sample, in the
+ *                  platform's native unit (G's on iOS, m/s² on
+ *                  Android) — caller has NOT yet applied `scale`
+ * @param scale     unit scale (G_TO_MPS2 on iOS, 1 on Android)
+ * @param dt        sample period, seconds
+ * @param budgetM   lateral budget, METRES
+ * @param graceMs   continuous-over-budget dwell before latching, ms
+ * @param nowMs     monotonic clock for this sample, ms
+ * @returns the same `s` (mutated): `pos` is the new cross-pan position
+ *          in metres; `exceeded` is the latched flag.
+ *
+ * NOTE the first call only seeds gravity and returns with `pos`
+ * unchanged (matches `useIMUTranslationGate`'s first-sample handling)
+ * — the first reading is assumed to be ~stationary at capture start.
+ */
+function _integrateLateralSample(s, rawAxis, scale, dt, budgetM, graceMs, nowMs) {
+    const a = rawAxis * scale; // cross-pan acceleration, m/s²
+    // First sample seeds the gravity estimate from itself.
+    if (Number.isNaN(s.gravity)) {
+        s.gravity = a;
+        return s;
+    }
+    // IIR low-pass to track the gravity component on the cross-pan axis.
+    s.gravity = GRAVITY_IIR_ALPHA * s.gravity + (1 - GRAVITY_IIR_ALPHA) * a;
+    // Linear acceleration = raw - gravity estimate.
+    const lin = a - s.gravity;
+    // Single integration with per-sample velocity damping.
+    s.vel = (s.vel + lin * dt) * (1 - VELOCITY_DAMPING_PER_SAMPLE);
+    s.pos += s.vel * dt;
+    // Grace-windowed latch — delegated to the pure decision helper so
+    // the debounce is unit-testable independently of the integrator
+    // physics.
+    const latch = _evalGraceLatch(Math.abs(s.pos) > budgetM, nowMs, s.overBudgetSinceMs, s.exceeded, graceMs);
+    s.exceeded = latch.exceeded;
+    s.overBudgetSinceMs = latch.overBudgetSinceMs;
+    return s;
+}
+function usePanMotion({ active, axis, goodMaxRadPerSec = DEFAULT_GOOD_RAD_PER_SEC, warnMaxRadPerSec = DEFAULT_WARN_RAD_PER_SEC, lateralBudgetCm = DEFAULT_LATERAL_BUDGET_CM, }) {
+    // Physical orientation (sensor-based — works under portrait-lock),
+    // same source `PanoramaGuidance` uses to pick the pan axis.
+    const deviceOrientation = (0, useDeviceOrientation_1.useDeviceOrientation)();
+    const resolvedAxis = _resolvePanAxis(deviceOrientation, axis);
+    // Qualitative pan speed — state so a bucket *flip* re-renders, but
+    // per-sample updates don't.
+    const [panSpeedBucket, setPanSpeedBucket] = (0, react_1.useState)('good');
+    const lastBucketRef = (0, react_1.useRef)('good');
+    // Lateral integrator state lives in a ref so the 50 Hz accelerometer
+    // callback never forces a re-render.
+    const lateralRef = (0, react_1.useRef)(_freshLateralState());
+    // PRIMARY lateral-drift signal (v0.16): an EMA of the CROSS-pan GYRO rate
+    // (`|gyro.x|`), updated in the gyro handler.  Smoothing rides through the
+    // raw rate's inter-sample noise (which defeated a binary dwell latch).
+    // Reset to 0 at capture start.
+    const crossEmaRef = (0, react_1.useRef)(0);
+    // The throttled, render-visible lateral magnitude (cm) + the latched
+    // exceeded flag.  These DO go through state because consumers render
+    // them, but they update at most ~10 Hz / once respectively.
+    const [lateralCm, setLateralCm] = (0, react_1.useState)(0);
+    const [lateralExceeded, setLateralExceeded] = (0, react_1.useState)(false);
+    // ── Gyroscope → pan-speed bucket + lateral-drift latch ─────────
+    // One gyro subscription drives BOTH item-4 (too fast) and item-6
+    // (lateral drift).  Item 6 keys on the CROSS-pan axis (gyro X): a user
+    // veering perpendicular to the arrow rotates about it (on-device traces
+    // showed |gyro.x| → 1.27 on a cross-turn vs < 0.1 on a clean pan).
+    const lateralEnabled = lateralBudgetCm > 0;
+    (0, react_1.useEffect)(() => {
+        if (!active) {
+            lastBucketRef.current = 'good';
+            setPanSpeedBucket('good');
+            return;
+        }
+        // Capture start: clear the cross-axis EMA.
+        crossEmaRef.current = 0;
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.gyroscope, GYRO_SAMPLE_INTERVAL_MS);
+        // Throttle for the optional dev diagnostic log (raw axes + rate).
+        let lastGyroLogMs = 0;
+        let sub = react_native_sensors_1.gyroscope.subscribe({
+            next: ({ x, y }) => {
+                const now = Date.now();
+                // Item 4 — axis-AGNOSTIC pan rate: the magnitude of rotation in the
+                // x–y (tilt) plane, ignoring roll about Z.  v0.16 — replaces the
+                // single-axis pick (`gyro.x` in landscape / `gyro.y` in portrait),
+                // which read ~0 and never tripped when the device's dominant pan
+                // rotation landed on the OTHER axis for the user's actual hold.
+                const rate = Math.hypot(x, y);
+                const next = _bucketForRate(rate, goodMaxRadPerSec, warnMaxRadPerSec);
+                if (next !== lastBucketRef.current) {
+                    lastBucketRef.current = next;
+                    setPanSpeedBucket(next);
+                }
+                // Item 6 — lateral drift via the CROSS-pan gyro axis (device X).
+                // Smooth |gyro.x| with an EMA so the noisy raw rate's dips don't
+                // reset the trigger; latch once the SMOOTHED rate stays over the
+                // threshold (the EMA's time constant IS the dwell).
+                let crossEma = crossEmaRef.current;
+                if (lateralEnabled) {
+                    crossEma =
+                        crossEma * (1 - LATERAL_CROSS_EMA_ALPHA)
+                            + Math.abs(x) * LATERAL_CROSS_EMA_ALPHA;
+                    crossEmaRef.current = crossEma;
+                    if (crossEma > DEFAULT_LATERAL_TURN_RAD_PER_SEC) {
+                        setLateralExceeded((prev) => (prev ? prev : true));
+                    }
+                }
+                if (__DEV__ && now - lastGyroLogMs >= 400) {
+                    lastGyroLogMs = now;
+                    // eslint-disable-next-line no-console
+                    console.log(`[panMotion] gyro x=${x.toFixed(2)} y=${y.toFixed(2)} `
+                        + `rate=${rate.toFixed(2)} bucket=${next} `
+                        + `crossEma=${crossEma.toFixed(2)} `
+                        + `latThresh=${DEFAULT_LATERAL_TURN_RAD_PER_SEC}`);
+                }
+            },
+            error: (err) => {
+                // eslint-disable-next-line no-console
+                console.warn('[usePanMotion] gyroscope error', err);
+            },
+        });
+        return () => {
+            sub?.unsubscribe();
+            sub = null;
+        };
+        // resolvedAxis intentionally NOT a dep: the rate is now axis-agnostic
+        // (hypot), so an orientation flip must not needlessly re-subscribe the
+        // gyro mid-capture.
+    }, [active, goodMaxRadPerSec, warnMaxRadPerSec, lateralEnabled]);
+    // ── Accelerometer → lateral-drift integrator ───────────────────
+    // NOTE: this effect intentionally does NOT depend on `resolvedAxis`.
+    // The cross-pan device axis is device-Y in BOTH pan modes (it is
+    // always orthogonal to the gate's device-X pan axis — see header),
+    // so re-subscribing on a portrait↔landscape flip would only reset
+    // the accumulator mid-capture for no benefit.  We do depend on
+    // `lateralBudgetCm` because the latch threshold changes with it.
+    (0, react_1.useEffect)(() => {
+        if (!active) {
+            // Reflect a clean slate while idle.
+            setLateralCm(0);
+            setLateralExceeded(false);
+            return;
+        }
+        // Capture start (false → true): zero the persistent accumulator.
+        // This is the ONLY place `pos` resets — NOT per keyframe.
+        _resetLateralState(lateralRef.current);
+        setLateralCm(0);
+        setLateralExceeded(false);
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.accelerometer, ACCEL_SAMPLE_INTERVAL_MS);
+        const scale = react_native_1.Platform.OS === 'ios' ? G_TO_MPS2 : 1;
+        const dt = ACCEL_SAMPLE_INTERVAL_MS / 1000.0;
+        const budgetM = lateralBudgetCm / M_TO_CM;
+        let lastEmitMs = 0;
+        let lastAccelLogMs = 0;
+        // Integrate device-Y — the cross-pan axis (orthogonal to the
+        // gate's device-X pan axis).  We read X too, only to log it for the
+        // on-device axis-verification (does a sideways slide spike X or Y?).
+        const sub = react_native_sensors_1.accelerometer.subscribe(({ x, y }) => {
+            const now = Date.now();
+            const s = _integrateLateralSample(lateralRef.current, y, scale, dt, budgetM, LATERAL_GRACE_MS, now);
+            if (__DEV__ && now - lastAccelLogMs >= 400) {
+                lastAccelLogMs = now;
+                // Raw x/y let us confirm the cross-pan axis on a real device: a
+                // deliberate sideways slide should spike the integrated axis.  If
+                // lateralCm stays ~0 while X spikes, swap the integrated axis y→x.
+                // eslint-disable-next-line no-console
+                console.log(`[panMotion] accel x=${x.toFixed(2)} y=${y.toFixed(2)} `
+                    + `lateralCm=${(s.pos * M_TO_CM).toFixed(1)} `
+                    + `budget=${lateralBudgetCm} exceeded=${s.exceeded}`);
+            }
+            // Latch the exceeded flag once (state write only on the edge).
+            if (s.exceeded) {
+                setLateralExceeded((prev) => (prev ? prev : true));
+            }
+            // Throttle the cosmetic cm readout to ~10 Hz.
+            if (now - lastEmitMs >= LATERAL_EMIT_INTERVAL_MS) {
+                lastEmitMs = now;
+                setLateralCm(s.pos * M_TO_CM);
+            }
+        });
+        return () => sub.unsubscribe();
+    }, [active, lateralBudgetCm]);
+    return { panSpeedBucket, lateralCm, lateralExceeded, resolvedAxis };
+}
+//# sourceMappingURL=usePanMotion.js.map

package/dist/index.d.ts

@@ -20,9 +20,11 @@
  * adds RetaiLens-specific features on top.
  */
 export { Camera, CameraError } from './camera/Camera';
-export type { CameraProps, CameraCaptureResult, CameraErrorCode, CaptureSource, CaptureSourcesMode, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
-export { userFacingStitchError } from './camera/cameraErrorMessages';
-export type { UserFacingStitchError } from './camera/cameraErrorMessages';
+export type { CameraProps, CameraCaptureResult, PanoramaCaptureResult, CameraErrorCode, CaptureSource, CaptureSourcesMode, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
+export type { CaptureWarning, CaptureWarningCode, CaptureWarningCopy, } from './camera/captureWarnings';
+export { DEFAULT_CAPTURE_WARNING_COPY } from './camera/captureWarnings';
+export { userFacingStitchError, RECOVERABLE_STITCH_GUIDANCE, RECOVERABLE_STITCH_CODES, } from './camera/cameraErrorMessages';
+export type { UserFacingStitchError, UserFacingStitchErrorOverrides, } from './camera/cameraErrorMessages';
 export { useARSession, ARTrackingState } from './ar/useARSession';
 export type { UseARSessionReturn, FramePose, } from './ar/useARSession';
 export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
@@ -66,6 +68,25 @@ export { useOrientationDrift } from './camera/useOrientationDrift';
 export type { UseOrientationDriftReturn } from './camera/useOrientationDrift';
 export { OrientationDriftModal } from './camera/OrientationDriftModal';
 export type { OrientationDriftModalProps } from './camera/OrientationDriftModal';
+export type { PanMode } from './camera/panModeGate';
+export { DEFAULT_GUIDANCE_COPY, } from './camera/cameraGuidanceCopy';
+export type { GuidanceCopy } from './camera/cameraGuidanceCopy';
+export { usePanMotion } from './camera/usePanMotion';
+export type { UsePanMotionOptions, UsePanMotionReturn, PanSpeedBucket, PanAxis, } from './camera/usePanMotion';
+export { RotateToLandscapePrompt } from './camera/RotateToLandscapePrompt';
+export type { RotateToLandscapePromptProps } from './camera/RotateToLandscapePrompt';
+export { PanHowToOverlay } from './camera/PanHowToOverlay';
+export type { PanHowToOverlayProps } from './camera/PanHowToOverlay';
+export { CaptureCountdownOverlay } from './camera/CaptureCountdownOverlay';
+export type { CaptureCountdownOverlayProps } from './camera/CaptureCountdownOverlay';
+export { CaptureFrameCounterOverlay } from './camera/CaptureFrameCounterOverlay';
+export type { CaptureFrameCounterOverlayProps } from './camera/CaptureFrameCounterOverlay';
+export { LateralMotionModal } from './camera/LateralMotionModal';
+export type { LateralMotionModalProps } from './camera/LateralMotionModal';
+export { RectCropPreview } from './camera/RectCropPreview';
+export type { RectCropPreviewProps, RectCropResult, ImageRect, } from './camera/RectCropPreview';
+export { cropQuad } from './stitching/cropQuad';
+export type { CropQuadOptions, CropQuadResult } from './stitching/cropQuad';
 export { IncrementalOutcome, incrementalStitcherIsAvailable, subscribeIncrementalState, getIncrementalNativeModule, cleanupOldKeyframes, } from './stitching/incremental';
 export type { IncrementalState, AcceptedKeyframe } from './stitching/incremental';
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';

package/dist/index.js

@@ -22,18 +22,26 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaBandOverlay = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.userFacingStitchError = exports.CameraError = exports.Camera = void 0;
+exports.useFrameProcessorDriver = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.cropQuad = exports.RectCropPreview = exports.LateralMotionModal = exports.CaptureFrameCounterOverlay = exports.CaptureCountdownOverlay = exports.PanHowToOverlay = exports.RotateToLandscapePrompt = exports.usePanMotion = exports.DEFAULT_GUIDANCE_COPY = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaBandOverlay = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.RECOVERABLE_STITCH_CODES = exports.RECOVERABLE_STITCH_GUIDANCE = exports.userFacingStitchError = exports.DEFAULT_CAPTURE_WARNING_COPY = exports.CameraError = exports.Camera = void 0;
+exports.stitchVideo = exports.useStitcherWorklet = void 0;
 // ─────────────────────────────────────────────────────────────────────
 // Layer 1 — the high-level <Camera> component
 // ─────────────────────────────────────────────────────────────────────
 var Camera_1 = require("./camera/Camera");
 Object.defineProperty(exports, "Camera", { enumerable: true, get: function () { return Camera_1.Camera; } });
 Object.defineProperty(exports, "CameraError", { enumerable: true, get: function () { return Camera_1.CameraError; } });
+// Default English warning templates (single source of truth; re-used by
+// `DEFAULT_GUIDANCE_COPY`).  Exposed so a host can diff / extend them.
+var captureWarnings_1 = require("./camera/captureWarnings");
+Object.defineProperty(exports, "DEFAULT_CAPTURE_WARNING_COPY", { enumerable: true, get: function () { return captureWarnings_1.DEFAULT_CAPTURE_WARNING_COPY; } });
 // Recoverable-stitch-failure → friendly Alert copy.  Hosts call this in
 // their onError handler to surface actionable guidance ("pan more slowly",
-// "pivot in place") instead of the raw cv::Stitcher diagnostic.
+// "pivot in place") instead of the raw cv::Stitcher diagnostic.  Pass an
+// `overrides` map (keyed by `RECOVERABLE_STITCH_CODES`) to localise it.
 var cameraErrorMessages_1 = require("./camera/cameraErrorMessages");
 Object.defineProperty(exports, "userFacingStitchError", { enumerable: true, get: function () { return cameraErrorMessages_1.userFacingStitchError; } });
+Object.defineProperty(exports, "RECOVERABLE_STITCH_GUIDANCE", { enumerable: true, get: function () { return cameraErrorMessages_1.RECOVERABLE_STITCH_GUIDANCE; } });
+Object.defineProperty(exports, "RECOVERABLE_STITCH_CODES", { enumerable: true, get: function () { return cameraErrorMessages_1.RECOVERABLE_STITCH_CODES; } });
 // ─────────────────────────────────────────────────────────────────────
 // AR foundation (public since 0.1.0)
 // ─────────────────────────────────────────────────────────────────────
@@ -139,6 +147,29 @@ var useOrientationDrift_1 = require("./camera/useOrientationDrift");
 Object.defineProperty(exports, "useOrientationDrift", { enumerable: true, get: function () { return useOrientationDrift_1.useOrientationDrift; } });
 var OrientationDriftModal_1 = require("./camera/OrientationDriftModal");
 Object.defineProperty(exports, "OrientationDriftModal", { enumerable: true, get: function () { return OrientationDriftModal_1.OrientationDriftModal; } });
+var cameraGuidanceCopy_1 = require("./camera/cameraGuidanceCopy");
+Object.defineProperty(exports, "DEFAULT_GUIDANCE_COPY", { enumerable: true, get: function () { return cameraGuidanceCopy_1.DEFAULT_GUIDANCE_COPY; } });
+// Shared motion hook — one gyro + one accelerometer subscription feeding
+// the pan-speed bucket (item 4) and the lateral-drift latch (item 6).
+var usePanMotion_1 = require("./camera/usePanMotion");
+Object.defineProperty(exports, "usePanMotion", { enumerable: true, get: function () { return usePanMotion_1.usePanMotion; } });
+// Presentational guidance surfaces (each renders null when not visible).
+var RotateToLandscapePrompt_1 = require("./camera/RotateToLandscapePrompt");
+Object.defineProperty(exports, "RotateToLandscapePrompt", { enumerable: true, get: function () { return RotateToLandscapePrompt_1.RotateToLandscapePrompt; } });
+var PanHowToOverlay_1 = require("./camera/PanHowToOverlay");
+Object.defineProperty(exports, "PanHowToOverlay", { enumerable: true, get: function () { return PanHowToOverlay_1.PanHowToOverlay; } });
+var CaptureCountdownOverlay_1 = require("./camera/CaptureCountdownOverlay");
+Object.defineProperty(exports, "CaptureCountdownOverlay", { enumerable: true, get: function () { return CaptureCountdownOverlay_1.CaptureCountdownOverlay; } });
+var CaptureFrameCounterOverlay_1 = require("./camera/CaptureFrameCounterOverlay");
+Object.defineProperty(exports, "CaptureFrameCounterOverlay", { enumerable: true, get: function () { return CaptureFrameCounterOverlay_1.CaptureFrameCounterOverlay; } });
+var LateralMotionModal_1 = require("./camera/LateralMotionModal");
+Object.defineProperty(exports, "LateralMotionModal", { enumerable: true, get: function () { return LateralMotionModal_1.LateralMotionModal; } });
+var RectCropPreview_1 = require("./camera/RectCropPreview");
+Object.defineProperty(exports, "RectCropPreview", { enumerable: true, get: function () { return RectCropPreview_1.RectCropPreview; } });
+// Native perspective-rectify crop used by RectCropPreview's confirm
+// path; hosts driving their own crop UI call it directly.
+var cropQuad_1 = require("./stitching/cropQuad");
+Object.defineProperty(exports, "cropQuad", { enumerable: true, get: function () { return cropQuad_1.cropQuad; } });
 // ── Incremental stitching engine ──────────────────────────────────────
 // JS bindings around the native `IncrementalStitcher` module.  Use
 // these when you need finer control than <Camera>'s built-in

package/dist/stitching/computeInscribedRect.d.ts

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

package/dist/stitching/computeInscribedRect.js

@@ -0,0 +1,55 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * computeInscribedRect — resolve the largest axis-aligned rectangle that
+ * fits entirely inside the non-black (coverage) region of a stitched
+ * panorama, via native `BatchStitcher.computeInscribedRect`.
+ *
+ * Used to SEED the post-capture crop editor (`RectCropPreview`): instead of
+ * a blind 8 %-inset rectangle, the editor opens on the max-inscribed rect —
+ * the tightest clean rectangle with no black corners — which the user then
+ * fine-tunes.  Best-effort: callers fall back to the default inset seed if
+ * the native module is absent or the call rejects.
+ *
+ * Same native module + defensive-availability posture as
+ * `src/stitching/cropQuad.ts` and `src/quality/normaliseOrientation.ts`.
+ * The native side (Android `BatchStitcher.computeInscribedRect`, iOS
+ * `OpenCVStitcher.computeInscribedRect`) is the exact `maxInscribedRectFromMask`
+ * port used by the opt-in auto-crop, so the seed matches what that crop would
+ * pick — only here the user can then drag outward to keep more content.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeInscribedRect = computeInscribedRect;
+const react_native_1 = require("react-native");
+/**
+ * Resolve the native `computeInscribedRect` function off
+ * `NativeModules.BatchStitcher`, or `null` when the module / method isn't
+ * registered (e.g. an older native build).
+ */
+function resolveComputeInscribedRect() {
+    const native = react_native_1.NativeModules['BatchStitcher'];
+    if (native
+        && typeof native === 'object'
+        && typeof native
+            .computeInscribedRect === 'function') {
+        return native.computeInscribedRect;
+    }
+    return null;
+}
+/**
+ * Compute the max-inscribed rectangle of `imagePath`'s coverage mask.
+ *
+ * @param imagePath  file:// URI or bare path of the stitched image (the
+ *                   native side strips the scheme).
+ * @returns the inscribed rect, or `null` when the native module isn't
+ *   registered (older native build) — callers then fall back to the default
+ *   seed.  REJECTS only if the native call itself errors (decode / read
+ *   failure); callers should catch and treat the rejection as "no seed".
+ */
+async function computeInscribedRect(imagePath) {
+    const fn = resolveComputeInscribedRect();
+    if (!fn)
+        return null;
+    return fn({ imagePath });
+}
+//# sourceMappingURL=computeInscribedRect.js.map