@chipmobilesdk/rn-camera 0.2.0 → 0.3.0

package/src/react/hooks.ts

@@ -1,58 +1,56 @@
-/**
- * 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, useRef, useState, useSyncExternalStore } 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);
-	// Construction has no side effects (the controller subscribes on first use),
-	// so a controller React builds and discards here costs nothing.
-	const [controller, setController] = useState(() => createCameraController(optionsRef.current));
-	const disposedRef = useRef(new WeakSet<CameraController>());
-
-	useEffect(() => {
-		// StrictMode, and React's planned offscreen reuse, run the cleanup and then
-		// this effect again on the same component. Disposal is final, so the old
-		// controller cannot be revived; replace it. Before this, the screen kept a
-		// dead controller after the remount and the camera never started.
-		const disposed = disposedRef.current;
-		if (disposed.has(controller)) {
-			setController(createCameraController(optionsRef.current));
-			return undefined;
-		}
-		return () => {
-			disposed.add(controller);
-			controller.dispose().catch(() => undefined);
-		};
-	}, [controller]);
-
-	return controller;
-}
-
-export function useCameraState(controller: CameraController): CameraState {
-	// `subscribe` is a property of the controller object, so it is stable for the
-	// controller's lifetime, which is what useSyncExternalStore requires. The
-	// store read is tear-free, unlike the previous useState copy, which could
-	// miss a change made between render and effect.
-	return useSyncExternalStore(
-		controller.subscribe,
-		() => controller.state,
-		() => controller.state,
-	);
-}
+/**
+ * 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, useRef, useState, useSyncExternalStore } 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);
+	// Construction has no side effects (the controller subscribes on first use),
+	// so a controller React builds and discards here costs nothing.
+	const [controller, setController] = useState(() => createCameraController(optionsRef.current));
+	const disposedRef = useRef(new WeakSet<CameraController>());
+
+	useEffect(() => {
+		// StrictMode, and React's planned offscreen reuse, run the cleanup and then
+		// this effect again on the same component. Disposal is final, so the old
+		// controller cannot be revived; replace it. Before this, the screen kept a
+		// dead controller after the remount and the camera never started.
+		const disposed = disposedRef.current;
+		if (disposed.has(controller)) {
+			setController(createCameraController(optionsRef.current));
+			return undefined;
+		}
+		return () => {
+			disposed.add(controller);
+			controller.dispose().catch(() => undefined);
+		};
+	}, [controller]);
+
+	return controller;
+}
+
+export function useCameraState(controller: CameraController): CameraState {
+	// `subscribe` is a property of the controller object, so it is stable for the
+	// controller's lifetime, which is what useSyncExternalStore requires. The
+	// store read is tear-free, unlike the previous useState copy, which could
+	// miss a change made between render and effect.
+	return useSyncExternalStore(
+		controller.subscribe,
+		() => controller.state,
+		() => controller.state,
+	);
+}

package/src/storage/artifactStore.ts

@@ -1,141 +1,141 @@
-/**
- * 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>;
-	/**
-	 * Brings a fresh capture under the store and returns its managed URI: a file
-	 * already inside the store is recorded as created by this process, a file
-	 * anywhere else is moved in. Without this, a capture the engine wrote to its
-	 * own temporary directory is never owned, so `cleanup()` refuses it and the
-	 * sweep never sees it. Optional so app-written stores keep compiling.
-	 */
-	adopt?(uri: string): Promise<string>;
-}
-
-/** 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>;
-	/**
-	 * Moves a file. Needed by `adopt()` to pull a capture out of the engine's own
-	 * temporary directory; a bridge without it can only adopt files already
-	 * inside the store.
-	 */
-	move?(from: string, to: 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>();
-
-	function owns(uri: string): boolean {
-		return normalize(uri).startsWith(`${normalizedRoot}/`);
-	}
-
-	return {
-		temporaryDirectory() {
-			return root;
-		},
-
-		owns,
-
-		async remove(uri) {
-			if (!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;
-		},
-
-		async adopt(uri) {
-			const path = normalize(uri);
-			if (owns(uri)) {
-				createdThisProcess.add(path);
-				return uri;
-			}
-			if (!fs.move) {
-				throw new Error('This FileSystemBridge has no move(), so it cannot adopt a capture');
-			}
-			await fs.ensureDirectory(root);
-			const name = path.slice(path.lastIndexOf('/') + 1) || `capture-${Date.now()}.jpg`;
-			const target = `${root}/${name}`;
-			await fs.move(path, target);
-			createdThisProcess.add(normalize(target));
-			return uri.startsWith('file://') ? `file://${normalize(target)}` : target;
-		},
-	};
-}
-
-/**
- * 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);
-}
+/**
+ * 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>;
+	/**
+	 * Brings a fresh capture under the store and returns its managed URI: a file
+	 * already inside the store is recorded as created by this process, a file
+	 * anywhere else is moved in. Without this, a capture the engine wrote to its
+	 * own temporary directory is never owned, so `cleanup()` refuses it and the
+	 * sweep never sees it. Optional so app-written stores keep compiling.
+	 */
+	adopt?(uri: string): Promise<string>;
+}
+
+/** 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>;
+	/**
+	 * Moves a file. Needed by `adopt()` to pull a capture out of the engine's own
+	 * temporary directory; a bridge without it can only adopt files already
+	 * inside the store.
+	 */
+	move?(from: string, to: 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>();
+
+	function owns(uri: string): boolean {
+		return normalize(uri).startsWith(`${normalizedRoot}/`);
+	}
+
+	return {
+		temporaryDirectory() {
+			return root;
+		},
+
+		owns,
+
+		async remove(uri) {
+			if (!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;
+		},
+
+		async adopt(uri) {
+			const path = normalize(uri);
+			if (owns(uri)) {
+				createdThisProcess.add(path);
+				return uri;
+			}
+			if (!fs.move) {
+				throw new Error('This FileSystemBridge has no move(), so it cannot adopt a capture');
+			}
+			await fs.ensureDirectory(root);
+			const name = path.slice(path.lastIndexOf('/') + 1) || `capture-${Date.now()}.jpg`;
+			const target = `${root}/${name}`;
+			await fs.move(path, target);
+			createdThisProcess.add(normalize(target));
+			return uri.startsWith('file://') ? `file://${normalize(target)}` : target;
+		},
+	};
+}
+
+/**
+ * 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/conformance.ts

@@ -0,0 +1,140 @@
+/**
+ * What any `PermissionPort` and `CameraEngine` must do (IOS-12, CAM-13).
+ *
+ * The same checks run against the in-memory test adapter and against the real
+ * VisionCamera adapters (native module mocked in Jest, or for real on a device),
+ * so the fake the app's tests rely on cannot drift from the adapter it stands in
+ * for. Each check builds its own port from a harness, under the conditions it
+ * needs.
+ */
+import {
+	ensure,
+	runChecks,
+	type Check,
+	type ConformanceReport,
+} from '@chipmobilesdk/rn-core/testing';
+
+import type { CameraPermissionState } from '../config/types';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+
+export type SystemPermission = 'undetermined' | 'granted' | 'deniedPermanently';
+
+export interface PermissionHarness {
+	/** A port over a system whose permission starts in `initial`. */
+	create(initial: SystemPermission): {
+		readonly port: PermissionPort;
+		/** Changes the system permission, as Settings would. */
+		setSystemState(state: SystemPermission): void;
+		/** How many times the system prompt was shown. */
+		prompts(): number;
+	};
+}
+
+export interface CameraDeviceSpec {
+	readonly position: 'front' | 'back';
+	readonly hasFlash?: boolean;
+	readonly hasTorch?: boolean;
+}
+
+export interface EngineHarness {
+	/** An engine on a device with these cameras. */
+	create(devices: readonly CameraDeviceSpec[]): CameraEngine;
+}
+
+export const permissionPortChecks: readonly Check<PermissionHarness>[] = [
+	{
+		name: 'reads the status without prompting',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			ensure((await system.port.getStatus()) === 'undetermined', 'expected undetermined');
+			ensure(system.prompts() === 0, 'getStatus prompted');
+		},
+	},
+	{
+		name: 'reports a grant after prompting once',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			const state = await system.port.request();
+			ensure(state === 'granted', `expected granted, got ${state}`);
+			ensure(system.prompts() === 1, `expected one prompt, got ${system.prompts()}`);
+		},
+	},
+	{
+		name: 'never prompts again after a permanent denial',
+		async run(harness) {
+			const system = harness.create('deniedPermanently');
+			const state = await system.port.request();
+			ensure(state === 'deniedPermanently', `expected deniedPermanently, got ${state}`);
+			ensure(system.prompts() === 0, 'prompted after a permanent denial');
+		},
+	},
+	{
+		name: 'tells subscribers about a change, and nothing after unsubscribing',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			const seen: CameraPermissionState[] = [];
+			const unsubscribe = system.port.subscribe(state => seen.push(state));
+			await system.port.request();
+			ensure(seen.includes('granted'), `subscriber saw ${JSON.stringify(seen)}`);
+			unsubscribe();
+			unsubscribe();
+			const before = seen.length;
+			system.setSystemState('deniedPermanently');
+			await system.port.getStatus();
+			ensure(seen.length === before, 'notified after unsubscribing');
+		},
+	},
+];
+
+export const cameraEngineChecks: readonly Check<EngineHarness>[] = [
+	{
+		name: 'refuses to start without a camera, as cameraUnavailable',
+		async run(harness) {
+			const engine = harness.create([]);
+			let code: unknown;
+			try {
+				await engine.start({});
+			} catch (error) {
+				code = (error as { code?: unknown }).code;
+			}
+			ensure(code === 'cameraUnavailable', `expected cameraUnavailable, got ${String(code)}`);
+		},
+	},
+	{
+		name: 'starts when a camera exists',
+		async run(harness) {
+			await harness.create([{ position: 'back' }]).start({});
+		},
+	},
+	{
+		name: 'reports capabilities from the cameras present',
+		async run(harness) {
+			const capabilities = await harness
+				.create([{ position: 'back', hasTorch: true, hasFlash: true }, { position: 'front' }])
+				.getCapabilities();
+			ensure(capabilities.hasCameraHardware, 'no camera hardware reported');
+			ensure(capabilities.hasTorch && capabilities.hasFlash, 'torch or flash not reported');
+			const positions = [...capabilities.availablePositions].sort();
+			ensure(positions.join(',') === 'back,front', `positions ${positions.join(',')}`);
+		},
+	},
+	{
+		name: 'stops safely, even without a start and twice',
+		async run(harness) {
+			const engine = harness.create([{ position: 'back' }]);
+			await engine.stop();
+			await engine.stop();
+		},
+	},
+];
+
+export function runPermissionPortConformance(
+	harness: PermissionHarness,
+): Promise<ConformanceReport> {
+	return runChecks(() => harness, permissionPortChecks);
+}
+
+export function runCameraEngineConformance(harness: EngineHarness): Promise<ConformanceReport> {
+	return runChecks(() => harness, cameraEngineChecks);
+}

package/src/testing/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `@chipmobilesdk/rn-camera/testing`: test doubles and the port conformance suites.
+ *
+ * A separate entrypoint so the suites cannot reach a production bundle. The test
+ * adapter is also exported from the main entrypoint for compatibility; it leaves
+ * there only in a major release.
+ */
+
+export {
+	createTestCamera,
+	createMemoryFileSystem,
+	DEFAULT_TEST_CAPABILITIES,
+} from './testCameraAdapter';
+export type { MemoryFileSystem, TestCameraConfig, TestCameraHandles } from './testCameraAdapter';
+
+export {
+	cameraEngineChecks,
+	permissionPortChecks,
+	runCameraEngineConformance,
+	runPermissionPortConformance,
+} from './conformance';
+export type {
+	CameraDeviceSpec,
+	EngineHarness,
+	PermissionHarness,
+	SystemPermission,
+} from './conformance';