@ai-matrx/capture 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

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,
@@ -3088,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"',
@@ -3342,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);