@ai-matrx/capture 0.5.3 → 0.5.5

package/dist/react.d.cts

@@ -231,6 +231,9 @@ interface CaptureMediaItem {
     /** Async URL resolution for persisted items. Called at most once per key
      *  while cached; concurrent callers share the in-flight promise. */
     resolve?: () => Promise<ResolvedMedia>;
+    /** Fresh bytes for pixel editing. Persisted hosts should provide this
+     *  instead of asking the editor to borrow a cache-owned viewer URL. */
+    resolveEditBlob?: () => Promise<Blob>;
     /** Upload/processing state — the filmstrip renders it honestly. */
     status?: "ready" | "uploading" | "error";
     /** Accent ring on the filmstrip tile (e.g. a delineator frame). */
@@ -773,6 +776,35 @@ declare function nextCameraDevice<T extends {
     deviceId: string;
 }>(cameras: readonly T[], currentDeviceId: string | null | undefined): T | null;
 
+/**
+ * The one terminal video contract shared by the package-owned MediaRecorder
+ * engine and host adapters. Emitted bytes are stronger MIME evidence than a
+ * requested/recorder format, and a delivered recording always carries a
+ * positive integer duration.
+ */
+interface FinalizeCapturedVideoOptions {
+    parts: readonly BlobPart[];
+    /** MIME observed on emitted/final Blob data — the strongest authority. */
+    emittedMime?: string | null | undefined;
+    /** MediaRecorder-reported MIME — fallback when emitted bytes have none. */
+    recorderMime?: string | null | undefined;
+    durationMs: number;
+    fileNamePrefix: string;
+    /** Injectable filename clock for deterministic tests. */
+    timestampMs?: number;
+}
+interface CapturedVideoResult {
+    file: File;
+    mime: string;
+    durationMs: number;
+}
+/**
+ * Finalize recording bytes without letting requested MIME, filename, and
+ * duration drift apart. Unknown/non-video formats fail loudly rather than
+ * producing a mislabeled upload.
+ */
+declare function finalizeCapturedVideo(options: FinalizeCapturedVideoOptions): CapturedVideoResult;
+
 /**
  * src/engine/permissions.ts — permission pre-checks + error classification
  * for the default engine (and for hosts, so they stop re-implementing the
@@ -983,4 +1015,4 @@ interface CloudLibrarySheetProps {
 }
 declare function CloudLibrarySheet({ open, onClose, items, loading, busy, onOpenItem, onUpload, title, }: CloudLibrarySheetProps): React__default.JSX.Element | null;
 
-export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };
+export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, type CapturedVideoResult, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, type FinalizeCapturedVideoOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, finalizeCapturedVideo, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };

package/dist/react.d.ts

@@ -231,6 +231,9 @@ interface CaptureMediaItem {
     /** Async URL resolution for persisted items. Called at most once per key
      *  while cached; concurrent callers share the in-flight promise. */
     resolve?: () => Promise<ResolvedMedia>;
+    /** Fresh bytes for pixel editing. Persisted hosts should provide this
+     *  instead of asking the editor to borrow a cache-owned viewer URL. */
+    resolveEditBlob?: () => Promise<Blob>;
     /** Upload/processing state — the filmstrip renders it honestly. */
     status?: "ready" | "uploading" | "error";
     /** Accent ring on the filmstrip tile (e.g. a delineator frame). */
@@ -773,6 +776,35 @@ declare function nextCameraDevice<T extends {
     deviceId: string;
 }>(cameras: readonly T[], currentDeviceId: string | null | undefined): T | null;
 
+/**
+ * The one terminal video contract shared by the package-owned MediaRecorder
+ * engine and host adapters. Emitted bytes are stronger MIME evidence than a
+ * requested/recorder format, and a delivered recording always carries a
+ * positive integer duration.
+ */
+interface FinalizeCapturedVideoOptions {
+    parts: readonly BlobPart[];
+    /** MIME observed on emitted/final Blob data — the strongest authority. */
+    emittedMime?: string | null | undefined;
+    /** MediaRecorder-reported MIME — fallback when emitted bytes have none. */
+    recorderMime?: string | null | undefined;
+    durationMs: number;
+    fileNamePrefix: string;
+    /** Injectable filename clock for deterministic tests. */
+    timestampMs?: number;
+}
+interface CapturedVideoResult {
+    file: File;
+    mime: string;
+    durationMs: number;
+}
+/**
+ * Finalize recording bytes without letting requested MIME, filename, and
+ * duration drift apart. Unknown/non-video formats fail loudly rather than
+ * producing a mislabeled upload.
+ */
+declare function finalizeCapturedVideo(options: FinalizeCapturedVideoOptions): CapturedVideoResult;
+
 /**
  * src/engine/permissions.ts — permission pre-checks + error classification
  * for the default engine (and for hosts, so they stop re-implementing the
@@ -983,4 +1015,4 @@ interface CloudLibrarySheetProps {
 }
 declare function CloudLibrarySheet({ open, onClose, items, loading, busy, onOpenItem, onUpload, title, }: CloudLibrarySheetProps): React__default.JSX.Element | null;
 
-export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };
+export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, type CapturedVideoResult, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, type FinalizeCapturedVideoOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, finalizeCapturedVideo, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };

package/dist/react.js

@@ -661,6 +661,16 @@ function invalidateMedia(key) {
   if (entry?.revoke && entry.url) URL.revokeObjectURL(entry.url);
   notify(key);
 }
+async function prepareMediaForEdit(item) {
+  if (item.resolveEditBlob) {
+    const blob = await item.resolveEditBlob();
+    if (blob.size === 0) throw new Error("media snapshot was empty");
+    return { url: URL.createObjectURL(blob), revoke: true };
+  }
+  const url = item.src ?? getMediaUrl(item);
+  if (!url) throw new Error("media item has no editable source");
+  return { url, revoke: false };
+}
 function useMediaUrl(item) {
   const [, bump] = useState2(0);
   const key = item?.key ?? null;
@@ -1549,6 +1559,10 @@ function CameraCapture({
   const [optionsOpen, setOptionsOpen] = useState5(false);
   const [viewerKey, setViewerKey] = useState5(null);
   const [editTarget, setEditTarget] = useState5(null);
+  const [editPreparing, setEditPreparing] = useState5(false);
+  const [editPreparationError, setEditPreparationError] = useState5(
+    null
+  );
   const [gridOn, setGridOn] = useState5(false);
   const [timerSetting, setTimerSetting] = useState5(0);
   const [aspect, setAspect] = useState5("full");
@@ -1573,6 +1587,12 @@ function CameraCapture({
   useEffect5(() => {
     onReviewOpenChange?.(reviewOpen);
   }, [reviewOpen, onReviewOpenChange]);
+  useEffect5(
+    () => () => {
+      if (editTarget?.revoke) URL.revokeObjectURL(editTarget.url);
+    },
+    [editTarget]
+  );
   const clearCountdown = useCallback4(() => {
     if (countdownRef.current) clearInterval(countdownRef.current);
     countdownRef.current = null;
@@ -1886,8 +1906,16 @@ function CameraCapture({
           invalidateMedia(item.key);
         } : void 0,
         onEdit: media.onReplacePhoto ? (item) => {
-          const url = getMediaUrl(item);
-          if (url) setEditTarget({ key: item.key, url });
+          if (editPreparing) return;
+          setEditPreparing(true);
+          setEditPreparationError(null);
+          void prepareMediaForEdit(item).then(
+            (prepared) => setEditTarget({ key: item.key, ...prepared })
+          ).catch(
+            () => setEditPreparationError(
+              "This photo could not be prepared for editing. Try again."
+            )
+          ).finally(() => setEditPreparing(false));
         } : void 0
       }
     ),
@@ -1908,6 +1936,14 @@ function CameraCapture({
         }
       }
     ),
+    editPreparationError && /* @__PURE__ */ jsx12(
+      "p",
+      {
+        role: "alert",
+        className: "fixed inset-x-4 bottom-24 z-[70] rounded-xl bg-black/85 px-4 py-3 text-center text-sm text-[#FF6961]",
+        children: editPreparationError
+      }
+    ),
     slots.overlays
   ] });
 }
@@ -2206,7 +2242,9 @@ function CameraCaptureV3({
   slots = {}
 }) {
   const [viewerKey, setViewerKey] = useState8(null);
-  const [editTarget, setEditTarget] = useState8(
+  const [editTarget, setEditTarget] = useState8(null);
+  const [editPreparing, setEditPreparing] = useState8(false);
+  const [editPreparationError, setEditPreparationError] = useState8(
     null
   );
   const [gridOn, setGridOn] = useState8(false);
@@ -2220,6 +2258,12 @@ function CameraCaptureV3({
   useEffect7(() => {
     onReviewOpenChange?.(reviewOpen);
   }, [reviewOpen, onReviewOpenChange]);
+  useEffect7(
+    () => () => {
+      if (editTarget?.revoke) URL.revokeObjectURL(editTarget.url);
+    },
+    [editTarget]
+  );
   const clearCountdown = useCallback6(() => {
     if (countdownRef.current) clearInterval(countdownRef.current);
     countdownRef.current = null;
@@ -2438,8 +2482,16 @@ function CameraCaptureV3({
           invalidateMedia(item.key);
         } : void 0,
         onEdit: media.onReplacePhoto ? (item) => {
-          const url = getMediaUrl(item);
-          if (url) setEditTarget({ key: item.key, url });
+          if (editPreparing) return;
+          setEditPreparing(true);
+          setEditPreparationError(null);
+          void prepareMediaForEdit(item).then(
+            (prepared) => setEditTarget({ key: item.key, ...prepared })
+          ).catch(
+            () => setEditPreparationError(
+              "This photo could not be prepared for editing. Try again."
+            )
+          ).finally(() => setEditPreparing(false));
         } : void 0
       }
     ),
@@ -2460,6 +2512,14 @@ function CameraCaptureV3({
         }
       }
     ),
+    editPreparationError && /* @__PURE__ */ jsx15(
+      "p",
+      {
+        role: "alert",
+        className: "fixed inset-x-4 bottom-24 z-[70] rounded-xl bg-black/85 px-4 py-3 text-center text-sm text-[#FF6961]",
+        children: editPreparationError
+      }
+    ),
     slots.overlays
   ] });
 }
@@ -2973,6 +3033,43 @@ function warmMicDebug() {
   };
 }
 
+// src/engine/video-result.ts
+var VIDEO_EXTENSIONS = {
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+  "video/ogg": "ogv",
+  "video/quicktime": "mov"
+};
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    const normalized = value?.trim();
+    if (normalized) return normalized;
+  }
+  return "video/webm";
+}
+function finalizeCapturedVideo(options) {
+  if (!Number.isFinite(options.durationMs)) {
+    throw new Error("finalizeCapturedVideo requires a finite duration.");
+  }
+  const mime = firstNonEmpty(options.emittedMime, options.recorderMime);
+  const container = mime.split(";")[0]?.trim().toLowerCase() ?? "";
+  const extension = VIDEO_EXTENSIONS[container];
+  if (!extension) {
+    throw new Error(
+      `finalizeCapturedVideo requires a recognized video MIME; received "${mime}".`
+    );
+  }
+  const durationMs = Math.max(1, Math.round(options.durationMs));
+  const blob = new Blob([...options.parts], { type: mime });
+  const timestampMs = options.timestampMs ?? Date.now();
+  const file = new File(
+    [blob],
+    `${options.fileNamePrefix}-video-${timestampMs}.${extension}`,
+    { type: mime }
+  );
+  return { file, mime, durationMs };
+}
+
 // src/engine/useDefaultEngine.ts
 var RECORDING_MIME_LADDER = [
   'video/mp4;codecs="avc1.42E01E,mp4a.40.2"',
@@ -3227,16 +3324,15 @@ function useDefaultCaptureEngine(options) {
         if (entry.micHeld) releaseWarmMic();
         recorderRef.current = null;
         setRecording(false);
-        const durationMs = Math.round(performance.now() - entry.startedAt);
-        const type = recorder.mimeType || entry.chunks[0]?.type || "video/webm";
-        const blob = new Blob(entry.chunks, { type });
-        const ext = type.includes("mp4") ? "mp4" : "webm";
-        callbacksRef.current.onVideo(
-          new File([blob], `${fileNamePrefix}-video-${Date.now()}.${ext}`, {
-            type
-          }),
-          durationMs
-        );
+        const captured = finalizeCapturedVideo({
+          parts: entry.chunks,
+          // Emitted chunk MIME is stronger evidence than recorder.mimeType.
+          emittedMime: entry.chunks.find((chunk) => chunk.type)?.type,
+          recorderMime: recorder.mimeType,
+          durationMs: performance.now() - entry.startedAt,
+          fileNamePrefix
+        });
+        callbacksRef.current.onVideo(captured.file, captured.durationMs);
       };
       recorder.start(1e3);
       setRecordElapsedSeconds(0);
@@ -3439,6 +3535,7 @@ export {
   buildWarmMicConstraints,
   classifyCameraBlockReason,
   cropBlobToAspect,
+  finalizeCapturedVideo,
   getMediaUrl,
   getWarmMicState,
   hardStopWarmMic,