@chipmobilesdk/rn-camera 0.2.0 → 0.2.1

package/src/core/controller.ts

@@ -1,518 +1,516 @@
-/**
- * Camera controller — the object consuming apps actually drive.
- *
- * It owns observable state and orchestrates the three ports (engine,
- * permissions, artifact store). All I/O lives here; the decisions live in
- * `sessionMachine` and `captureController`, which stay pure so they can be
- * tested without a camera.
- */
-
-import {
-	type CameraPermissionState,
-	type CameraPosition,
-	type CameraState,
-	type CapabilityProfile,
-	type CapturedImage,
-	type CaptureRequest,
-	type FlashMode,
-	type StartOptions,
-} from '../config/types';
-import { CameraError, isCameraError } from '../diagnostics/errors';
-import { silentLogger, type CameraLogger } from '../diagnostics/logger';
-import type { CameraEngine } from '../native/cameraEngine';
-import type { PermissionPort } from '../permissions/permissionPort';
-import type { ArtifactStore } from '../storage/artifactStore';
-import { EMPTY_CAPABILITIES, assertSupported, supportsTorch } from './capabilities';
-import {
-	SingleFlight,
-	assertCaptureAllowed,
-	finalizeResult,
-	type CaptureContext,
-} from './captureController';
-import { canStart, initialSession, sessionReducer, type SessionSnapshot } from './sessionMachine';
-
-/** 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>;
-}
-
-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();
-}
-
-export function createCameraController(
-	options: CameraControllerOptions = {},
-): CameraController {
-	if (!options.engine || !options.permissions) {
-		throw new CameraError(
-			'unsupportedCapability',
-			'createCameraController requires `engine` and `permissions` ports. Use the ' +
-				'default adapters, or createTestCamera() in tests.',
-		);
-	}
-
-	// 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 ttlMs = options.temporaryTtlMs ?? DEFAULT_TEMPORARY_TTL_MS;
-
-	let session: SessionSnapshot = initialSession;
-	let permission: CameraPermissionState = 'undetermined';
-	let capabilities: CapabilityProfile | null = null;
-	let cameraPosition: CameraPosition = 'back';
-	let flashMode: FlashMode = 'off';
-	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>();
-
-	function snapshot(): CameraState {
-		return {
-			session: session.status,
-			permission,
-			capabilities,
-			cameraPosition,
-			flashMode,
-			torchEnabled,
-			capturing: capture.busy,
-			error: session.error
-				? {
-						code: session.error.code,
-						recoverable: session.error.recoverable,
-						message: session.error.message,
-				  }
-				: null,
-		};
-	}
-
-	let current = snapshot();
-
-	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' });
-			}
-		}
-	}
-
-	function dispatch(event: Parameters<typeof sessionReducer>[1]): void {
-		const next = sessionReducer(session, event);
-		if (next !== session) {
-			session = next;
-			logger.log({
-				type: 'session',
-				code: session.status,
-				recoverable: session.error?.recoverable,
-			});
-			emit();
-		}
-	}
-
-	/** 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
-	 * render it then throws away (StrictMode does so on purpose); construction
-	 * that subscribed leaked a listener pair every time.
-	 */
-	function attach(): void {
-		if (detach || disposed) {
-			return;
-		}
-		const unsubscribePermission = permissions.subscribe(next => {
-			permission = next;
-			logger.log({ type: 'permission', code: next });
-			emit();
-			// A revocation while running must tear the session down, not leave a
-			// frozen preview on screen (FR-007).
-			if (next !== 'granted') {
-				resumeOnForeground = false;
-				if (session.status !== 'idle' && session.status !== 'stopped') {
-					releaseCamera().catch(() => undefined);
-				}
-			}
-		});
-		const unsubscribeAppState = (options.subscribeToAppState ?? defaultAppStateSubscribe)(
-			onAppState,
-		);
-		detach = () => {
-			unsubscribePermission();
-			unsubscribeAppState();
-		};
-
-		// FR-029: sweep our own temp directory once, asynchronously, so it can
-		// never add latency to the capture path or the preview start.
-		if (store && options.sweepOnInit !== false) {
-			store
-				.sweep(ttlMs)
-				.then(removed => {
-					if (removed > 0) {
-						logger.log({ type: 'cleanup', code: `swept:${removed}` });
-					}
-				})
-				.catch(() => {
-					// A failed sweep must never block startup.
-				});
-		}
-	}
-
-	/** Entry guard for operations that need a live controller. */
-	function live(operation: string): void {
-		if (disposed) {
-			throw new CameraError('notReady', `${operation}() called on a disposed camera controller`);
-		}
-		attach();
-	}
-
-	/**
-	 * Puts a package-temporary capture under the store so `cleanup()` and the
-	 * sweep can reach it. Never throws: the capture itself succeeded, and a file
-	 * the store cannot manage is still a usable photo.
-	 */
-	async function manage(image: CapturedImage): Promise<CapturedImage> {
-		if (image.ownership !== 'packageTemporary') {
-			return image;
-		}
-		if (store?.adopt) {
-			try {
-				return { ...image, uri: await store.adopt(image.uri) };
-			} catch {
-				logger.log({ type: 'cleanup', code: 'adopt-failed' });
-				return image;
-			}
-		}
-		if (!store?.owns(image.uri) && !warnedUnmanaged) {
-			warnedUnmanaged = true;
-			logger.log({ type: 'cleanup', code: store ? 'unmanaged:store-cannot-adopt' : 'unmanaged:no-store' });
-		}
-		return image;
-	}
-
-	const controller: CameraController = {
-		get state() {
-			return current;
-		},
-
-		subscribe(listener) {
-			if (disposed) {
-				return () => undefined;
-			}
-			attach();
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
-		},
-
-		async getPermission() {
-			live('getPermission');
-			permission = await permissions.getStatus();
-			emit();
-			return permission;
-		},
-
-		async requestPermission() {
-			live('requestPermission');
-			permission = 'requesting';
-			emit();
-			permission = await permissions.request();
-			emit();
-			return permission;
-		},
-
-		async start(startOptions: StartOptions = {}) {
-			live('start');
-			if (permission !== 'granted') {
-				dispatch({ type: 'FAIL', code: 'permissionDenied' });
-				throw new CameraError('permissionDenied', 'Camera permission is not granted');
-			}
-			if (!canStart(session.status)) {
-				throw new CameraError('sessionConflict', `Session already ${session.status}`);
-			}
-			if (startOptions.cameraPosition) {
-				cameraPosition = startOptions.cameraPosition;
-			}
-			dispatch({ type: 'START' });
-			await startEngine(startOptions);
-			if (session.error) {
-				throw session.error;
-			}
-		},
-
-		async pause() {
-			if (disposed) {
-				return;
-			}
-			await forceTorchOff();
-			dispatch({ type: 'PAUSE' });
-		},
-
-		async resume() {
-			live('resume');
-			dispatch({ type: 'RESUME' });
-			if (session.status === 'starting') {
-				await startEngine();
-			}
-		},
-
-		async stop() {
-			// An explicit stop is the user's decision; foregrounding must not undo it.
-			resumeOnForeground = false;
-			if (disposed) {
-				return;
-			}
-			await releaseCamera();
-		},
-
-		async capture(request: CaptureRequest = {}) {
-			live('capture');
-			const context: CaptureContext = {
-				engine,
-				sessionStatus: session.status,
-				permissionGranted: permission === 'granted',
-				capabilities,
-				cameraPosition,
-				flashMode,
-			};
-			// Guards run before the single-flight slot is taken so a rejected
-			// request cannot block a subsequent legal one.
-			assertCaptureAllowed(context, request);
-
-			try {
-				const result = await capture.run(async () => {
-					emit();
-					const raw = await engine.capture({
-						...request,
-						flashMode: request.flashMode ?? flashMode,
-						cameraPosition: request.cameraPosition ?? cameraPosition,
-					});
-					return manage(finalizeResult(raw, request, context));
-				});
-				logger.log({ type: 'capture', code: 'succeeded' });
-				return result;
-			} catch (error) {
-				// The contract promises a CameraError; a raw native error carries
-				// no code to branch on and its message may hold a file path.
-				const failure = isCameraError(error)
-					? error
-					: new CameraError('captureFailed', 'The camera failed to capture a photo');
-				logger.log({ type: 'capture', code: failure.code, recoverable: failure.recoverable });
-				throw failure;
-			} finally {
-				// Without this a failed capture left `capturing: true` published
-				// until some unrelated change emitted again.
-				emit();
-			}
-		},
-
-		async cleanup(image: CapturedImage | string) {
-			const uri = typeof image === 'string' ? image : image.uri;
-			if (!store) {
-				return;
-			}
-			// Refuse anything we did not create rather than deleting an arbitrary
-			// path, which also covers every appOwned artifact (FR-026b, FR-028).
-			if (!store.owns(uri)) {
-				logger.log({ type: 'cleanup', code: 'refused-not-owned' });
-				return;
-			}
-			await store.remove(uri);
-			logger.log({ type: 'cleanup', code: 'removed' });
-		},
-
-		async getCapabilities() {
-			live('getCapabilities');
-			try {
-				capabilities = await engine.getCapabilities();
-			} catch {
-				capabilities = EMPTY_CAPABILITIES;
-			}
-			logger.log({
-				type: 'capability',
-				code: capabilities.hasCameraHardware ? 'available' : 'no-hardware',
-			});
-			emit();
-			return capabilities;
-		},
-
-		setFlashMode(mode: FlashMode) {
-			assertSupported(
-				mode === 'off' || capabilities?.hasFlash === true,
-				`flash mode "${mode}"`,
-			);
-			flashMode = mode;
-			emit();
-		},
-
-		async setTorch(enabled: boolean) {
-			if (disposed && !enabled) {
-				return;
-			}
-			live('setTorch');
-			if (enabled) {
-				assertSupported(supportsTorch(capabilities), 'torch');
-			}
-			await engine.setTorch(enabled);
-			torchEnabled = enabled;
-			emit();
-		},
-
-		setSurfaceMounted(mounted: boolean) {
-			if (disposed) {
-				return;
-			}
-			surfaceMounted = mounted;
-		},
-
-		async dispose() {
-			if (disposed) {
-				return;
-			}
-			disposed = true;
-			resumeOnForeground = false;
-			detach?.();
-			detach = null;
-			await releaseCamera();
-			listeners.clear();
-		},
-	};
-
-	return controller;
-}
+/**
+ * Camera controller — the object consuming apps actually drive.
+ *
+ * It owns observable state and orchestrates the three ports (engine,
+ * permissions, artifact store). All I/O lives here; the decisions live in
+ * `sessionMachine` and `captureController`, which stay pure so they can be
+ * tested without a camera.
+ */
+
+import {
+	type CameraPermissionState,
+	type CameraPosition,
+	type CameraState,
+	type CapabilityProfile,
+	type CapturedImage,
+	type CaptureRequest,
+	type FlashMode,
+	type StartOptions,
+} from '../config/types';
+import { CameraError, isCameraError } from '../diagnostics/errors';
+import { silentLogger, type CameraLogger } from '../diagnostics/logger';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+import type { ArtifactStore } from '../storage/artifactStore';
+import { EMPTY_CAPABILITIES, assertSupported, supportsTorch } from './capabilities';
+import {
+	SingleFlight,
+	assertCaptureAllowed,
+	finalizeResult,
+	type CaptureContext,
+} from './captureController';
+import { canStart, initialSession, sessionReducer, type SessionSnapshot } from './sessionMachine';
+
+/** 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>;
+}
+
+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();
+}
+
+export function createCameraController(options: CameraControllerOptions = {}): CameraController {
+	if (!options.engine || !options.permissions) {
+		throw new CameraError(
+			'unsupportedCapability',
+			'createCameraController requires `engine` and `permissions` ports. Use the ' +
+				'default adapters, or createTestCamera() in tests.',
+		);
+	}
+
+	// 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 ttlMs = options.temporaryTtlMs ?? DEFAULT_TEMPORARY_TTL_MS;
+
+	let session: SessionSnapshot = initialSession;
+	let permission: CameraPermissionState = 'undetermined';
+	let capabilities: CapabilityProfile | null = null;
+	let cameraPosition: CameraPosition = 'back';
+	let flashMode: FlashMode = 'off';
+	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>();
+
+	function snapshot(): CameraState {
+		return {
+			session: session.status,
+			permission,
+			capabilities,
+			cameraPosition,
+			flashMode,
+			torchEnabled,
+			capturing: capture.busy,
+			error: session.error
+				? {
+						code: session.error.code,
+						recoverable: session.error.recoverable,
+						message: session.error.message,
+					}
+				: null,
+		};
+	}
+
+	let current = snapshot();
+
+	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' });
+			}
+		}
+	}
+
+	function dispatch(event: Parameters<typeof sessionReducer>[1]): void {
+		const next = sessionReducer(session, event);
+		if (next !== session) {
+			session = next;
+			logger.log({
+				type: 'session',
+				code: session.status,
+				recoverable: session.error?.recoverable,
+			});
+			emit();
+		}
+	}
+
+	/** 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
+	 * render it then throws away (StrictMode does so on purpose); construction
+	 * that subscribed leaked a listener pair every time.
+	 */
+	function attach(): void {
+		if (detach || disposed) {
+			return;
+		}
+		const unsubscribePermission = permissions.subscribe(next => {
+			permission = next;
+			logger.log({ type: 'permission', code: next });
+			emit();
+			// A revocation while running must tear the session down, not leave a
+			// frozen preview on screen (FR-007).
+			if (next !== 'granted') {
+				resumeOnForeground = false;
+				if (session.status !== 'idle' && session.status !== 'stopped') {
+					releaseCamera().catch(() => undefined);
+				}
+			}
+		});
+		const unsubscribeAppState = (options.subscribeToAppState ?? defaultAppStateSubscribe)(
+			onAppState,
+		);
+		detach = () => {
+			unsubscribePermission();
+			unsubscribeAppState();
+		};
+
+		// FR-029: sweep our own temp directory once, asynchronously, so it can
+		// never add latency to the capture path or the preview start.
+		if (store && options.sweepOnInit !== false) {
+			store
+				.sweep(ttlMs)
+				.then(removed => {
+					if (removed > 0) {
+						logger.log({ type: 'cleanup', code: `swept:${removed}` });
+					}
+				})
+				.catch(() => {
+					// A failed sweep must never block startup.
+				});
+		}
+	}
+
+	/** Entry guard for operations that need a live controller. */
+	function live(operation: string): void {
+		if (disposed) {
+			throw new CameraError('notReady', `${operation}() called on a disposed camera controller`);
+		}
+		attach();
+	}
+
+	/**
+	 * Puts a package-temporary capture under the store so `cleanup()` and the
+	 * sweep can reach it. Never throws: the capture itself succeeded, and a file
+	 * the store cannot manage is still a usable photo.
+	 */
+	async function manage(image: CapturedImage): Promise<CapturedImage> {
+		if (image.ownership !== 'packageTemporary') {
+			return image;
+		}
+		if (store?.adopt) {
+			try {
+				return { ...image, uri: await store.adopt(image.uri) };
+			} catch {
+				logger.log({ type: 'cleanup', code: 'adopt-failed' });
+				return image;
+			}
+		}
+		if (!store?.owns(image.uri) && !warnedUnmanaged) {
+			warnedUnmanaged = true;
+			logger.log({
+				type: 'cleanup',
+				code: store ? 'unmanaged:store-cannot-adopt' : 'unmanaged:no-store',
+			});
+		}
+		return image;
+	}
+
+	const controller: CameraController = {
+		get state() {
+			return current;
+		},
+
+		subscribe(listener) {
+			if (disposed) {
+				return () => undefined;
+			}
+			attach();
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+
+		async getPermission() {
+			live('getPermission');
+			permission = await permissions.getStatus();
+			emit();
+			return permission;
+		},
+
+		async requestPermission() {
+			live('requestPermission');
+			permission = 'requesting';
+			emit();
+			permission = await permissions.request();
+			emit();
+			return permission;
+		},
+
+		async start(startOptions: StartOptions = {}) {
+			live('start');
+			if (permission !== 'granted') {
+				dispatch({ type: 'FAIL', code: 'permissionDenied' });
+				throw new CameraError('permissionDenied', 'Camera permission is not granted');
+			}
+			if (!canStart(session.status)) {
+				throw new CameraError('sessionConflict', `Session already ${session.status}`);
+			}
+			if (startOptions.cameraPosition) {
+				cameraPosition = startOptions.cameraPosition;
+			}
+			dispatch({ type: 'START' });
+			await startEngine(startOptions);
+			if (session.error) {
+				throw session.error;
+			}
+		},
+
+		async pause() {
+			if (disposed) {
+				return;
+			}
+			await forceTorchOff();
+			dispatch({ type: 'PAUSE' });
+		},
+
+		async resume() {
+			live('resume');
+			dispatch({ type: 'RESUME' });
+			if (session.status === 'starting') {
+				await startEngine();
+			}
+		},
+
+		async stop() {
+			// An explicit stop is the user's decision; foregrounding must not undo it.
+			resumeOnForeground = false;
+			if (disposed) {
+				return;
+			}
+			await releaseCamera();
+		},
+
+		async capture(request: CaptureRequest = {}) {
+			live('capture');
+			const context: CaptureContext = {
+				engine,
+				sessionStatus: session.status,
+				permissionGranted: permission === 'granted',
+				capabilities,
+				cameraPosition,
+				flashMode,
+			};
+			// Guards run before the single-flight slot is taken so a rejected
+			// request cannot block a subsequent legal one.
+			assertCaptureAllowed(context, request);
+
+			try {
+				const result = await capture.run(async () => {
+					emit();
+					const raw = await engine.capture({
+						...request,
+						flashMode: request.flashMode ?? flashMode,
+						cameraPosition: request.cameraPosition ?? cameraPosition,
+					});
+					return manage(finalizeResult(raw, request, context));
+				});
+				logger.log({ type: 'capture', code: 'succeeded' });
+				return result;
+			} catch (error) {
+				// The contract promises a CameraError; a raw native error carries
+				// no code to branch on and its message may hold a file path.
+				const failure = isCameraError(error)
+					? error
+					: new CameraError('captureFailed', 'The camera failed to capture a photo');
+				logger.log({ type: 'capture', code: failure.code, recoverable: failure.recoverable });
+				throw failure;
+			} finally {
+				// Without this a failed capture left `capturing: true` published
+				// until some unrelated change emitted again.
+				emit();
+			}
+		},
+
+		async cleanup(image: CapturedImage | string) {
+			const uri = typeof image === 'string' ? image : image.uri;
+			if (!store) {
+				return;
+			}
+			// Refuse anything we did not create rather than deleting an arbitrary
+			// path, which also covers every appOwned artifact (FR-026b, FR-028).
+			if (!store.owns(uri)) {
+				logger.log({ type: 'cleanup', code: 'refused-not-owned' });
+				return;
+			}
+			await store.remove(uri);
+			logger.log({ type: 'cleanup', code: 'removed' });
+		},
+
+		async getCapabilities() {
+			live('getCapabilities');
+			try {
+				capabilities = await engine.getCapabilities();
+			} catch {
+				capabilities = EMPTY_CAPABILITIES;
+			}
+			logger.log({
+				type: 'capability',
+				code: capabilities.hasCameraHardware ? 'available' : 'no-hardware',
+			});
+			emit();
+			return capabilities;
+		},
+
+		setFlashMode(mode: FlashMode) {
+			assertSupported(mode === 'off' || capabilities?.hasFlash === true, `flash mode "${mode}"`);
+			flashMode = mode;
+			emit();
+		},
+
+		async setTorch(enabled: boolean) {
+			if (disposed && !enabled) {
+				return;
+			}
+			live('setTorch');
+			if (enabled) {
+				assertSupported(supportsTorch(capabilities), 'torch');
+			}
+			await engine.setTorch(enabled);
+			torchEnabled = enabled;
+			emit();
+		},
+
+		setSurfaceMounted(mounted: boolean) {
+			if (disposed) {
+				return;
+			}
+			surfaceMounted = mounted;
+		},
+
+		async dispose() {
+			if (disposed) {
+				return;
+			}
+			disposed = true;
+			resumeOnForeground = false;
+			detach?.();
+			detach = null;
+			await releaseCamera();
+			listeners.clear();
+		},
+	};
+
+	return controller;
+}