@chipmobilesdk/rn-camera 0.1.0

package/src/diagnostics/logger.ts

@@ -0,0 +1,31 @@
+/**
+ * Optional consumer-supplied logger (research R4).
+ *
+ * The default is no logging at all, so FR-038 holds whether or not a consumer
+ * opts in. Event bodies carry codes and states only — never file paths, never
+ * image data — so an opted-in logger still cannot leak an image path.
+ */
+
+export type CameraLogEventType =
+	| 'session'
+	| 'permission'
+	| 'capture'
+	| 'capability'
+	| 'cleanup';
+
+export interface CameraLogEvent {
+	readonly type: CameraLogEventType;
+	readonly code: string;
+	readonly recoverable?: boolean;
+}
+
+export interface CameraLogger {
+	log(event: CameraLogEvent): void;
+}
+
+/** No-op logger used when the consumer supplies none. */
+export const silentLogger: CameraLogger = {
+	log() {
+		// Intentionally empty: logging is opt-in.
+	},
+};

package/src/geometry/coordinateMapping.ts

@@ -0,0 +1,129 @@
+/**
+ * Bidirectional coordinate mapping between preview space and captured-image
+ * space (FR-036, SC-012).
+ *
+ * Pure functions with no native involvement (research R5). Everything needed is
+ * already known in JavaScript, so keeping this pure is what makes the 2-pixel
+ * round-trip tolerance verifiable in CI rather than only on a device.
+ *
+ * Composition order, preview -> image: undo mirror, undo letterbox/crop offset,
+ * undo scale, undo orientation. Image -> preview reverses it exactly.
+ */
+
+import type { Point, PreviewGeometry, Rect } from '../config/types';
+
+/** Orientation rotates the image for display, swapping dimensions at 90/270. */
+function isQuarterTurn(orientation: number): boolean {
+	const normalized = ((orientation % 360) + 360) % 360;
+	return normalized === 90 || normalized === 270;
+}
+
+function normalizeOrientation(orientation: number): 0 | 90 | 180 | 270 {
+	const normalized = ((Math.round(orientation / 90) * 90) % 360 + 360) % 360;
+	return normalized as 0 | 90 | 180 | 270;
+}
+
+interface Projection {
+	readonly scale: number;
+	readonly offsetX: number;
+	readonly offsetY: number;
+	/** Image dimensions as displayed, after orientation. */
+	readonly displayWidth: number;
+	readonly displayHeight: number;
+}
+
+function projection(geometry: PreviewGeometry): Projection {
+	const swap = isQuarterTurn(geometry.orientation);
+	const displayWidth = swap ? geometry.imageHeight : geometry.imageWidth;
+	const displayHeight = swap ? geometry.imageWidth : geometry.imageHeight;
+
+	const scaleX = geometry.previewWidth / displayWidth;
+	const scaleY = geometry.previewHeight / displayHeight;
+	// `cover` fills and crops the overflow; `contain` fits and letterboxes.
+	const scale =
+		geometry.resizeMode === 'cover' ? Math.max(scaleX, scaleY) : Math.min(scaleX, scaleY);
+
+	return {
+		scale,
+		// Negative under `cover` (cropped away), positive under `contain`
+		// (letterbox bands). The same arithmetic covers both.
+		offsetX: (geometry.previewWidth - displayWidth * scale) / 2,
+		offsetY: (geometry.previewHeight - displayHeight * scale) / 2,
+		displayWidth,
+		displayHeight,
+	};
+}
+
+/** Display-space point -> original image point, undoing the rotation. */
+function unrotate(point: Point, geometry: PreviewGeometry): Point {
+	switch (normalizeOrientation(geometry.orientation)) {
+		case 90:
+			return { x: point.y, y: geometry.imageHeight - point.x };
+		case 180:
+			return { x: geometry.imageWidth - point.x, y: geometry.imageHeight - point.y };
+		case 270:
+			return { x: geometry.imageWidth - point.y, y: point.x };
+		default:
+			return point;
+	}
+}
+
+/** Original image point -> display-space point, applying the rotation. */
+function rotate(point: Point, geometry: PreviewGeometry): Point {
+	switch (normalizeOrientation(geometry.orientation)) {
+		case 90:
+			return { x: geometry.imageHeight - point.y, y: point.x };
+		case 180:
+			return { x: geometry.imageWidth - point.x, y: geometry.imageHeight - point.y };
+		case 270:
+			return { x: point.y, y: geometry.imageWidth - point.x };
+		default:
+			return point;
+	}
+}
+
+/**
+ * Maps a preview-space point into captured-image space. Points outside the
+ * visible region stay representable (they fall outside the image bounds) rather
+ * than being clamped to an edge, so callers can detect an out-of-frame overlay.
+ */
+export function mapPointToImage(point: Point, geometry: PreviewGeometry): Point {
+	const { scale, offsetX, offsetY } = projection(geometry);
+	const x = geometry.isMirrored ? geometry.previewWidth - point.x : point.x;
+	return unrotate({ x: (x - offsetX) / scale, y: (point.y - offsetY) / scale }, geometry);
+}
+
+/** Maps a captured-image point into preview space. Exact inverse of the above. */
+export function mapPointToPreview(point: Point, geometry: PreviewGeometry): Point {
+	const { scale, offsetX, offsetY } = projection(geometry);
+	const rotated = rotate(point, geometry);
+	const x = rotated.x * scale + offsetX;
+	return {
+		x: geometry.isMirrored ? geometry.previewWidth - x : x,
+		y: rotated.y * scale + offsetY,
+	};
+}
+
+/** Axis-aligned bounding box of the mapped corners — exact for quarter turns. */
+function boundsOf(a: Point, b: Point): Rect {
+	return {
+		x: Math.min(a.x, b.x),
+		y: Math.min(a.y, b.y),
+		width: Math.abs(b.x - a.x),
+		height: Math.abs(b.y - a.y),
+	};
+}
+
+export function mapRectToImage(rect: Rect, geometry: PreviewGeometry): Rect {
+	return boundsOf(
+		mapPointToImage({ x: rect.x, y: rect.y }, geometry),
+		mapPointToImage({ x: rect.x + rect.width, y: rect.y + rect.height }, geometry),
+	);
+}
+
+export function mapRectToPreview(rect: Rect, geometry: PreviewGeometry): Rect {
+	return boundsOf(
+		mapPointToPreview({ x: rect.x, y: rect.y }, geometry),
+		mapPointToPreview({ x: rect.x + rect.width, y: rect.y + rect.height }, geometry),
+	);
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @chipmobilesdk/rn-camera — reusable camera infrastructure for
+ * ChipMobileSdk-family React Native apps.
+ *
+ * This is the single public entrypoint (LIB-003). Modules under `core/`,
+ * `native/`, `permissions/`, `storage/`, `geometry/`, `diagnostics/`, and
+ * `testing/` are private; import them only through this file.
+ *
+ * The package contains no business logic, sends nothing over the network, and
+ * writes nothing to the device gallery. Phase one runs no on-device inference —
+ * see the reserved frame-processing extension point in the README.
+ */
+
+// Public types
+export type {
+	ArtifactOwnership,
+	CameraErrorLike,
+	CameraPermissionState,
+	CameraPosition,
+	CameraState,
+	CapabilityProfile,
+	CapturedImage,
+	CaptureRequest,
+	FlashMode,
+	Known,
+	Maybe,
+	Point,
+	PreviewGeometry,
+	Rect,
+	ResizeMode,
+	SessionStatus,
+	StartOptions,
+	Unavailable,
+} from './config/types';
+export { known, unavailable } from './config/types';
+
+// Controller
+export { createCameraController, DEFAULT_TEMPORARY_TTL_MS } from './core/controller';
+export type {
+	AppStatus,
+	CameraController,
+	CameraControllerOptions,
+} from './core/controller';
+
+// Ports + default adapters
+export type { CameraEngine, EngineOptions } from './native/cameraEngine';
+export { createVisionCameraEngine } from './native/cameraEngine';
+export type { PermissionPort } from './permissions/permissionPort';
+export { createVisionCameraPermissions } from './permissions/permissionPort';
+export type { ArtifactStore, FileSystemBridge, StoreOptions } from './storage/artifactStore';
+export { createArtifactStore, createCacheArtifactStore } from './storage/artifactStore';
+
+// React surface
+export { CameraPreview } from './react/CameraPreview';
+export type { CameraPreviewProps } from './react/CameraPreview';
+export { useCameraController, useCameraState } from './react/hooks';
+
+// Coordinate mapping (pure)
+export {
+	mapPointToImage,
+	mapPointToPreview,
+	mapRectToImage,
+	mapRectToPreview,
+} from './geometry/coordinateMapping';
+
+// Diagnostics
+export { CameraError, isCameraError, redact } from './diagnostics/errors';
+export type { CameraErrorCode } from './diagnostics/errors';
+export type { CameraLogEvent, CameraLogEventType, CameraLogger } from './diagnostics/logger';
+
+// Test adapter (FR-041) — exported from the single entrypoint so consumer tests
+// exercise the same published ports the real adapters implement.
+export { createTestCamera, createMemoryFileSystem, DEFAULT_TEST_CAPABILITIES } from './testing/testCameraAdapter';
+export type {
+	MemoryFileSystem,
+	TestCameraConfig,
+	TestCameraHandles,
+} from './testing/testCameraAdapter';

package/src/native/cameraEngine.ts

@@ -0,0 +1,113 @@
+/**
+ * CameraEngine port + default react-native-vision-camera adapter.
+ *
+ * This is the only module that knows a native camera library exists. The
+ * default adapter lazily requires it, mirroring
+ * `packages/rn-auth/src/tokens/secureStore.ts`, so unit tests that inject a
+ * fake never load native code.
+ *
+ * Preview frames never cross this boundary: `capture` returns a file reference
+ * plus metadata and nothing else (PERF-002, FR-021a).
+ *
+ * Targets the VisionCamera v5 API, where devices come from an async
+ * `CameraDeviceFactory` and capture runs through the photo output owned by the
+ * mounted preview surface (see `visionSurface`).
+ */
+
+import type {
+	CapabilityProfile,
+	CapturedImage,
+	CaptureRequest,
+	StartOptions,
+} from '../config/types';
+import { CameraError } from '../diagnostics/errors';
+import { getActiveVisionSurface } from './visionSurface';
+
+export interface CameraEngine {
+	start(options: StartOptions): Promise<void>;
+	stop(): Promise<void>;
+	capture(request: CaptureRequest): Promise<CapturedImage>;
+	setTorch(enabled: boolean): Promise<void>;
+	getCapabilities(): Promise<CapabilityProfile>;
+}
+
+export interface EngineOptions {
+	/** Overrides device discovery. Primarily an escape hatch for diagnostics. */
+	readonly preferredPosition?: 'front' | 'back';
+}
+
+/** The subset of VisionCamera's `CameraDevice` this adapter reads. */
+interface DiscoveredDevice {
+	readonly position?: string;
+	readonly hasFlash?: boolean;
+	readonly hasTorch?: boolean;
+}
+
+/**
+ * Default engine. VisionCamera drives the preview through its own React
+ * component, so this adapter owns capability discovery while `CameraPreview`
+ * owns the rendered surface and the photo output that capture runs through.
+ */
+export function createVisionCameraEngine(_options: EngineOptions = {}): CameraEngine {
+	// Lazy require: only loaded when the default adapter is actually used.
+	const { VisionCamera } = require('react-native-vision-camera');
+
+	// The factory is created once and reused: it keeps its own device list up to
+	// date, so re-creating it per call would only add latency.
+	let factory: Promise<{ readonly cameraDevices: DiscoveredDevice[] }> | null = null;
+
+	async function devices(): Promise<readonly DiscoveredDevice[]> {
+		factory ??= VisionCamera.createDeviceFactory();
+		return (await factory)?.cameraDevices ?? [];
+	}
+
+	return {
+		async start() {
+			// The preview component owns session activation; the engine only needs
+			// to confirm a device exists before the surface mounts.
+			const available = await devices();
+			if (available.length === 0) {
+				throw new CameraError('cameraUnavailable', 'No camera device is available');
+			}
+		},
+
+		async stop() {
+			// Teardown is driven by unmounting the preview surface.
+		},
+
+		async capture(request: CaptureRequest) {
+			const surface = getActiveVisionSurface();
+			if (!surface) {
+				throw new CameraError(
+					'notReady',
+					'The default VisionCamera engine captures through the CameraPreview ' +
+						'surface. Mount <CameraPreview> before calling capture().',
+				);
+			}
+			return surface.capture(request);
+		},
+
+		async setTorch() {
+			// Torch is a preview-surface prop; the controller mirrors the state and
+			// CameraPreview applies it.
+		},
+
+		async getCapabilities(): Promise<CapabilityProfile> {
+			const available = await devices();
+			const positions = Array.from(
+				new Set(
+					available
+						.map(device => device.position)
+						.filter((p): p is 'front' | 'back' => p === 'front' || p === 'back'),
+				),
+			);
+			return {
+				availablePositions: positions,
+				hasFlash: available.some(device => device.hasFlash === true),
+				hasTorch: available.some(device => device.hasTorch === true),
+				supportsOrientationChange: true,
+				hasCameraHardware: available.length > 0,
+			};
+		},
+	};
+}

package/src/native/visionSurface.ts

@@ -0,0 +1,34 @@
+/**
+ * Bridge between the mounted VisionCamera preview surface and the default
+ * engine adapter.
+ *
+ * VisionCamera v5 owns capture through the session that the `<Camera>` view
+ * configures, so the photo output only exists while a surface is mounted. The
+ * engine is created by the app before any surface exists, so the surface
+ * registers itself here on mount and the engine reads it back at capture time.
+ *
+ * A single registration slot is deliberate: one camera session can be active at
+ * a time, so a second surface replacing the first is the correct behaviour.
+ */
+
+import type { CapturedImage, CaptureRequest } from '../config/types';
+
+export interface VisionSurface {
+	capture(request: CaptureRequest): Promise<CapturedImage>;
+}
+
+let active: VisionSurface | null = null;
+
+/** Registers the mounted surface. Returns an unregister function. */
+export function registerVisionSurface(surface: VisionSurface): () => void {
+	active = surface;
+	return () => {
+		if (active === surface) {
+			active = null;
+		}
+	};
+}
+
+export function getActiveVisionSurface(): VisionSurface | null {
+	return active;
+}

package/src/permissions/permissionPort.ts

@@ -0,0 +1,115 @@
+/**
+ * PermissionPort + default react-native-vision-camera adapter (FR-004..FR-008).
+ *
+ * `getStatus` never prompts and never opens a session (FR-005); only `request`
+ * may prompt, and it refuses to re-prompt once the OS reports a permanent
+ * denial (FR-006). The default adapter lazily requires the native module so
+ * unit tests that inject a fake never load native code — same approach as
+ * `packages/rn-auth/src/tokens/secureStore.ts`.
+ *
+ * The adapter targets the VisionCamera v5 API: permissions live on the
+ * `VisionCamera` hybrid object, not on the `Camera` component (which carries no
+ * statics since v5).
+ */
+
+import type { CameraPermissionState } from '../config/types';
+
+export interface PermissionPort {
+	/** Reads current status. MUST NOT prompt or start a session (FR-005). */
+	getStatus(): Promise<CameraPermissionState>;
+	/** Explicitly requests permission (FR-006). */
+	request(): Promise<CameraPermissionState>;
+	/** Notifies on external changes, e.g. revocation in Settings (FR-007). */
+	subscribe(listener: (state: CameraPermissionState) => void): () => void;
+}
+
+/**
+ * VisionCamera `PermissionStatus` mapped onto our seven-state contract.
+ *
+ * `not-determined` also covers "denied once, but the app may ask again" on
+ * Android, which is exactly the state where re-prompting is allowed, so it maps
+ * to `undetermined` rather than `denied`.
+ */
+function mapStatus(raw: string): CameraPermissionState {
+	switch (raw) {
+		case 'authorized':
+			return 'granted';
+		case 'not-determined':
+			return 'undetermined';
+		case 'denied':
+			return 'deniedPermanently';
+		case 'restricted':
+			return 'deniedPermanently';
+		default:
+			return 'unsupported';
+	}
+}
+
+export function createVisionCameraPermissions(): PermissionPort {
+	// Lazy require: only loaded when the default adapter is actually used.
+	const { VisionCamera } = require('react-native-vision-camera');
+	const { AppState } = require('react-native');
+	const listeners = new Set<(state: CameraPermissionState) => void>();
+	let last: CameraPermissionState | null = null;
+	let appStateSubscription: { remove(): void } | null = null;
+
+	function read(): CameraPermissionState {
+		try {
+			return mapStatus(VisionCamera.cameraPermissionStatus);
+		} catch {
+			// The native module is unreachable; report it rather than pretending
+			// the permission is merely undetermined.
+			return 'unsupported';
+		}
+	}
+
+	function emit(state: CameraPermissionState): CameraPermissionState {
+		if (state !== last) {
+			last = state;
+			for (const listener of listeners) {
+				listener(state);
+			}
+		}
+		return state;
+	}
+
+	return {
+		async getStatus() {
+			return emit(read());
+		},
+
+		async request() {
+			// Never re-prompt after a permanent denial (FR-006); report the
+			// settings-required state instead so the app can route the user.
+			const current = read();
+			if (current === 'deniedPermanently') {
+				return emit(current);
+			}
+			await VisionCamera.requestCameraPermission();
+			// Re-read rather than trusting the boolean result: the status carries
+			// the richer distinction the contract needs.
+			return emit(read());
+		},
+
+		subscribe(listener) {
+			listeners.add(listener);
+			// Grants and revocations made in system Settings send the app through
+			// background/foreground, so re-reading on foreground is what surfaces
+			// them (FR-007). Attached only while somebody is listening.
+			if (!appStateSubscription) {
+				appStateSubscription = AppState.addEventListener('change', (next: string) => {
+					if (next === 'active') {
+						emit(read());
+					}
+				});
+			}
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size === 0 && appStateSubscription) {
+					appStateSubscription.remove();
+					appStateSubscription = null;
+				}
+			};
+		},
+	};
+}

package/src/react/CameraPreview.tsx

@@ -0,0 +1,120 @@
+/**
+ * Camera preview surface (FR-009..FR-013, UX-001, UX-003).
+ *
+ * Renders the camera feed and nothing else: no shutter button, no permission
+ * copy, no error text, and no theme dependency. Consuming apps draw their own
+ * controls and overlays through `children`, positioned with the geometry
+ * reported by `onGeometryChange`.
+ */
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+	View,
+	type AccessibilityRole,
+	type LayoutChangeEvent,
+	type StyleProp,
+	type ViewStyle,
+} from 'react-native';
+
+import type { PreviewGeometry, ResizeMode } from '../config/types';
+import type { CameraController } from '../core/controller';
+import type { VisionCameraFeedProps } from './VisionCameraFeed';
+
+export interface CameraPreviewProps {
+	readonly controller: CameraController;
+	readonly resizeMode?: ResizeMode;
+	readonly style?: StyleProp<ViewStyle>;
+	readonly onGeometryChange?: (geometry: PreviewGeometry) => void;
+	/** Forwarded untouched; the package never overrides consumer a11y (UX-003). */
+	readonly accessibilityLabel?: string;
+	readonly accessibilityRole?: AccessibilityRole;
+	/** Overlay layer rendered above the feed. */
+	readonly children?: React.ReactNode;
+}
+
+/** Nominal capture dimensions until the engine reports the real format. */
+const DEFAULT_IMAGE_WIDTH = 1920;
+const DEFAULT_IMAGE_HEIGHT = 1080;
+
+export const CameraPreview: React.FC<CameraPreviewProps> = ({
+	controller,
+	resizeMode = 'cover',
+	style,
+	onGeometryChange,
+	accessibilityLabel,
+	accessibilityRole,
+	children,
+}) => {
+	const [layout, setLayout] = useState<{ width: number; height: number } | null>(null);
+	const state = controller.state;
+
+	// Tell the controller a surface exists so foregrounding can restart the
+	// session, and clear it on unmount so the camera is released (FR-016).
+	useEffect(() => {
+		controller.setSurfaceMounted(true);
+		return () => {
+			controller.setSurfaceMounted(false);
+			controller.stop().catch(() => undefined);
+		};
+	}, [controller]);
+
+	const onLayout = useCallback((event: LayoutChangeEvent) => {
+		const { width, height } = event.nativeEvent.layout;
+		setLayout({ width, height });
+	}, []);
+
+	const geometry = useMemo<PreviewGeometry | null>(() => {
+		if (!layout || layout.width === 0 || layout.height === 0) {
+			return null;
+		}
+		return {
+			imageWidth: DEFAULT_IMAGE_WIDTH,
+			imageHeight: DEFAULT_IMAGE_HEIGHT,
+			previewWidth: layout.width,
+			previewHeight: layout.height,
+			resizeMode,
+			orientation: 0,
+			isMirrored: state.cameraPosition === 'front',
+		};
+	}, [layout, resizeMode, state.cameraPosition]);
+
+	useEffect(() => {
+		if (geometry && onGeometryChange) {
+			onGeometryChange(geometry);
+		}
+	}, [geometry, onGeometryChange]);
+
+	const feedRequested = state.session === 'active' && state.permission === 'granted';
+
+	// Lazy require so importing this package never pulls in the native module
+	// for consumers that only use the pure utilities or the test adapter.
+	const Feed = useMemo(() => {
+		if (!feedRequested) {
+			return null;
+		}
+		try {
+			return require('./VisionCameraFeed')
+				.VisionCameraFeed as React.ComponentType<VisionCameraFeedProps>;
+		} catch {
+			return null;
+		}
+	}, [feedRequested]);
+
+	return (
+		<View
+			style={style}
+			onLayout={onLayout}
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole={accessibilityRole}
+			testID="rn-camera-preview">
+			{Feed ? (
+				<Feed
+					cameraPosition={state.cameraPosition}
+					resizeMode={resizeMode}
+					torchEnabled={state.torchEnabled}
+				/>
+			) : null}
+			{children}
+		</View>
+	);
+};