@ai-matrx/capture 0.4.2 → 0.5.0

package/dist/react.d.cts

@@ -40,6 +40,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;
@@ -709,17 +717,270 @@ interface TrackControls {
 declare function useTrackControls(stream: MediaStream | null): TrackControls;
 
 interface DefaultEngineOptions {
-    /** Receives every captured photo as a JPEG File. */
+    /** Receives every captured photo as a JPEG File (full sensor, aspect crop
+     *  already applied). */
     onPhoto: (file: File) => void;
     /** Receives the finished recording. */
     onVideo: (file: File, durationMs: number) => void;
     /** Receives files chosen through the Upload lane. */
     onFiles: (files: FileList) => void;
-    /** Record microphone audio with video (asks once, at record time). */
+    /** Record microphone audio with video. Default true. With audio on, the
+     *  engine folds the mic permission into the CAMERA's browser prompt (one
+     *  combined prompt) whenever a mic prompt would actually appear. */
     withAudio?: boolean;
+    /** The chrome's current mode. In "video" the engine warm-holds the mic so
+     *  iOS Safari prompts at most once per medium per session. Omitting it
+     *  skips the warm hold (the record path still acquires the mic). */
+    mode?: CaptureCameraMode;
     facingMode?: "environment" | "user";
     photoQuality?: number;
+    /** Filename prefix for captures (default "capture"). */
+    fileNamePrefix?: string;
+    /** Loud failure sink (a toast, a logger). Default: console.error. A tapped
+     *  shutter that produced nothing must say so — never a silent drop. */
+    onError?: (message: string, err: unknown) => void;
+}
+/** The engine plus the extras the default path owns (white shutter flash). */
+interface DefaultCaptureEngine extends CaptureCameraEngine {
+    /** White shutter-flash flag (120 ms), for the host's flash overlay. */
+    flash: boolean;
+    /** Take a photo with a non-default filename prefix (e.g. delineators). */
+    capturePhotoWith: (opts: {
+        fileNamePrefix: string;
+        aspect?: CaptureAspect;
+    }) => void;
+}
+declare function useDefaultCaptureEngine(options: DefaultEngineOptions): DefaultCaptureEngine;
+
+/**
+ * src/engine/crop.ts — the ONE aspect-crop implementation.
+ *
+ * Center-crops a captured JPEG to the requested output aspect. The crop is
+ * applied to the FULL sensor frame (honest pixels, not a preview grab) —
+ * §2 policy 6 of the chrome: the shutter always captures full-sensor and the
+ * selected aspect is a REAL crop of that frame. Ported from the matrx-frontend
+ * host adapter (C22 retrofit, 2026-08-30) so every host shares one geometry.
+ */
+
+declare const PHOTO_JPEG_QUALITY = 0.92;
+declare function cropBlobToAspect(blob: Blob, aspect: CaptureAspect, quality?: number): Promise<Blob>;
+/**
+ * Cycle to the next camera in a device list — the flip algorithm the host
+ * adapter and the default engine share. Returns null when there is nothing
+ * to flip to (fewer than two cameras).
+ */
+declare function nextCameraDevice<T extends {
+    deviceId: string;
+}>(cameras: readonly T[], currentDeviceId: string | null | undefined): T | null;
+
+/**
+ * src/engine/permissions.ts — permission pre-checks + error classification
+ * for the default engine (and for hosts, so they stop re-implementing the
+ * NotAllowedError branch — the C22 rule: quirk branches live HERE).
+ */
+type MediaPermissionState = "granted" | "denied" | "prompt" | "unknown";
+/**
+ * Pre-check the camera permission WITHOUT prompting. A known-"denied" state
+ * lets a surface render its how-to-re-enable explainer instead of hammering
+ * getUserMedia with calls that instantly reject (the proven matrx-frontend
+ * pre-check contract). "unknown" (Safari) means: just try — the gUM outcome
+ * is the truth there.
+ */
+declare function queryCameraPermission(): Promise<MediaPermissionState>;
+/** Same pre-check for the microphone — drives the combined-prompt decision. */
+declare function queryMicPermission(): Promise<MediaPermissionState>;
+/**
+ * Pure decision for the combined camera+mic prompt: only worth it when a mic
+ * prompt would actually appear ("prompt"/"unknown"). "granted" needs no
+ * prompt; "denied" would reject the WHOLE combined call and take the camera
+ * with it.
+ */
+declare function shouldCombineMicPrompt(micPermissionState: MediaPermissionState): boolean;
+/** True when a getUserMedia rejection means the USER/OS denied permission
+ *  (a missing device is not a denial). */
+declare function isMediaDenialError(err: unknown): boolean;
+/**
+ * Classify a camera-acquisition failure into the engine's `blocked` reason.
+ * The ONE place the NotAllowedError/SecurityError branch lives — hosts adapt
+ * their runtime errors through this instead of re-implementing it.
+ */
+declare function classifyCameraBlockReason(err: unknown): "permission-denied" | "not-supported";
+
+/**
+ * src/engine/warm-mic.ts — the package's warm microphone manager.
+ *
+ * Ported VERBATIM (2026-08-30, the C22/C23 retrofit) from matrx-frontend's
+ * proven `features/audio/micStream.ts` — the module that encodes the real
+ * iOS Safari device pain the default engine previously did not have:
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every recording surface used to call `navigator.mediaDevices.getUserMedia`
+ * itself and fully `track.stop()` the stream when it finished. On mobile
+ * (notably iOS Safari) that produces a permission/"in use" prompt on *every*
+ * single recording, because the previous grant is torn down before the next
+ * acquisition. Tapping record three times = three prompts.
+ *
+ * This manager keeps ONE stream warm and hands it to every caller. After the
+ * last holder releases it, the stream is kept alive for a SHORT keepalive
+ * window; if another recording starts within that window, the same live
+ * stream (and the same OS grant) is reused — no second prompt. Only after the
+ * window elapses with no holders is the stream actually stopped (mic light
+ * off), so we don't hold the mic open forever.
+ *
+ * KEEPALIVE IS DELIBERATELY SHORT (a few seconds). Minutes keep the browser's
+ * recording indicator lit long after the user stopped — alarming and abnormal
+ * ("why is my mic still on?"). A few seconds still coalesces a quick
+ * stop→re-record (the iOS re-prompt case) while clearing the mic light almost
+ * immediately once the user is actually done. On desktop, re-acquiring after
+ * release does NOT re-prompt (the origin's grant persists), so a short window
+ * costs nothing there.
+ *
+ * THE FOUR iOS-SAFARI RECOVERY BRANCHES (`MicInterruptionReason`), each of
+ * which used to be a silent audio drop:
+ *   1. `ended`              — the OS killed the track (lock screen, incoming
+ *                             call, app switch, device unplug). The warm grant
+ *                             is gone; the dead stream is dropped so the next
+ *                             acquire re-acquires (and WILL re-prompt).
+ *   2. `muted`              — transient interruption (iOS mutes during a
+ *                             call). The grant survives; no re-prompt.
+ *   3. `unmuted`            — the transient interruption ended.
+ *   4. `permission-revoked` — the user/OS pulled the permission; the warm
+ *                             stream is hard-stopped NOW.
+ * All four are reported loudly on the interruption channel so a recording
+ * surface can react instead of just dropping audio.
+ *
+ * Reference-counted: concurrent holders (an analyser tap + a recorder) are
+ * fine; the stream is only eligible for release when the count hits zero.
+ * Callers MUST NOT call `track.stop()` on the returned stream — call
+ * `releaseWarmMic()` instead.
+ *
+ * State lives on `globalThis` under a `Symbol.for` slot (the media-cache
+ * pattern) — a dual ESM/CJS module graph must still see ONE mic manager.
+ */
+type Listener = (state: MicStreamState) => void;
+type MicInterruptionReason = "ended" | "muted" | "unmuted" | "permission-revoked";
+type InterruptionListener = (reason: MicInterruptionReason) => void;
+type MicStreamState = "idle" | "acquiring" | "active" | "keepalive" | "error";
+/**
+ * Subscribe to mic interruptions (track end / mute / permission loss).
+ * Returns an unsubscribe fn. Surfaces are expected to make these LOUD — an
+ * interruption during a recording is a real event the user must see, not a
+ * silent drop.
+ */
+declare function subscribeWarmMicInterruption(listener: InterruptionListener): () => void;
+/**
+ * Mic-permission revocation → stop the warm stream NOW and emit a loud
+ * interruption. In matrx-frontend the ONE canonical permission watcher
+ * (audioDevices) calls this; the package, having no host device layer, wires
+ * its own minimal Permissions API watcher lazily (`watchMicPermission`) —
+ * best-effort only, since Safari's Permissions API may not answer for
+ * "microphone" (there, `ended` is the branch that fires instead).
+ */
+declare function notifyMicPermissionRevoked(): void;
+/**
+ * Set the preferred microphone. Applied as an `{ideal}` deviceId constraint
+ * on the NEXT acquire — it does NOT switch a live stream (call
+ * `hardStopWarmMic()` then re-acquire to switch mid-session). Pass null to
+ * fall back to the system default.
+ */
+declare function setPreferredMicDeviceId(id: string | null): void;
+/**
+ * The default audio constraints this manager acquires with — exported so the
+ * default engine's COMBINED `getUserMedia({video, audio})` prompt (one
+ * browser prompt for both permissions instead of camera-then-mic) requests
+ * the mic with exactly the same processing + preferred-device shape the
+ * singleton itself would use.
+ */
+declare function buildWarmMicConstraints(): MediaTrackConstraints;
+/**
+ * Adopt an audio stream acquired ELSEWHERE (the default engine's combined
+ * camera+mic prompt) as this manager's warm stream, so the grant that
+ * combined prompt just earned is banked exactly like one of our own: the
+ * next `acquireWarmMic()` inside the keepalive window reuses it with no
+ * second prompt. If a warm stream already exists (or one is being acquired),
+ * the incoming tracks are stopped immediately — never two live mic streams.
+ * With zero holders the adopted stream is parked in the keepalive window, so
+ * the mic light clears on the normal schedule.
+ */
+declare function adoptWarmAudioStream(stream: MediaStream): void;
+/**
+ * Acquire the shared warm mic stream, incrementing the holder count. The
+ * returned stream is shared — DO NOT stop its tracks. Call `releaseWarmMic()`
+ * when done. If a warm stream exists (active or in its keepalive window) it
+ * is reused with no new permission prompt.
+ */
+declare function acquireWarmMic(constraints?: MediaTrackConstraints): Promise<MediaStream>;
+/**
+ * Release a previously-acquired hold. When the last holder releases, the
+ * stream is kept warm for the keepalive window, then actually stopped.
+ */
+declare function releaseWarmMic(): void;
+/**
+ * Immediately stop the warm stream regardless of keepalive. Use only when
+ * the mic must be released NOW; normal teardown uses `releaseWarmMic()`.
+ */
+declare function hardStopWarmMic(): void;
+declare function getWarmMicState(): MicStreamState;
+declare function subscribeWarmMic(listener: Listener): () => void;
+/** Diagnostics snapshot for debug panels. */
+declare function warmMicDebug(): {
+    state: MicStreamState;
+    refCount: number;
+    live: boolean;
+    keepAliveMs: number;
+};
+
+/**
+ * CloudLibrarySheet — the recents-thumb destination: where the iPhone opens
+ * the camera roll, we open the user's CLOUD media in a full-screen tiled
+ * gallery — dark chrome to match the camera, square tiles, newest first.
+ *
+ * Absorbed from the matrx-frontend host (C22/C23 retrofit, 2026-08-30):
+ * the 206-line host sheet was pure chrome over three injectable facts — the
+ * item list, the thumbnail renderer, and where a tile navigates. The chrome
+ * now ships here; the host injects only data and identity:
+ *
+ *   <CloudLibrarySheet
+ *     open={open} onClose={close}
+ *     loading={treeLoading}
+ *     items={files.map(f => ({ id, fileName, kind, thumbnail: <MyThumb/> }))}
+ *     onOpenItem={(id) => router.push(`/files/f/${id}`)}
+ *     onUpload={openPicker}   // v3 hosts — upload lives INSIDE the library
+ *   />
+ *
+ * Every tile OPENS the real file (no dead ends), and an empty gallery whose
+ * only affordance is "close" is a dead end too — with `onUpload` supplied,
+ * the empty state offers the one thing a user can do from here.
+ */
+
+interface CloudLibrarySheetProps {
+    open: boolean;
+    onClose: () => void;
+    /** Newest-first media items. The host supplies the thumbnail node — the
+     *  sheet never fetches (law 1: no network in this package). */
+    items: readonly CaptureCloudLibraryItem[];
+    /** True while the host's library data is still loading. */
+    loading: boolean;
+    /** Opening a tile (host navigation) — a busy overlay renders while true. */
+    busy?: boolean;
+    /** A tile was tapped. The host opens the REAL file route (no dead ends). */
+    onOpenItem: (id: string) => void;
+    /**
+     * Pick files from the device. Supplied by v3 hosts, where this drawer is
+     * the ONLY door to existing media (Arman, 2026-08-30: "we don't need both
+     * upload and cloud because we can modify the drawer that has the cloud
+     * images to just show an option for uploading").
+     *
+     * Two controls that both mean "media I already have" is a choice the user
+     * should never have been asked to make: whether a file happens to be in
+     * the cloud yet is our bookkeeping, not their mental model. Omitted by v2
+     * hosts, which still carry a separate UPLOAD lane in the mode row.
+     */
+    onUpload?: (() => void) | undefined;
+    /** Sheet title. Default "Your media". */
+    title?: string;
 }
-declare function useDefaultCaptureEngine(options: DefaultEngineOptions): CaptureCameraEngine;
+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 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, CountdownOverlay, type DefaultEngineOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, MediaViewer, type MediaViewerProps, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, getMediaUrl, invalidateMedia, primeMedia, useDefaultCaptureEngine, useMediaUrl, useTrackControls };
+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 };

package/dist/react.d.ts

@@ -40,6 +40,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;
@@ -709,17 +717,270 @@ interface TrackControls {
 declare function useTrackControls(stream: MediaStream | null): TrackControls;
 
 interface DefaultEngineOptions {
-    /** Receives every captured photo as a JPEG File. */
+    /** Receives every captured photo as a JPEG File (full sensor, aspect crop
+     *  already applied). */
     onPhoto: (file: File) => void;
     /** Receives the finished recording. */
     onVideo: (file: File, durationMs: number) => void;
     /** Receives files chosen through the Upload lane. */
     onFiles: (files: FileList) => void;
-    /** Record microphone audio with video (asks once, at record time). */
+    /** Record microphone audio with video. Default true. With audio on, the
+     *  engine folds the mic permission into the CAMERA's browser prompt (one
+     *  combined prompt) whenever a mic prompt would actually appear. */
     withAudio?: boolean;
+    /** The chrome's current mode. In "video" the engine warm-holds the mic so
+     *  iOS Safari prompts at most once per medium per session. Omitting it
+     *  skips the warm hold (the record path still acquires the mic). */
+    mode?: CaptureCameraMode;
     facingMode?: "environment" | "user";
     photoQuality?: number;
+    /** Filename prefix for captures (default "capture"). */
+    fileNamePrefix?: string;
+    /** Loud failure sink (a toast, a logger). Default: console.error. A tapped
+     *  shutter that produced nothing must say so — never a silent drop. */
+    onError?: (message: string, err: unknown) => void;
+}
+/** The engine plus the extras the default path owns (white shutter flash). */
+interface DefaultCaptureEngine extends CaptureCameraEngine {
+    /** White shutter-flash flag (120 ms), for the host's flash overlay. */
+    flash: boolean;
+    /** Take a photo with a non-default filename prefix (e.g. delineators). */
+    capturePhotoWith: (opts: {
+        fileNamePrefix: string;
+        aspect?: CaptureAspect;
+    }) => void;
+}
+declare function useDefaultCaptureEngine(options: DefaultEngineOptions): DefaultCaptureEngine;
+
+/**
+ * src/engine/crop.ts — the ONE aspect-crop implementation.
+ *
+ * Center-crops a captured JPEG to the requested output aspect. The crop is
+ * applied to the FULL sensor frame (honest pixels, not a preview grab) —
+ * §2 policy 6 of the chrome: the shutter always captures full-sensor and the
+ * selected aspect is a REAL crop of that frame. Ported from the matrx-frontend
+ * host adapter (C22 retrofit, 2026-08-30) so every host shares one geometry.
+ */
+
+declare const PHOTO_JPEG_QUALITY = 0.92;
+declare function cropBlobToAspect(blob: Blob, aspect: CaptureAspect, quality?: number): Promise<Blob>;
+/**
+ * Cycle to the next camera in a device list — the flip algorithm the host
+ * adapter and the default engine share. Returns null when there is nothing
+ * to flip to (fewer than two cameras).
+ */
+declare function nextCameraDevice<T extends {
+    deviceId: string;
+}>(cameras: readonly T[], currentDeviceId: string | null | undefined): T | null;
+
+/**
+ * src/engine/permissions.ts — permission pre-checks + error classification
+ * for the default engine (and for hosts, so they stop re-implementing the
+ * NotAllowedError branch — the C22 rule: quirk branches live HERE).
+ */
+type MediaPermissionState = "granted" | "denied" | "prompt" | "unknown";
+/**
+ * Pre-check the camera permission WITHOUT prompting. A known-"denied" state
+ * lets a surface render its how-to-re-enable explainer instead of hammering
+ * getUserMedia with calls that instantly reject (the proven matrx-frontend
+ * pre-check contract). "unknown" (Safari) means: just try — the gUM outcome
+ * is the truth there.
+ */
+declare function queryCameraPermission(): Promise<MediaPermissionState>;
+/** Same pre-check for the microphone — drives the combined-prompt decision. */
+declare function queryMicPermission(): Promise<MediaPermissionState>;
+/**
+ * Pure decision for the combined camera+mic prompt: only worth it when a mic
+ * prompt would actually appear ("prompt"/"unknown"). "granted" needs no
+ * prompt; "denied" would reject the WHOLE combined call and take the camera
+ * with it.
+ */
+declare function shouldCombineMicPrompt(micPermissionState: MediaPermissionState): boolean;
+/** True when a getUserMedia rejection means the USER/OS denied permission
+ *  (a missing device is not a denial). */
+declare function isMediaDenialError(err: unknown): boolean;
+/**
+ * Classify a camera-acquisition failure into the engine's `blocked` reason.
+ * The ONE place the NotAllowedError/SecurityError branch lives — hosts adapt
+ * their runtime errors through this instead of re-implementing it.
+ */
+declare function classifyCameraBlockReason(err: unknown): "permission-denied" | "not-supported";
+
+/**
+ * src/engine/warm-mic.ts — the package's warm microphone manager.
+ *
+ * Ported VERBATIM (2026-08-30, the C22/C23 retrofit) from matrx-frontend's
+ * proven `features/audio/micStream.ts` — the module that encodes the real
+ * iOS Safari device pain the default engine previously did not have:
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every recording surface used to call `navigator.mediaDevices.getUserMedia`
+ * itself and fully `track.stop()` the stream when it finished. On mobile
+ * (notably iOS Safari) that produces a permission/"in use" prompt on *every*
+ * single recording, because the previous grant is torn down before the next
+ * acquisition. Tapping record three times = three prompts.
+ *
+ * This manager keeps ONE stream warm and hands it to every caller. After the
+ * last holder releases it, the stream is kept alive for a SHORT keepalive
+ * window; if another recording starts within that window, the same live
+ * stream (and the same OS grant) is reused — no second prompt. Only after the
+ * window elapses with no holders is the stream actually stopped (mic light
+ * off), so we don't hold the mic open forever.
+ *
+ * KEEPALIVE IS DELIBERATELY SHORT (a few seconds). Minutes keep the browser's
+ * recording indicator lit long after the user stopped — alarming and abnormal
+ * ("why is my mic still on?"). A few seconds still coalesces a quick
+ * stop→re-record (the iOS re-prompt case) while clearing the mic light almost
+ * immediately once the user is actually done. On desktop, re-acquiring after
+ * release does NOT re-prompt (the origin's grant persists), so a short window
+ * costs nothing there.
+ *
+ * THE FOUR iOS-SAFARI RECOVERY BRANCHES (`MicInterruptionReason`), each of
+ * which used to be a silent audio drop:
+ *   1. `ended`              — the OS killed the track (lock screen, incoming
+ *                             call, app switch, device unplug). The warm grant
+ *                             is gone; the dead stream is dropped so the next
+ *                             acquire re-acquires (and WILL re-prompt).
+ *   2. `muted`              — transient interruption (iOS mutes during a
+ *                             call). The grant survives; no re-prompt.
+ *   3. `unmuted`            — the transient interruption ended.
+ *   4. `permission-revoked` — the user/OS pulled the permission; the warm
+ *                             stream is hard-stopped NOW.
+ * All four are reported loudly on the interruption channel so a recording
+ * surface can react instead of just dropping audio.
+ *
+ * Reference-counted: concurrent holders (an analyser tap + a recorder) are
+ * fine; the stream is only eligible for release when the count hits zero.
+ * Callers MUST NOT call `track.stop()` on the returned stream — call
+ * `releaseWarmMic()` instead.
+ *
+ * State lives on `globalThis` under a `Symbol.for` slot (the media-cache
+ * pattern) — a dual ESM/CJS module graph must still see ONE mic manager.
+ */
+type Listener = (state: MicStreamState) => void;
+type MicInterruptionReason = "ended" | "muted" | "unmuted" | "permission-revoked";
+type InterruptionListener = (reason: MicInterruptionReason) => void;
+type MicStreamState = "idle" | "acquiring" | "active" | "keepalive" | "error";
+/**
+ * Subscribe to mic interruptions (track end / mute / permission loss).
+ * Returns an unsubscribe fn. Surfaces are expected to make these LOUD — an
+ * interruption during a recording is a real event the user must see, not a
+ * silent drop.
+ */
+declare function subscribeWarmMicInterruption(listener: InterruptionListener): () => void;
+/**
+ * Mic-permission revocation → stop the warm stream NOW and emit a loud
+ * interruption. In matrx-frontend the ONE canonical permission watcher
+ * (audioDevices) calls this; the package, having no host device layer, wires
+ * its own minimal Permissions API watcher lazily (`watchMicPermission`) —
+ * best-effort only, since Safari's Permissions API may not answer for
+ * "microphone" (there, `ended` is the branch that fires instead).
+ */
+declare function notifyMicPermissionRevoked(): void;
+/**
+ * Set the preferred microphone. Applied as an `{ideal}` deviceId constraint
+ * on the NEXT acquire — it does NOT switch a live stream (call
+ * `hardStopWarmMic()` then re-acquire to switch mid-session). Pass null to
+ * fall back to the system default.
+ */
+declare function setPreferredMicDeviceId(id: string | null): void;
+/**
+ * The default audio constraints this manager acquires with — exported so the
+ * default engine's COMBINED `getUserMedia({video, audio})` prompt (one
+ * browser prompt for both permissions instead of camera-then-mic) requests
+ * the mic with exactly the same processing + preferred-device shape the
+ * singleton itself would use.
+ */
+declare function buildWarmMicConstraints(): MediaTrackConstraints;
+/**
+ * Adopt an audio stream acquired ELSEWHERE (the default engine's combined
+ * camera+mic prompt) as this manager's warm stream, so the grant that
+ * combined prompt just earned is banked exactly like one of our own: the
+ * next `acquireWarmMic()` inside the keepalive window reuses it with no
+ * second prompt. If a warm stream already exists (or one is being acquired),
+ * the incoming tracks are stopped immediately — never two live mic streams.
+ * With zero holders the adopted stream is parked in the keepalive window, so
+ * the mic light clears on the normal schedule.
+ */
+declare function adoptWarmAudioStream(stream: MediaStream): void;
+/**
+ * Acquire the shared warm mic stream, incrementing the holder count. The
+ * returned stream is shared — DO NOT stop its tracks. Call `releaseWarmMic()`
+ * when done. If a warm stream exists (active or in its keepalive window) it
+ * is reused with no new permission prompt.
+ */
+declare function acquireWarmMic(constraints?: MediaTrackConstraints): Promise<MediaStream>;
+/**
+ * Release a previously-acquired hold. When the last holder releases, the
+ * stream is kept warm for the keepalive window, then actually stopped.
+ */
+declare function releaseWarmMic(): void;
+/**
+ * Immediately stop the warm stream regardless of keepalive. Use only when
+ * the mic must be released NOW; normal teardown uses `releaseWarmMic()`.
+ */
+declare function hardStopWarmMic(): void;
+declare function getWarmMicState(): MicStreamState;
+declare function subscribeWarmMic(listener: Listener): () => void;
+/** Diagnostics snapshot for debug panels. */
+declare function warmMicDebug(): {
+    state: MicStreamState;
+    refCount: number;
+    live: boolean;
+    keepAliveMs: number;
+};
+
+/**
+ * CloudLibrarySheet — the recents-thumb destination: where the iPhone opens
+ * the camera roll, we open the user's CLOUD media in a full-screen tiled
+ * gallery — dark chrome to match the camera, square tiles, newest first.
+ *
+ * Absorbed from the matrx-frontend host (C22/C23 retrofit, 2026-08-30):
+ * the 206-line host sheet was pure chrome over three injectable facts — the
+ * item list, the thumbnail renderer, and where a tile navigates. The chrome
+ * now ships here; the host injects only data and identity:
+ *
+ *   <CloudLibrarySheet
+ *     open={open} onClose={close}
+ *     loading={treeLoading}
+ *     items={files.map(f => ({ id, fileName, kind, thumbnail: <MyThumb/> }))}
+ *     onOpenItem={(id) => router.push(`/files/f/${id}`)}
+ *     onUpload={openPicker}   // v3 hosts — upload lives INSIDE the library
+ *   />
+ *
+ * Every tile OPENS the real file (no dead ends), and an empty gallery whose
+ * only affordance is "close" is a dead end too — with `onUpload` supplied,
+ * the empty state offers the one thing a user can do from here.
+ */
+
+interface CloudLibrarySheetProps {
+    open: boolean;
+    onClose: () => void;
+    /** Newest-first media items. The host supplies the thumbnail node — the
+     *  sheet never fetches (law 1: no network in this package). */
+    items: readonly CaptureCloudLibraryItem[];
+    /** True while the host's library data is still loading. */
+    loading: boolean;
+    /** Opening a tile (host navigation) — a busy overlay renders while true. */
+    busy?: boolean;
+    /** A tile was tapped. The host opens the REAL file route (no dead ends). */
+    onOpenItem: (id: string) => void;
+    /**
+     * Pick files from the device. Supplied by v3 hosts, where this drawer is
+     * the ONLY door to existing media (Arman, 2026-08-30: "we don't need both
+     * upload and cloud because we can modify the drawer that has the cloud
+     * images to just show an option for uploading").
+     *
+     * Two controls that both mean "media I already have" is a choice the user
+     * should never have been asked to make: whether a file happens to be in
+     * the cloud yet is our bookkeeping, not their mental model. Omitted by v2
+     * hosts, which still carry a separate UPLOAD lane in the mode row.
+     */
+    onUpload?: (() => void) | undefined;
+    /** Sheet title. Default "Your media". */
+    title?: string;
 }
-declare function useDefaultCaptureEngine(options: DefaultEngineOptions): CaptureCameraEngine;
+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 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, CountdownOverlay, type DefaultEngineOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, MediaViewer, type MediaViewerProps, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, getMediaUrl, invalidateMedia, primeMedia, useDefaultCaptureEngine, useMediaUrl, useTrackControls };
+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 };