react-native-image-stitcher 0.15.2 → 0.16.1

package/dist/camera/RectCropPreview.js

@@ -0,0 +1,370 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * RectCropPreview — item-7 of the first-time-user guidance flow: the
+ * post-capture crop editor.
+ *
+ * Shows the full stitched result image (contain-fit, letterboxed) with a
+ * 4-corner quad overlay.  Each corner is INDEPENDENTLY draggable in
+ * on-screen coords via RN-core `PanResponder` (deliberately NO
+ * react-native-gesture-handler dependency — this library ships zero extra
+ * native deps for guidance).  Corner positions are mapped to image-pixel
+ * space through the pure `cropGeometry` letterbox transform.
+ *
+ * ## What it surfaces (and what it does NOT do)
+ *
+ * This component is presentation + gesture only.  On confirm it computes
+ * the 4 image-pixel corners and hands them to `onConfirm` — it does NOT
+ * call any native crop.  The PARENT decides between the cheap axis-aligned
+ * `cropToRect` (when the quad is ~rectangular) and the perspective
+ * `cropToQuad`, using the `perspective` flag in the result:
+ *
+ *   onConfirm({ quad, perspective: perspectiveCorrect && !isAxisAligned })
+ *
+ * Promoted + extended from `example/InscribedRectDebug.tsx`, which already
+ * did the image-px ↔ on-screen contain-fit mapping, a rect overlay, and
+ * the in-place native crop.  This version replaces the single computed
+ * inscribed rect with a user-draggable free quad and the perspective
+ * decision; the letterbox math now lives in the shared `cropGeometry`
+ * module.  Styling is carried over from InscribedRectDebug.
+ *
+ * ## Seeding
+ *
+ * The initial quad comes from `initialRect` (image-pixel coords) when the
+ * host passes one — `<Camera>` passes the panorama's MAX-INSCRIBED rectangle
+ * (the tightest clean rectangle with no black corners; item 2) so the editor
+ * opens on a sensible crop the user drags to taste.  With no `initialRect`
+ * (native inscribed-rect unavailable) it falls back to an 8 %-inset
+ * rectangle.  "Reset" returns to whichever seed was used.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RectCropPreview = RectCropPreview;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const cameraGuidanceCopy_1 = require("./cameraGuidanceCopy");
+const cropGeometry_1 = require("./cropGeometry");
+const guidanceTokens_1 = require("./guidanceTokens");
+const CaptureMemoryPill_1 = require("./CaptureMemoryPill");
+/** Default inset (fraction of each dimension) for the seed quad. */
+const DEFAULT_INSET_FRACTION = 0.08;
+/** On-screen radius of each draggable corner handle. */
+const HANDLE_RADIUS = 16;
+/** Enlarged hit-slop radius so the small handle is easy to grab. */
+const HANDLE_HIT_RADIUS = 28;
+/**
+ * Build the seed quad in IMAGE-PIXEL coords: the host's `initialRect` if
+ * given, else an inset rectangle of the full image.  Always returned in
+ * [TL, TR, BR, BL] order.
+ */
+function seedImageQuad(imageWidth, imageHeight, initialRect) {
+    if (initialRect) {
+        const { x, y, width, height } = initialRect;
+        return [
+            { x, y },
+            { x: x + width, y },
+            { x: x + width, y: y + height },
+            { x, y: y + height },
+        ];
+    }
+    const ix = imageWidth * DEFAULT_INSET_FRACTION;
+    const iy = imageHeight * DEFAULT_INSET_FRACTION;
+    return [
+        { x: ix, y: iy },
+        { x: imageWidth - ix, y: iy },
+        { x: imageWidth - ix, y: imageHeight - iy },
+        { x: ix, y: imageHeight - iy },
+    ];
+}
+function RectCropPreview(props) {
+    const { imageUri, imageWidth, imageHeight, visible, onConfirm, onUseOriginal, onRetake, warnings, showCropControls = true, initialRect, copy, topInset = 0, bottomInset = 0, debugInfo, showMemoryPill, } = props;
+    const resolvedCopy = (0, react_1.useMemo)(() => (0, cameraGuidanceCopy_1.mergeGuidanceCopy)(copy), [copy]);
+    // The 4 corners live in IMAGE-PIXEL space (the source of truth) so they
+    // survive layout-box changes (rotation, keyboard) without drift.  We map
+    // to screen for rendering and back on every drag via cropGeometry.
+    const [imageQuad, setImageQuad] = (0, react_1.useState)(() => seedImageQuad(imageWidth, imageHeight, initialRect));
+    const [box, setBox] = (0, react_1.useState)(null);
+    // Drag bookkeeping kept in refs so the per-move handler doesn't churn
+    // state identity / re-create PanResponders mid-gesture.
+    const boxRef = (0, react_1.useRef)(null);
+    const dragCornerRef = (0, react_1.useRef)(null);
+    // Screen-space corner positions at gesture start, so dx/dy from the
+    // gesture state apply to a stable origin (PanResponder reports
+    // cumulative deltas from touch-down, not per-frame).
+    const dragStartScreenRef = (0, react_1.useRef)(null);
+    const onLayout = (0, react_1.useCallback)((e) => {
+        const { width, height } = e.nativeEvent.layout;
+        const next = { width, height };
+        boxRef.current = next;
+        setBox(next);
+    }, []);
+    const handleConfirm = (0, react_1.useCallback)(() => {
+        const ordered = (0, cropGeometry_1.orderQuadCorners)(imageQuad);
+        // Guard: if the user collapsed the quad to something un-warpable, emit
+        // the original un-cropped panorama rather than hand native a degenerate
+        // quad.
+        if (!(0, cropGeometry_1.isQuadValid)(ordered)) {
+            onUseOriginal();
+            return;
+        }
+        const axisAligned = (0, cropGeometry_1.isAxisAlignedRect)(ordered);
+        // A skewed quad is perspective-rectified; a ~rectangular drag is a plain
+        // axis-aligned crop.  (The former `perspectiveCorrect` opt-out was removed
+        // in v0.16 — the SDK always honours a skewed quad with a warp.)
+        onConfirm({
+            quad: ordered,
+            perspective: !axisAligned,
+        });
+    }, [imageQuad, onConfirm, onUseOriginal]);
+    // One PanResponder per corner.  Built once (the corner index is the
+    // closure key); the move handler reads live box/quad via refs + setState
+    // updater so the responders never need to be rebuilt on drag.
+    const responders = (0, react_1.useMemo)(() => [0, 1, 2, 3].map((corner) => react_native_1.PanResponder.create({
+        onStartShouldSetPanResponder: () => true,
+        onMoveShouldSetPanResponder: () => true,
+        onPanResponderGrant: () => {
+            dragCornerRef.current = corner;
+            const layout = boxRef.current;
+            if (!layout)
+                return;
+            // Capture this corner's screen position at touch-down.
+            setImageQuad((q) => {
+                dragStartScreenRef.current = (0, cropGeometry_1.imageToScreen)(q[corner], layout, imageWidth, imageHeight);
+                return q;
+            });
+        },
+        onPanResponderMove: (_e, gesture) => {
+            const layout = boxRef.current;
+            const start = dragStartScreenRef.current;
+            if (!layout || !start)
+                return;
+            const screenPt = {
+                x: start.x + gesture.dx,
+                y: start.y + gesture.dy,
+            };
+            const imgPt = (0, cropGeometry_1.screenToImage)(screenPt, layout, imageWidth, imageHeight);
+            setImageQuad((q) => {
+                const next = [...q];
+                next[corner] = imgPt;
+                return next;
+            });
+        },
+        onPanResponderRelease: () => {
+            dragCornerRef.current = null;
+            dragStartScreenRef.current = null;
+        },
+        onPanResponderTerminate: () => {
+            dragCornerRef.current = null;
+            dragStartScreenRef.current = null;
+        },
+    })), [imageWidth, imageHeight]);
+    // ── Derived screen geometry (recomputed each render from the box) ──
+    // The display box (letterboxed image rect) and the 4 corners projected
+    // into screen space for the overlay + handles.
+    let imageBox = null;
+    let screenCorners = null;
+    if (box) {
+        const fit = (0, cropGeometry_1.containFit)(box, imageWidth, imageHeight);
+        if (fit) {
+            imageBox = {
+                left: fit.offX,
+                top: fit.offY,
+                width: imageWidth * fit.scale,
+                height: imageHeight * fit.scale,
+            };
+            // Quad corners only apply in crop mode.
+            screenCorners = showCropControls
+                ? imageQuad.map((p) => (0, cropGeometry_1.imageToScreen)(p, box, imageWidth, imageHeight))
+                : null;
+        }
+    }
+    // Outline path (a <View> per edge — RN core has no <Polygon>; this
+    // mirrors InscribedRectDebug's single-rect border treatment, generalised
+    // to 4 free edges).
+    const edges = screenCorners
+        ? screenCorners.map((from, i) => {
+            const to = screenCorners[(i + 1) % screenCorners.length];
+            return edgeStyle(from, to);
+        })
+        : [];
+    return (react_1.default.createElement(react_native_1.Modal, { visible: visible, animationType: "fade", onRequestClose: () => onUseOriginal(), accessibilityLabel: showCropControls
+            ? 'Crop the captured panorama'
+            : 'Review the captured panorama', 
+        // Mirror OrientationDriftModal: declare all 4 orientations so iOS
+        // doesn't force-rotate the window when this opens mid-rotation.
+        supportedOrientations: [
+            'portrait',
+            'portrait-upside-down',
+            'landscape-left',
+            'landscape-right',
+        ] },
+        react_1.default.createElement(react_native_1.View, { style: [styles.root, { paddingTop: topInset }] },
+            showMemoryPill ? (react_1.default.createElement(CaptureMemoryPill_1.CaptureMemoryPill, { style: {
+                    position: 'absolute',
+                    top: topInset + 8,
+                    left: 12,
+                    zIndex: 21,
+                } })) : null,
+            debugInfo ? (react_1.default.createElement(react_native_1.View, { style: [styles.debugPill, { top: topInset + 8 }], pointerEvents: "none", accessibilityRole: "text" },
+                react_1.default.createElement(react_native_1.Text, { style: styles.debugPillText }, debugInfo))) : null,
+            warnings && warnings.length > 0 && (react_1.default.createElement(react_native_1.View, { style: styles.warningBanner, accessibilityRole: "alert" }, warnings.map((w, i) => (react_1.default.createElement(react_native_1.Text, { key: `warn-${i}`, style: styles.warningText }, w))))),
+            react_1.default.createElement(react_native_1.View, { style: styles.canvas, onLayout: onLayout },
+                imageBox && (react_1.default.createElement(react_native_1.Image, { source: { uri: imageUri }, style: [styles.image, imageBox], resizeMode: "stretch" })),
+                showCropControls && (react_1.default.createElement(react_1.default.Fragment, null,
+                    edges.map((e, i) => (react_1.default.createElement(react_native_1.View, { key: `edge-${i}`, style: [styles.edge, e], pointerEvents: "none" }))),
+                    screenCorners
+                        && screenCorners.map((c, i) => (react_1.default.createElement(react_native_1.View, { key: `handle-${i}`, ...responders[i].panHandlers, hitSlop: {
+                                top: HANDLE_HIT_RADIUS,
+                                bottom: HANDLE_HIT_RADIUS,
+                                left: HANDLE_HIT_RADIUS,
+                                right: HANDLE_HIT_RADIUS,
+                            }, accessibilityRole: "adjustable", accessibilityLabel: `Crop corner ${i + 1}`, style: [
+                                styles.handle,
+                                {
+                                    left: c.x - HANDLE_RADIUS,
+                                    top: c.y - HANDLE_RADIUS,
+                                },
+                            ] },
+                            react_1.default.createElement(react_native_1.View, { style: styles.handleDot, pointerEvents: "none" }))))))),
+            react_1.default.createElement(react_native_1.View, { style: [styles.bar, { paddingBottom: 16 + bottomInset }] },
+                react_1.default.createElement(react_native_1.View, { style: styles.buttons },
+                    react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [styles.btn, pressed && styles.btnPressed], onPress: onRetake, accessibilityRole: "button", accessibilityLabel: resolvedCopy.cropRetake },
+                        react_1.default.createElement(react_native_1.Text, { style: styles.btnText }, resolvedCopy.cropRetake)),
+                    showCropControls && (react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [styles.btn, pressed && styles.btnPressed], onPress: () => onUseOriginal(), accessibilityRole: "button", accessibilityLabel: resolvedCopy.cropUseOriginal },
+                        react_1.default.createElement(react_native_1.Text, { style: styles.btnText }, resolvedCopy.cropUseOriginal))),
+                    react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [
+                            styles.btn,
+                            styles.primary,
+                            pressed && styles.btnPressed,
+                        ], onPress: showCropControls ? handleConfirm : () => onUseOriginal(), accessibilityRole: "button", accessibilityLabel: showCropControls
+                            ? resolvedCopy.cropConfirm
+                            : resolvedCopy.previewConfirm },
+                        react_1.default.createElement(react_native_1.Text, { style: styles.btnText }, showCropControls
+                            ? resolvedCopy.cropConfirm
+                            : resolvedCopy.previewConfirm)))))));
+}
+/**
+ * Absolute-positioned style for a 1-px-thick edge line between two
+ * screen points (origin → length + rotation).  RN core has no line
+ * primitive, so we render a thin rotated <View> per quad edge.
+ */
+function edgeStyle(from, to) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const length = Math.hypot(dx, dy);
+    const angle = Math.atan2(dy, dx);
+    return {
+        left: from.x,
+        top: from.y,
+        width: length,
+        // Rotate about the line's start point (RN rotates about centre, so
+        // translate the midpoint back onto the start first).
+        transform: [
+            { translateX: -length / 2 },
+            { rotate: `${angle}rad` },
+            { translateX: length / 2 },
+        ],
+    };
+}
+const styles = react_native_1.StyleSheet.create({
+    root: { flex: 1, backgroundColor: '#000' },
+    debugPill: {
+        position: 'absolute',
+        right: 8,
+        zIndex: 20,
+        maxWidth: '60%',
+        paddingVertical: 6,
+        paddingHorizontal: 8,
+        borderRadius: 6,
+        backgroundColor: 'rgba(0,0,0,0.66)',
+        borderWidth: react_native_1.StyleSheet.hairlineWidth,
+        borderColor: 'rgba(120,220,160,0.5)',
+    },
+    debugPillText: {
+        color: '#7fe3a8',
+        fontSize: 10,
+        lineHeight: 14,
+        fontFamily: react_native_1.Platform.select({ ios: 'Menlo', android: 'monospace' }),
+    },
+    warningBanner: {
+        paddingVertical: 10,
+        paddingHorizontal: 16,
+        backgroundColor: 'rgba(255,196,98,0.16)',
+        borderBottomWidth: react_native_1.StyleSheet.hairlineWidth,
+        borderBottomColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+        gap: 4,
+    },
+    warningText: {
+        color: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+        fontSize: 13,
+        fontWeight: '600',
+    },
+    canvas: { flex: 1 },
+    image: { position: 'absolute' },
+    edge: {
+        position: 'absolute',
+        height: 2,
+        backgroundColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+    },
+    handle: {
+        position: 'absolute',
+        width: HANDLE_RADIUS * 2,
+        height: HANDLE_RADIUS * 2,
+        borderRadius: HANDLE_RADIUS,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: 'rgba(0,0,0,0.35)',
+        borderWidth: 2,
+        borderColor: guidanceTokens_1.GUIDANCE_TOKENS.white,
+    },
+    handleDot: {
+        width: 8,
+        height: 8,
+        borderRadius: 4,
+        backgroundColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+    },
+    bar: { padding: 16, backgroundColor: '#111', gap: 12 },
+    buttons: { flexDirection: 'row', justifyContent: 'center', gap: 12 },
+    btn: {
+        paddingVertical: 12,
+        paddingHorizontal: 20,
+        borderRadius: 10,
+        backgroundColor: '#333',
+    },
+    primary: { backgroundColor: '#0A84FF' },
+    btnPressed: { opacity: 0.6 },
+    btnText: { color: '#fff', fontSize: 15, fontWeight: '600' },
+});
+//# sourceMappingURL=RectCropPreview.js.map

package/dist/camera/RotateToLandscapePrompt.d.ts

@@ -0,0 +1,87 @@
+/**
+ * RotateToLandscapePrompt — full-screen, non-interactive overlay shown
+ * while a Mode-A (landscape, top→bottom pan) capture is waiting for the
+ * user to physically rotate the device to landscape.
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │                  (faint scrim over preview)               │
+ *   │                                                           │
+ *   │                    ┌───────────────┐                      │
+ *   │                    │   ⟳  phone    │  ← code-drawn        │
+ *   │                    │   line-art    │     (240px square)   │
+ *   │                    └───────────────┘                      │
+ *   │                                                           │
+ *   │             ●  Rotate to landscape   ← caption pill       │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * Item 2 of the first-time-user guidance set.  It is the first thing a
+ * user sees after starting a landscape-only capture in portrait — the
+ * GIF demonstrates the rotation gesture and the pill names the goal.
+ *
+ * ## Pure-presentational
+ *
+ * The component owns no orientation/eligibility logic: the host
+ * (`<Camera>`) decides *when* a Mode-A capture is blocked on rotation
+ * and drives `visible`.  When `visible` is false we render `null` so
+ * the host can mount us unconditionally without layout churn — mirrors
+ * `CaptureStatusOverlay`'s `idle` → `null` contract.
+ *
+ * ## Why the WHOLE prompt counter-rotates
+ *
+ * The host app is typically portrait-locked, so when the user tilts to
+ * landscape the OS does NOT rotate the framebuffer and JS-"up" stays at
+ * the device's side edge.  We counter-rotate the entire prompt (graphic
+ * + caption) via `useContentRotation()` — the same hook the bottom
+ * controls use — so it reads upright relative to actual gravity.
+ *
+ * This matters for BOTH children, not just the text:
+ *   - the **caption** is text and must read left-to-right;
+ *   - the **graphic is now directional** — its camera dot starts on one
+ *     edge and rotates to another to demonstrate the gesture, so an
+ *     un-rotated graphic in a landscape hold reads 90° off (the dot
+ *     appears to start "down" and travel "left" instead of "left" →
+ *     "top").  It is therefore counter-rotated with the caption.
+ *   - the column **layout** (caption below the graphic) also only reads
+ *     as a physical column once the wrapper is upright — otherwise
+ *     "below" lands at the physical side edge.
+ *
+ * (An earlier version rotated only the caption, back when the graphic
+ * was a symmetric spinner with no start/end direction.)  In a portrait
+ * hold the hook returns 0° so this is a no-op; once the device reaches
+ * the target orientation the host flips `visible` to false anyway, but
+ * the counter-rotation keeps everything legible during the in-between
+ * tilt.
+ *
+ * ## Accessibility
+ *
+ * `accessibilityRole='alert'` + `accessibilityLiveRegion='polite'` so
+ * VoiceOver / TalkBack announce the rotation instruction when the
+ * prompt appears (and re-announce if the copy changes), matching the
+ * pattern in `PanoramaGuidance`.
+ */
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface RotateToLandscapePromptProps {
+    /**
+     * Show / hide.  Driven by the host while a Mode-A capture is blocked
+     * on the user rotating to landscape.  `false` renders nothing.
+     */
+    visible: boolean;
+    /**
+     * Caption copy.  Defaults to `DEFAULT_GUIDANCE_COPY.rotateToLandscape`
+     * ("Rotate to landscape").  Hosts localise via the `guidanceCopy`
+     * `<Camera>` prop and pass the resolved string here.  When `target` is
+     * `'portrait'`, pass the rotate-to-portrait copy.
+     */
+    copy?: string;
+    /**
+     * Orientation to rotate TO: `'landscape'` (default, panMode `'vertical'`)
+     * or `'portrait'` (panMode `'horizontal'`).  Drives the rotating-phone
+     * graphic's direction.
+     */
+    target?: 'landscape' | 'portrait';
+    /** Outer style passthrough (applied to the absolute-fill root). */
+    style?: StyleProp<ViewStyle>;
+}
+export declare function RotateToLandscapePrompt({ visible, copy, target, style, }: RotateToLandscapePromptProps): React.JSX.Element | null;
+//# sourceMappingURL=RotateToLandscapePrompt.d.ts.map

package/dist/camera/RotateToLandscapePrompt.js

@@ -0,0 +1,138 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * RotateToLandscapePrompt — full-screen, non-interactive overlay shown
+ * while a Mode-A (landscape, top→bottom pan) capture is waiting for the
+ * user to physically rotate the device to landscape.
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │                  (faint scrim over preview)               │
+ *   │                                                           │
+ *   │                    ┌───────────────┐                      │
+ *   │                    │   ⟳  phone    │  ← code-drawn        │
+ *   │                    │   line-art    │     (240px square)   │
+ *   │                    └───────────────┘                      │
+ *   │                                                           │
+ *   │             ●  Rotate to landscape   ← caption pill       │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * Item 2 of the first-time-user guidance set.  It is the first thing a
+ * user sees after starting a landscape-only capture in portrait — the
+ * GIF demonstrates the rotation gesture and the pill names the goal.
+ *
+ * ## Pure-presentational
+ *
+ * The component owns no orientation/eligibility logic: the host
+ * (`<Camera>`) decides *when* a Mode-A capture is blocked on rotation
+ * and drives `visible`.  When `visible` is false we render `null` so
+ * the host can mount us unconditionally without layout churn — mirrors
+ * `CaptureStatusOverlay`'s `idle` → `null` contract.
+ *
+ * ## Why the WHOLE prompt counter-rotates
+ *
+ * The host app is typically portrait-locked, so when the user tilts to
+ * landscape the OS does NOT rotate the framebuffer and JS-"up" stays at
+ * the device's side edge.  We counter-rotate the entire prompt (graphic
+ * + caption) via `useContentRotation()` — the same hook the bottom
+ * controls use — so it reads upright relative to actual gravity.
+ *
+ * This matters for BOTH children, not just the text:
+ *   - the **caption** is text and must read left-to-right;
+ *   - the **graphic is now directional** — its camera dot starts on one
+ *     edge and rotates to another to demonstrate the gesture, so an
+ *     un-rotated graphic in a landscape hold reads 90° off (the dot
+ *     appears to start "down" and travel "left" instead of "left" →
+ *     "top").  It is therefore counter-rotated with the caption.
+ *   - the column **layout** (caption below the graphic) also only reads
+ *     as a physical column once the wrapper is upright — otherwise
+ *     "below" lands at the physical side edge.
+ *
+ * (An earlier version rotated only the caption, back when the graphic
+ * was a symmetric spinner with no start/end direction.)  In a portrait
+ * hold the hook returns 0° so this is a no-op; once the device reaches
+ * the target orientation the host flips `visible` to false anyway, but
+ * the counter-rotation keeps everything legible during the in-between
+ * tilt.
+ *
+ * ## Accessibility
+ *
+ * `accessibilityRole='alert'` + `accessibilityLiveRegion='polite'` so
+ * VoiceOver / TalkBack announce the rotation instruction when the
+ * prompt appears (and re-announce if the copy changes), matching the
+ * pattern in `PanoramaGuidance`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RotateToLandscapePrompt = RotateToLandscapePrompt;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+const cameraGuidanceCopy_1 = require("./cameraGuidanceCopy");
+const guidanceGraphics_1 = require("./guidanceGraphics");
+const guidanceTokens_1 = require("./guidanceTokens");
+const useContentRotation_1 = require("./useContentRotation");
+function RotateToLandscapePrompt({ visible, copy = cameraGuidanceCopy_1.DEFAULT_GUIDANCE_COPY.rotateToLandscape, target = 'landscape', style, }) {
+    // Counter-rotate the WHOLE prompt so it reads upright relative to
+    // gravity while the device is mid-tilt (locked-portrait hosts) — see
+    // the file header.  Called before the early return so the hook order
+    // stays stable across visible toggles.
+    const contentRotation = (0, useContentRotation_1.useContentRotation)();
+    if (!visible)
+        return null;
+    return (react_1.default.createElement(react_native_1.View
+    // pointerEvents=none — the prompt is read-only and must never
+    // steal taps from the camera / shutter beneath it.
+    , { 
+        // pointerEvents=none — the prompt is read-only and must never
+        // steal taps from the camera / shutter beneath it.
+        pointerEvents: "none", style: [react_native_1.StyleSheet.absoluteFill, styles.root, style], accessibilityRole: "alert", accessibilityLiveRegion: "polite" },
+        react_1.default.createElement(react_native_1.View, { style: [styles.content, contentRotation] },
+            react_1.default.createElement(guidanceGraphics_1.RotatePhoneGraphic, { playing: visible, target: target }),
+            react_1.default.createElement(react_native_1.View, { style: styles.pill },
+                react_1.default.createElement(react_native_1.View, { style: styles.dot }),
+                react_1.default.createElement(react_native_1.Text, { style: styles.caption, numberOfLines: 1 }, copy)))));
+}
+const styles = react_native_1.StyleSheet.create({
+    root: {
+        // Faint scrim over the live preview so the white line-art graphic and
+        // caption read against bright scenes, while the preview stays
+        // visible underneath (the user is framing a rotation, not a shot).
+        backgroundColor: guidanceTokens_1.GUIDANCE_TOKENS.scrim,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    // Counter-rotated column holding the graphic + caption.  Rotating this
+    // wrapper (not the children individually) keeps the "caption below the
+    // graphic" relationship intact while orienting the pair to gravity.
+    content: {
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    pill: {
+        // Caption pill directly below the rotating-phone graphic (both are
+        // centred in the column by the root's center alignment).
+        marginTop: 16,
+        flexDirection: 'row',
+        alignItems: 'center',
+        paddingVertical: guidanceTokens_1.GUIDANCE_PILL.paddingVertical,
+        paddingHorizontal: guidanceTokens_1.GUIDANCE_PILL.paddingHorizontal,
+        borderRadius: guidanceTokens_1.GUIDANCE_PILL.borderRadius,
+        backgroundColor: guidanceTokens_1.GUIDANCE_TOKENS.scrim,
+        borderWidth: react_native_1.StyleSheet.hairlineWidth,
+        borderColor: guidanceTokens_1.GUIDANCE_TOKENS.hairline,
+    },
+    dot: {
+        width: guidanceTokens_1.GUIDANCE_PILL.dotSize,
+        height: guidanceTokens_1.GUIDANCE_PILL.dotSize,
+        borderRadius: guidanceTokens_1.GUIDANCE_PILL.dotSize / 2,
+        backgroundColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+        marginRight: guidanceTokens_1.GUIDANCE_PILL.dotGap,
+    },
+    caption: {
+        color: guidanceTokens_1.GUIDANCE_TOKENS.white,
+        fontSize: guidanceTokens_1.GUIDANCE_PILL.fontSize,
+        fontWeight: guidanceTokens_1.GUIDANCE_PILL.fontWeight,
+    },
+});
+//# sourceMappingURL=RotateToLandscapePrompt.js.map

package/dist/camera/buildPanoramaInitialSettings.d.ts

@@ -27,7 +27,7 @@
  * settings-translation surface — every consumer of the helper sees
  * exactly the prop fields that drive the settings tree.
  */
-import { type PanoramaSettings } from './PanoramaSettings';
+import { type BatchStitcherSettings, type FlowGateSettings, type FrameSelectionSettings, type PanoramaSettings } from './PanoramaSettings';
 /**
  * Subset of <Camera>'s props that map onto fields of the initial
  * `PanoramaSettings` snapshot.  Anything outside this interface
@@ -52,7 +52,7 @@ export interface PanoramaPropOverrides {
     defaultKeyframeOverlapThreshold?: number;
     /**
      * Initial value for `frameSelection.maxKeyframeIntervalMs` — the
-     * time-budget force-accept (ms).  `0` disables it.  Default 2000.
+     * time-budget force-accept (ms).  `0` disables it.  Default 1500.
      */
     defaultMaxKeyframeIntervalMs?: number;
     /**
@@ -61,6 +61,23 @@ export interface PanoramaPropOverrides {
      * Omitted ⇒ the stitcher default (false = bounding-rect crop).
      */
     maxInscribedRectCrop?: boolean;
+    /**
+     * v0.16 — pass the stitcher config as a JSON OBJECT (canonical field names:
+     * `warperType` / `blenderType` / `seamFinderType` / `stitchMode` /
+     * `enableMaxInscribedRectCrop`).  Any field set here OVERRIDES the matching
+     * flat `default*` prop; unset fields fall back to the flat prop, then the SDK
+     * default.  Partial — set only what you want.
+     */
+    stitcher?: Partial<BatchStitcherSettings>;
+    /**
+     * v0.16 — pass the frame-gate config as a JSON OBJECT (canonical field names:
+     * `mode` / `maxKeyframes` / `overlapThreshold` / `maxKeyframeIntervalMs` /
+     * `flow`).  Overrides the matching flat `default*` props; `flow` is
+     * DEEP-merged so you can set a single flow knob without restating the rest.
+     */
+    frameSelection?: Partial<Omit<FrameSelectionSettings, 'flow'>> & {
+        flow?: Partial<FlowGateSettings>;
+    };
 }
 /**
  * Whether this device is low-memory enough to benefit from the

package/dist/camera/buildPanoramaInitialSettings.js

@@ -78,6 +78,8 @@ function buildPanoramaInitialSettings(overrides, isLowMemDevice) {
             seamFinderType: overrides.defaultSeamFinder ?? stitcherDefaults.seamFinderType,
             enableMaxInscribedRectCrop: overrides.maxInscribedRectCrop
                 ?? stitcherDefaults.enableMaxInscribedRectCrop,
+            // The JSON-object prop wins over the flat default* props above.
+            ...(overrides.stitcher ?? {}),
         },
         frameSelection: {
             ...base.frameSelection,
@@ -86,6 +88,11 @@ function buildPanoramaInitialSettings(overrides, isLowMemDevice) {
                 ?? base.frameSelection.overlapThreshold,
             maxKeyframeIntervalMs: overrides.defaultMaxKeyframeIntervalMs
                 ?? base.frameSelection.maxKeyframeIntervalMs,
+            // The JSON-object prop wins over the flat default* props above for the
+            // scalar fields (mode / maxKeyframes / overlapThreshold / intervalMs).
+            // Its `flow` (if any) is dropped here and DEEP-merged in the explicit
+            // `flow:` key below, so a partial flow object doesn't wipe the rest.
+            ...(overrides.frameSelection ?? {}),
             flow: {
                 ...flowDefaults,
                 noveltyPercentile: overrides.defaultFlowNoveltyPercentile
@@ -94,6 +101,8 @@ function buildPanoramaInitialSettings(overrides, isLowMemDevice) {
                     ?? flowDefaults.evalEveryNFrames,
                 maxTranslationCm: overrides.defaultFlowMaxTranslationCm
                     ?? flowDefaults.maxTranslationCm,
+                // The object prop's flow wins over the flat default*Flow* props.
+                ...(overrides.frameSelection?.flow ?? {}),
             },
         },
     };