@ai-matrx/capture 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog — @ai-matrx/capture
+
+## 0.1.0 — 2026-08-29
+
+Initial extraction from matrx-frontend `features/capture-camera/` (the iPhone-style rebuild of the commerce intake camera, generalized):
+
+- `CameraCapture` chrome (translucent bars, shutter, VIDEO·PHOTO·UPLOAD mode row, recents thumb, flip, honesty chips).
+- Two-tap `OptionsGridPanel` (Flash/Timer/Grid/Aspect/Exposure + injected tiles).
+- `ImageEditSheet` (crop/rotate/flip, canvas re-encode).
+- `CaptureSheet` iOS-style system sheet (content + busy variants).
+- `useTrackControls` (honest torch/zoom/exposure from track capabilities).
+- THE CLOUD LAW: required `CaptureCloudPort`; laws test bans network, gUM, storage, and an optional cloud port.
+
+Published 2026-08-29 via tag `npm/capture/v0.1.0` (trusted publishing; the name was pre-reserved at 0.0.0).
+
+## 0.1.1 — 2026-08-29
+
+Real-phone feedback pass (the bar was eating the viewfinder):
+
+- Top bar compacted to ONE h-11 row (was h-16); smaller icons/hit targets.
+- ModeSelector rebuilt as the CONNECTED sliding-thumb track (spring easing, uppercase yellow-active labels) — narrow on purpose so both sides of the row stay usable; extras join the track.
+- New `slots.aboveBar`: host content rendered OVER the feed above the bottom bar (filmstrip home) — zero bar height.
+- Domain action returned to the mode row (absolute right of the narrow track).
+- Bottom paddings cut (mode row py-1.5, shutter row pb-1.5), thumbs 44px.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
 # @ai-matrx/capture
 
-Reserved for the AI Matrx opinionated camera and media-capture package. This `0.0.0` release reserves the canonical package name; the implementation is being built separately.
+The AI Matrx capture kit — the opinionated, iPhone-style camera experience as a reusable React package.
+
+**THE CLOUD LAW:** cloud integration is WHAT this system does, not an add-on. `CameraCapture` requires a `CaptureCloudPort` (recents thumb, library opener, edited-image persistence). The host decides HOW the cloud is reached — never WHETHER.
+
+## What's inside
+
+- `CameraCapture` — the assembled chrome: full-bleed feed under semi-transparent near-black bars; top bar (close · center slot · torch · extras · options); real zoom pills (track capabilities only — nothing faked); VIDEO · PHOTO · UPLOAD mode row (upload is first-class); recents thumb · shutter · flip; honesty chips (recording clock survives hidden chrome).
+- `OptionsGridPanel` — the two-tap options surface (reveal, then act): Flash (torch), Timer (0/3/10s), Grid, Aspect (full/4:3/1:1/16:9), Exposure (when the hardware reports a range), plus host-injected tiles.
+- `ImageEditSheet` — instant in-browser editing: crop (free/1:1/4:3/16:9), rotate, flip; canvas re-encode of the original pixels.
+- `CaptureSheet` — the iOS-style system sheet (content + "busy" transient variant).
+- `useTrackControls` — honest torch/zoom/exposure over `MediaTrackCapabilities`.
+- Slot-based extensibility (`CaptureCameraSlots`) — typed slots for domain add-ons (status chips, option tiles, extra modes such as SCAN, rows above the mode selector, overlays). No plugin framework.
+
+## 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 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`.
+
+## Usage sketch
+
+```tsx
+import { CameraCapture } from "@ai-matrx/capture/react";
+import type { CaptureCameraEngine, CaptureCloudPort } from "@ai-matrx/capture";
+
+<CameraCapture
+  engine={engine}          // host camera runtime adapter
+  cloud={cloud}            // REQUIRED — recents thumb, library, save-edited
+  mode={mode}
+  onModeChange={setMode}
+  preview={<YourLivePreview />}
+  onClose={close}
+  blockedSheet={{ body: <p>…</p>, actions: [...] }}
+  slots={{ optionTiles: [...], statusChips: <...>, extraModes: [{ id: "scan", label: "Scan", onSelect: openScanner }] }}
+/>
+```
+
+The reference host integration is matrx-frontend `features/capture-camera/` (staging source) with the commerce intake surface at `/commerce/intake/v2` as the worked domain-extension example.

package/dist/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+module.exports = __toCommonJS(src_exports);
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":[]}

package/dist/index.d.cts

@@ -0,0 +1,119 @@
+import * as React from 'react';
+
+/**
+ * features/capture-camera/ — EXTRACTION SOURCE for the `@ai-matrx/capture`
+ * package (aidream/apps/shared/capture). Everything outside `host/` must stay
+ * free of app imports beyond React, lucide-react and `cn` — those are the
+ * documented substitution points when this directory is mirrored into the
+ * package (icons → inlined SVGs, cn → tailwind-merge), exactly like
+ * `@ai-matrx/media` was extracted from `features/files`.
+ *
+ * The package is the OPINIONATED iPhone-style camera chrome: translucent
+ * top/bottom bars over a full-bleed feed, the two-tap options grid, zoom
+ * pills, shutter, VIDEO·PHOTO·UPLOAD mode selector, recents thumb, flip
+ * button, rule-of-thirds grid, countdown timer, and the iOS-style sheet.
+ * It renders and orchestrates UI state ONLY — the host injects the engine
+ * (stream + capture callbacks) and everything persisted (upload, gallery,
+ * thumbnails). No fetch, no storage, no getUserMedia in this layer.
+ */
+
+/** The two persistent capture modes; Upload is an immediate action. */
+type CaptureCameraMode = "photo" | "video";
+/** Timer options genuinely supported (a countdown before the shutter). */
+type CaptureTimerSetting = 0 | 3 | 10;
+/** Output aspect for photo capture (center-cropped from the full sensor). */
+type CaptureAspect = "full" | "4:3" | "1:1" | "16:9";
+/**
+ * THE CLOUD LAW of this package: cloud integration is WHAT the system does,
+ * not an optional add-on. Every `CameraCapture` REQUIRES this port — the
+ * type system refuses a camera with no cloud. How the host fulfills it
+ * (fileHandler, a client SDK, a domain uploader) is injected; that it is
+ * fulfilled is not negotiable.
+ */
+interface CaptureCloudPort {
+    /** Content of the bottom-left recents thumbnail (latest cloud/session
+     *  media). Null renders the placeholder — the button still opens the
+     *  library. */
+    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
+ * runtime. The host owns lease acquisition/release, capture and recording;
+ * the chrome never touches getUserMedia.
+ */
+interface CaptureCameraEngine {
+    /** Live stream for the preview, or null while connecting/blocked. */
+    stream: MediaStream | null;
+    /** The preview <video> element ref the host's capture path reads from. */
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    /** Camera unavailable: permission denied or unsupported. */
+    blocked: null | {
+        reason: "permission-denied" | "not-supported";
+    };
+    /** Take a photo NOW (any timer countdown already elapsed). The chrome's
+     *  current aspect setting rides along; the host center-crops the full
+     *  sensor frame to it ("full" = untouched). */
+    onCapturePhoto: (opts?: {
+        aspect?: CaptureAspect;
+    }) => void;
+    /** Start / stop video recording. */
+    onStartRecording: () => void;
+    onStopRecording: () => void;
+    recording: boolean;
+    /** Elapsed recording seconds (host-owned monotonic clock). */
+    recordElapsedSeconds: number;
+    /** Open the device files picker (the Upload lane). */
+    onUpload: () => void;
+    /** Flip to the next camera; null hides the flip button. */
+    onFlipCamera: (() => void) | null;
+}
+/** One tile in the two-tap options grid. */
+interface CaptureOptionTile {
+    id: string;
+    label: string;
+    icon: React.ReactNode;
+    /** Highlight state (iPhone: yellow when engaged/auto). */
+    active?: boolean;
+    /** Small value read-out under the icon (e.g. "3s", "4:3"). */
+    valueLabel?: string;
+    disabled?: boolean;
+    onPress: () => void;
+}
+/**
+ * Slot-based extensibility — how domain layers (e.g. commerce intake) attach
+ * their own affordances without forking the chrome. Typed slots, not a plugin
+ * registry, on purpose.
+ */
+interface CaptureCameraSlots {
+    /** Extra buttons in the top bar, before the options-grid button. */
+    topBarTrailing?: React.ReactNode;
+    /** Center of the top bar (e.g. current-item label + count). */
+    topBarCenter?: React.ReactNode;
+    /** Honesty chips under the top bar (QR confirmation, etc.). */
+    statusChips?: React.ReactNode;
+    /** Rendered OVER THE FEED just above the bottom bar (with the zoom
+     *  pills) — costs the bar no height. The filmstrip belongs here. */
+    aboveBar?: React.ReactNode;
+    /** Rows rendered inside the bottom bar ABOVE the mode selector
+     *  (keep to ONE compact row — bar height is stolen from the feed). */
+    aboveModeSelector?: React.ReactNode;
+    /** A compact action pinned right of the mode selector (Next/Break). */
+    modeRowTrailing?: React.ReactNode;
+    /** Extra tiles appended to the options grid. */
+    optionTiles?: CaptureOptionTile[];
+    /** Extra entries in the mode row after UPLOAD (e.g. SCAN). Selecting one
+     *  is an immediate host action — the chrome keeps its current mode. */
+    extraModes?: {
+        id: string;
+        label: string;
+        onSelect: () => void;
+    }[];
+    /** Free overlays rendered above everything (sheets, pagers). */
+    overlays?: React.ReactNode;
+}
+
+export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCloudPort, CaptureOptionTile, CaptureTimerSetting };

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+import * as React from 'react';
+
+/**
+ * features/capture-camera/ — EXTRACTION SOURCE for the `@ai-matrx/capture`
+ * package (aidream/apps/shared/capture). Everything outside `host/` must stay
+ * free of app imports beyond React, lucide-react and `cn` — those are the
+ * documented substitution points when this directory is mirrored into the
+ * package (icons → inlined SVGs, cn → tailwind-merge), exactly like
+ * `@ai-matrx/media` was extracted from `features/files`.
+ *
+ * The package is the OPINIONATED iPhone-style camera chrome: translucent
+ * top/bottom bars over a full-bleed feed, the two-tap options grid, zoom
+ * pills, shutter, VIDEO·PHOTO·UPLOAD mode selector, recents thumb, flip
+ * button, rule-of-thirds grid, countdown timer, and the iOS-style sheet.
+ * It renders and orchestrates UI state ONLY — the host injects the engine
+ * (stream + capture callbacks) and everything persisted (upload, gallery,
+ * thumbnails). No fetch, no storage, no getUserMedia in this layer.
+ */
+
+/** The two persistent capture modes; Upload is an immediate action. */
+type CaptureCameraMode = "photo" | "video";
+/** Timer options genuinely supported (a countdown before the shutter). */
+type CaptureTimerSetting = 0 | 3 | 10;
+/** Output aspect for photo capture (center-cropped from the full sensor). */
+type CaptureAspect = "full" | "4:3" | "1:1" | "16:9";
+/**
+ * THE CLOUD LAW of this package: cloud integration is WHAT the system does,
+ * not an optional add-on. Every `CameraCapture` REQUIRES this port — the
+ * type system refuses a camera with no cloud. How the host fulfills it
+ * (fileHandler, a client SDK, a domain uploader) is injected; that it is
+ * fulfilled is not negotiable.
+ */
+interface CaptureCloudPort {
+    /** Content of the bottom-left recents thumbnail (latest cloud/session
+     *  media). Null renders the placeholder — the button still opens the
+     *  library. */
+    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
+ * runtime. The host owns lease acquisition/release, capture and recording;
+ * the chrome never touches getUserMedia.
+ */
+interface CaptureCameraEngine {
+    /** Live stream for the preview, or null while connecting/blocked. */
+    stream: MediaStream | null;
+    /** The preview <video> element ref the host's capture path reads from. */
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    /** Camera unavailable: permission denied or unsupported. */
+    blocked: null | {
+        reason: "permission-denied" | "not-supported";
+    };
+    /** Take a photo NOW (any timer countdown already elapsed). The chrome's
+     *  current aspect setting rides along; the host center-crops the full
+     *  sensor frame to it ("full" = untouched). */
+    onCapturePhoto: (opts?: {
+        aspect?: CaptureAspect;
+    }) => void;
+    /** Start / stop video recording. */
+    onStartRecording: () => void;
+    onStopRecording: () => void;
+    recording: boolean;
+    /** Elapsed recording seconds (host-owned monotonic clock). */
+    recordElapsedSeconds: number;
+    /** Open the device files picker (the Upload lane). */
+    onUpload: () => void;
+    /** Flip to the next camera; null hides the flip button. */
+    onFlipCamera: (() => void) | null;
+}
+/** One tile in the two-tap options grid. */
+interface CaptureOptionTile {
+    id: string;
+    label: string;
+    icon: React.ReactNode;
+    /** Highlight state (iPhone: yellow when engaged/auto). */
+    active?: boolean;
+    /** Small value read-out under the icon (e.g. "3s", "4:3"). */
+    valueLabel?: string;
+    disabled?: boolean;
+    onPress: () => void;
+}
+/**
+ * Slot-based extensibility — how domain layers (e.g. commerce intake) attach
+ * their own affordances without forking the chrome. Typed slots, not a plugin
+ * registry, on purpose.
+ */
+interface CaptureCameraSlots {
+    /** Extra buttons in the top bar, before the options-grid button. */
+    topBarTrailing?: React.ReactNode;
+    /** Center of the top bar (e.g. current-item label + count). */
+    topBarCenter?: React.ReactNode;
+    /** Honesty chips under the top bar (QR confirmation, etc.). */
+    statusChips?: React.ReactNode;
+    /** Rendered OVER THE FEED just above the bottom bar (with the zoom
+     *  pills) — costs the bar no height. The filmstrip belongs here. */
+    aboveBar?: React.ReactNode;
+    /** Rows rendered inside the bottom bar ABOVE the mode selector
+     *  (keep to ONE compact row — bar height is stolen from the feed). */
+    aboveModeSelector?: React.ReactNode;
+    /** A compact action pinned right of the mode selector (Next/Break). */
+    modeRowTrailing?: React.ReactNode;
+    /** Extra tiles appended to the options grid. */
+    optionTiles?: CaptureOptionTile[];
+    /** Extra entries in the mode row after UPLOAD (e.g. SCAN). Selecting one
+     *  is an immediate host action — the chrome keeps its current mode. */
+    extraModes?: {
+        id: string;
+        label: string;
+        onSelect: () => void;
+    }[];
+    /** Free overlays rendered above everything (sheets, pagers). */
+    overlays?: React.ReactNode;
+}
+
+export type { CaptureAspect, CaptureCameraEngine, CaptureCameraMode, CaptureCameraSlots, CaptureCloudPort, CaptureOptionTile, CaptureTimerSetting };

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}