@ai-matrx/capture 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -49,3 +49,16 @@ The package-completeness release: the whole capture loop now lives in the box (A
 ## 0.2.1 — 2026-08-29
 
 - `CameraCapture.onReviewOpenChange` — hosts pause feed-watchers (QR scanning) while the package viewer/editor covers the camera.
+
+## 0.3.0 — 2026-08-30
+
+**v3 — the vertical-rail chrome.** `CameraCaptureV3` is a SECOND chrome over the same engine, cloud port and package-owned review loop, not a replacement; `CameraCapture` is unchanged and still exported. Every difference answers something v2 got wrong on a real phone (Arman):
+
+- **`HoldShutter` — one button.** Tap = photo, press-and-hold = video. v2 spent a row on a mode selector, so the user paid bar height AND a decision before the moment they were trying to catch. A hold that passes ~1.2s LATCHES, so a slipped finger does not lose the take; the next tap stops it. Pointer capture + cancel/lost-capture handling means a drag off the button can never leave the camera recording with nothing to stop.
+- **`CaptureRail` — options on the right edge.** A rail over the feed instead of a two-tap grid behind a button: no layout cost, one tap to anything, viewfinder intact. Actions marked `primary` (flip, flash) stay; the rest collapse behind a chevron, and the chevron only renders when there is genuinely something to hide.
+- **`CaptureExpandingField` — text is a button until you need it.** A pill that expands into a field on press (the pattern Apple uses for search). v2 pinned a live `<input>` in the bottom bar: a permanent row for occasional use, keyboard-bait over the viewfinder, and an idle camera that looked like a form. Commits on Enter, blur AND unmount — the v2 input's evaporating-value bug, kept fixed.
+- **ONE media door.** v3 has no UPLOAD mode. The library button is the only way to existing media and `engine.onUpload` is called from INSIDE the host's drawer. New law 5 fails the build if the v3 chrome ever grows its own upload button.
+- **`onRecordIntent`** — fires on pointer-DOWN, before the hold threshold decides. Hosts warm the mic on it; with a hold shutter there is no "user chose VIDEO" moment, and warming after recording starts costs the first second of audio on iOS Safari or throws a permission prompt mid-take.
+- Law 4 now scans EVERY `CameraCapture*.tsx` for the required cloud port, by filename pattern — a third chrome inherits THE CLOUD LAW by existing, not by someone remembering.
+
+Deliberately not copied from the app this borrows its shape from: fixed duration choices (they belong to that product's format, not to a camera) and the oversized promo pill for a new feature (chrome is not a billboard).

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  CaptureCloudPort,\n  CaptureOptionTile,\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  CaptureCloudPort,\n  CaptureOptionTile,\n  CaptureRailAction,\n  CaptureTimerSetting,\n} from \"./types\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/index.d.cts

@@ -113,5 +113,53 @@ interface CaptureCameraSlots {
     /** Free overlays rendered above everything (sheets, pagers). */
     overlays?: React.ReactNode;
 }
+/** One action on the v3 right-hand rail. */
+interface CaptureRailAction {
+    id: string;
+    /** Accessible name; also the label shown when `showLabels` is on. */
+    label: string;
+    icon: React.ReactNode;
+    /** Engaged/on — rendered in the accent colour. */
+    active?: boolean;
+    /** A short read-out under the icon (e.g. "3s", "4:3", "Auto"). */
+    valueLabel?: string;
+    disabled?: boolean;
+    /**
+     * Primary actions stay visible when the rail is collapsed. Everything else
+     * hides behind the chevron. Keep this to the two or three a user reaches for
+     * without thinking — a rail where nothing collapses is just a long rail.
+     */
+    primary?: boolean;
+    onPress: () => void;
+}
+/**
+ * Slots for the v3 chrome. Deliberately fewer and differently shaped than
+ * `CaptureCameraSlots`: v3 has no mode row, so the slots that existed to sit
+ * around one are gone, and the rail replaces the options grid.
+ */
+interface CaptureCameraV3Slots {
+    /** Centre of the top row — the item label / count. Keep it to one line. */
+    topCenter?: React.ReactNode;
+    /** Honesty chips under the top row (QR confirmation, upload progress). */
+    statusChips?: React.ReactNode;
+    /** Rendered OVER the feed just above the shutter row — the filmstrip home. */
+    aboveShutter?: React.ReactNode;
+    /**
+     * The one action to the RIGHT of the shutter (Next / Break / Process).
+     * Exactly one: the shutter row is a thumb-reach zone and a second control
+     * there turns a one-hand camera into a two-hand one.
+     */
+    shutterTrailing?: React.ReactNode;
+    /** Actions on the right rail, in order. */
+    railActions?: CaptureRailAction[];
+    /**
+     * The expanding text entry pinned to the top row (serial, tag, caption).
+     * Supply `<CaptureExpandingField/>` or any control — it is a slot so a host
+     * that needs none pays nothing for it.
+     */
+    topEntry?: React.ReactNode;
+    /** Free overlays above everything (sheets, pagers). */
+    overlays?: React.ReactNode;
+}
 
-export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCloudPort, CaptureOptionTile, CaptureTimerSetting };
+export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCameraV3Slots, CaptureCloudPort, CaptureOptionTile, CaptureRailAction, CaptureTimerSetting };

package/dist/index.d.ts

@@ -113,5 +113,53 @@ interface CaptureCameraSlots {
     /** Free overlays rendered above everything (sheets, pagers). */
     overlays?: React.ReactNode;
 }
+/** One action on the v3 right-hand rail. */
+interface CaptureRailAction {
+    id: string;
+    /** Accessible name; also the label shown when `showLabels` is on. */
+    label: string;
+    icon: React.ReactNode;
+    /** Engaged/on — rendered in the accent colour. */
+    active?: boolean;
+    /** A short read-out under the icon (e.g. "3s", "4:3", "Auto"). */
+    valueLabel?: string;
+    disabled?: boolean;
+    /**
+     * Primary actions stay visible when the rail is collapsed. Everything else
+     * hides behind the chevron. Keep this to the two or three a user reaches for
+     * without thinking — a rail where nothing collapses is just a long rail.
+     */
+    primary?: boolean;
+    onPress: () => void;
+}
+/**
+ * Slots for the v3 chrome. Deliberately fewer and differently shaped than
+ * `CaptureCameraSlots`: v3 has no mode row, so the slots that existed to sit
+ * around one are gone, and the rail replaces the options grid.
+ */
+interface CaptureCameraV3Slots {
+    /** Centre of the top row — the item label / count. Keep it to one line. */
+    topCenter?: React.ReactNode;
+    /** Honesty chips under the top row (QR confirmation, upload progress). */
+    statusChips?: React.ReactNode;
+    /** Rendered OVER the feed just above the shutter row — the filmstrip home. */
+    aboveShutter?: React.ReactNode;
+    /**
+     * The one action to the RIGHT of the shutter (Next / Break / Process).
+     * Exactly one: the shutter row is a thumb-reach zone and a second control
+     * there turns a one-hand camera into a two-hand one.
+     */
+    shutterTrailing?: React.ReactNode;
+    /** Actions on the right rail, in order. */
+    railActions?: CaptureRailAction[];
+    /**
+     * The expanding text entry pinned to the top row (serial, tag, caption).
+     * Supply `<CaptureExpandingField/>` or any control — it is a slot so a host
+     * that needs none pays nothing for it.
+     */
+    topEntry?: React.ReactNode;
+    /** Free overlays above everything (sheets, pagers). */
+    overlays?: React.ReactNode;
+}
 
-export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCloudPort, CaptureOptionTile, CaptureTimerSetting };
+export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCameraV3Slots, CaptureCloudPort, CaptureOptionTile, CaptureRailAction, CaptureTimerSetting };