@ai-matrx/capture 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog — @ai-matrx/capture
 
+## 0.5.5 — 2026-09-01
+
+- Added the package-owned `finalizeCapturedVideo` terminal contract for default engines and host adapters. Emitted/final Blob MIME outranks the recorder-request MIME, filename extension is derived from that same authority, and delivered duration is a positive integer.
+- The default engine now uses the shared finalizer, preventing a WebM payload from being mislabeled as MP4 when `MediaRecorder.mimeType` disagrees with emitted chunks.
+
+## 0.5.4 — 2026-09-01
+
+- Persisted-media editing now has an explicit fresh-byte port (`resolveEditBlob`). The package creates and owns an editor-private object URL instead of reusing a viewer URL that the host byte cache may evict and revoke while the decoded viewer frame remains visible.
+- Both camera chromes revoke the editor-private URL on every close/save/unmount path and surface a visible retry remedy when byte preparation fails. Exact fail-first coverage reproduces a stale viewer URL and proves the editor consumes fresh bytes.
+
 ## 0.5.3 — 2026-09-01
 
 - `ImageEditSheet` now keeps Save, crop presets, rotate, and flip unavailable while a newly baked bitmap is decoding, then enables them from the image's real `load` event. A transformed image can no longer hit the zero-dimension silent-return race and leave the editor stuck with no persistence or error.

package/README.md

@@ -76,12 +76,16 @@ instead of the default one; persisted items provide `resolve()` instead of
 
 ## What's NOT inside (by design)
 
-- **No getUserMedia** — the host injects a `CaptureCameraEngine` (stream, capture/record callbacks). In AI Matrx that host is the `features/media-capture` runtime (lease manager, recorder, chunk journal); those move here in a later major once extracted.
+- **No forced host runtime.** The package includes `useDefaultCaptureEngine` (its sole `getUserMedia` implementation under `src/engine/`) for runtime-less hosts. Apps with an existing cross-feature camera runtime inject a `CaptureCameraEngine`; AI Matrx does this for lease management, recorder journaling, and diagnostics.
 - **No network, no storage** — enforced by `src/laws.test.ts`.
 - Persisted-media rendering (thumbnails, lightboxes, durable refs) — that's `@ai-matrx/media`.
 - Audio-only recording UX — `@ai-matrx/browser-audio`.
 - QR decoding — `@ai-matrx/kit/qr`.
 
+Both the default engine and injected host adapters finalize recordings through
+`finalizeCapturedVideo`: emitted/final Blob MIME is authoritative, the filename
+extension matches it, and delivered duration is a positive integer.
+
 ## Usage sketch
 
 ```tsx

package/dist/react.cjs

@@ -44,6 +44,7 @@ __export(react_exports, {
   buildWarmMicConstraints: () => buildWarmMicConstraints,
   classifyCameraBlockReason: () => classifyCameraBlockReason,
   cropBlobToAspect: () => cropBlobToAspect,
+  finalizeCapturedVideo: () => finalizeCapturedVideo,
   getMediaUrl: () => getMediaUrl,
   getWarmMicState: () => getWarmMicState,
   hardStopWarmMic: () => hardStopWarmMic,
@@ -727,6 +728,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] = (0, import_react2.useState)(0);
   const key = item?.key ?? null;
@@ -1604,6 +1615,10 @@ function CameraCapture({
   const [optionsOpen, setOptionsOpen] = (0, import_react5.useState)(false);
   const [viewerKey, setViewerKey] = (0, import_react5.useState)(null);
   const [editTarget, setEditTarget] = (0, import_react5.useState)(null);
+  const [editPreparing, setEditPreparing] = (0, import_react5.useState)(false);
+  const [editPreparationError, setEditPreparationError] = (0, import_react5.useState)(
+    null
+  );
   const [gridOn, setGridOn] = (0, import_react5.useState)(false);
   const [timerSetting, setTimerSetting] = (0, import_react5.useState)(0);
   const [aspect, setAspect] = (0, import_react5.useState)("full");
@@ -1628,6 +1643,12 @@ function CameraCapture({
   (0, import_react5.useEffect)(() => {
     onReviewOpenChange?.(reviewOpen);
   }, [reviewOpen, onReviewOpenChange]);
+  (0, import_react5.useEffect)(
+    () => () => {
+      if (editTarget?.revoke) URL.revokeObjectURL(editTarget.url);
+    },
+    [editTarget]
+  );
   const clearCountdown = (0, import_react5.useCallback)(() => {
     if (countdownRef.current) clearInterval(countdownRef.current);
     countdownRef.current = null;
@@ -1941,8 +1962,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
       }
     ),
@@ -1963,6 +1992,14 @@ function CameraCapture({
         }
       }
     ),
+    editPreparationError && /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
+      "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
   ] });
 }
@@ -2261,7 +2298,9 @@ function CameraCaptureV3({
   slots = {}
 }) {
   const [viewerKey, setViewerKey] = (0, import_react8.useState)(null);
-  const [editTarget, setEditTarget] = (0, import_react8.useState)(
+  const [editTarget, setEditTarget] = (0, import_react8.useState)(null);
+  const [editPreparing, setEditPreparing] = (0, import_react8.useState)(false);
+  const [editPreparationError, setEditPreparationError] = (0, import_react8.useState)(
     null
   );
   const [gridOn, setGridOn] = (0, import_react8.useState)(false);
@@ -2275,6 +2314,12 @@ function CameraCaptureV3({
   (0, import_react8.useEffect)(() => {
     onReviewOpenChange?.(reviewOpen);
   }, [reviewOpen, onReviewOpenChange]);
+  (0, import_react8.useEffect)(
+    () => () => {
+      if (editTarget?.revoke) URL.revokeObjectURL(editTarget.url);
+    },
+    [editTarget]
+  );
   const clearCountdown = (0, import_react8.useCallback)(() => {
     if (countdownRef.current) clearInterval(countdownRef.current);
     countdownRef.current = null;
@@ -2493,8 +2538,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
       }
     ),
@@ -2515,6 +2568,14 @@ function CameraCaptureV3({
         }
       }
     ),
+    editPreparationError && /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
+      "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
   ] });
 }
@@ -3028,6 +3089,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"',
@@ -3282,16 +3380,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);