@chipmobilesdk/rn-camera 0.1.0

package/src/react/VisionCameraFeed.tsx

@@ -0,0 +1,155 @@
+/**
+ * The live VisionCamera surface rendered inside `CameraPreview`.
+ *
+ * Split into its own module so `CameraPreview` can require it lazily: consumers
+ * that only use the pure utilities or the test adapter never load the native
+ * module, while the hooks this component needs (`useCameraDevice`,
+ * `usePhotoOutput`) can still be called normally.
+ *
+ * It also owns capture. In VisionCamera v5 the photo output belongs to the
+ * session the `<Camera>` view configures, so the output only exists while this
+ * surface is mounted; it is published to the engine through `visionSurface`.
+ */
+
+import React, { useEffect, useMemo } from 'react';
+import { StyleSheet } from 'react-native';
+import {
+	Camera,
+	useCameraDevice,
+	usePhotoOutput,
+	type CameraPhotoOutput,
+} from 'react-native-vision-camera';
+
+import {
+	known,
+	unavailable,
+	type CameraPosition,
+	type CapturedImage,
+	type CaptureRequest,
+	type ResizeMode,
+} from '../config/types';
+import { clampMaxDimension, clampQuality } from '../core/captureController';
+import { CameraError } from '../diagnostics/errors';
+import { registerVisionSurface } from '../native/visionSurface';
+
+export interface VisionCameraFeedProps {
+	readonly cameraPosition: CameraPosition;
+	readonly resizeMode: ResizeMode;
+	readonly torchEnabled: boolean;
+}
+
+const styles = StyleSheet.create({
+	feed: { flex: 1 },
+});
+
+const MIME_TYPES: Record<string, string> = {
+	jpeg: 'image/jpeg',
+	heic: 'image/heic',
+	dng: 'image/x-adobe-dng',
+	tiff: 'image/tiff',
+};
+
+/** VisionCamera reports orientation as a compass value; the contract wants degrees. */
+const ORIENTATION_DEGREES: Record<string, number> = {
+	up: 0,
+	right: 90,
+	down: 180,
+	left: 270,
+};
+
+function toFileUri(path: string): string {
+	return path.startsWith('file://') ? path : `file://${path}`;
+}
+
+function toFilePath(uri: string): string {
+	return uri.startsWith('file://') ? uri.slice('file://'.length) : uri;
+}
+
+async function capturePhoto(
+	photoOutput: CameraPhotoOutput,
+	request: CaptureRequest,
+	cameraPosition: CameraPosition,
+): Promise<CapturedImage> {
+	const photo = await photoOutput.capturePhoto(
+		{ flashMode: request.flashMode ?? 'off' },
+		{},
+	);
+	try {
+		// A destination makes the artifact app-owned, so it is written straight
+		// there; otherwise it goes to a temporary file (FR-026a).
+		let path: string;
+		if (request.destination) {
+			try {
+				await photo.saveToFileAsync(toFilePath(request.destination));
+			} catch (error) {
+				throw new CameraError(
+					'storageFailure',
+					`Could not write the capture to the requested destination: ${
+						error instanceof Error ? error.message : 'unknown error'
+					}`,
+				);
+			}
+			path = request.destination;
+		} else {
+			path = await photo.saveToTemporaryFileAsync();
+		}
+
+		return {
+			uri: toFileUri(path),
+			mimeType: MIME_TYPES[photo.containerFormat] ?? 'application/octet-stream',
+			width: photo.width,
+			height: photo.height,
+			timestamp: Date.now(),
+			cameraPosition: request.cameraPosition ?? cameraPosition,
+			// Ownership is decided by the controller from the original request;
+			// this value is overwritten there and is only a safe default.
+			ownership: request.destination ? 'appOwned' : 'packageTemporary',
+			effectiveQuality: clampQuality(request.quality),
+			effectiveMaxDimension: clampMaxDimension(request.maxDimension),
+			// The native layer reports neither back after a save, and guessing them
+			// would be worse than saying so (FR-022).
+			fileSize: unavailable(),
+			orientation:
+				photo.orientation in ORIENTATION_DEGREES
+					? known(ORIENTATION_DEGREES[photo.orientation])
+					: unavailable(),
+		};
+	} finally {
+		// Large native buffers must not wait for the JS GC.
+		photo.dispose();
+	}
+}
+
+export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
+	cameraPosition,
+	resizeMode,
+	torchEnabled,
+}) => {
+	const device = useCameraDevice(cameraPosition);
+	const photoOutput = usePhotoOutput();
+
+	const surface = useMemo(
+		() => ({
+			capture: (request: CaptureRequest) =>
+				capturePhoto(photoOutput, request, cameraPosition),
+		}),
+		[photoOutput, cameraPosition],
+	);
+
+	useEffect(() => registerVisionSurface(surface), [surface]);
+
+	if (!device) {
+		return null;
+	}
+
+	return (
+		<Camera
+			style={styles.feed}
+			device={device}
+			outputs={[photoOutput]}
+			isActive={true}
+			resizeMode={resizeMode}
+			torchMode={torchEnabled ? 'on' : 'off'}
+		/>
+	);
+};

package/src/react/hooks.ts

@@ -0,0 +1,44 @@
+/**
+ * React bindings for the camera controller.
+ *
+ * `useCameraController` owns the controller lifetime and disposes it on
+ * unmount, which is what guarantees the camera is released when a screen goes
+ * away (FR-016).
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import type { CameraState } from '../config/types';
+import {
+	createCameraController,
+	type CameraController,
+	type CameraControllerOptions,
+} from '../core/controller';
+
+export function useCameraController(
+	options: CameraControllerOptions = {},
+): CameraController {
+	// Options usually arrive as a fresh object literal each render; capturing
+	// them in a ref keeps the controller stable for the component's lifetime.
+	const optionsRef = useRef(options);
+	const controller = useMemo(() => createCameraController(optionsRef.current), []);
+
+	useEffect(() => {
+		return () => {
+			controller.dispose().catch(() => undefined);
+		};
+	}, [controller]);
+
+	return controller;
+}
+
+export function useCameraState(controller: CameraController): CameraState {
+	const [state, setState] = useState<CameraState>(controller.state);
+
+	useEffect(() => {
+		setState(controller.state);
+		return controller.subscribe(setState);
+	}, [controller]);
+
+	return state;
+}

package/src/storage/artifactStore.ts

@@ -0,0 +1,108 @@
+/**
+ * ArtifactStore port + default cache-directory adapter (FR-026..FR-029).
+ *
+ * Package-owned artifacts live in a dedicated `rn-camera` subdirectory of the
+ * platform cache directory (research R6). That dedicated prefix is what makes
+ * ownership checkable rather than advisory: `owns()` is a path-prefix test, so
+ * the package can refuse to delete anything it did not create (FR-028).
+ */
+
+export interface ArtifactStore {
+	/** Absolute path of the package-owned temporary directory. */
+	temporaryDirectory(): string;
+	/** True only for paths the package created (FR-028). */
+	owns(uri: string): boolean;
+	/** Deletes an artifact. Resolves even if already gone (FR-027). */
+	remove(uri: string): Promise<void>;
+	/** Deletes owned artifacts older than `olderThanMs`; returns the count. */
+	sweep(olderThanMs: number): Promise<number>;
+}
+
+/** Minimal filesystem surface the adapter needs. Injectable for tests. */
+export interface FileSystemBridge {
+	cacheDirectory(): string;
+	exists(path: string): Promise<boolean>;
+	unlink(path: string): Promise<void>;
+	list(directory: string): Promise<readonly string[]>;
+	createdAt(path: string): Promise<number>;
+	ensureDirectory(directory: string): Promise<void>;
+}
+
+export interface StoreOptions {
+	readonly fs?: FileSystemBridge;
+	/** Directory name under the cache directory. Defaults to `rn-camera`. */
+	readonly directoryName?: string;
+}
+
+/** Normalizes separators so prefix comparison works on both platforms. */
+function normalize(path: string): string {
+	return path.replace(/\\/g, '/').replace(/^file:\/\//, '');
+}
+
+export function createArtifactStore(
+	fs: FileSystemBridge,
+	directoryName = 'rn-camera',
+): ArtifactStore {
+	const root = `${fs.cacheDirectory().replace(/\/$/, '')}/${directoryName}`;
+	const normalizedRoot = normalize(root);
+	// Artifacts created by this process are never swept, no matter their age.
+	const createdThisProcess = new Set<string>();
+
+	return {
+		temporaryDirectory() {
+			return root;
+		},
+
+		owns(uri) {
+			return normalize(uri).startsWith(`${normalizedRoot}/`);
+		},
+
+		async remove(uri) {
+			if (!this.owns(uri)) {
+				return;
+			}
+			const path = normalize(uri);
+			// Idempotent: a missing artifact is a successful cleanup (FR-027).
+			if (await fs.exists(path)) {
+				await fs.unlink(path);
+			}
+			createdThisProcess.delete(path);
+		},
+
+		async sweep(olderThanMs) {
+			await fs.ensureDirectory(root);
+			const entries = await fs.list(root);
+			const cutoff = Date.now() - olderThanMs;
+			let removed = 0;
+
+			for (const entry of entries) {
+				const path = normalize(entry);
+				if (createdThisProcess.has(path)) {
+					continue;
+				}
+				const created = await fs.createdAt(path);
+				if (created < cutoff) {
+					await fs.unlink(path);
+					removed += 1;
+				}
+			}
+			return removed;
+		},
+	};
+}
+
+/**
+ * Default adapter. The concrete filesystem bridge is supplied by the native
+ * layer at runtime; it is a parameter rather than a hard import so the package
+ * takes no filesystem dependency of its own.
+ */
+export function createCacheArtifactStore(options: StoreOptions = {}): ArtifactStore {
+	const fs = options.fs;
+	if (!fs) {
+		throw new Error(
+			'createCacheArtifactStore requires a FileSystemBridge. Pass `fs`, or use ' +
+				'createTestCamera() in tests.',
+		);
+	}
+	return createArtifactStore(fs, options.directoryName);
+}

package/src/testing/testCameraAdapter.ts

@@ -0,0 +1,249 @@
+/**
+ * Deterministic in-memory camera for tests (FR-041, SC-010).
+ *
+ * These are real implementations of the same published ports the production
+ * adapters implement, not a parallel mock — so a contract change breaks them at
+ * compile time and they cannot drift. Nothing here touches a native module, the
+ * filesystem, or a permission API.
+ */
+
+import {
+	known,
+	unavailable,
+	type CameraPermissionState,
+	type CameraPosition,
+	type CapabilityProfile,
+	type CapturedImage,
+	type CaptureRequest,
+} from '../config/types';
+import { CameraError, type CameraErrorCode } from '../diagnostics/errors';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+import {
+	createArtifactStore,
+	type ArtifactStore,
+	type FileSystemBridge,
+} from '../storage/artifactStore';
+import type { AppStatus } from '../core/controller';
+
+export interface MemoryFileSystem extends FileSystemBridge {
+	/** Seeds a file with an explicit creation time, for time-to-live tests. */
+	seed(path: string, createdAtMs: number): void;
+	/** Every path currently present. */
+	paths(): readonly string[];
+}
+
+export function createMemoryFileSystem(root = '/cache'): MemoryFileSystem {
+	const files = new Map<string, number>();
+	const directories = new Set<string>();
+
+	return {
+		cacheDirectory: () => root,
+		async exists(path) {
+			return files.has(path);
+		},
+		async unlink(path) {
+			files.delete(path);
+		},
+		async list(directory) {
+			const prefix = `${directory.replace(/\/$/, '')}/`;
+			return Array.from(files.keys()).filter(path => path.startsWith(prefix));
+		},
+		async createdAt(path) {
+			return files.get(path) ?? Date.now();
+		},
+		async ensureDirectory(directory) {
+			directories.add(directory);
+		},
+		seed(path, createdAtMs) {
+			files.set(path, createdAtMs);
+		},
+		paths: () => Array.from(files.keys()),
+	};
+}
+
+export const DEFAULT_TEST_CAPABILITIES: CapabilityProfile = {
+	availablePositions: ['back', 'front'],
+	hasFlash: true,
+	hasTorch: true,
+	supportsOrientationChange: true,
+	hasCameraHardware: true,
+};
+
+export interface TestCameraConfig {
+	readonly permission?: CameraPermissionState;
+	readonly capabilities?: Partial<CapabilityProfile>;
+	readonly captureResult?: Partial<CapturedImage>;
+	readonly captureError?: CameraErrorCode;
+	readonly startError?: CameraErrorCode;
+	readonly cacheRoot?: string;
+}
+
+export interface TestCameraHandles {
+	readonly engine: CameraEngine;
+	readonly permissions: PermissionPort;
+	readonly store: ArtifactStore;
+	readonly fs: MemoryFileSystem;
+	/** Drives the controller's app foreground/background handling. */
+	subscribeToAppState(listener: (status: AppStatus) => void): () => void;
+	setAppState(status: AppStatus): void;
+	/** Simulates a Settings-level permission change while running (FR-007). */
+	setPermission(state: CameraPermissionState): void;
+	/** Simulates an OS preemption such as an incoming call. */
+	emitInterruption(): void;
+	setCaptureError(code: CameraErrorCode | null): void;
+	setStartError(code: CameraErrorCode | null): void;
+	/** Every capture the engine produced, in order. */
+	captures(): readonly CapturedImage[];
+	torchState(): boolean;
+	startCount(): number;
+	stopCount(): number;
+}
+
+export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandles {
+	const fs = createMemoryFileSystem(config.cacheRoot ?? '/cache');
+	const store = createArtifactStore(fs);
+	const capabilities: CapabilityProfile = {
+		...DEFAULT_TEST_CAPABILITIES,
+		...config.capabilities,
+	};
+
+	let permission: CameraPermissionState = config.permission ?? 'undetermined';
+	let captureError: CameraErrorCode | null = config.captureError ?? null;
+	let startError: CameraErrorCode | null = config.startError ?? null;
+	let torch = false;
+	let starts = 0;
+	let stops = 0;
+	let sequence = 0;
+
+	const produced: CapturedImage[] = [];
+	const permissionListeners = new Set<(state: CameraPermissionState) => void>();
+	const appStateListeners = new Set<(status: AppStatus) => void>();
+	const interruptionListeners = new Set<() => void>();
+
+	const permissions: PermissionPort = {
+		async getStatus() {
+			return permission;
+		},
+		async request() {
+			// Mirrors the real adapter: never re-prompt after a permanent denial.
+			if (permission === 'deniedPermanently') {
+				return permission;
+			}
+			permission = permission === 'undetermined' || permission === 'denied' ? 'granted' : permission;
+			for (const listener of permissionListeners) {
+				listener(permission);
+			}
+			return permission;
+		},
+		subscribe(listener) {
+			permissionListeners.add(listener);
+			return () => {
+				permissionListeners.delete(listener);
+			};
+		},
+	};
+
+	const engine: CameraEngine = {
+		async start() {
+			starts += 1;
+			if (startError) {
+				throw new CameraError(startError);
+			}
+			if (!capabilities.hasCameraHardware) {
+				throw new CameraError('cameraUnavailable');
+			}
+		},
+
+		async stop() {
+			stops += 1;
+			torch = false;
+		},
+
+		async capture(request: CaptureRequest) {
+			if (captureError) {
+				throw new CameraError(captureError);
+			}
+			sequence += 1;
+			const position: CameraPosition = request.cameraPosition ?? 'back';
+			const uri =
+				request.destination ?? `${store.temporaryDirectory()}/capture-${sequence}.jpg`;
+			fs.seed(uri, Date.now());
+
+			const image: CapturedImage = {
+				uri,
+				mimeType: 'image/jpeg',
+				width: 1920,
+				height: 1080,
+				timestamp: Date.now(),
+				cameraPosition: position,
+				ownership: request.destination ? 'appOwned' : 'packageTemporary',
+				effectiveQuality: request.quality ?? 0.9,
+				effectiveMaxDimension:
+					request.maxDimension === undefined ? unavailable() : known(request.maxDimension),
+				fileSize: known(1024),
+				orientation: known(0),
+				...config.captureResult,
+			};
+			produced.push(image);
+			return image;
+		},
+
+		async setTorch(enabled: boolean) {
+			torch = enabled;
+		},
+
+		async getCapabilities() {
+			return capabilities;
+		},
+	};
+
+	return {
+		engine,
+		permissions,
+		store,
+		fs,
+
+		subscribeToAppState(listener) {
+			appStateListeners.add(listener);
+			return () => {
+				appStateListeners.delete(listener);
+			};
+		},
+
+		setAppState(status) {
+			for (const listener of appStateListeners) {
+				listener(status);
+			}
+		},
+
+		setPermission(state) {
+			permission = state;
+			for (const listener of permissionListeners) {
+				listener(state);
+			}
+		},
+
+		emitInterruption() {
+			for (const listener of interruptionListeners) {
+				listener();
+			}
+			// An interruption behaves like the OS taking the camera away: the next
+			// start attempt fails until the app clears it.
+			startError = 'interrupted';
+		},
+
+		setCaptureError(code) {
+			captureError = code;
+		},
+
+		setStartError(code) {
+			startError = code;
+		},
+
+		captures: () => produced,
+		torchState: () => torch,
+		startCount: () => starts,
+		stopCount: () => stops,
+	};
+}