@chipmobilesdk/rn-camera 0.2.0 → 0.3.0

package/src/core/captureController.ts

@@ -1,120 +1,120 @@
-/**
- * Capture guards, single-flight enforcement, and metadata assembly
- * (FR-020..FR-026b).
- *
- * The single-flight guard rejects rather than queues or coalesces. A queue
- * turns a double-tapped shutter into two photos the user never asked for, and
- * coalescing hides a deliberate second capture behind an accidental one — so a
- * fast, explicit `captureInProgress` error is the only option that lets the app
- * decide (clarification session 2026-07-26).
- */
-
-import {
-	known,
-	unavailable,
-	type CameraPosition,
-	type CapabilityProfile,
-	type CapturedImage,
-	type CaptureRequest,
-	type FlashMode,
-	type Maybe,
-	type SessionStatus,
-} from '../config/types';
-import { CameraError } from '../diagnostics/errors';
-import type { CameraEngine } from '../native/cameraEngine';
-import { assertSupported, supportsFlashMode, supportsPosition } from './capabilities';
-import { canCapture } from './sessionMachine';
-
-export const DEFAULT_QUALITY = 0.9;
-
-export function clampQuality(quality: number | undefined): number {
-	if (quality === undefined || Number.isNaN(quality)) {
-		return DEFAULT_QUALITY;
-	}
-	return Math.min(1, Math.max(0, quality));
-}
-
-export function clampMaxDimension(maxDimension: number | undefined): Maybe<number> {
-	if (maxDimension === undefined || !Number.isFinite(maxDimension) || maxDimension <= 0) {
-		return unavailable();
-	}
-	return known(Math.floor(maxDimension));
-}
-
-export interface CaptureContext {
-	readonly engine: CameraEngine;
-	readonly sessionStatus: SessionStatus;
-	readonly permissionGranted: boolean;
-	readonly capabilities: CapabilityProfile | null;
-	readonly cameraPosition: CameraPosition;
-	readonly flashMode: FlashMode;
-}
-
-/**
- * Validates a capture request against permission, readiness, and capability.
- * Throws before any artifact could be created, so a rejected capture never
- * leaves a file behind (FR-020).
- */
-export function assertCaptureAllowed(context: CaptureContext, request: CaptureRequest): void {
-	if (!context.permissionGranted) {
-		throw new CameraError('permissionDenied', 'Camera permission is not granted');
-	}
-	if (!canCapture(context.sessionStatus)) {
-		throw new CameraError('notReady', `Camera is not ready (session: ${context.sessionStatus})`);
-	}
-	const flashMode = request.flashMode ?? context.flashMode;
-	assertSupported(supportsFlashMode(context.capabilities, flashMode), `flash mode "${flashMode}"`);
-
-	const position = request.cameraPosition ?? context.cameraPosition;
-	assertSupported(supportsPosition(context.capabilities, position), `${position} camera`);
-}
-
-/**
- * Normalizes whatever the engine returned into the published contract, filling
- * in effective hint values and marking undeterminable fields explicitly
- * unavailable rather than guessing them (FR-022, FR-023).
- */
-export function finalizeResult(
-	raw: CapturedImage,
-	request: CaptureRequest,
-	context: CaptureContext,
-): CapturedImage {
-	const ownership = request.destination ? 'appOwned' : 'packageTemporary';
-	return {
-		...raw,
-		ownership,
-		cameraPosition: raw.cameraPosition ?? request.cameraPosition ?? context.cameraPosition,
-		timestamp: raw.timestamp ?? Date.now(),
-		effectiveQuality: raw.effectiveQuality ?? clampQuality(request.quality),
-		effectiveMaxDimension: raw.effectiveMaxDimension ?? clampMaxDimension(request.maxDimension),
-		fileSize: raw.fileSize ?? unavailable(),
-		orientation: raw.orientation ?? unavailable(),
-	};
-}
-
-/**
- * Serializes captures. The slot is taken synchronously, before the operation
- * runs, so two calls in the same tick cannot both pass the check — and the
- * operation's own first `emit()` already sees `busy`. Holding the operation's
- * promise instead set the slot only after that first emit, so `capturing: true`
- * was never published at all.
- */
-export class SingleFlight {
-	private active = false;
-
-	get busy(): boolean {
-		return this.active;
-	}
-
-	async run(operation: () => Promise<CapturedImage>): Promise<CapturedImage> {
-		if (this.active) {
-			throw new CameraError('captureInProgress', 'A capture is already in progress');
-		}
-		this.active = true;
-		try {
-			return await operation();
-		} finally {
-			this.active = false;
-		}
-	}
-}
+/**
+ * Capture guards, single-flight enforcement, and metadata assembly
+ * (FR-020..FR-026b).
+ *
+ * The single-flight guard rejects rather than queues or coalesces. A queue
+ * turns a double-tapped shutter into two photos the user never asked for, and
+ * coalescing hides a deliberate second capture behind an accidental one — so a
+ * fast, explicit `captureInProgress` error is the only option that lets the app
+ * decide (clarification session 2026-07-26).
+ */
+
+import {
+	known,
+	unavailable,
+	type CameraPosition,
+	type CapabilityProfile,
+	type CapturedImage,
+	type CaptureRequest,
+	type FlashMode,
+	type Maybe,
+	type SessionStatus,
+} from '../config/types';
+import { CameraError } from '../diagnostics/errors';
+import type { CameraEngine } from '../native/cameraEngine';
+import { assertSupported, supportsFlashMode, supportsPosition } from './capabilities';
+import { canCapture } from './sessionMachine';
+
+export const DEFAULT_QUALITY = 0.9;
+
+export function clampQuality(quality: number | undefined): number {
+	if (quality === undefined || Number.isNaN(quality)) {
+		return DEFAULT_QUALITY;
+	}
+	return Math.min(1, Math.max(0, quality));
+}
+
+export function clampMaxDimension(maxDimension: number | undefined): Maybe<number> {
+	if (maxDimension === undefined || !Number.isFinite(maxDimension) || maxDimension <= 0) {
+		return unavailable();
+	}
+	return known(Math.floor(maxDimension));
+}
+
+export interface CaptureContext {
+	readonly engine: CameraEngine;
+	readonly sessionStatus: SessionStatus;
+	readonly permissionGranted: boolean;
+	readonly capabilities: CapabilityProfile | null;
+	readonly cameraPosition: CameraPosition;
+	readonly flashMode: FlashMode;
+}
+
+/**
+ * Validates a capture request against permission, readiness, and capability.
+ * Throws before any artifact could be created, so a rejected capture never
+ * leaves a file behind (FR-020).
+ */
+export function assertCaptureAllowed(context: CaptureContext, request: CaptureRequest): void {
+	if (!context.permissionGranted) {
+		throw new CameraError('permissionDenied', 'Camera permission is not granted');
+	}
+	if (!canCapture(context.sessionStatus)) {
+		throw new CameraError('notReady', `Camera is not ready (session: ${context.sessionStatus})`);
+	}
+	const flashMode = request.flashMode ?? context.flashMode;
+	assertSupported(supportsFlashMode(context.capabilities, flashMode), `flash mode "${flashMode}"`);
+
+	const position = request.cameraPosition ?? context.cameraPosition;
+	assertSupported(supportsPosition(context.capabilities, position), `${position} camera`);
+}
+
+/**
+ * Normalizes whatever the engine returned into the published contract, filling
+ * in effective hint values and marking undeterminable fields explicitly
+ * unavailable rather than guessing them (FR-022, FR-023).
+ */
+export function finalizeResult(
+	raw: CapturedImage,
+	request: CaptureRequest,
+	context: CaptureContext,
+): CapturedImage {
+	const ownership = request.destination ? 'appOwned' : 'packageTemporary';
+	return {
+		...raw,
+		ownership,
+		cameraPosition: raw.cameraPosition ?? request.cameraPosition ?? context.cameraPosition,
+		timestamp: raw.timestamp ?? Date.now(),
+		effectiveQuality: raw.effectiveQuality ?? clampQuality(request.quality),
+		effectiveMaxDimension: raw.effectiveMaxDimension ?? clampMaxDimension(request.maxDimension),
+		fileSize: raw.fileSize ?? unavailable(),
+		orientation: raw.orientation ?? unavailable(),
+	};
+}
+
+/**
+ * Serializes captures. The slot is taken synchronously, before the operation
+ * runs, so two calls in the same tick cannot both pass the check — and the
+ * operation's own first `emit()` already sees `busy`. Holding the operation's
+ * promise instead set the slot only after that first emit, so `capturing: true`
+ * was never published at all.
+ */
+export class SingleFlight {
+	private active = false;
+
+	get busy(): boolean {
+		return this.active;
+	}
+
+	async run(operation: () => Promise<CapturedImage>): Promise<CapturedImage> {
+		if (this.active) {
+			throw new CameraError('captureInProgress', 'A capture is already in progress');
+		}
+		this.active = true;
+		try {
+			return await operation();
+		} finally {
+			this.active = false;
+		}
+	}
+}