@chipmobilesdk/rn-camera 0.2.1 → 0.4.0

package/src/diagnostics/errors.ts

@@ -6,6 +6,8 @@
  * payloads — `redact` is applied before any value reaches a log sink.
  */
 
+import { COMMON_PATTERNS, PATH_PATTERN, SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
+
 export type CameraErrorCode =
 	| 'permissionDenied'
 	| 'cameraUnavailable'
@@ -32,16 +34,16 @@ const RECOVERABLE: ReadonlySet<CameraErrorCode> = new Set<CameraErrorCode>([
 	'interrupted',
 ]);
 
-export class CameraError extends Error {
-	readonly code: CameraErrorCode;
-	readonly recoverable: boolean;
-
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-camera'`. */
+export class CameraError extends SdkError<CameraErrorCode> {
 	constructor(code: CameraErrorCode, message?: string) {
-		super(message ?? code);
+		super('rn-camera', code, { message, retryable: RECOVERABLE.has(code) });
 		this.name = 'CameraError';
-		this.code = code;
-		this.recoverable = RECOVERABLE.has(code);
-		Object.setPrototypeOf(this, CameraError.prototype);
+	}
+
+	/** @deprecated Use `retryable`, the name every SDK package shares. */
+	get recoverable(): boolean {
+		return this.retryable;
 	}
 }
 
@@ -49,17 +51,17 @@ export function isCameraError(value: unknown): value is CameraError {
 	return value instanceof CameraError;
 }
 
-/** Matches anything path-like: file URIs, POSIX paths, and Windows paths. */
-const PATH_PATTERN =
-	/(?:[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"']+)|(?:[a-zA-Z]:[\\/][^\s"']+)|(?:\/[^\s"']*\/[^\s"']*)/g;
-/** Matches base64-ish runs long enough to be an encoded image payload. */
-const PAYLOAD_PATTERN = /[A-Za-z0-9+/=]{64,}/g;
+/**
+ * rn-core's shared patterns (URLs, including file URIs; JWTs; e-mail addresses;
+ * UUIDs; base64-ish payload runs) plus POSIX and Windows paths.
+ */
+const PATTERNS = [...COMMON_PATTERNS, PATH_PATTERN];
 
 const REDACTED = '[redacted]';
 const SENSITIVE_KEYS = new Set(['uri', 'path', 'destination', 'file', 'data', 'base64']);
 
 function redactString(value: string): string {
-	return value.replace(PATH_PATTERN, REDACTED).replace(PAYLOAD_PATTERN, REDACTED);
+	return redactPatterns(value, PATTERNS);
 }
 
 /**
@@ -76,7 +78,7 @@ export function redact(value: unknown): unknown {
 		return value.map(redact);
 	}
 	if (value instanceof CameraError) {
-		return { code: value.code, recoverable: value.recoverable };
+		return { code: value.code, recoverable: value.retryable };
 	}
 	if (value instanceof Error) {
 		return { name: value.name, message: redactString(value.message) };

package/src/diagnostics/logger.ts

@@ -6,18 +6,39 @@
  * image data — so an opted-in logger still cannot leak an image path.
  */
 
+import { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
 export type CameraLogEventType = 'session' | 'permission' | 'capture' | 'capability' | 'cleanup';
 
 export interface CameraLogEvent {
 	readonly type: CameraLogEventType;
 	readonly code: string;
-	readonly recoverable?: boolean;
+	readonly recoverable?: boolean | undefined;
 }
 
 export interface CameraLogger {
 	log(event: CameraLogEvent): void;
 }
 
+const channel = createDiagnosticChannel('rn-camera');
+
+/**
+ * Every event also reaches the app's SDK sinks (`installSdkSink`, CORE-08), as
+ * `<type>.<code>`: the same code-and-state body, so nothing new can leak.
+ */
+export function withSdkSinks(logger: CameraLogger): CameraLogger {
+	return {
+		log(event) {
+			channel.emit(
+				`${event.type}.${event.code}`,
+				event.code === 'listener-threw' ? 'error' : event.recoverable === false ? 'warn' : 'info',
+				event.recoverable === undefined ? undefined : { retryable: event.recoverable },
+			);
+			logger.log(event);
+		},
+	};
+}
+
 /** No-op logger used when the consumer supplies none. */
 export const silentLogger: CameraLogger = {
 	log() {

package/src/index.ts

@@ -39,7 +39,9 @@ export { createCameraController, DEFAULT_TEMPORARY_TTL_MS } from './core/control
 export type { AppStatus, CameraController, CameraControllerOptions } from './core/controller';
 
 // Ports + default adapters
-export type { CameraEngine, EngineOptions } from './native/cameraEngine';
+export type { CameraEngine } from './native/cameraEngine';
+export type { SurfaceInfo, SurfaceRegistry, VisionSurface } from './native/visionSurface';
+export { createSurfaceRegistry } from './native/visionSurface';
 export { createVisionCameraEngine } from './native/cameraEngine';
 export type { PermissionPort } from './permissions/permissionPort';
 export { createVisionCameraPermissions } from './permissions/permissionPort';

package/src/native/cameraEngine.ts

@@ -14,14 +14,16 @@
  * mounted preview surface (see `visionSurface`).
  */
 
+import { loadVisionCamera } from './visionCameraPeer';
 import type {
 	CapabilityProfile,
 	CapturedImage,
 	CaptureRequest,
 	StartOptions,
 } from '../config/types';
+import type { CameraErrorCode } from '../diagnostics/errors';
 import { CameraError } from '../diagnostics/errors';
-import { getActiveVisionSurface } from './visionSurface';
+import { createSurfaceRegistry, type VisionSurface } from './visionSurface';
 
 export interface CameraEngine {
 	start(options: StartOptions): Promise<void>;
@@ -29,11 +31,24 @@ export interface CameraEngine {
 	capture(request: CaptureRequest): Promise<CapturedImage>;
 	setTorch(enabled: boolean): Promise<void>;
 	getCapabilities(): Promise<CapabilityProfile>;
-}
-
-export interface EngineOptions {
-	/** Overrides device discovery. Primarily an escape hatch for diagnostics. */
-	readonly preferredPosition?: 'front' | 'back';
+	/**
+	 * True when `start()` only prepares the engine and the session becomes
+	 * active once a mounted preview surface reports frames. The controller then
+	 * waits for that report instead of calling the session active immediately,
+	 * and times out rather than sitting in `starting` forever (CAM-08).
+	 */
+	readonly awaitsSurfaceStart?: boolean;
+	/**
+	 * Attaches the mounted preview surface this engine captures through.
+	 * Returns the detach function. Engines that own their own session omit it.
+	 */
+	attachSurface?(surface: VisionSurface): () => void;
+	/**
+	 * The engine lost the camera: another app took it, a call came in, the
+	 * device was disconnected. The controller tears the session down with this
+	 * code rather than leaving a frozen preview (CAM-19).
+	 */
+	subscribeToInterruptions?(listener: (code: CameraErrorCode) => void): () => void;
 }
 
 /** The subset of VisionCamera's `CameraDevice` this adapter reads. */
@@ -48,9 +63,15 @@ interface DiscoveredDevice {
  * component, so this adapter owns capability discovery while `CameraPreview`
  * owns the rendered surface and the photo output that capture runs through.
  */
-export function createVisionCameraEngine(_options: EngineOptions = {}): CameraEngine {
-	// Lazy require: only loaded when the default adapter is actually used.
-	const { VisionCamera } = require('react-native-vision-camera');
+export function createVisionCameraEngine(): CameraEngine {
+	// One registry per engine, so two controllers never share a surface.
+	const surfaces = createSurfaceRegistry();
+	// Loaded when the default adapter is created; a missing peer is `cameraUnavailable`.
+	const { VisionCamera } = loadVisionCamera<{
+		VisionCamera: {
+			createDeviceFactory(): Promise<{ readonly cameraDevices: DiscoveredDevice[] }>;
+		};
+	}>();
 
 	// The factory is created once and reused: it keeps its own device list up to
 	// date, so re-creating it per call would only add latency.
@@ -62,6 +83,10 @@ export function createVisionCameraEngine(_options: EngineOptions = {}): CameraEn
 	}
 
 	return {
+		awaitsSurfaceStart: true,
+
+		attachSurface: surface => surfaces.attach(surface),
+
 		async start() {
 			// The preview component owns session activation; the engine only needs
 			// to confirm a device exists before the surface mounts.
@@ -76,7 +101,7 @@ export function createVisionCameraEngine(_options: EngineOptions = {}): CameraEn
 		},
 
 		async capture(request: CaptureRequest) {
-			const surface = getActiveVisionSurface();
+			const surface = surfaces.current();
 			if (!surface) {
 				throw new CameraError(
 					'notReady',

package/src/native/visionCameraPeer.ts

@@ -0,0 +1,30 @@
+/**
+ * react-native-vision-camera, loaded on first use (rn-core's lazy peer). A missing
+ * or unlinked module is a `cameraUnavailable` CameraError, the code the controller
+ * already reports when the camera cannot be reached.
+ */
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { CameraError } from '../diagnostics/errors';
+
+// The engine and the permission port each describe the slice they use.
+type VisionCameraModule = { VisionCamera: Record<string, (...args: never[]) => unknown> };
+
+const visionCamera = lazyPeer('react-native-vision-camera', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-vision-camera') as VisionCameraModule;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+export function loadVisionCamera<T>(): T {
+	return visionCamera.require(
+		peer =>
+			new CameraError(
+				'cameraUnavailable',
+				`${peer} is not installed or its native module is not linked`,
+			),
+	) as unknown as T;
+}

package/src/native/visionSurface.ts

@@ -1,34 +1,59 @@
 /**
- * Bridge between the mounted VisionCamera preview surface and the default
- * engine adapter.
+ * The port between a mounted preview surface and an engine.
  *
- * VisionCamera v5 owns capture through the session that the `<Camera>` view
+ * VisionCamera v5 owns capture through the session the `<Camera>` view
  * configures, so the photo output only exists while a surface is mounted. The
- * engine is created by the app before any surface exists, so the surface
- * registers itself here on mount and the engine reads it back at capture time.
+ * engine is created before any surface exists, so the surface attaches itself
+ * to the engine and the engine reads it back at capture time.
  *
- * A single registration slot is deliberate: one camera session can be active at
- * a time, so a second surface replacing the first is the correct behaviour.
+ * The registry belongs to an engine instance, not to the module. A module-level
+ * slot meant two controllers — two screens in a stack — shared one, so a
+ * capture could run through the other screen's surface (CAM-20).
  */
 
+import type { CameraErrorCode } from '../diagnostics/errors';
 import type { CapturedImage, CaptureRequest } from '../config/types';
 
+/** What the mounted preview actually is, once the device and format are known. */
+export interface SurfaceInfo {
+	/** Capture dimensions of the selected format, in pixels. */
+	readonly imageWidth: number;
+	readonly imageHeight: number;
+	/** Clockwise degrees the image is rotated relative to the preview. */
+	readonly orientation: number;
+	/** The position of the device actually mounted, whatever was asked for. */
+	readonly cameraPosition: 'front' | 'back';
+}
+
 export interface VisionSurface {
 	capture(request: CaptureRequest): Promise<CapturedImage>;
 }
 
-let active: VisionSurface | null = null;
+/** What a surface reports back about its own session. */
+export interface SurfaceEvents {
+	/** The preview is running: frames are arriving. */
+	onStarted(info: SurfaceInfo): void;
+	/** The session failed or was taken away (another app, a phone call). */
+	onFailed(code: CameraErrorCode): void;
+}
 
-/** Registers the mounted surface. Returns an unregister function. */
-export function registerVisionSurface(surface: VisionSurface): () => void {
-	active = surface;
-	return () => {
-		if (active === surface) {
-			active = null;
-		}
-	};
+export interface SurfaceRegistry {
+	/** Attaches the mounted surface. Returns the detach function. */
+	attach(surface: VisionSurface): () => void;
+	current(): VisionSurface | null;
 }
 
-export function getActiveVisionSurface(): VisionSurface | null {
-	return active;
+export function createSurfaceRegistry(): SurfaceRegistry {
+	let active: VisionSurface | null = null;
+	return {
+		attach(surface) {
+			active = surface;
+			return () => {
+				if (active === surface) {
+					active = null;
+				}
+			};
+		},
+		current: () => active,
+	};
 }

package/src/permissions/permissionPort.ts

@@ -12,6 +12,9 @@
  * statics since v5).
  */
 
+import { loadVisionCamera } from '../native/visionCameraPeer';
+import { appLifecycle, createListenerSet } from '@chipmobilesdk/rn-core';
+
 import type { CameraPermissionState } from '../config/types';
 
 export interface PermissionPort {
@@ -46,12 +49,16 @@ function mapStatus(raw: string): CameraPermissionState {
 }
 
 export function createVisionCameraPermissions(): PermissionPort {
-	// Lazy require: only loaded when the default adapter is actually used.
-	const { VisionCamera } = require('react-native-vision-camera');
-	const { AppState } = require('react-native');
-	const listeners = new Set<(state: CameraPermissionState) => void>();
+	// Loaded when the default adapter is created; a missing peer is `cameraUnavailable`.
+	const { VisionCamera } = loadVisionCamera<{
+		VisionCamera: {
+			readonly cameraPermissionStatus: string;
+			requestCameraPermission(): Promise<unknown>;
+		};
+	}>();
+	const listeners = createListenerSet<[CameraPermissionState]>();
 	let last: CameraPermissionState | null = null;
-	let appStateSubscription: { remove(): void } | null = null;
+	let stopWatchingLifecycle: (() => void) | null = null;
 
 	function read(): CameraPermissionState {
 		try {
@@ -66,9 +73,7 @@ export function createVisionCameraPermissions(): PermissionPort {
 	function emit(state: CameraPermissionState): CameraPermissionState {
 		if (state !== last) {
 			last = state;
-			for (const listener of listeners) {
-				listener(state);
-			}
+			listeners.notify(state);
 		}
 		return state;
 	}
@@ -92,22 +97,21 @@ export function createVisionCameraPermissions(): PermissionPort {
 		},
 
 		subscribe(listener) {
-			listeners.add(listener);
+			const remove = listeners.add(listener);
 			// Grants and revocations made in system Settings send the app through
 			// background/foreground, so re-reading on foreground is what surfaces
 			// them (FR-007). Attached only while somebody is listening.
-			if (!appStateSubscription) {
-				appStateSubscription = AppState.addEventListener('change', (next: string) => {
-					if (next === 'active') {
-						emit(read());
-					}
-				});
-			}
+			// rn-core's shared lifecycle port, so this adds no native subscription of its own.
+			stopWatchingLifecycle ??= appLifecycle().subscribe(state => {
+				if (state === 'active') {
+					emit(read());
+				}
+			});
 			return () => {
-				listeners.delete(listener);
-				if (listeners.size === 0 && appStateSubscription) {
-					appStateSubscription.remove();
-					appStateSubscription = null;
+				remove();
+				if (listeners.size === 0 && stopWatchingLifecycle) {
+					stopWatchingLifecycle();
+					stopWatchingLifecycle = null;
 				}
 			};
 		},

package/src/react/CameraPreview.tsx

@@ -18,6 +18,8 @@ import {
 
 import type { PreviewGeometry, ResizeMode } from '../config/types';
 import type { CameraController } from '../core/controller';
+import type { CameraErrorCode } from '../diagnostics/errors';
+import type { SurfaceInfo, VisionSurface } from '../native/visionSurface';
 import { useCameraState } from './hooks';
 import type { VisionCameraFeedProps } from './VisionCameraFeed';
 
@@ -33,7 +35,18 @@ export interface CameraPreviewProps {
 	readonly children?: React.ReactNode;
 }
 
-/** Nominal capture dimensions until the engine reports the real format. */
+/** The feed module failed to load; distinct from `null`, which means not requested. */
+const FEED_UNAVAILABLE = 'unavailable' as const;
+
+/**
+ * Nominal capture dimensions, until the mounted surface reports its own.
+ *
+ * Geometry built on these was landscape on a portrait phone, so every mapped
+ * rectangle was wrong on a real device (CAM-10). `onGeometryChange` now fires
+ * again with the real numbers as soon as the preview reports them, and apps
+ * that map coordinates should wait for `state.surface` rather than the first
+ * geometry.
+ */
 const DEFAULT_IMAGE_WIDTH = 1920;
 const DEFAULT_IMAGE_HEIGHT = 1080;
 
@@ -63,6 +76,19 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 		};
 	}, [controller]);
 
+	const attachSurface = useCallback(
+		(surface: VisionSurface) => controller.attachSurface(surface),
+		[controller],
+	);
+	const onSurfaceStarted = useCallback(
+		(info: SurfaceInfo) => controller.reportSurfaceStarted(info),
+		[controller],
+	);
+	const onSurfaceFailed = useCallback(
+		(code: CameraErrorCode) => controller.reportSurfaceFailed(code),
+		[controller],
+	);
+
 	const onLayout = useCallback((event: LayoutChangeEvent) => {
 		const { width, height } = event.nativeEvent.layout;
 		setLayout({ width, height });
@@ -72,16 +98,17 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 		if (!layout || layout.width === 0 || layout.height === 0) {
 			return null;
 		}
+		const surface = state.surface;
 		return {
-			imageWidth: DEFAULT_IMAGE_WIDTH,
-			imageHeight: DEFAULT_IMAGE_HEIGHT,
+			imageWidth: surface && surface.imageWidth > 0 ? surface.imageWidth : DEFAULT_IMAGE_WIDTH,
+			imageHeight: surface && surface.imageHeight > 0 ? surface.imageHeight : DEFAULT_IMAGE_HEIGHT,
 			previewWidth: layout.width,
 			previewHeight: layout.height,
 			resizeMode,
-			orientation: 0,
-			isMirrored: state.cameraPosition === 'front',
+			orientation: surface?.orientation ?? 0,
+			isMirrored: (surface?.cameraPosition ?? state.cameraPosition) === 'front',
 		};
-	}, [layout, resizeMode, state.cameraPosition]);
+	}, [layout, resizeMode, state.cameraPosition, state.surface]);
 
 	useEffect(() => {
 		if (geometry && onGeometryChange) {
@@ -89,7 +116,12 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 		}
 	}, [geometry, onGeometryChange]);
 
-	const feedRequested = state.session === 'active' && state.permission === 'granted';
+	// Mounted while the session is coming up, running, or paused: the surface is
+	// what makes it come up at all, and unmounting it on a pause meant rebuilding
+	// the device, the session and the photo output on every resume (CAM-08, CAM-09).
+	const feedRequested =
+		state.permission === 'granted' &&
+		(state.session === 'starting' || state.session === 'active' || state.session === 'paused');
 
 	// Lazy require so importing this package never pulls in the native module
 	// for consumers that only use the pure utilities or the test adapter.
@@ -101,10 +133,18 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 			return require('./VisionCameraFeed')
 				.VisionCameraFeed as React.ComponentType<VisionCameraFeedProps>;
 		} catch {
-			return null;
+			// Reported, not swallowed (CAM-21): the session fails with
+			// `cameraUnavailable` instead of showing a black preview.
+			return FEED_UNAVAILABLE;
 		}
 	}, [feedRequested]);
 
+	useEffect(() => {
+		if (Feed === FEED_UNAVAILABLE) {
+			controller.reportSurfaceUnavailable();
+		}
+	}, [Feed, controller]);
+
 	return (
 		<View
 			style={style}
@@ -113,11 +153,15 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 			accessibilityRole={accessibilityRole}
 			testID="rn-camera-preview"
 		>
-			{Feed ? (
+			{Feed && Feed !== FEED_UNAVAILABLE ? (
 				<Feed
 					cameraPosition={state.cameraPosition}
 					resizeMode={resizeMode}
 					torchEnabled={state.torchEnabled}
+					isActive={state.session !== 'paused'}
+					attachSurface={attachSurface}
+					onStarted={onSurfaceStarted}
+					onFailed={onSurfaceFailed}
 				/>
 			) : null}
 			{children}

package/src/react/VisionCameraFeed.tsx

@@ -26,16 +26,25 @@ import {
 	type CameraPosition,
 	type CapturedImage,
 	type CaptureRequest,
+	type Maybe,
 	type ResizeMode,
 } from '../config/types';
 import { DEFAULT_QUALITY } from '../core/captureController';
-import { CameraError, isCameraError } from '../diagnostics/errors';
-import { registerVisionSurface } from '../native/visionSurface';
+import { CameraError, isCameraError, type CameraErrorCode } from '../diagnostics/errors';
+import type { SurfaceInfo, VisionSurface } from '../native/visionSurface';
 
 export interface VisionCameraFeedProps {
 	readonly cameraPosition: CameraPosition;
 	readonly resizeMode: ResizeMode;
 	readonly torchEnabled: boolean;
+	/** False while the session is paused: the view stays mounted, the camera stops. */
+	readonly isActive: boolean;
+	/** Attaches this surface to the engine that captures through it. */
+	readonly attachSurface: (surface: VisionSurface) => () => void;
+	/** The preview is running; carries what the mounted device turned out to be. */
+	readonly onStarted: (info: SurfaceInfo) => void;
+	/** The session failed or the camera was taken away. */
+	readonly onFailed: (code: CameraErrorCode) => void;
 }
 
 const styles = StyleSheet.create({
@@ -57,6 +66,11 @@ const ORIENTATION_DEGREES: Record<string, number> = {
 	left: 270,
 };
 
+function orientationOf(orientation: string): Maybe<number> {
+	const degrees = ORIENTATION_DEGREES[orientation];
+	return degrees === undefined ? unavailable() : known(degrees);
+}
+
 function toFileUri(path: string): string {
 	return path.startsWith('file://') ? path : `file://${path}`;
 }
@@ -65,6 +79,20 @@ function toFilePath(uri: string): string {
 	return uri.startsWith('file://') ? uri.slice('file://'.length) : uri;
 }
 
+/**
+ * What a native session error means, from the code VisionCamera reports
+ * (CAM-08). Anything unrecognised is an interruption: the session is gone, and
+ * the app may try again.
+ */
+function nativeSessionCode(error: unknown): CameraErrorCode {
+	const code = String((error as { code?: unknown })?.code ?? '').toLowerCase();
+	if (code.includes('permission')) return 'permissionDenied';
+	if (code.includes('in-use') || code.includes('already-in-use')) return 'cameraInUse';
+	if (code.includes('unavailable') || code.includes('no-device')) return 'cameraUnavailable';
+	if (code.includes('restricted') || code.includes('blocked')) return 'cameraBlocked';
+	return 'interrupted';
+}
+
 /** Native failures carry no code and may name a file path; never surface them raw. */
 function asCameraError(error: unknown, code: 'captureFailed' | 'storageFailure'): CameraError {
 	return isCameraError(error) ? error : new CameraError(code);
@@ -73,6 +101,7 @@ function asCameraError(error: unknown, code: 'captureFailed' | 'storageFailure')
 async function capturePhoto(
 	photoOutput: CameraPhotoOutput,
 	request: CaptureRequest,
+	/** The device actually mounted; the request cannot ask for another one. */
 	cameraPosition: CameraPosition,
 ): Promise<CapturedImage> {
 	let photo: Awaited<ReturnType<CameraPhotoOutput['capturePhoto']>>;
@@ -111,7 +140,8 @@ async function capturePhoto(
 			width: photo.width,
 			height: photo.height,
 			timestamp: Date.now(),
-			cameraPosition: request.cameraPosition ?? cameraPosition,
+			// The camera that took it, not the one the request named (CAM-06).
+			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',
@@ -122,10 +152,7 @@ async function capturePhoto(
 			// 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(),
+			orientation: orientationOf(photo.orientation),
 		};
 	} finally {
 		// Large native buffers must not wait for the JS GC.
@@ -133,10 +160,37 @@ async function capturePhoto(
 	}
 }
 
+/** What the device actually is, for coordinate mapping (CAM-10). */
+function surfaceInfoOf(
+	device: { readonly position?: string; readonly formats?: readonly DeviceFormat[] } | undefined,
+	fallback: CameraPosition,
+): SurfaceInfo {
+	const format = device?.formats?.[0];
+	return {
+		imageWidth: format?.photoWidth ?? format?.videoWidth ?? 0,
+		imageHeight: format?.photoHeight ?? format?.videoHeight ?? 0,
+		orientation: 0,
+		cameraPosition:
+			device?.position === 'front' || device?.position === 'back' ? device.position : fallback,
+	};
+}
+
+/** The slice of VisionCamera's `CameraDeviceFormat` the geometry needs. */
+interface DeviceFormat {
+	readonly photoWidth?: number;
+	readonly photoHeight?: number;
+	readonly videoWidth?: number;
+	readonly videoHeight?: number;
+}
+
 export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 	cameraPosition,
 	resizeMode,
 	torchEnabled,
+	isActive,
+	attachSurface,
+	onStarted,
+	onFailed,
 }) => {
 	const device = useCameraDevice(cameraPosition);
 	const photoOutput = usePhotoOutput({ quality: DEFAULT_QUALITY });
@@ -148,7 +202,7 @@ export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 		[photoOutput, cameraPosition],
 	);
 
-	useEffect(() => registerVisionSurface(surface), [surface]);
+	useEffect(() => attachSurface(surface), [attachSurface, surface]);
 
 	// VisionCamera applies `torchMode` on mount, before the camera is active, and
 	// leaves the native "Camera is not active" rejection unhandled — one red
@@ -169,9 +223,15 @@ export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 			style={styles.feed}
 			device={device}
 			outputs={[photoOutput]}
-			isActive={true}
+			// Mounted through `paused` and `starting`: unmounting the view tore the
+			// session down and rebuilding it cost the first-frame budget (CAM-09).
+			isActive={isActive}
+			// The session is active when frames arrive, not when it was asked for.
+			onStarted={() => onStarted(surfaceInfoOf(device, cameraPosition))}
+			onError={(error: unknown) => onFailed(nativeSessionCode(error))}
 			resizeMode={resizeMode}
-			torchMode={torchMode}
+			// Left unset until the app first touches the torch, so the device's own default stands.
+			{...(torchMode === undefined ? {} : { torchMode })}
 		/>
 	);
 };