react-native-image-stitcher 0.15.2 → 0.16.1

package/dist/camera/cameraErrorMessages.d.ts

@@ -21,12 +21,41 @@ export interface UserFacingStitchError {
     /** One-paragraph, plain-language corrective guidance. */
     message: string;
 }
+/**
+ * The four recoverable stitch outcomes, each with copy tuned to its
+ * actual root cause.  `Partial<Record<...>>` keeps the keys
+ * compile-checked against the `CameraErrorCode` union — a renamed or
+ * dropped code breaks the build here rather than silently going
+ * unhandled.
+ */
+/**
+ * A partial map of recoverable-error code → copy, for the `overrides`
+ * argument of {@link userFacingStitchError}.  Hosts localising the SDK pass
+ * their translated strings here (typically built from their i18n catalogue,
+ * keyed by the same `CameraErrorCode`s exposed by {@link RECOVERABLE_STITCH_CODES}).
+ */
+export type UserFacingStitchErrorOverrides = Partial<Record<CameraErrorCode, UserFacingStitchError>>;
+export declare const RECOVERABLE_STITCH_GUIDANCE: Partial<Record<CameraErrorCode, UserFacingStitchError>>;
+/**
+ * The recoverable stitch-error codes this module has built-in copy for.
+ * A host wiring i18n iterates these to know exactly which codes need a
+ * translation (every other `CameraErrorCode` maps to `null` and uses the
+ * host's generic error UI).
+ */
+export declare const RECOVERABLE_STITCH_CODES: CameraErrorCode[];
 /**
  * Maps a `CameraErrorCode` to friendly, action-guiding alert copy.
  *
+ * Localisation: pass `overrides` (a partial code→copy map, typically from
+ * your i18n catalogue) and any code present there wins over the built-in
+ * English; codes you omit fall back to the bundled copy.  This is the
+ * host-side mirror of the `guidanceCopy` prop — the recoverable-error alert
+ * is rendered by the HOST (in its `onError` handler), so it is localised
+ * here rather than through `<Camera>`.
+ *
  * @returns the title+message for a recoverable stitch failure, or `null`
  *   if `code` has no single user-recoverable action (the host should
  *   then show its generic error UI).
  */
-export declare function userFacingStitchError(code: CameraErrorCode): UserFacingStitchError | null;
+export declare function userFacingStitchError(code: CameraErrorCode, overrides?: UserFacingStitchErrorOverrides): UserFacingStitchError | null;
 //# sourceMappingURL=cameraErrorMessages.d.ts.map

package/dist/camera/cameraErrorMessages.js

@@ -1,14 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOVERABLE_STITCH_CODES = exports.RECOVERABLE_STITCH_GUIDANCE = void 0;
 exports.userFacingStitchError = userFacingStitchError;
-/**
- * The four recoverable stitch outcomes, each with copy tuned to its
- * actual root cause.  `Partial<Record<...>>` keeps the keys
- * compile-checked against the `CameraErrorCode` union — a renamed or
- * dropped code breaks the build here rather than silently going
- * unhandled.
- */
-const RECOVERABLE_STITCH_GUIDANCE = {
+exports.RECOVERABLE_STITCH_GUIDANCE = {
     // cv::Stitcher ERR_NEED_MORE_IMGS / the manual pipeline's "0 valid
     // pairwise matches" — the frames simply don't overlap enough to chain.
     STITCH_NEED_MORE_IMGS: {
@@ -33,6 +27,14 @@ const RECOVERABLE_STITCH_GUIDANCE = {
         message: "The frames couldn't be aligned — keep the phone level and steady so "
             + 'each frame overlaps the one before it.',
     },
+    // v0.16 — the post-stitch validator rejected the output as disjoint /
+    // fragmented: the frames stitched but didn't form one coherent panorama
+    // (usually a too-fast or jerky sweep that broke alignment partway).
+    STITCH_LOW_QUALITY: {
+        title: "That didn't come out right",
+        message: "The panorama didn't stitch into one clean image — try again, panning "
+            + 'slowly and steadily in one direction so each frame overlaps the last.',
+    },
     // Ran out of memory finishing the stitch — usually an over-long sweep.
     STITCH_OOM: {
         title: 'Try a shorter sweep',
@@ -40,14 +42,28 @@ const RECOVERABLE_STITCH_GUIDANCE = {
             + '— a shorter, narrower sweep (or 1x for wide scenes) will fit.',
     },
 };
+/**
+ * The recoverable stitch-error codes this module has built-in copy for.
+ * A host wiring i18n iterates these to know exactly which codes need a
+ * translation (every other `CameraErrorCode` maps to `null` and uses the
+ * host's generic error UI).
+ */
+exports.RECOVERABLE_STITCH_CODES = Object.keys(exports.RECOVERABLE_STITCH_GUIDANCE);
 /**
  * Maps a `CameraErrorCode` to friendly, action-guiding alert copy.
  *
+ * Localisation: pass `overrides` (a partial code→copy map, typically from
+ * your i18n catalogue) and any code present there wins over the built-in
+ * English; codes you omit fall back to the bundled copy.  This is the
+ * host-side mirror of the `guidanceCopy` prop — the recoverable-error alert
+ * is rendered by the HOST (in its `onError` handler), so it is localised
+ * here rather than through `<Camera>`.
+ *
  * @returns the title+message for a recoverable stitch failure, or `null`
  *   if `code` has no single user-recoverable action (the host should
  *   then show its generic error UI).
  */
-function userFacingStitchError(code) {
-    return RECOVERABLE_STITCH_GUIDANCE[code] ?? null;
+function userFacingStitchError(code, overrides) {
+    return overrides?.[code] ?? exports.RECOVERABLE_STITCH_GUIDANCE[code] ?? null;
 }
 //# sourceMappingURL=cameraErrorMessages.js.map

package/dist/camera/cameraGuidanceCopy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * cameraGuidanceCopy — the single user-overridable copy surface for EVERY
+ * string the panorama capture UI renders itself: the rotate prompt, pan
+ * hint, too-fast cue, lateral-stop popup, the capture-status banner
+ * (recording / stitching) AND the crop-editor warning banners.  Centralised
+ * so a host can localise or re-word the whole capture experience in one
+ * place via the `guidanceCopy` `<Camera>` prop (see the README's
+ * "Internationalization" section), and so the defaults live together.
+ *
+ * NOTE on coverage: the *recoverable stitch-error* alert copy
+ * (`userFacingStitchError`) is rendered by the HOST (it calls that helper
+ * in its `onError` handler), so it is localised there — see
+ * `cameraErrorMessages.ts`, which accepts an override map for the same
+ * reason.  Everything the SDK draws on screen flows through THIS object.
+ *
+ * Mirrors the override pattern of `PanoramaGuidance.messages` and
+ * `cameraErrorMessages.ts`.
+ */
+import { type CaptureWarningCopy } from './captureWarnings';
+export interface GuidanceCopy {
+    /** Item 2 — caption pill while waiting for the user to rotate to landscape
+     *  (panMode `'vertical'`). */
+    rotateToLandscape: string;
+    /** Item 2 — caption pill while waiting for the user to rotate to portrait
+     *  (panMode `'horizontal'`). */
+    rotateToPortrait: string;
+    /** Item 3 — short hint shown with the how-to-pan animation. */
+    panHint: string;
+    /** Item 4 — transient warning when the pan is too fast. */
+    tooFast: string;
+    /** Item 6 — popup title when the user drifts laterally (cross-axis). */
+    lateralStopTitle: string;
+    /** Item 6 — popup body / guidance for the lateral-drift stop. */
+    lateralStopBody: string;
+    /** Item 6 — popup dismiss button label. */
+    lateralStopDismiss: string;
+    /**
+     * Item 6 — popup TITLE when lateral drift stopped the capture before
+     * enough frames were captured to stitch (the user panned the wrong way
+     * almost immediately).  Nothing was produced, so the copy points them at
+     * the arrow instead of saying "we kept what you captured".
+     */
+    lateralWrongDirectionTitle: string;
+    /** Item 6 — popup BODY for the too-few-frames wrong-direction stop. */
+    lateralWrongDirectionBody: string;
+    /** Item 7 — confirm button on the crop editor. */
+    cropConfirm: string;
+    /** Item 7 — reset-corners button on the crop editor. */
+    cropReset: string;
+    /** Item 7 — "emit the stitch un-cropped" button on the crop editor. */
+    cropUseOriginal: string;
+    /** Item 7 — discard this capture and return to the camera. */
+    cropRetake: string;
+    /**
+     * Accept button in PREVIEW-ONLY mode (`showPreview` without `rectCrop`):
+     * the editor shows the stitched image with no crop box, and this confirms
+     * it as-is.
+     */
+    previewConfirm: string;
+    /** Banner while a capture is recording (the calm, green state). */
+    statusRecording: string;
+    /** Banner while the panorama is being stitched after release. */
+    statusStitching: string;
+    /**
+     * LOW_FRAME_UTILIZATION warning.  TEMPLATE — keep the `{included}`,
+     * `{requested}` and `{percent}` placeholders (substituted at runtime).
+     */
+    warnLowFrameUtilization: string;
+    /** LATERAL_DRIFT_FINALIZE warning. */
+    warnLateralDriftFinalize: string;
+    /** HIGH_PAN_SPEED warning. */
+    warnHighPanSpeed: string;
+}
+export declare const DEFAULT_GUIDANCE_COPY: GuidanceCopy;
+/**
+ * Project the warning keys of a resolved `GuidanceCopy` back onto the
+ * {@link CaptureWarningCopy} shape `buildCaptureWarnings` consumes.  Keeps
+ * the two call sites in `<Camera>` from re-spelling the mapping (DRY).
+ */
+export declare function captureWarningCopyFrom(g: GuidanceCopy): CaptureWarningCopy;
+/**
+ * Merge a partial host override onto the defaults.  Undefined / missing keys
+ * fall back to the default string; an empty-object / undefined override
+ * returns the defaults unchanged.
+ */
+export declare function mergeGuidanceCopy(override?: Partial<GuidanceCopy>): GuidanceCopy;
+//# sourceMappingURL=cameraGuidanceCopy.d.ts.map

package/dist/camera/cameraGuidanceCopy.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GUIDANCE_COPY = void 0;
+exports.captureWarningCopyFrom = captureWarningCopyFrom;
+exports.mergeGuidanceCopy = mergeGuidanceCopy;
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * cameraGuidanceCopy — the single user-overridable copy surface for EVERY
+ * string the panorama capture UI renders itself: the rotate prompt, pan
+ * hint, too-fast cue, lateral-stop popup, the capture-status banner
+ * (recording / stitching) AND the crop-editor warning banners.  Centralised
+ * so a host can localise or re-word the whole capture experience in one
+ * place via the `guidanceCopy` `<Camera>` prop (see the README's
+ * "Internationalization" section), and so the defaults live together.
+ *
+ * NOTE on coverage: the *recoverable stitch-error* alert copy
+ * (`userFacingStitchError`) is rendered by the HOST (it calls that helper
+ * in its `onError` handler), so it is localised there — see
+ * `cameraErrorMessages.ts`, which accepts an override map for the same
+ * reason.  Everything the SDK draws on screen flows through THIS object.
+ *
+ * Mirrors the override pattern of `PanoramaGuidance.messages` and
+ * `cameraErrorMessages.ts`.
+ */
+const captureWarnings_1 = require("./captureWarnings");
+exports.DEFAULT_GUIDANCE_COPY = {
+    rotateToLandscape: 'Rotate to landscape',
+    rotateToPortrait: 'Rotate to portrait',
+    panHint: 'Pan slowly top to bottom',
+    tooFast: 'Moving too fast — slow down',
+    lateralStopTitle: 'Keep the pan straight',
+    lateralStopBody: 'You moved sideways. Pan in one direction only — we stitched what you captured.',
+    lateralStopDismiss: 'Got it',
+    lateralWrongDirectionTitle: 'Follow the arrow',
+    lateralWrongDirectionBody: 'You moved the phone the wrong way. Pan slowly in the direction the '
+        + 'arrow shows, in one straight line.',
+    cropConfirm: 'Crop',
+    cropReset: 'Reset',
+    cropUseOriginal: 'Use original',
+    cropRetake: 'Retake',
+    previewConfirm: 'Confirm',
+    statusRecording: 'Hold steady — pan slowly',
+    statusStitching: 'Stitching panorama…',
+    // DRY: the English warning copy lives once, in captureWarnings.ts.
+    warnLowFrameUtilization: captureWarnings_1.DEFAULT_CAPTURE_WARNING_COPY.lowFrameUtilization,
+    warnLateralDriftFinalize: captureWarnings_1.DEFAULT_CAPTURE_WARNING_COPY.lateralDriftFinalize,
+    warnHighPanSpeed: captureWarnings_1.DEFAULT_CAPTURE_WARNING_COPY.highPanSpeed,
+};
+/**
+ * Project the warning keys of a resolved `GuidanceCopy` back onto the
+ * {@link CaptureWarningCopy} shape `buildCaptureWarnings` consumes.  Keeps
+ * the two call sites in `<Camera>` from re-spelling the mapping (DRY).
+ */
+function captureWarningCopyFrom(g) {
+    return {
+        lowFrameUtilization: g.warnLowFrameUtilization,
+        lateralDriftFinalize: g.warnLateralDriftFinalize,
+        highPanSpeed: g.warnHighPanSpeed,
+    };
+}
+/**
+ * Merge a partial host override onto the defaults.  Undefined / missing keys
+ * fall back to the default string; an empty-object / undefined override
+ * returns the defaults unchanged.
+ */
+function mergeGuidanceCopy(override) {
+    if (!override)
+        return exports.DEFAULT_GUIDANCE_COPY;
+    return { ...exports.DEFAULT_GUIDANCE_COPY, ...stripUndefined(override) };
+}
+/** Drop keys whose value is `undefined` so they don't clobber a default. */
+function stripUndefined(o) {
+    const out = {};
+    Object.keys(o).forEach((k) => {
+        if (o[k] !== undefined)
+            out[k] = o[k];
+    });
+    return out;
+}
+//# sourceMappingURL=cameraGuidanceCopy.js.map

package/dist/camera/captureCountdown.d.ts

@@ -0,0 +1,52 @@
+/**
+ * captureCountdown — pure timing helpers for the recording-time countdown
+ * and auto-finalize (guidance item 5).
+ *
+ * The non-AR panorama hold-and-pan has a hard recording ceiling (`maxMs`).
+ * As the user pans, a blinking countdown shows the whole seconds remaining;
+ * when it hits 0 the host auto-finalizes (stops recording and stitches what
+ * was captured — the FINALIZE-on-zero decision is handled by `<Camera>`,
+ * not here).
+ *
+ * Both functions are pure (no React, no timers, no `Date.now()` baked in —
+ * the caller threads `now` from its own animation frame / interval) so the
+ * boundary behaviour is unit-testable in the node jest env.  Mirrors the
+ * pure-helper + `__tests__` pattern of `contentRotationDeg`.
+ *
+ * `maxMs <= 0` DISABLES the feature: `shouldAutoStop` never returns true
+ * (recording is unbounded) and the countdown is meant to be hidden by the
+ * caller.  `countdownSecondsFrom` still returns a clamped, non-negative
+ * number in that case (0) so a caller that renders it regardless won't show
+ * a negative value.
+ */
+/**
+ * Whole seconds remaining in the recording window, for the countdown UI.
+ *
+ *   - While recording (`recordingStartedAt` non-null):
+ *       `ceil((maxMs - elapsed) / 1000)`, where `elapsed = now - start`,
+ *       clamped to `[0, round(maxMs / 1000)]`.  `ceil` means the displayed
+ *       number ticks to N only once strictly fewer than N seconds remain
+ *       (e.g. at exactly 1 ms before the 1s boundary it still reads the
+ *       higher value), and it reaches 0 exactly at `elapsed === maxMs`.
+ *   - Before recording (`recordingStartedAt === null`): the full window,
+ *       `round(maxMs / 1000)` — the at-rest value shown before the user
+ *       starts the hold.
+ *   - `maxMs <= 0` (feature disabled): returns 0.
+ *
+ * The result is always a whole, non-negative number.
+ */
+export declare function countdownSecondsFrom(recordingStartedAt: number | null, now: number, maxMs: number): number;
+/**
+ * True when the host should auto-finalize the recording NOW.
+ *
+ * Fires only when ALL of:
+ *   1. recording (`recordingStartedAt` non-null),
+ *   2. the window is enabled (`maxMs > 0`), AND
+ *   3. elapsed (`now - start`) has reached or passed the ceiling
+ *      (`>= maxMs`).
+ *
+ * `maxMs <= 0` disables auto-stop entirely (unbounded recording), so this
+ * returns false regardless of how long the user has been recording.
+ */
+export declare function shouldAutoStop(recordingStartedAt: number | null, now: number, maxMs: number): boolean;
+//# sourceMappingURL=captureCountdown.d.ts.map

package/dist/camera/captureCountdown.js

@@ -0,0 +1,76 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * captureCountdown — pure timing helpers for the recording-time countdown
+ * and auto-finalize (guidance item 5).
+ *
+ * The non-AR panorama hold-and-pan has a hard recording ceiling (`maxMs`).
+ * As the user pans, a blinking countdown shows the whole seconds remaining;
+ * when it hits 0 the host auto-finalizes (stops recording and stitches what
+ * was captured — the FINALIZE-on-zero decision is handled by `<Camera>`,
+ * not here).
+ *
+ * Both functions are pure (no React, no timers, no `Date.now()` baked in —
+ * the caller threads `now` from its own animation frame / interval) so the
+ * boundary behaviour is unit-testable in the node jest env.  Mirrors the
+ * pure-helper + `__tests__` pattern of `contentRotationDeg`.
+ *
+ * `maxMs <= 0` DISABLES the feature: `shouldAutoStop` never returns true
+ * (recording is unbounded) and the countdown is meant to be hidden by the
+ * caller.  `countdownSecondsFrom` still returns a clamped, non-negative
+ * number in that case (0) so a caller that renders it regardless won't show
+ * a negative value.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countdownSecondsFrom = countdownSecondsFrom;
+exports.shouldAutoStop = shouldAutoStop;
+/**
+ * Whole seconds remaining in the recording window, for the countdown UI.
+ *
+ *   - While recording (`recordingStartedAt` non-null):
+ *       `ceil((maxMs - elapsed) / 1000)`, where `elapsed = now - start`,
+ *       clamped to `[0, round(maxMs / 1000)]`.  `ceil` means the displayed
+ *       number ticks to N only once strictly fewer than N seconds remain
+ *       (e.g. at exactly 1 ms before the 1s boundary it still reads the
+ *       higher value), and it reaches 0 exactly at `elapsed === maxMs`.
+ *   - Before recording (`recordingStartedAt === null`): the full window,
+ *       `round(maxMs / 1000)` — the at-rest value shown before the user
+ *       starts the hold.
+ *   - `maxMs <= 0` (feature disabled): returns 0.
+ *
+ * The result is always a whole, non-negative number.
+ */
+function countdownSecondsFrom(recordingStartedAt, now, maxMs) {
+    if (maxMs <= 0)
+        return 0;
+    const maxSeconds = Math.round(maxMs / 1000);
+    // Not recording yet — show the full window at rest.
+    if (recordingStartedAt === null)
+        return maxSeconds;
+    const elapsed = now - recordingStartedAt;
+    const remainingSeconds = Math.ceil((maxMs - elapsed) / 1000);
+    // Clamp into [0, maxSeconds]: guards a clock that ran past the ceiling
+    // (negative remaining → 0) and a `now` before the start (`elapsed < 0`,
+    // remaining > maxSeconds → maxSeconds).
+    return Math.min(maxSeconds, Math.max(0, remainingSeconds));
+}
+/**
+ * True when the host should auto-finalize the recording NOW.
+ *
+ * Fires only when ALL of:
+ *   1. recording (`recordingStartedAt` non-null),
+ *   2. the window is enabled (`maxMs > 0`), AND
+ *   3. elapsed (`now - start`) has reached or passed the ceiling
+ *      (`>= maxMs`).
+ *
+ * `maxMs <= 0` disables auto-stop entirely (unbounded recording), so this
+ * returns false regardless of how long the user has been recording.
+ */
+function shouldAutoStop(recordingStartedAt, now, maxMs) {
+    if (recordingStartedAt === null)
+        return false;
+    if (maxMs <= 0)
+        return false;
+    return now - recordingStartedAt >= maxMs;
+}
+//# sourceMappingURL=captureCountdown.js.map

package/dist/camera/captureWarnings.d.ts

@@ -0,0 +1,90 @@
+/**
+ * captureWarnings — non-fatal quality / behaviour signals attached to a
+ * SUCCESSFUL capture result.  A stitch that *failed* surfaces a
+ * `CameraError` (via the `ok:false` result + `onError`); these warnings
+ * cover the "it succeeded but the host/user should know something" cases:
+ *
+ *   • LOW_FRAME_UTILIZATION — fewer than `threshold` (default 70 %) of the
+ *     captured frames survived the confidence filter, so the panorama may
+ *     be patchy / shorter than intended.
+ *   • LATERAL_DRIFT_FINALIZE — the capture was auto-finalized early because
+ *     the phone drifted sideways (item 6); only the pre-drift portion was
+ *     stitched.
+ *   • HIGH_PAN_SPEED — the pan exceeded the recommended pace at some point
+ *     during the capture (the live "too fast" cue fired), so motion blur /
+ *     thin overlap may have hurt the result.
+ *
+ * `<Camera>` builds these at finalize and threads them into BOTH the
+ * `onCapture` result payload (so any host — not just the example app —
+ * learns of degraded output programmatically) AND the crop editor's banner
+ * (so the user sees it before accepting the crop).
+ *
+ * Pure + dependency-free so it's unit-testable in isolation (the lib's jest
+ * config is pure-TS and can't mount `<Camera>`), mirroring
+ * `classifyStitchError` / `buildPanoramaInitialSettings`.
+ */
+/** Stable codes a host can branch on (in addition to the message). */
+export type CaptureWarningCode = 'LOW_FRAME_UTILIZATION' | 'LATERAL_DRIFT_FINALIZE' | 'HIGH_PAN_SPEED';
+export interface CaptureWarning {
+    /** Stable, host-switchable code. */
+    code: CaptureWarningCode;
+    /** Plain-language default message (shown in the crop banner). */
+    message: string;
+    /** Frames the engine tried to use (LOW_FRAME_UTILIZATION only). */
+    framesRequested?: number;
+    /** Frames that survived the confidence filter (LOW_FRAME_UTILIZATION). */
+    framesIncluded?: number;
+    /** included / requested in [0, 1] (LOW_FRAME_UTILIZATION only). */
+    utilization?: number;
+}
+/**
+ * Default trip point for LOW_FRAME_UTILIZATION: warn when fewer than 70 %
+ * of captured frames survived.  Matches the threshold the user specified.
+ */
+export declare const LOW_FRAME_UTILIZATION_THRESHOLD = 0.7;
+/**
+ * The overridable message strings for the three capture warnings.  This is
+ * the SINGLE SOURCE OF TRUTH for the default English warning copy — the
+ * `GuidanceCopy` surface re-uses these defaults (see `cameraGuidanceCopy`),
+ * so a host that localises via the `guidanceCopy` `<Camera>` prop re-words
+ * these too.
+ *
+ * `lowFrameUtilization` is a TEMPLATE: the placeholders `{included}`,
+ * `{requested}` and `{percent}` are substituted at build time with the
+ * actual frame counts.  A translation must keep the placeholders (any it
+ * omits is simply not interpolated; an unknown placeholder is left as-is).
+ */
+export interface CaptureWarningCopy {
+    /** LOW_FRAME_UTILIZATION — template; `{included}`/`{requested}`/`{percent}`. */
+    lowFrameUtilization: string;
+    /** LATERAL_DRIFT_FINALIZE. */
+    lateralDriftFinalize: string;
+    /** HIGH_PAN_SPEED. */
+    highPanSpeed: string;
+}
+export declare const DEFAULT_CAPTURE_WARNING_COPY: CaptureWarningCopy;
+export interface BuildCaptureWarningsInput {
+    /** `framesRequested` from the native finalize result. */
+    framesRequested?: number;
+    /** `framesIncluded` from the native finalize result. */
+    framesIncluded?: number;
+    /** True when this finalize was triggered by lateral-drift auto-stop. */
+    lateralFinalize?: boolean;
+    /** True when the pan exceeded the recommended pace during the capture. */
+    highPanSpeed?: boolean;
+    /** Override the LOW_FRAME_UTILIZATION trip point (fraction in (0, 1]). */
+    lowFrameUtilizationThreshold?: number;
+    /**
+     * Localised / re-worded warning messages.  Missing keys fall back to
+     * {@link DEFAULT_CAPTURE_WARNING_COPY}.  `<Camera>` threads the resolved
+     * `guidanceCopy` here so the crop-banner warnings honour the host's i18n.
+     */
+    copy?: Partial<CaptureWarningCopy>;
+}
+/**
+ * Build the warning list for a successful capture.  Order is by cause →
+ * symptom: a lateral-drift stop (the reason a capture is short) is listed
+ * before the low-utilization symptom it usually produces.
+ */
+export declare function buildCaptureWarnings(input: BuildCaptureWarningsInput): CaptureWarning[];
+//# sourceMappingURL=captureWarnings.d.ts.map

package/dist/camera/captureWarnings.js

@@ -0,0 +1,108 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * captureWarnings — non-fatal quality / behaviour signals attached to a
+ * SUCCESSFUL capture result.  A stitch that *failed* surfaces a
+ * `CameraError` (via the `ok:false` result + `onError`); these warnings
+ * cover the "it succeeded but the host/user should know something" cases:
+ *
+ *   • LOW_FRAME_UTILIZATION — fewer than `threshold` (default 70 %) of the
+ *     captured frames survived the confidence filter, so the panorama may
+ *     be patchy / shorter than intended.
+ *   • LATERAL_DRIFT_FINALIZE — the capture was auto-finalized early because
+ *     the phone drifted sideways (item 6); only the pre-drift portion was
+ *     stitched.
+ *   • HIGH_PAN_SPEED — the pan exceeded the recommended pace at some point
+ *     during the capture (the live "too fast" cue fired), so motion blur /
+ *     thin overlap may have hurt the result.
+ *
+ * `<Camera>` builds these at finalize and threads them into BOTH the
+ * `onCapture` result payload (so any host — not just the example app —
+ * learns of degraded output programmatically) AND the crop editor's banner
+ * (so the user sees it before accepting the crop).
+ *
+ * Pure + dependency-free so it's unit-testable in isolation (the lib's jest
+ * config is pure-TS and can't mount `<Camera>`), mirroring
+ * `classifyStitchError` / `buildPanoramaInitialSettings`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CAPTURE_WARNING_COPY = exports.LOW_FRAME_UTILIZATION_THRESHOLD = void 0;
+exports.buildCaptureWarnings = buildCaptureWarnings;
+/**
+ * Default trip point for LOW_FRAME_UTILIZATION: warn when fewer than 70 %
+ * of captured frames survived.  Matches the threshold the user specified.
+ */
+exports.LOW_FRAME_UTILIZATION_THRESHOLD = 0.7;
+exports.DEFAULT_CAPTURE_WARNING_COPY = {
+    lowFrameUtilization: 'Only {included} of {requested} captured frames ({percent}%) could be '
+        + 'used — the panorama may be incomplete. Pan more slowly and steadily '
+        + 'next time.',
+    lateralDriftFinalize: 'Capture stopped early because the phone drifted sideways — only the '
+        + 'part captured before the drift was stitched.',
+    highPanSpeed: 'The capture was taken faster than the recommended pace — the result '
+        + 'may not be the best. Pan more slowly next time.',
+};
+/**
+ * Substitute `{name}` placeholders in a template with `vars[name]`.  An
+ * unknown placeholder is left verbatim (so a malformed translation degrades
+ * to showing `{percent}` rather than throwing).
+ */
+function fillTemplate(tpl, vars) {
+    return tpl.replace(/\{(\w+)\}/g, (m, k) => k in vars ? String(vars[k]) : m);
+}
+/**
+ * Build the warning list for a successful capture.  Order is by cause →
+ * symptom: a lateral-drift stop (the reason a capture is short) is listed
+ * before the low-utilization symptom it usually produces.
+ */
+function buildCaptureWarnings(input) {
+    const { framesRequested, framesIncluded, lateralFinalize = false, highPanSpeed = false, lowFrameUtilizationThreshold = exports.LOW_FRAME_UTILIZATION_THRESHOLD, } = input;
+    const copy = {
+        ...exports.DEFAULT_CAPTURE_WARNING_COPY,
+        ...stripUndefinedCopy(input.copy),
+    };
+    const warnings = [];
+    if (lateralFinalize) {
+        warnings.push({
+            code: 'LATERAL_DRIFT_FINALIZE',
+            message: copy.lateralDriftFinalize,
+        });
+    }
+    if (highPanSpeed) {
+        warnings.push({
+            code: 'HIGH_PAN_SPEED',
+            message: copy.highPanSpeed,
+        });
+    }
+    if (typeof framesRequested === 'number'
+        && typeof framesIncluded === 'number'
+        && framesRequested > 0
+        && framesIncluded >= 0
+        && framesIncluded < framesRequested * lowFrameUtilizationThreshold) {
+        const utilization = framesIncluded / framesRequested;
+        warnings.push({
+            code: 'LOW_FRAME_UTILIZATION',
+            message: fillTemplate(copy.lowFrameUtilization, {
+                included: framesIncluded,
+                requested: framesRequested,
+                percent: Math.round(utilization * 100),
+            }),
+            framesRequested,
+            framesIncluded,
+            utilization,
+        });
+    }
+    return warnings;
+}
+/** Drop `undefined` values so a partial override never clobbers a default. */
+function stripUndefinedCopy(o) {
+    if (!o)
+        return {};
+    const out = {};
+    Object.keys(o).forEach((k) => {
+        if (o[k] !== undefined)
+            out[k] = o[k];
+    });
+    return out;
+}
+//# sourceMappingURL=captureWarnings.js.map

package/dist/camera/classifyStitchError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * classifyStitchError — map a raw native stitch-failure message to a
+ * `CameraErrorCode`.
+ *
+ * This is the load-bearing C++↔JS contract: the native pipeline reports
+ * failures only as exception strings (see cpp/stitcher.cpp — the warp /
+ * cumulative-canvas guards throw "warpRoi too large … degenerate camera
+ * params", cv::Stitcher reports "need more images", etc.), and this
+ * function is the single place that turns those strings into the typed
+ * codes `<Camera onError>` surfaces.  The code then drives the friendly
+ * copy in {@link userFacingStitchError} (cameraErrorMessages.ts) — e.g.
+ * STITCH_CAMERA_PARAMS_FAIL → "Please pan more slowly".
+ *
+ * Extracted from the inline chain in Camera.tsx so the contract is
+ * unit-testable against the actual native strings (the lib's jest config
+ * is pure-TS and can't mount <Camera>).
+ *
+ * Ordering matters — the branches are checked top-to-bottom and the first
+ * match wins:
+ *   1. need-more-images (insufficient overlap) — most specific.
+ *   2. homography estimation.
+ *   3. degenerate camera params / warp-canvas guard (the divergent-warp
+ *      OOM path, now converted to a clean throw by the canvas guard).
+ *   4. low-quality / disjoint output (the post-stitch validator, v0.16).
+ *   5. out-of-memory (incl. the pre-stitch memory abort).
+ *   6. fallback — an unclassified finalize failure.
+ */
+import type { CameraErrorCode } from './Camera';
+export declare function classifyStitchError(message: string): CameraErrorCode;
+//# sourceMappingURL=classifyStitchError.d.ts.map