@chipmobilesdk/rn-camera 0.2.1 → 0.4.0

package/src/core/controller.ts

@@ -7,6 +7,8 @@
  * tested without a camera.
  */
 
+import { appLifecycle, createListenerSet } from '@chipmobilesdk/rn-core';
+
 import {
 	type CameraPermissionState,
 	type CameraPosition,
@@ -18,10 +20,15 @@ import {
 	type StartOptions,
 } from '../config/types';
 import { CameraError, isCameraError } from '../diagnostics/errors';
-import { silentLogger, type CameraLogger } from '../diagnostics/logger';
+import { silentLogger, withSdkSinks } from '../diagnostics/logger';
 import type { CameraEngine } from '../native/cameraEngine';
+import {
+	DEFAULT_TEMPORARY_TTL_MS,
+	type AppStatus,
+	type CameraController,
+	type CameraControllerOptions,
+} from './contract';
 import type { PermissionPort } from '../permissions/permissionPort';
-import type { ArtifactStore } from '../storage/artifactStore';
 import { EMPTY_CAPABILITIES, assertSupported, supportsTorch } from './capabilities';
 import {
 	SingleFlight,
@@ -30,72 +37,29 @@ import {
 	type CaptureContext,
 } from './captureController';
 import { canStart, initialSession, sessionReducer, type SessionSnapshot } from './sessionMachine';
+import { createSessionRuntime } from './sessionRuntime';
 
 /** 24 hours (FR-029). */
-export const DEFAULT_TEMPORARY_TTL_MS = 24 * 60 * 60 * 1000;
-
-export type AppStatus = 'active' | 'background';
-
-export interface CameraControllerOptions {
-	readonly engine?: CameraEngine;
-	readonly permissions?: PermissionPort;
-	readonly store?: ArtifactStore;
-	readonly logger?: CameraLogger;
-	readonly temporaryTtlMs?: number;
-	/**
-	 * App foreground/background source. Defaults to React Native `AppState`.
-	 * Injectable so lifecycle rules are testable without an app (FR-015).
-	 */
-	readonly subscribeToAppState?: (listener: (status: AppStatus) => void) => () => void;
-	/**
-	 * Set false to skip the sweep that runs when the controller is first used
-	 * (tests). Defaults to true.
-	 */
-	readonly sweepOnInit?: boolean;
-}
-
-export interface CameraController {
-	readonly state: CameraState;
-	subscribe(listener: (state: CameraState) => void): () => void;
-
-	getPermission(): Promise<CameraPermissionState>;
-	requestPermission(): Promise<CameraPermissionState>;
-
-	start(options?: StartOptions): Promise<void>;
-	pause(): Promise<void>;
-	resume(): Promise<void>;
-	stop(): Promise<void>;
-
-	capture(request?: CaptureRequest): Promise<CapturedImage>;
-	cleanup(image: CapturedImage | string): Promise<void>;
-
-	getCapabilities(): Promise<CapabilityProfile>;
-	setFlashMode(mode: FlashMode): void;
-	setTorch(enabled: boolean): Promise<void>;
-
-	/** Marks the preview surface mounted, enabling foreground auto-restart. */
-	setSurfaceMounted(mounted: boolean): void;
-	/**
-	 * Releases ports, listeners, and the camera. Safe to call twice. Afterwards
-	 * `start`, `resume`, `capture` and the permission and capability reads reject
-	 * with `notReady`; `stop`, `pause` and `cleanup` stay safe no-ops so teardown
-	 * code never has to check.
-	 */
-	dispose(): Promise<void>;
-}
+export {
+	DEFAULT_TEMPORARY_TTL_MS,
+	type AppStatus,
+	type CameraController,
+	type CameraControllerOptions,
+} from './contract';
 
 function defaultAppStateSubscribe(listener: (status: AppStatus) => void): () => void {
-	// Lazy require so importing the package outside React Native (for example in
-	// a Node-based test runner) does not pull in the RN runtime.
-	const { AppState } = require('react-native');
-	const subscription = AppState.addEventListener('change', (next: string) => {
-		listener(next === 'active' ? 'active' : 'background');
-	});
-	return () => subscription.remove();
+	// rn-core's one lifecycle subscription, shared with every other package; it
+	// requires react-native only on first subscribe (PERF-07).
+	return appLifecycle().subscribe(state => listener(state === 'active' ? 'active' : 'background'));
 }
 
-export function createCameraController(options: CameraControllerOptions = {}): CameraController {
-	if (!options.engine || !options.permissions) {
+/** 8 s: a cold camera on a slow device, with room to spare (PERF-001 is 1.5 s). */
+export const DEFAULT_START_TIMEOUT_MS = 8_000;
+
+export function createCameraController(options: CameraControllerOptions): CameraController {
+	if (!options?.engine || !options?.permissions) {
+		// A configuration fault, named as one. The ports are required by the type;
+		// this is the answer for a JavaScript caller or a cast.
 		throw new CameraError(
 			'unsupportedCapability',
 			'createCameraController requires `engine` and `permissions` ports. Use the ' +
@@ -103,13 +67,18 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 		);
 	}
 
-	// Bound after the guard so the closures below see non-optional ports.
 	const engine: CameraEngine = options.engine;
 	const permissions: PermissionPort = options.permissions;
 	const store = options.store;
-	const logger = options.logger ?? silentLogger;
+	const logger = withSdkSinks(options.logger ?? silentLogger);
 	const ttlMs = options.temporaryTtlMs ?? DEFAULT_TEMPORARY_TTL_MS;
 
+	const startTimeoutMs = options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+	const scheduler = options.scheduler ?? {
+		setTimeout: (callback: () => void, ms: number) => setTimeout(callback, ms),
+		clearTimeout: (handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+	};
+
 	let session: SessionSnapshot = initialSession;
 	let permission: CameraPermissionState = 'undetermined';
 	let capabilities: CapabilityProfile | null = null;
@@ -118,18 +87,40 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 	let torchEnabled = false;
 	let surfaceMounted = false;
 	let disposed = false;
-	let appStatus: AppStatus = 'active';
-	// Set only when backgrounding cut a running session short. Foregrounding
-	// used to restart from any idle or stopped session, so a camera the user had
-	// stopped — or never started, or no longer had permission for — came back on
-	// with the app.
-	let resumeOnForeground = false;
-	let releasing: Promise<void> | null = null;
 	let warnedUnmanaged = false;
 	let detach: (() => void) | null = null;
 
 	const capture = new SingleFlight();
-	const listeners = new Set<(state: CameraState) => void>();
+	const listeners = createListenerSet<[CameraState]>({
+		onListenerError: () => logger.log({ type: 'session', code: 'listener-threw' }),
+	});
+
+	/**
+	 * The session's own I/O (`sessionRuntime`): starting it, waiting for frames,
+	 * releasing it, following the app in and out of the foreground. It reads and
+	 * writes the state above through this context, so one snapshot reaches
+	 * subscribers whichever part changed it.
+	 */
+	const runtime = createSessionRuntime({
+		engine,
+		logger,
+		startTimeoutMs,
+		scheduler,
+		session: () => session,
+		dispatch,
+		emit,
+		cameraPosition: () => cameraPosition,
+		setCameraPosition: position => {
+			cameraPosition = position;
+		},
+		torchEnabled: () => torchEnabled,
+		setTorchEnabled: enabled => {
+			torchEnabled = enabled;
+		},
+		surfaceMounted: () => surfaceMounted,
+		permissionGranted: () => permission === 'granted',
+		disposed: () => disposed,
+	});
 
 	function snapshot(): CameraState {
 		return {
@@ -140,6 +131,9 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			flashMode,
 			torchEnabled,
 			capturing: capture.busy,
+			// What the mounted preview turned out to be, once it reported: the
+			// format's pixel size and the orientation coordinate mapping needs.
+			surface: runtime.surfaceInfo(),
 			error: session.error
 				? {
 						code: session.error.code,
@@ -154,15 +148,9 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 
 	function emit(): void {
 		current = snapshot();
-		for (const listener of listeners) {
-			// One throwing subscriber must not starve the others, nor unwind into
-			// the transition that emitted — that left the controller half-updated.
-			try {
-				listener(current);
-			} catch {
-				logger.log({ type: 'session', code: 'listener-threw' });
-			}
-		}
+		// Isolated: one throwing subscriber neither starves the others nor unwinds
+		// into the transition that emitted, which left the controller half-updated.
+		listeners.notify(current);
 	}
 
 	function dispatch(event: Parameters<typeof sessionReducer>[1]): void {
@@ -178,72 +166,6 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 		}
 	}
 
-	/** Torch must never survive leaving the active state (FR-034b). */
-	async function forceTorchOff(): Promise<void> {
-		if (!torchEnabled) {
-			return;
-		}
-		torchEnabled = false;
-		try {
-			await engine.setTorch(false);
-		} catch {
-			// Torch-off is best effort; the session is going away regardless.
-		}
-		emit();
-	}
-
-	async function releaseCamera(): Promise<void> {
-		await forceTorchOff();
-		// Nothing to release. Going through STOP/STOPPED here turned an idle
-		// controller into `stopped` on every preview unmount.
-		if (session.status === 'idle' || session.status === 'stopped') {
-			return;
-		}
-		dispatch({ type: 'STOP' });
-		try {
-			await engine.stop();
-			dispatch({ type: 'STOPPED' });
-		} catch (error) {
-			dispatch({ type: 'FAIL', code: isCameraError(error) ? error.code : 'captureFailed' });
-		}
-	}
-
-	async function startEngine(startOptions: StartOptions = {}): Promise<void> {
-		try {
-			await engine.start({ cameraPosition: startOptions.cameraPosition ?? cameraPosition });
-			dispatch({ type: 'STARTED' });
-		} catch (error) {
-			dispatch({ type: 'FAIL', code: isCameraError(error) ? error.code : 'cameraUnavailable' });
-		}
-	}
-
-	function resumeAfterForeground(): void {
-		if (disposed || appStatus !== 'active' || !resumeOnForeground) {
-			return;
-		}
-		resumeOnForeground = false;
-		if (!surfaceMounted || permission !== 'granted') {
-			return;
-		}
-		dispatch({ type: 'FOREGROUND', surfaceMounted });
-		if (session.status === 'starting') {
-			startEngine().catch(() => undefined);
-		}
-	}
-
-	function onAppState(status: AppStatus): void {
-		appStatus = status;
-		if (status === 'background') {
-			resumeOnForeground ||= session.status === 'active' || session.status === 'starting';
-			dispatch({ type: 'BACKGROUND' });
-			releasing = releaseCamera().catch(() => undefined);
-		} else {
-			// Wait for a release still in flight, or the restart lands on a
-			// `stopping` session and is dropped.
-			(releasing ?? Promise.resolve()).then(resumeAfterForeground).catch(() => undefined);
-		}
-	}
-
 	/**
 	 * Subscribes to permission and app-state changes and runs the sweep, on first
 	 * use rather than at construction. React may build a controller during a
@@ -261,18 +183,23 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			// A revocation while running must tear the session down, not leave a
 			// frozen preview on screen (FR-007).
 			if (next !== 'granted') {
-				resumeOnForeground = false;
+				runtime.armResumeOnForeground();
 				if (session.status !== 'idle' && session.status !== 'stopped') {
-					releaseCamera().catch(() => undefined);
+					runtime.release().catch(() => undefined);
 				}
 			}
 		});
-		const unsubscribeAppState = (options.subscribeToAppState ?? defaultAppStateSubscribe)(
-			onAppState,
+		const unsubscribeAppState = (options.subscribeToAppState ?? defaultAppStateSubscribe)(status =>
+			runtime.onAppState(status),
 		);
+		// The OS can take the camera at any moment — another app, an incoming
+		// call, a disconnected device. The session has to go with it (CAM-19).
+		const unsubscribeInterruptions =
+			engine.subscribeToInterruptions?.(code => runtime.onInterruption(code)) ?? (() => undefined);
 		detach = () => {
 			unsubscribePermission();
 			unsubscribeAppState();
+			unsubscribeInterruptions();
 		};
 
 		// FR-029: sweep our own temp directory once, asynchronously, so it can
@@ -336,10 +263,7 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 				return () => undefined;
 			}
 			attach();
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
+			return listeners.add(listener);
 		},
 
 		async getPermission() {
@@ -353,7 +277,17 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			live('requestPermission');
 			permission = 'requesting';
 			emit();
-			permission = await permissions.request();
+			try {
+				permission = await permissions.request();
+			} catch (error) {
+				// A native call that failed used to leave the state at `requesting`
+				// forever, with no way for the app to ask again (CAM-07).
+				permission = await permissions.getStatus().catch(() => 'unavailable' as const);
+				emit();
+				throw isCameraError(error)
+					? error
+					: new CameraError('permissionDenied', 'The permission request could not be completed');
+			}
 			emit();
 			return permission;
 		},
@@ -371,7 +305,7 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 				cameraPosition = startOptions.cameraPosition;
 			}
 			dispatch({ type: 'START' });
-			await startEngine(startOptions);
+			await runtime.start(startOptions);
 			if (session.error) {
 				throw session.error;
 			}
@@ -381,7 +315,7 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			if (disposed) {
 				return;
 			}
-			await forceTorchOff();
+			await runtime.forceTorchOff();
 			dispatch({ type: 'PAUSE' });
 		},
 
@@ -389,17 +323,17 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			live('resume');
 			dispatch({ type: 'RESUME' });
 			if (session.status === 'starting') {
-				await startEngine();
+				await runtime.start();
 			}
 		},
 
 		async stop() {
 			// An explicit stop is the user's decision; foregrounding must not undo it.
-			resumeOnForeground = false;
+			runtime.armResumeOnForeground();
 			if (disposed) {
 				return;
 			}
-			await releaseCamera();
+			await runtime.release();
 		},
 
 		async capture(request: CaptureRequest = {}) {
@@ -492,6 +426,26 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			emit();
 		},
 
+		reportSurfaceUnavailable() {
+			if (disposed) {
+				return;
+			}
+			logger.log({ type: 'session', code: 'surface-unavailable', recoverable: false });
+			dispatch({ type: 'FAIL', code: 'cameraUnavailable' });
+		},
+
+		attachSurface(surface) {
+			return engine.attachSurface?.(surface) ?? (() => undefined);
+		},
+
+		reportSurfaceStarted(info) {
+			runtime.reportSurfaceStarted(info);
+		},
+
+		reportSurfaceFailed(code) {
+			runtime.reportSurfaceFailed(code);
+		},
+
 		setSurfaceMounted(mounted: boolean) {
 			if (disposed) {
 				return;
@@ -504,10 +458,10 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 				return;
 			}
 			disposed = true;
-			resumeOnForeground = false;
+			runtime.armResumeOnForeground();
 			detach?.();
 			detach = null;
-			await releaseCamera();
+			await runtime.release();
 			listeners.clear();
 		},
 	};

package/src/core/sessionRuntime.ts

@@ -0,0 +1,242 @@
+/**
+ * The session's own I/O: starting it, waiting for frames, releasing it, and
+ * following the app in and out of the foreground.
+ *
+ * Split out of `controller.ts`, which had grown to hold three jobs at once:
+ * publishing state, running the session, and serving the public API. The
+ * decisions still live in `sessionMachine` (pure); this is the part that
+ * actually awaits the engine, and the controller composes it.
+ *
+ * It reads and writes the controller's state through `SessionContext` rather
+ * than owning it: one snapshot reaches subscribers, whichever part of the
+ * controller changed it.
+ */
+
+import type { StartOptions } from '../config/types';
+import { isCameraError, type CameraErrorCode } from '../diagnostics/errors';
+import type { CameraLogger } from '../diagnostics/logger';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { SurfaceInfo } from '../native/visionSurface';
+import type { SessionEvent, SessionSnapshot } from './sessionMachine';
+
+/** What the runtime needs from the controller that owns the state. */
+export interface SessionContext {
+	readonly engine: CameraEngine;
+	readonly logger: CameraLogger;
+	/** How long to wait for a preview surface to report frames. */
+	readonly startTimeoutMs: number;
+	readonly scheduler: {
+		setTimeout(callback: () => void, ms: number): unknown;
+		clearTimeout(handle: unknown): void;
+	};
+	session(): SessionSnapshot;
+	dispatch(event: SessionEvent): void;
+	emit(): void;
+	cameraPosition(): 'front' | 'back';
+	setCameraPosition(position: 'front' | 'back'): void;
+	torchEnabled(): boolean;
+	setTorchEnabled(enabled: boolean): void;
+	surfaceMounted(): boolean;
+	permissionGranted(): boolean;
+	disposed(): boolean;
+}
+
+export interface SessionRuntime {
+	/** Starts the engine and, where the surface owns the session, waits for frames. */
+	start(options?: StartOptions): Promise<void>;
+	/** Turns the torch off and releases the camera. Safe from any state. */
+	release(): Promise<void>;
+	/** Torch off, whatever the session is doing. */
+	forceTorchOff(): Promise<void>;
+	/** The app went to the background or came back. */
+	onAppState(status: 'active' | 'background'): void;
+	/** The preview reported frames; carries what the mounted device turned out to be. */
+	reportSurfaceStarted(info: SurfaceInfo): void;
+	/** The preview's own session failed, or the OS took the camera. */
+	reportSurfaceFailed(code: CameraErrorCode): void;
+	/** The engine lost the camera: another app, a call, a disconnected device. */
+	onInterruption(code: CameraErrorCode): void;
+	/** What the surface last reported, for the published state. */
+	surfaceInfo(): SurfaceInfo | null;
+	/** Set when the app foregrounds with a surface mounted, so the session restarts. */
+	armResumeOnForeground(): void;
+	/** A release still in flight, so a restart can wait for it. */
+	pending(): Promise<void> | undefined;
+}
+
+export function createSessionRuntime(context: SessionContext): SessionRuntime {
+	let surfaceInfo: SurfaceInfo | null = null;
+	/** Resolved by the surface's own report, or by the start timeout. */
+	let pendingStart: { settle(): void; fail(code: CameraErrorCode): void } | null = null;
+	let appStatus: 'active' | 'background' = 'active';
+	let resumeOnForeground = false;
+	let releasing: Promise<void> | undefined;
+
+	/** Torch must never survive leaving the active state (FR-034b). */
+	async function forceTorchOff(): Promise<void> {
+		if (!context.torchEnabled()) {
+			return;
+		}
+		context.setTorchEnabled(false);
+		try {
+			await context.engine.setTorch(false);
+		} catch {
+			// Torch-off is best effort; the session is going away regardless.
+		}
+		context.emit();
+	}
+
+	async function release(): Promise<void> {
+		await forceTorchOff();
+		// Nothing to release. Going through STOP/STOPPED here turned an idle
+		// controller into `stopped` on every preview unmount.
+		const status = context.session().status;
+		if (status === 'idle' || status === 'stopped') {
+			return;
+		}
+		context.dispatch({ type: 'STOP' });
+		try {
+			await context.engine.stop();
+			context.dispatch({ type: 'STOPPED' });
+		} catch (error) {
+			context.dispatch({
+				type: 'FAIL',
+				code: isCameraError(error) ? error.code : 'captureFailed',
+			});
+		}
+	}
+
+	/**
+	 * Waits for the mounted preview to report frames.
+	 *
+	 * `engine.start()` only confirms a device exists for the VisionCamera
+	 * adapter: the session belongs to the `<Camera>` view. Calling the session
+	 * active there made `capture()` right after `start()` fail with `notReady`,
+	 * and a camera that never produced a frame left the session in `starting`
+	 * forever (CAM-08).
+	 */
+	function awaitSurfaceStart(): Promise<void> {
+		return new Promise<void>(resolve => {
+			const timer = context.scheduler.setTimeout(() => {
+				if (pendingStart) {
+					pendingStart = null;
+					context.dispatch({ type: 'START_TIMEOUT' });
+					resolve();
+				}
+			}, context.startTimeoutMs);
+			const finish = () => {
+				context.scheduler.clearTimeout(timer);
+				pendingStart = null;
+				resolve();
+			};
+			pendingStart = {
+				settle: () => {
+					context.dispatch({ type: 'STARTED' });
+					finish();
+				},
+				fail: code => {
+					context.dispatch({ type: 'FAIL', code });
+					finish();
+				},
+			};
+		});
+	}
+
+	async function start(options: StartOptions = {}): Promise<void> {
+		try {
+			await context.engine.start({
+				cameraPosition: options.cameraPosition ?? context.cameraPosition(),
+			});
+		} catch (error) {
+			context.dispatch({
+				type: 'FAIL',
+				code: isCameraError(error) ? error.code : 'cameraUnavailable',
+			});
+			return;
+		}
+		if (context.engine.awaitsSurfaceStart !== true || !context.surfaceMounted()) {
+			// The engine owns its session, or there is no preview to wait for.
+			context.dispatch({ type: 'STARTED' });
+			return;
+		}
+		await awaitSurfaceStart();
+	}
+
+	function resumeAfterForeground(): void {
+		if (context.disposed() || appStatus !== 'active' || !resumeOnForeground) {
+			return;
+		}
+		resumeOnForeground = false;
+		if (!context.surfaceMounted() || !context.permissionGranted()) {
+			return;
+		}
+		context.dispatch({ type: 'FOREGROUND', surfaceMounted: true });
+		if (context.session().status === 'starting') {
+			start().catch(() => undefined);
+		}
+	}
+
+	return {
+		start,
+		release,
+		forceTorchOff,
+
+		onAppState(status) {
+			appStatus = status;
+			if (status === 'background') {
+				const running = context.session().status;
+				resumeOnForeground ||= running === 'active' || running === 'starting';
+				context.dispatch({ type: 'BACKGROUND' });
+				releasing = release().catch(() => undefined);
+			} else {
+				// Wait for a release still in flight, or the restart lands on a
+				// `stopping` session and is dropped.
+				(releasing ?? Promise.resolve()).then(resumeAfterForeground).catch(() => undefined);
+			}
+		},
+
+		reportSurfaceStarted(info) {
+			surfaceInfo = info;
+			if (info.cameraPosition !== context.cameraPosition()) {
+				// The device that mounted is the one taking the photos.
+				context.setCameraPosition(info.cameraPosition);
+			}
+			if (pendingStart) {
+				pendingStart.settle();
+			} else if (context.session().status === 'starting') {
+				context.dispatch({ type: 'STARTED' });
+			} else {
+				context.emit();
+			}
+		},
+
+		reportSurfaceFailed(code) {
+			if (pendingStart) {
+				pendingStart.fail(code);
+				return;
+			}
+			context.dispatch({ type: 'FAIL', code });
+		},
+
+		onInterruption(code) {
+			context.logger.log({ type: 'session', code });
+			if (pendingStart) {
+				pendingStart.fail(code);
+				return;
+			}
+			const status = context.session().status;
+			if (status !== 'idle' && status !== 'stopped') {
+				context.dispatch({ type: 'FAIL', code });
+				release().catch(() => undefined);
+			}
+		},
+
+		surfaceInfo: () => surfaceInfo,
+
+		armResumeOnForeground() {
+			resumeOnForeground = false;
+		},
+
+		pending: () => releasing,
+	};
+}