@ai-matrx/capture 0.1.2 → 0.2.0

package/dist/react.d.cts

@@ -38,8 +38,6 @@ interface CaptureCloudPort {
     recentsThumb: React.ReactNode;
     /** Opens the host's cloud media library (tiled gallery). */
     onOpenLibrary: () => void;
-    /** Persists an edited image produced by the edit sheet. */
-    onSaveEdited: (blob: Blob, suggestedName: string) => void;
 }
 /**
  * The engine port — everything the chrome needs from the host's camera
@@ -148,6 +146,51 @@ interface CaptureSheetProps {
 }
 declare function CaptureSheet({ open, onClose, variant, icon, title, body, actions, busyLabel, }: CaptureSheetProps): React__default.JSX.Element | null;
 
+/**
+ * Package-owned media resolution cache — THE fix for "every page turn feels
+ * like a refetch".
+ *
+ * The host supplies, per media item, either a ready `src` (a local object
+ * URL for a fresh capture) or an async `resolve()` (a persisted file that
+ * needs an authenticated URL). Everything else — memoization, in-flight
+ * dedup, LRU eviction, revocation of URLs the cache itself created — is the
+ * package's job. This lives IN the package on the completeness rule: if the
+ * host had to rebuild this, most hosts wouldn't, and every viewer would lag.
+ *
+ * Ownership: URLs returned by `resolve()` are revoked on eviction ONLY when
+ * the resolver marks them owned (`{ url, revoke: true }`); a plain string is
+ * assumed host-owned and never revoked.
+ */
+type ResolvedMedia = string | {
+    url: string;
+    revoke?: boolean;
+};
+interface CaptureMediaItem {
+    /** Stable identity for the item (drives caching + React keys). */
+    key: string;
+    kind: "photo" | "video" | "audio";
+    /** Ready-to-render URL (fresh capture). Host-owned, never revoked here. */
+    src?: string | null;
+    /** Async URL resolution for persisted items. Called at most once per key
+     *  while cached; concurrent callers share the in-flight promise. */
+    resolve?: () => Promise<ResolvedMedia>;
+    /** Upload/processing state — the filmstrip renders it honestly. */
+    status?: "ready" | "uploading" | "error";
+    /** Accent ring on the filmstrip tile (e.g. a delineator frame). */
+    accent?: boolean;
+}
+/**
+ * Resolve an item's URL through the cache. Synchronous when already known;
+ * kicks off (or joins) the resolution otherwise and notifies subscribers.
+ */
+declare function getMediaUrl(item: CaptureMediaItem): string | null;
+/** Drop one item (e.g. after delete). Revokes only cache-owned URLs. */
+declare function invalidateMedia(key: string): void;
+/** React binding: the item's URL, updating when resolution lands. */
+declare function useMediaUrl(item: CaptureMediaItem | null): string | null;
+/** Warm the cache for a set of items (the viewer's neighbor preload). */
+declare function primeMedia(items: (CaptureMediaItem | undefined)[]): void;
+
 /**
  * CameraCapture — the opinionated iPhone-style camera surface, assembled.
  *
@@ -170,6 +213,21 @@ declare function CaptureSheet({ open, onClose, variant, icon, title, body, actio
  * Package source (`@ai-matrx/capture`).
  */
 
+/**
+ * The session's captured media, handed to the chrome so the WHOLE review
+ * loop — filmstrip → swipe viewer → edit → replace — runs inside the
+ * package with its tuned gestures, preload and caching. The host only
+ * implements the item CRUD.
+ */
+interface CaptureMediaSession {
+    items: CaptureMediaItem[];
+    /** Remove one item (viewer trash button). */
+    onDelete?: (key: string) => void;
+    /** Replace semantics for the built-in editor: persist the edited JPEG in
+     *  place of the source item. Edit means edit — after saving, the original
+     *  must be gone. Omit to hide the edit affordance. */
+    onReplacePhoto?: (key: string, blob: Blob) => void;
+}
 interface CameraCaptureProps {
     engine: CaptureCameraEngine;
     /** THE CLOUD LAW: the cloud port is REQUIRED — a camera with no cloud
@@ -177,8 +235,11 @@ interface CameraCaptureProps {
     cloud: CaptureCloudPort;
     mode: CaptureCameraMode;
     onModeChange: (mode: CaptureCameraMode) => void;
-    /** The live preview element (host wires its runtime's `CameraPreview`). */
+    /** The live preview element (`<CameraFeed engine={engine}/>` for the
+     *  default engine; hosts with their own runtime wire their own). */
     preview: React__default.ReactNode;
+    /** Session media — enables the package-owned filmstrip + viewer + editor. */
+    media?: CaptureMediaSession;
     /** Close affordance top-left; omitted = no close button. */
     onClose?: () => void;
     /** Body + actions for the camera-blocked iOS-style sheet. */
@@ -191,7 +252,41 @@ interface CameraCaptureProps {
     shutterDisabled?: boolean;
     slots?: CaptureCameraSlots;
 }
-declare function CameraCapture({ engine, cloud, mode, onModeChange, preview, onClose, blockedSheet, controlsHidden, shutterDisabled, slots, }: CameraCaptureProps): React__default.JSX.Element;
+declare function CameraCapture({ engine, cloud, mode, onModeChange, preview, media, onClose, blockedSheet, controlsHidden, shutterDisabled, slots, }: CameraCaptureProps): React__default.JSX.Element;
+
+/**
+ * CameraFeed — the package's live preview <video> for the default engine
+ * (drop-in hosts). Attaches the engine's stream imperatively (srcObject is
+ * not a React DOM prop), fills its container with object-cover, and exposes
+ * the element through the engine's videoRef so photo capture can read it.
+ * Inline styles on purpose: host stylesheets (e.g. mobile `video { height:
+ * auto }` resets) must never shrink the live view below the captured frame.
+ *
+ * Hosts with their own runtime render their own preview component instead —
+ * this one is part of the batteries-included path.
+ */
+
+declare function CameraFeed({ engine, mirror, }: {
+    engine: CaptureCameraEngine;
+    /** Preview-only CSS mirror (front camera). Output is never mirrored. */
+    mirror?: boolean;
+}): React__default.JSX.Element;
+
+/**
+ * CaptureFilmstrip — the row of session-capture thumbnails floating over the
+ * feed. Package-owned so the tile states (uploading spinner, error ring,
+ * accent ring) and the tap-to-view wiring are tuned once, everywhere.
+ * Thumbnails resolve through the package media cache, so the strip never
+ * re-fetches what the viewer already resolved (and vice versa).
+ */
+
+interface CaptureFilmstripProps {
+    items: CaptureMediaItem[];
+    onOpen: (item: CaptureMediaItem) => void;
+    /** Show at most this many trailing tiles (default 12). */
+    limit?: number;
+}
+declare function CaptureFilmstrip({ items, onOpen, limit, }: CaptureFilmstripProps): React__default.JSX.Element | null;
 
 /**
  * CountdownOverlay — the big centered timer digits (iPhone timer capture):
@@ -240,6 +335,41 @@ interface ImageEditSheetProps {
 }
 declare function ImageEditSheet({ open, src, onClose, onSave, }: ImageEditSheetProps): React__default.JSX.Element | null;
 
+/**
+ * MediaViewer — the package's full-screen swipe pager (iOS Photos pattern),
+ * moved INTO the package after real-phone tuning so every host inherits the
+ * tuned gestures, neighbor preload and resolution caching for free.
+ *
+ * - Pointer-event gestures, zero animation deps: horizontal drag pages
+ *   (40px travel OR a 0.25px/ms flick), vertical drag ≥110px dismisses,
+ *   direction locked on first movement.
+ * - Neighbors stay MOUNTED and invisible (±2 photos, ±1 video) so a page
+ *   turn lands on already-resolved, already-decoded pixels — the "revisit
+ *   lag" fix. URLs come from the package media cache (`media-cache.ts`).
+ * - Optional per-item Delete and Edit (edit hands off to the host — the
+ *   `CameraCapture` orchestration pairs it with `ImageEditSheet` and
+ *   replace semantics).
+ * - Desktop: arrow keys page, Escape closes, chevrons on hover-capable
+ *   screens.
+ */
+
+interface MediaViewerProps {
+    items: CaptureMediaItem[];
+    /** Key of the item to open on. */
+    initialKey: string | null;
+    onClose: () => void;
+    onDelete?: (item: CaptureMediaItem) => void;
+    /** Offered on photo items with a renderable URL. */
+    onEdit?: (item: CaptureMediaItem) => void;
+    /** What deleting costs, stated BEFORE the delete (destructive-actions
+     *  rule). Override per domain; deletion is never one silent tap. */
+    deleteConsequence?: string;
+    /** Suppress keyboard handling while another overlay (the editor) is on
+     *  top — Escape must close the top-most surface, not this one. */
+    keysDisabled?: boolean;
+}
+declare function MediaViewer({ items, initialKey, onClose, onDelete, onEdit, deleteConsequence, keysDisabled, }: MediaViewerProps): React__default.JSX.Element | null;
+
 /**
  * ModeSelector — the CONNECTED capture-mode bar: one compact rounded track
  * holding VIDEO · PHOTO · UPLOAD (+ injected extras) with a spring-sliding
@@ -347,4 +477,18 @@ interface TrackControls {
 }
 declare function useTrackControls(stream: MediaStream | null): TrackControls;
 
-export { CameraCapture, type CameraCaptureProps, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCloudPort, type CaptureOptionTile, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CountdownOverlay, GridOverlay, ImageEditSheet, type ImageEditSheetProps, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, useTrackControls };
+interface DefaultEngineOptions {
+    /** Receives every captured photo as a JPEG File. */
+    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). */
+    withAudio?: boolean;
+    facingMode?: "environment" | "user";
+    photoQuality?: number;
+}
+declare function useDefaultCaptureEngine(options: DefaultEngineOptions): CaptureCameraEngine;
+
+export { CameraCapture, type CameraCaptureProps, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCloudPort, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CountdownOverlay, type DefaultEngineOptions, GridOverlay, 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 };

package/dist/react.d.ts

@@ -38,8 +38,6 @@ interface CaptureCloudPort {
     recentsThumb: React.ReactNode;
     /** Opens the host's cloud media library (tiled gallery). */
     onOpenLibrary: () => void;
-    /** Persists an edited image produced by the edit sheet. */
-    onSaveEdited: (blob: Blob, suggestedName: string) => void;
 }
 /**
  * The engine port — everything the chrome needs from the host's camera
@@ -148,6 +146,51 @@ interface CaptureSheetProps {
 }
 declare function CaptureSheet({ open, onClose, variant, icon, title, body, actions, busyLabel, }: CaptureSheetProps): React__default.JSX.Element | null;
 
+/**
+ * Package-owned media resolution cache — THE fix for "every page turn feels
+ * like a refetch".
+ *
+ * The host supplies, per media item, either a ready `src` (a local object
+ * URL for a fresh capture) or an async `resolve()` (a persisted file that
+ * needs an authenticated URL). Everything else — memoization, in-flight
+ * dedup, LRU eviction, revocation of URLs the cache itself created — is the
+ * package's job. This lives IN the package on the completeness rule: if the
+ * host had to rebuild this, most hosts wouldn't, and every viewer would lag.
+ *
+ * Ownership: URLs returned by `resolve()` are revoked on eviction ONLY when
+ * the resolver marks them owned (`{ url, revoke: true }`); a plain string is
+ * assumed host-owned and never revoked.
+ */
+type ResolvedMedia = string | {
+    url: string;
+    revoke?: boolean;
+};
+interface CaptureMediaItem {
+    /** Stable identity for the item (drives caching + React keys). */
+    key: string;
+    kind: "photo" | "video" | "audio";
+    /** Ready-to-render URL (fresh capture). Host-owned, never revoked here. */
+    src?: string | null;
+    /** Async URL resolution for persisted items. Called at most once per key
+     *  while cached; concurrent callers share the in-flight promise. */
+    resolve?: () => Promise<ResolvedMedia>;
+    /** Upload/processing state — the filmstrip renders it honestly. */
+    status?: "ready" | "uploading" | "error";
+    /** Accent ring on the filmstrip tile (e.g. a delineator frame). */
+    accent?: boolean;
+}
+/**
+ * Resolve an item's URL through the cache. Synchronous when already known;
+ * kicks off (or joins) the resolution otherwise and notifies subscribers.
+ */
+declare function getMediaUrl(item: CaptureMediaItem): string | null;
+/** Drop one item (e.g. after delete). Revokes only cache-owned URLs. */
+declare function invalidateMedia(key: string): void;
+/** React binding: the item's URL, updating when resolution lands. */
+declare function useMediaUrl(item: CaptureMediaItem | null): string | null;
+/** Warm the cache for a set of items (the viewer's neighbor preload). */
+declare function primeMedia(items: (CaptureMediaItem | undefined)[]): void;
+
 /**
  * CameraCapture — the opinionated iPhone-style camera surface, assembled.
  *
@@ -170,6 +213,21 @@ declare function CaptureSheet({ open, onClose, variant, icon, title, body, actio
  * Package source (`@ai-matrx/capture`).
  */
 
+/**
+ * The session's captured media, handed to the chrome so the WHOLE review
+ * loop — filmstrip → swipe viewer → edit → replace — runs inside the
+ * package with its tuned gestures, preload and caching. The host only
+ * implements the item CRUD.
+ */
+interface CaptureMediaSession {
+    items: CaptureMediaItem[];
+    /** Remove one item (viewer trash button). */
+    onDelete?: (key: string) => void;
+    /** Replace semantics for the built-in editor: persist the edited JPEG in
+     *  place of the source item. Edit means edit — after saving, the original
+     *  must be gone. Omit to hide the edit affordance. */
+    onReplacePhoto?: (key: string, blob: Blob) => void;
+}
 interface CameraCaptureProps {
     engine: CaptureCameraEngine;
     /** THE CLOUD LAW: the cloud port is REQUIRED — a camera with no cloud
@@ -177,8 +235,11 @@ interface CameraCaptureProps {
     cloud: CaptureCloudPort;
     mode: CaptureCameraMode;
     onModeChange: (mode: CaptureCameraMode) => void;
-    /** The live preview element (host wires its runtime's `CameraPreview`). */
+    /** The live preview element (`<CameraFeed engine={engine}/>` for the
+     *  default engine; hosts with their own runtime wire their own). */
     preview: React__default.ReactNode;
+    /** Session media — enables the package-owned filmstrip + viewer + editor. */
+    media?: CaptureMediaSession;
     /** Close affordance top-left; omitted = no close button. */
     onClose?: () => void;
     /** Body + actions for the camera-blocked iOS-style sheet. */
@@ -191,7 +252,41 @@ interface CameraCaptureProps {
     shutterDisabled?: boolean;
     slots?: CaptureCameraSlots;
 }
-declare function CameraCapture({ engine, cloud, mode, onModeChange, preview, onClose, blockedSheet, controlsHidden, shutterDisabled, slots, }: CameraCaptureProps): React__default.JSX.Element;
+declare function CameraCapture({ engine, cloud, mode, onModeChange, preview, media, onClose, blockedSheet, controlsHidden, shutterDisabled, slots, }: CameraCaptureProps): React__default.JSX.Element;
+
+/**
+ * CameraFeed — the package's live preview <video> for the default engine
+ * (drop-in hosts). Attaches the engine's stream imperatively (srcObject is
+ * not a React DOM prop), fills its container with object-cover, and exposes
+ * the element through the engine's videoRef so photo capture can read it.
+ * Inline styles on purpose: host stylesheets (e.g. mobile `video { height:
+ * auto }` resets) must never shrink the live view below the captured frame.
+ *
+ * Hosts with their own runtime render their own preview component instead —
+ * this one is part of the batteries-included path.
+ */
+
+declare function CameraFeed({ engine, mirror, }: {
+    engine: CaptureCameraEngine;
+    /** Preview-only CSS mirror (front camera). Output is never mirrored. */
+    mirror?: boolean;
+}): React__default.JSX.Element;
+
+/**
+ * CaptureFilmstrip — the row of session-capture thumbnails floating over the
+ * feed. Package-owned so the tile states (uploading spinner, error ring,
+ * accent ring) and the tap-to-view wiring are tuned once, everywhere.
+ * Thumbnails resolve through the package media cache, so the strip never
+ * re-fetches what the viewer already resolved (and vice versa).
+ */
+
+interface CaptureFilmstripProps {
+    items: CaptureMediaItem[];
+    onOpen: (item: CaptureMediaItem) => void;
+    /** Show at most this many trailing tiles (default 12). */
+    limit?: number;
+}
+declare function CaptureFilmstrip({ items, onOpen, limit, }: CaptureFilmstripProps): React__default.JSX.Element | null;
 
 /**
  * CountdownOverlay — the big centered timer digits (iPhone timer capture):
@@ -240,6 +335,41 @@ interface ImageEditSheetProps {
 }
 declare function ImageEditSheet({ open, src, onClose, onSave, }: ImageEditSheetProps): React__default.JSX.Element | null;
 
+/**
+ * MediaViewer — the package's full-screen swipe pager (iOS Photos pattern),
+ * moved INTO the package after real-phone tuning so every host inherits the
+ * tuned gestures, neighbor preload and resolution caching for free.
+ *
+ * - Pointer-event gestures, zero animation deps: horizontal drag pages
+ *   (40px travel OR a 0.25px/ms flick), vertical drag ≥110px dismisses,
+ *   direction locked on first movement.
+ * - Neighbors stay MOUNTED and invisible (±2 photos, ±1 video) so a page
+ *   turn lands on already-resolved, already-decoded pixels — the "revisit
+ *   lag" fix. URLs come from the package media cache (`media-cache.ts`).
+ * - Optional per-item Delete and Edit (edit hands off to the host — the
+ *   `CameraCapture` orchestration pairs it with `ImageEditSheet` and
+ *   replace semantics).
+ * - Desktop: arrow keys page, Escape closes, chevrons on hover-capable
+ *   screens.
+ */
+
+interface MediaViewerProps {
+    items: CaptureMediaItem[];
+    /** Key of the item to open on. */
+    initialKey: string | null;
+    onClose: () => void;
+    onDelete?: (item: CaptureMediaItem) => void;
+    /** Offered on photo items with a renderable URL. */
+    onEdit?: (item: CaptureMediaItem) => void;
+    /** What deleting costs, stated BEFORE the delete (destructive-actions
+     *  rule). Override per domain; deletion is never one silent tap. */
+    deleteConsequence?: string;
+    /** Suppress keyboard handling while another overlay (the editor) is on
+     *  top — Escape must close the top-most surface, not this one. */
+    keysDisabled?: boolean;
+}
+declare function MediaViewer({ items, initialKey, onClose, onDelete, onEdit, deleteConsequence, keysDisabled, }: MediaViewerProps): React__default.JSX.Element | null;
+
 /**
  * ModeSelector — the CONNECTED capture-mode bar: one compact rounded track
  * holding VIDEO · PHOTO · UPLOAD (+ injected extras) with a spring-sliding
@@ -347,4 +477,18 @@ interface TrackControls {
 }
 declare function useTrackControls(stream: MediaStream | null): TrackControls;
 
-export { CameraCapture, type CameraCaptureProps, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCloudPort, type CaptureOptionTile, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CountdownOverlay, GridOverlay, ImageEditSheet, type ImageEditSheetProps, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, useTrackControls };
+interface DefaultEngineOptions {
+    /** Receives every captured photo as a JPEG File. */
+    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). */
+    withAudio?: boolean;
+    facingMode?: "environment" | "user";
+    photoQuality?: number;
+}
+declare function useDefaultCaptureEngine(options: DefaultEngineOptions): CaptureCameraEngine;
+
+export { CameraCapture, type CameraCaptureProps, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCloudPort, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CountdownOverlay, type DefaultEngineOptions, GridOverlay, 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 };