@ai-matrx/capture 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -84,3 +84,68 @@ Deliberately not copied from the app this borrows its shape from: fixed duration
 ## 0.4.3 — 2026-08-30
 
 - Filmstrip video tiles paint their first frame on iOS (`#t=0.01` media fragment) — a `preload="metadata"` tile rendered black.
+
+## 0.5.0 — 2026-08-30
+
+**The C22/C23 retrofit: the hard parts move INTO the package** (all-inclusive-retrofit capture row). matrx-frontend's host adapter carried 415 lines of camera orchestration the package's default engine lacked, plus a 206-line cloud-library sheet. Absorbed:
+
+- **Production default engine** (`useDefaultCaptureEngine`, rewritten):
+  permission pre-check (known-denied → `blocked` without hammering gUM);
+  the COMBINED camera+mic prompt (one browser prompt for both permissions,
+  audio banked in the warm-mic manager, combined denial retried ONCE
+  video-only so a mic denial never takes the camera down); REAL device flip
+  (cycles `videoinput` deviceIds, hidden + guarded while recording); camera
+  track-health with one bounded reacquire on OS interruption; monotonic
+  recording clock; one-capture-at-a-time shutter guard; 120 ms `flash` flag;
+  loud shutter failures via the `onError` sink; mic discipline on recording
+  (warm acquire → clone → stop only clones → release exactly once). Returns
+  `DefaultCaptureEngine` (engine + `flash` + `capturePhotoWith`).
+- **`src/engine/warm-mic.ts`** — the warm microphone manager, ported VERBATIM
+  from the proven matrx-frontend `micStream` (short keepalive, refcount,
+  coalesced in-flight, pagehide backstop, `adoptWarmAudioStream` banking) with
+  ALL FOUR iOS-Safari recovery branches: `ended` / `muted` / `unmuted` /
+  `permission-revoked` — each reported loudly on the interruption channel.
+  State on a `globalThis` `Symbol.for` slot (dual ESM/CJS graph safe).
+- **`src/engine/permissions.ts`** — `queryCameraPermission` / `queryMicPermission`
+  pre-checks, `shouldCombineMicPrompt`, and `classifyCameraBlockReason` (the
+  ONE NotAllowedError/SecurityError branch — hosts import it instead of
+  re-implementing it).
+- **`src/engine/crop.ts`** — `cropBlobToAspect` (the ONE full-sensor
+  center-crop) + `nextCameraDevice` (the shared flip-cycling algorithm).
+- **`CloudLibrarySheet`** — the recents-thumb destination absorbed as a
+  package component over injected data (`CaptureCloudLibraryItem[]`,
+  host-supplied thumbnail nodes, `onOpenItem` navigation, optional v3
+  in-library Upload door). Chrome identical to the host original; two new
+  C19 inlined glyphs (upload, image-off).
+- **Laws amended DELIBERATELY**: law 2's header records why the pre-C23
+  "no getUserMedia" wording changed (the ban outside `src/engine/` survives);
+  new law 6 is the forcing function — the warm-mic manager must carry all
+  four recovery branches and the engine must pre-check + combine prompts +
+  use the warm-mic manager, or the build fails.
+
+The injected-engine seam is unchanged: hosts with their own cross-feature
+media runtime (matrx-frontend's lease manager) still inject a
+`CaptureCameraEngine`; their adapters now import the package's crop /
+classification / flip helpers instead of carrying twins.
+
+### Consumer action (C28)
+
+- **Host engine adapters**: delete local copies of the aspect crop, the
+  NotAllowedError/SecurityError classification, and the flip-cycling
+  algorithm — import `cropBlobToAspect`, `classifyCameraBlockReason`,
+  `nextCameraDevice`, `PHOTO_JPEG_QUALITY` from `@ai-matrx/capture/react`.
+  Any remaining adapter line must be lease-runtime identity wiring with a
+  C22 justification. (matrx-frontend: done same-session.)
+- **Host cloud-library sheets**: replace bespoke tiled-gallery chrome with
+  the package `CloudLibrarySheet` — the host supplies
+  `items: CaptureCloudLibraryItem[]` (own thumbnail nodes), `loading`,
+  `onOpenItem`, optional `onUpload` (v3 in-library door). (matrx-frontend:
+  host copy collapsed to a data wrapper, consumer props unchanged.)
+- **Runtime-less hosts**: adopt the rewritten `useDefaultCaptureEngine`
+  (now returns `DefaultCaptureEngine` = engine + `flash` +
+  `capturePhotoWith`; new options `mode`, `fileNamePrefix`, `onError`).
+  No breaking signature change — existing options still work.
+- **`DefaultEngineOptions` behavior delta**: video capture callbacks now
+  fire with warm-mic-managed audio and the combined permission prompt;
+  hosts that suppressed their own double-prompt workarounds can delete
+  them.

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @ai-matrx/capture — root entry: TYPES ONLY, RSC-safe (no \"use client\").\n *\n * THE CLOUD LAW: cloud integration is WHAT this system does, not an option.\n * `CameraCapture` (from `@ai-matrx/capture/react`) requires a\n * `CaptureCloudPort`; the host injects HOW it is fulfilled, never WHETHER.\n */\n\nexport type {\n  CaptureAspect,\n  CaptureCameraEngine,\n  CaptureCameraMode,\n  CaptureCameraSlots,\n  CaptureCameraV3Slots,\n  CaptureCloudPort,\n  CaptureOptionTile,\n  CaptureRailAction,\n  CaptureTimerSetting,\n} from \"./types\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @ai-matrx/capture — root entry: TYPES ONLY, RSC-safe (no \"use client\").\n *\n * THE CLOUD LAW: cloud integration is WHAT this system does, not an option.\n * `CameraCapture` (from `@ai-matrx/capture/react`) requires a\n * `CaptureCloudPort`; the host injects HOW it is fulfilled, never WHETHER.\n */\n\nexport type {\n  CaptureAspect,\n  CaptureCameraEngine,\n  CaptureCameraMode,\n  CaptureCameraSlots,\n  CaptureCameraV3Slots,\n  CaptureCloudLibraryItem,\n  CaptureCloudPort,\n  CaptureOptionTile,\n  CaptureRailAction,\n  CaptureTimerSetting,\n} from \"./types\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/index.d.cts

@@ -39,6 +39,14 @@ interface CaptureCloudPort {
     /** Opens the host's cloud media library (tiled gallery). */
     onOpenLibrary: () => void;
 }
+/** One media item in the cloud library sheet. The host supplies the
+ *  thumbnail NODE (its own resolver/auth) — the package never fetches. */
+interface CaptureCloudLibraryItem {
+    id: string;
+    fileName: string;
+    kind: "image" | "video";
+    thumbnail: React.ReactNode;
+}
 /**
  * The engine port — everything the chrome needs from the host's camera
  * runtime. The host owns lease acquisition/release, capture and recording;
@@ -163,4 +171,4 @@ interface CaptureCameraV3Slots {
     overlays?: React.ReactNode;
 }
 
-export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCameraV3Slots, CaptureCloudPort, CaptureOptionTile, CaptureRailAction, CaptureTimerSetting };
+export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCameraV3Slots, CaptureCloudLibraryItem, CaptureCloudPort, CaptureOptionTile, CaptureRailAction, CaptureTimerSetting };

package/dist/index.d.ts

@@ -39,6 +39,14 @@ interface CaptureCloudPort {
     /** Opens the host's cloud media library (tiled gallery). */
     onOpenLibrary: () => void;
 }
+/** One media item in the cloud library sheet. The host supplies the
+ *  thumbnail NODE (its own resolver/auth) — the package never fetches. */
+interface CaptureCloudLibraryItem {
+    id: string;
+    fileName: string;
+    kind: "image" | "video";
+    thumbnail: React.ReactNode;
+}
 /**
  * The engine port — everything the chrome needs from the host's camera
  * runtime. The host owns lease acquisition/release, capture and recording;
@@ -163,4 +171,4 @@ interface CaptureCameraV3Slots {
     overlays?: React.ReactNode;
 }
 
-export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCameraV3Slots, CaptureCloudPort, CaptureOptionTile, CaptureRailAction, CaptureTimerSetting };
+export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCameraV3Slots, CaptureCloudLibraryItem, CaptureCloudPort, CaptureOptionTile, CaptureRailAction, CaptureTimerSetting };