react-native-image-stitcher 0.15.2 → 0.16.1

package/dist/camera/guidanceGraphics.js

@@ -0,0 +1,280 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * guidanceGraphics — code-drawn replacements for the two authored guidance
+ * GIFs (rotate-to-landscape, pan-capture).  Built from pure React-Native
+ * core `View` + `Animated` primitives — NO `react-native-svg`, NO bundled
+ * image assets — so the library keeps its "zero extra native deps for
+ * guidance" contract (see `RectCropPreview`) AND no longer needs the host
+ * to add Fresco's `animated-gif` module on Android just to make the
+ * coach-marks move.
+ *
+ * Why not GIFs:  the authored GIFs were 280 px sources shown at 240 dp;
+ * on a ~2.6×-density phone that 240 dp is ~630 physical px, so the 280 px
+ * source was up-scaled ~2.25× → visibly pixelated.  A 256-colour GIF also
+ * bands.  These vector-ish primitives are resolution-independent (they're
+ * just borders + transforms the GPU rasterises at native density) and fully
+ * themeable via `GUIDANCE_TOKENS`.
+ *
+ * Both graphics:
+ *   • run a single `Animated.loop` on the NATIVE driver (transform/opacity
+ *     only) so the loop is off the JS thread;
+ *   • take a `playing` flag — the host renders them only while `visible`,
+ *     but we still gate the loop so a mounted-but-paused graphic costs
+ *     nothing;
+ *   • scale every dimension off a single `size` (defaults to the shared
+ *     `GUIDANCE_TOKENS.graphicSize`) so callers can resize without restyle.
+ */
+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.RotatePhoneGraphic = RotatePhoneGraphic;
+exports.PanPhoneGraphic = PanPhoneGraphic;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const guidanceTokens_1 = require("./guidanceTokens");
+const DEFAULT_SIZE = guidanceTokens_1.GUIDANCE_TOKENS.graphicSize;
+/**
+ * A white rounded-rectangle "phone" outline with a small camera dot on its
+ * top short edge.  The dot makes the device's up-axis legible, so when the
+ * rotate graphic turns the body the rotation reads unambiguously.  Children
+ * (e.g. the pan sweep band) render over the screen area.
+ */
+function PhoneBody({ width, height, children, style, }) {
+    const radius = Math.min(width, height) * 0.16;
+    const short = Math.min(width, height);
+    const dotSize = Math.max(4, short * 0.09);
+    const inset = Math.max(4, short * 0.06);
+    // The front-facing camera always sits on a SHORT edge: top-centre for a
+    // tall (portrait) body, side-centre for a wide (landscape) body.  (Was
+    // top-centre unconditionally, which put the dot mid-LONG-edge on a
+    // landscape body.)
+    const isWide = width > height;
+    const dotPos = isWide
+        ? { left: inset, top: height / 2 - dotSize / 2 }
+        : { top: inset, left: width / 2 - dotSize / 2 };
+    return (react_1.default.createElement(react_native_1.View, { style: [
+            {
+                width,
+                height,
+                borderRadius: radius,
+                borderWidth: Math.max(2, width * 0.03),
+                borderColor: guidanceTokens_1.GUIDANCE_TOKENS.white,
+            },
+            styles.phoneBody,
+            style,
+        ] },
+        react_1.default.createElement(react_native_1.View, { style: [
+                styles.cameraDot,
+                { width: dotSize, height: dotSize, borderRadius: dotSize / 2 },
+                dotPos,
+            ] }),
+        children));
+}
+/**
+ * RotatePhoneGraphic — a portrait phone outline that rotates 0°→90°→0°
+ * (portrait → landscape → portrait) on a loop, riding a faint amber guide
+ * ring with a clockwise arrowhead, demonstrating the "rotate to landscape"
+ * gesture.  Replaces `rotate-to-landscape.gif`.
+ */
+function RotatePhoneGraphic({ size = DEFAULT_SIZE, playing = true, style, target = 'landscape', }) {
+    // Single 0→1 loop value drives a ONE-WAY demonstration: hold the START
+    // orientation, rotate to the TARGET, hold, then fade out + reset (the
+    // reverse rotation happens while invisible).  This avoids the symmetric
+    // oscillation, which dwelt at the target and read as "starts at target,
+    // rotates away" — i.e. backwards.
+    const t = (0, react_1.useRef)(new react_native_1.Animated.Value(0)).current;
+    (0, react_1.useEffect)(() => {
+        if (!playing) {
+            t.setValue(0);
+            return;
+        }
+        const loop = react_native_1.Animated.loop(react_native_1.Animated.timing(t, {
+            toValue: 1,
+            duration: 2200,
+            easing: react_native_1.Easing.inOut(react_native_1.Easing.cubic),
+            useNativeDriver: true,
+        }));
+        loop.start();
+        return () => loop.stop();
+    }, [playing, t]);
+    // To-landscape: start portrait (tall), rotate anticlockwise to landscape.
+    // To-portrait: start landscape (wide), rotate clockwise to stand upright.
+    const toLandscape = target === 'landscape';
+    const targetDeg = toLandscape ? '-90deg' : '90deg';
+    // Hold START (0°) → rotate to TARGET → hold TARGET.
+    const rotate = t.interpolate({
+        inputRange: [0, 0.18, 0.62, 1],
+        outputRange: ['0deg', '0deg', targetDeg, targetDeg],
+    });
+    // Fade in at START, hold through the rotation, fade out at TARGET so the
+    // invisible reset (target→start on loop) is never seen.
+    const phoneOpacity = t.interpolate({
+        inputRange: [0, 0.12, 0.82, 1],
+        outputRange: [0, 1, 1, 0],
+    });
+    const ring = size * 0.78;
+    const ringInset = (size - ring) / 2;
+    const phoneW = toLandscape ? size * 0.3 : size * 0.56;
+    const phoneH = toLandscape ? size * 0.56 : size * 0.3;
+    return (react_1.default.createElement(react_native_1.View, { style: [{ width: size, height: size }, styles.center, style], pointerEvents: "none" },
+        react_1.default.createElement(react_native_1.View, { style: [
+                styles.ring,
+                {
+                    width: ring,
+                    height: ring,
+                    borderRadius: ring / 2,
+                    top: ringInset,
+                    left: ringInset,
+                    borderColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+                },
+            ] }),
+        react_1.default.createElement(react_native_1.View, { style: [
+                styles.arrowHead,
+                toLandscape ? styles.arrowHeadLeft : styles.arrowHeadRight,
+                { top: ringInset - 5, left: size / 2 - 5 },
+            ] }),
+        react_1.default.createElement(react_native_1.Animated.View, { style: { opacity: phoneOpacity, transform: [{ rotate }] } },
+            react_1.default.createElement(PhoneBody, { width: phoneW, height: phoneH }))));
+}
+/**
+ * PanPhoneGraphic — a phone outline (landscape for Mode-A `down`, portrait
+ * for Mode-B `right`) with an amber sweep band that travels across the pan
+ * axis on a loop, demonstrating the camera sweep.  The band fades in/out at
+ * the travel ends so the loop reset is invisible.  Replaces
+ * `pan-capture.gif`.  The bouncing direction arrow stays in PanHowToOverlay.
+ */
+function PanPhoneGraphic({ direction, size = DEFAULT_SIZE, playing = true, style, }) {
+    // One value loops 0→1; drives the phone's travel + perspective tilt
+    // together so the device reads as ROTATING as it sweeps along the arrow.
+    const t = (0, react_1.useRef)(new react_native_1.Animated.Value(0)).current;
+    (0, react_1.useEffect)(() => {
+        if (!playing) {
+            t.setValue(0);
+            return;
+        }
+        const loop = react_native_1.Animated.loop(react_native_1.Animated.timing(t, {
+            toValue: 1,
+            duration: 1900,
+            easing: react_native_1.Easing.inOut(react_native_1.Easing.ease),
+            useNativeDriver: true,
+        }));
+        loop.start();
+        return () => loop.stop();
+    }, [playing, t, direction]);
+    const down = direction === 'down';
+    // Mode A (down) holds the phone LANDSCAPE; Mode B (right) PORTRAIT.
+    const phoneW = down ? size * 0.5 : size * 0.34;
+    const phoneH = down ? size * 0.34 : size * 0.5;
+    // Travel ± along the pan axis (down → +Y, right → +X), kept in-canvas.
+    const amp = size * 0.2;
+    const translate = t.interpolate({
+        inputRange: [0, 1],
+        outputRange: [-amp, amp],
+    });
+    // The device TILTS through the sweep — rotating about the cross-pan axis
+    // as it pans — which is the 3D "the phone is turning" read the flat
+    // band lacked.  rotateX for a vertical (down) pan, rotateY for horizontal.
+    // The horizontal (right) tilt is INVERTED vs the vertical one so the edge
+    // on the side the phone is currently on reads LONGER (convex toward the
+    // viewer) — matched to on-device feedback for the portrait Mode-B pan.
+    const tilt = t.interpolate({
+        inputRange: [0, 1],
+        outputRange: down ? ['-24deg', '24deg'] : ['24deg', '-24deg'],
+    });
+    // Fade at the travel ends so the loop's restart is invisible.
+    const opacity = t.interpolate({
+        inputRange: [0, 0.15, 0.85, 1],
+        outputRange: [0, 1, 1, 0],
+    });
+    // `perspective` makes the rotateX/rotateY read as depth (a turning
+    // device), not a flat vertical squash.
+    const transform = down
+        ? [{ perspective: 800 }, { translateY: translate }, { rotateX: tilt }]
+        : [{ perspective: 800 }, { translateX: translate }, { rotateY: tilt }];
+    return (react_1.default.createElement(react_native_1.View, { style: [{ width: size, height: size }, styles.center, style], pointerEvents: "none" },
+        react_1.default.createElement(react_native_1.Animated.View, { style: { opacity, transform } },
+            react_1.default.createElement(PhoneBody, { width: phoneW, height: phoneH },
+                react_1.default.createElement(react_native_1.View, { style: styles.screenGlow, pointerEvents: "none" })))));
+}
+const styles = react_native_1.StyleSheet.create({
+    center: { alignItems: 'center', justifyContent: 'center' },
+    phoneBody: {
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: 'transparent',
+    },
+    cameraDot: {
+        position: 'absolute',
+        backgroundColor: guidanceTokens_1.GUIDANCE_TOKENS.white,
+    },
+    ring: {
+        position: 'absolute',
+        borderWidth: 1.5,
+        opacity: 0.28,
+        backgroundColor: 'transparent',
+    },
+    // Amber CSS-triangle arrowhead at the top of the ring.  The base props are
+    // shared; the direction-specific style colours the trailing border so the
+    // apex points along the rotation tangent.
+    arrowHead: {
+        position: 'absolute',
+        width: 0,
+        height: 0,
+        borderTopWidth: 6,
+        borderBottomWidth: 6,
+        borderTopColor: 'transparent',
+        borderBottomColor: 'transparent',
+    },
+    // Points LEFT (anticlockwise / to-landscape): RIGHT border amber.
+    arrowHeadLeft: {
+        borderRightWidth: 10,
+        borderRightColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+    },
+    // Points RIGHT (clockwise / to-portrait): LEFT border amber.
+    arrowHeadRight: {
+        borderLeftWidth: 10,
+        borderLeftColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+    },
+    // Faint amber fill inside the phone outline — a hint of the live
+    // preview so the turning device reads as a screen, not an empty frame.
+    screenGlow: {
+        width: '78%',
+        height: '70%',
+        borderRadius: 6,
+        backgroundColor: guidanceTokens_1.GUIDANCE_TOKENS.amber,
+        opacity: 0.14,
+    },
+});
+//# sourceMappingURL=guidanceGraphics.js.map

package/dist/camera/guidanceTokens.d.ts

@@ -0,0 +1,54 @@
+/**
+ * guidanceTokens — the single source of truth for the panorama capture
+ * GUIDANCE visual language (rotate prompt, pan how-to, countdown, too-fast
+ * pill, lateral popup).  Values are taken verbatim from the design handoff
+ * ("Camera Capture Guides") so every guidance surface shares exact styling
+ * instead of re-declaring colors per component.
+ *
+ * The two looping device-motion graphics are drawn programmatically (see
+ * ./guidanceGraphics — pure RN View + Animated, no image assets); these
+ * tokens cover both those graphics and the code-built chrome around them.
+ */
+export declare const GUIDANCE_TOKENS: {
+    /** Device outline, caption text, countdown number. */
+    readonly white: "#FFFFFF";
+    /** Rotation ring/arrow, pan guide line, dots, glow — the one accent. */
+    readonly amber: "#FFC462";
+    /** Caption-pill / popup background scrim. */
+    readonly scrim: "rgba(0,0,0,0.42)";
+    /** Pill hairline border. */
+    readonly hairline: "rgba(255,255,255,0.16)";
+    /** On-screen size (px square) of the rotate / pan guidance graphics. */
+    readonly graphicSize: 240;
+};
+/**
+ * Caption-pill spec (item 2 "Rotate to landscape" + reused by the too-fast
+ * pill): full pill, scrim bg, hairline border, amber leading dot, white
+ * 13px/600 text.
+ */
+export declare const GUIDANCE_PILL: {
+    readonly paddingVertical: 8;
+    readonly paddingHorizontal: 15;
+    readonly borderRadius: 999;
+    readonly dotSize: 6;
+    readonly dotGap: 7;
+    readonly fontSize: 13;
+    readonly fontWeight: "600";
+};
+/**
+ * Countdown spec (item 5): amber dot + glow, white 30px/700 tabular-nums
+ * number, whole timer blinks opacity 0.18↔1 over a 1s ease-in-out cycle.
+ */
+export declare const GUIDANCE_COUNTDOWN: {
+    readonly dotSize: 9;
+    readonly dotGap: 8;
+    readonly dotGlow: "rgba(255,196,98,0.85)";
+    readonly fontSize: 30;
+    readonly fontWeight: "700";
+    readonly blinkMinOpacity: 0.18;
+    readonly blinkMaxOpacity: 1;
+    readonly blinkPeriodMs: 1000;
+    /** top/left inset from the (user-perceived) corner. */
+    readonly inset: 16;
+};
+//# sourceMappingURL=guidanceTokens.d.ts.map

package/dist/camera/guidanceTokens.js

@@ -0,0 +1,58 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * guidanceTokens — the single source of truth for the panorama capture
+ * GUIDANCE visual language (rotate prompt, pan how-to, countdown, too-fast
+ * pill, lateral popup).  Values are taken verbatim from the design handoff
+ * ("Camera Capture Guides") so every guidance surface shares exact styling
+ * instead of re-declaring colors per component.
+ *
+ * The two looping device-motion graphics are drawn programmatically (see
+ * ./guidanceGraphics — pure RN View + Animated, no image assets); these
+ * tokens cover both those graphics and the code-built chrome around them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUIDANCE_COUNTDOWN = exports.GUIDANCE_PILL = exports.GUIDANCE_TOKENS = void 0;
+exports.GUIDANCE_TOKENS = {
+    /** Device outline, caption text, countdown number. */
+    white: '#FFFFFF',
+    /** Rotation ring/arrow, pan guide line, dots, glow — the one accent. */
+    amber: '#FFC462',
+    /** Caption-pill / popup background scrim. */
+    scrim: 'rgba(0,0,0,0.42)',
+    /** Pill hairline border. */
+    hairline: 'rgba(255,255,255,0.16)',
+    /** On-screen size (px square) of the rotate / pan guidance graphics. */
+    graphicSize: 240,
+};
+/**
+ * Caption-pill spec (item 2 "Rotate to landscape" + reused by the too-fast
+ * pill): full pill, scrim bg, hairline border, amber leading dot, white
+ * 13px/600 text.
+ */
+exports.GUIDANCE_PILL = {
+    paddingVertical: 8,
+    paddingHorizontal: 15,
+    borderRadius: 999,
+    dotSize: 6,
+    dotGap: 7,
+    fontSize: 13,
+    fontWeight: '600',
+};
+/**
+ * Countdown spec (item 5): amber dot + glow, white 30px/700 tabular-nums
+ * number, whole timer blinks opacity 0.18↔1 over a 1s ease-in-out cycle.
+ */
+exports.GUIDANCE_COUNTDOWN = {
+    dotSize: 9,
+    dotGap: 8,
+    dotGlow: 'rgba(255,196,98,0.85)',
+    fontSize: 30,
+    fontWeight: '700',
+    blinkMinOpacity: 0.18,
+    blinkMaxOpacity: 1,
+    blinkPeriodMs: 1000,
+    /** top/left inset from the (user-perceived) corner. */
+    inset: 16,
+};
+//# sourceMappingURL=guidanceTokens.js.map

package/dist/camera/panModeGate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * panModeGate — pure decision helper for the first-time-user "rotate the
+ * device" gate (guidance item 1).
+ *
+ * The non-AR panorama flow has two pan directions:
+ *
+ *   - **vertical** — the user holds the phone LANDSCAPE and pans the camera
+ *     TOP → BOTTOM down a tall fixture.  Both `landscape-left` and
+ *     `landscape-right` are valid holds.
+ *   - **horizontal** — the user holds the phone PORTRAIT and pans LEFT →
+ *     RIGHT across a wide scene.  Both portrait holds are valid.
+ *
+ * A host restricts capture via the `panMode` flag:
+ *   - `'vertical'`   → landscape-only; a PORTRAIT hold is gated (rotate to
+ *                      landscape).
+ *   - `'horizontal'` → portrait-only; a LANDSCAPE hold is gated (rotate to
+ *                      portrait).
+ *   - `'both'`       → either; the gate never fires.
+ *
+ * When the gate fires the host must NOT start the capture — it shows the
+ * rotate prompt (guidance item 2, pointing at the target orientation) and
+ * waits for the user to rotate.
+ *
+ * This module is the single pure predicate for that decision: no React, no
+ * sensors, no side effects, so the gate logic is unit-testable in the node
+ * jest env without booting a render or mocking the accelerometer.
+ */
+import type { DeviceOrientation } from './useDeviceOrientation';
+/**
+ * Which device holds the panorama capture accepts.
+ *
+ *   - `'vertical'`   — LANDSCAPE only (top→bottom pan; the product default).
+ *     Portrait holds are gated behind the rotate-to-landscape prompt.
+ *   - `'horizontal'` — PORTRAIT only (left→right pan).  Landscape holds are
+ *     gated behind the rotate-to-portrait prompt.
+ *   - `'both'`       — LANDSCAPE or PORTRAIT; the gate never fires, the user
+ *     captures in whichever hold they're already in.
+ */
+export type PanMode = 'vertical' | 'horizontal' | 'both';
+/**
+ * True when the caller must BLOCK capture-start and show the rotate prompt
+ * for the current device hold:
+ *   - `'vertical'`   gates a PORTRAIT hold (needs landscape).
+ *   - `'horizontal'` gates a LANDSCAPE hold (needs portrait).
+ *   - `'both'`       never gates.
+ */
+export declare function shouldGateForPanMode(panMode: PanMode, orientation: DeviceOrientation): boolean;
+/**
+ * The orientation the user must rotate TO when a hold is gated, used to pick
+ * the rotate prompt's copy + graphic.  `'vertical'` wants landscape,
+ * `'horizontal'` wants portrait; `'both'` never gates so returns `null`.
+ */
+export declare function gateTargetOrientation(panMode: PanMode): 'landscape' | 'portrait' | null;
+//# sourceMappingURL=panModeGate.d.ts.map

package/dist/camera/panModeGate.js

@@ -0,0 +1,62 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * panModeGate — pure decision helper for the first-time-user "rotate the
+ * device" gate (guidance item 1).
+ *
+ * The non-AR panorama flow has two pan directions:
+ *
+ *   - **vertical** — the user holds the phone LANDSCAPE and pans the camera
+ *     TOP → BOTTOM down a tall fixture.  Both `landscape-left` and
+ *     `landscape-right` are valid holds.
+ *   - **horizontal** — the user holds the phone PORTRAIT and pans LEFT →
+ *     RIGHT across a wide scene.  Both portrait holds are valid.
+ *
+ * A host restricts capture via the `panMode` flag:
+ *   - `'vertical'`   → landscape-only; a PORTRAIT hold is gated (rotate to
+ *                      landscape).
+ *   - `'horizontal'` → portrait-only; a LANDSCAPE hold is gated (rotate to
+ *                      portrait).
+ *   - `'both'`       → either; the gate never fires.
+ *
+ * When the gate fires the host must NOT start the capture — it shows the
+ * rotate prompt (guidance item 2, pointing at the target orientation) and
+ * waits for the user to rotate.
+ *
+ * This module is the single pure predicate for that decision: no React, no
+ * sensors, no side effects, so the gate logic is unit-testable in the node
+ * jest env without booting a render or mocking the accelerometer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldGateForPanMode = shouldGateForPanMode;
+exports.gateTargetOrientation = gateTargetOrientation;
+function isPortrait(orientation) {
+    return (orientation === 'portrait' || orientation === 'portrait-upside-down');
+}
+/**
+ * True when the caller must BLOCK capture-start and show the rotate prompt
+ * for the current device hold:
+ *   - `'vertical'`   gates a PORTRAIT hold (needs landscape).
+ *   - `'horizontal'` gates a LANDSCAPE hold (needs portrait).
+ *   - `'both'`       never gates.
+ */
+function shouldGateForPanMode(panMode, orientation) {
+    if (panMode === 'vertical')
+        return isPortrait(orientation);
+    if (panMode === 'horizontal')
+        return !isPortrait(orientation);
+    return false; // 'both'
+}
+/**
+ * The orientation the user must rotate TO when a hold is gated, used to pick
+ * the rotate prompt's copy + graphic.  `'vertical'` wants landscape,
+ * `'horizontal'` wants portrait; `'both'` never gates so returns `null`.
+ */
+function gateTargetOrientation(panMode) {
+    if (panMode === 'vertical')
+        return 'landscape';
+    if (panMode === 'horizontal')
+        return 'portrait';
+    return null;
+}
+//# sourceMappingURL=panModeGate.js.map

package/dist/camera/pickCaptureFormat.d.ts

@@ -0,0 +1,71 @@
+/**
+ * pickCaptureFormat — choose the vision-camera format for the capture stream.
+ *
+ * Replaces a plain `useCameraFormat([{ videoResolution: 'max' }, …])`, which
+ * picks the device's MAX-video format and lets the PHOTO resolution ride
+ * along — on the iPhone 16 Pro ultra-wide that pairs a **48 MP** still
+ * (8064×6048) with the 4032×3024 max-video format, so a tap photo came out
+ * ~6000 px.  vision-camera 4.x exposes each format's photo/video resolution
+ * but NOT its pixel format / bit-depth, so we can't filter for 8-bit; the
+ * empirical rule is that the device's MAX 4:3 video format is 8-bit (the
+ * frame processor needs 8-bit for non-AR stitching), and lower video
+ * resolutions risk 10-bit.
+ *
+ * Strategy: among the ~4:3 formats whose photo long-edge is within
+ * `maxPhotoLongEdge`, pick the one with the HIGHEST video resolution (keeps
+ * the preview/stitch stream as sharp as possible while bounding the still),
+ * tie-breaking on higher fps, then the largest photo under the cap, then
+ * non-HDR (a hedge toward 8-bit).  If NO format fits the cap, fall back to
+ * the overall max-video format (never returns nothing for a non-empty list).
+ *
+ * Verified against the real iPhone 16 Pro ultra-wide format list (see the
+ * unit test): cap 4032 → 4032×3024 photo (12 MP) + 3264×2448 video (was
+ * 8064×6048 photo); cap 2048 → 2016×1512 photo (3 MP) + 1920×1440 video.
+ *
+ * Pure + structurally-typed (no vision-camera import) so it unit-tests in the
+ * node jest env; `CameraDeviceFormat` is structurally assignable to
+ * `FormatLike`.
+ */
+/** The CameraDeviceFormat fields this picker reads. */
+export interface FormatLike {
+    photoWidth: number;
+    photoHeight: number;
+    videoWidth: number;
+    videoHeight: number;
+    maxFps: number;
+    supportsVideoHdr: boolean;
+}
+export interface PickFormatOptions {
+    /**
+     * Cap on the chosen format's photo LONG edge, in px.  The picker prefers
+     * the sharpest-video format whose photo fits this.  `0` disables the cap
+     * (reverts to pure max-video).  Default 4032 (≈12 MP at 4:3, "4K"-ish).
+     */
+    maxPhotoLongEdge?: number;
+    /** Target capture aspect (W/H in landscape). Default 4/3. */
+    aspect?: number;
+    /** Aspect match tolerance. Default 0.05. */
+    aspectTolerance?: number;
+    /**
+     * Prefer a SMOOTH (high-fps) preview over the sharpest video format.  Off by
+     * default → max-video-resolution-first (back-compat).  On (the panorama
+     * camera opts in) → rank by frame rate up to `fpsTarget` first, THEN video
+     * resolution.  The default video-first sort picks e.g. a 3264×2448 **@30 fps**
+     * format over a 1920×1440 **@60 fps** one, halving the preview frame rate —
+     * visible as jitter while panning.  The stitch clamps keyframes to 640/1280 px
+     * anyway, so the higher video resolution buys nothing for the panorama; a
+     * 60 fps stream just looks smooth.
+     */
+    preferHighFps?: boolean;
+    /**
+     * Ceiling for the fps preference when `preferHighFps` is on.  Formats at or
+     * above this are treated as equally smooth (so resolution breaks the tie
+     * instead of chasing 120 fps at a lower resolution).  Default 60.
+     */
+    fpsTarget?: number;
+}
+/**
+ * Pick the best capture format, or `undefined` for an empty list.
+ */
+export declare function pickCaptureFormat<F extends FormatLike>(formats: readonly F[], opts?: PickFormatOptions): F | undefined;
+//# sourceMappingURL=pickCaptureFormat.d.ts.map

package/dist/camera/pickCaptureFormat.js

@@ -0,0 +1,85 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * pickCaptureFormat — choose the vision-camera format for the capture stream.
+ *
+ * Replaces a plain `useCameraFormat([{ videoResolution: 'max' }, …])`, which
+ * picks the device's MAX-video format and lets the PHOTO resolution ride
+ * along — on the iPhone 16 Pro ultra-wide that pairs a **48 MP** still
+ * (8064×6048) with the 4032×3024 max-video format, so a tap photo came out
+ * ~6000 px.  vision-camera 4.x exposes each format's photo/video resolution
+ * but NOT its pixel format / bit-depth, so we can't filter for 8-bit; the
+ * empirical rule is that the device's MAX 4:3 video format is 8-bit (the
+ * frame processor needs 8-bit for non-AR stitching), and lower video
+ * resolutions risk 10-bit.
+ *
+ * Strategy: among the ~4:3 formats whose photo long-edge is within
+ * `maxPhotoLongEdge`, pick the one with the HIGHEST video resolution (keeps
+ * the preview/stitch stream as sharp as possible while bounding the still),
+ * tie-breaking on higher fps, then the largest photo under the cap, then
+ * non-HDR (a hedge toward 8-bit).  If NO format fits the cap, fall back to
+ * the overall max-video format (never returns nothing for a non-empty list).
+ *
+ * Verified against the real iPhone 16 Pro ultra-wide format list (see the
+ * unit test): cap 4032 → 4032×3024 photo (12 MP) + 3264×2448 video (was
+ * 8064×6048 photo); cap 2048 → 2016×1512 photo (3 MP) + 1920×1440 video.
+ *
+ * Pure + structurally-typed (no vision-camera import) so it unit-tests in the
+ * node jest env; `CameraDeviceFormat` is structurally assignable to
+ * `FormatLike`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickCaptureFormat = pickCaptureFormat;
+const DEFAULT_MAX_PHOTO_LONG_EDGE = 4032;
+const DEFAULT_FPS_TARGET = 60;
+const longEdge = (f) => Math.max(f.photoWidth, f.photoHeight);
+const videoPixels = (f) => f.videoWidth * f.videoHeight;
+/**
+ * Pick the best capture format, or `undefined` for an empty list.
+ */
+function pickCaptureFormat(formats, opts = {}) {
+    if (!formats || formats.length === 0)
+        return undefined;
+    const aspect = opts.aspect ?? 4 / 3;
+    const tol = opts.aspectTolerance ?? 0.05;
+    const cap = opts.maxPhotoLongEdge ?? DEFAULT_MAX_PHOTO_LONG_EDGE;
+    const preferHighFps = opts.preferHighFps ?? false;
+    const fpsTarget = opts.fpsTarget ?? DEFAULT_FPS_TARGET;
+    // Treat everything at/above the target as equally smooth so resolution, not
+    // a chase for 120 fps, breaks the tie.
+    const smoothness = (f) => Math.min(f.maxFps, fpsTarget);
+    const matchesAspect = (f) => f.photoHeight > 0
+        && f.videoHeight > 0
+        && Math.abs(f.photoWidth / f.photoHeight - aspect) < tol
+        && Math.abs(f.videoWidth / f.videoHeight - aspect) < tol;
+    // Prefer 4:3 formats; if the device has none, consider all.
+    const fourThree = formats.filter(matchesAspect);
+    const base = fourThree.length > 0 ? fourThree : formats.slice();
+    // Among those within the photo cap; if none fit, fall back to all (which
+    // then resolves to the max-video format — never worse than today).
+    const withinCap = cap > 0 ? base.filter((f) => longEdge(f) <= cap) : base.slice();
+    const candidates = withinCap.length > 0 ? withinCap : base;
+    return candidates.slice().sort((a, b) => {
+        if (preferHighFps) {
+            // Smooth-preview priority: frame rate (up to the target) before video
+            // resolution.  Keeps the panorama preview at ~60 fps instead of dropping
+            // to a sharper-but-30fps format.
+            const sa = smoothness(a);
+            const sb = smoothness(b);
+            if (sb !== sa)
+                return sb - sa;
+        }
+        const va = videoPixels(a);
+        const vb = videoPixels(b);
+        if (vb !== va)
+            return vb - va; // highest video resolution first
+        if (b.maxFps !== a.maxFps)
+            return b.maxFps - a.maxFps; // then higher fps
+        if (longEdge(b) !== longEdge(a))
+            return longEdge(b) - longEdge(a); // largest photo under cap
+        // Prefer non-HDR — a hedge toward an 8-bit pixel format (the stitch
+        // frame processor needs 8-bit; vision-camera doesn't expose bit-depth).
+        return (a.supportsVideoHdr ? 1 : 0) - (b.supportsVideoHdr ? 1 : 0);
+    })[0];
+}
+//# sourceMappingURL=pickCaptureFormat.js.map