@chipmobilesdk/rn-camera 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @chipmobilesdk/rn-camera
 
+## 0.4.0
+
+### Minor Changes
+
+- `start()` resolves when the preview is producing frames. With the VisionCamera adapter the session belongs to the `<Camera>` view, so the controller now waits for that view to report instead of calling the session active as soon as the request was made — `capture()` straight after `start()` used to fail with `notReady`. A camera that never produces a frame fails the start after `startTimeoutMs` (8 s by default) rather than leaving the session in `starting` forever, and the native session errors the preview reports map to `cameraInUse`, `cameraBlocked`, `permissionDenied`, `cameraUnavailable` or `interrupted`. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  `pause()` keeps the preview surface mounted and stops the camera, so `resume()` no longer rebuilds the device, the session and the photo output — the whole first-frame cost was paid on every resume, with a black flash to go with it.
+
+  Geometry comes from the camera. `onGeometryChange` fires again with the selected format's pixel size, the device's orientation and the position of the device that actually mounted, as soon as the surface reports them; the same values are published as `state.surface`. Mapping a rectangle on a portrait phone was being done against a nominal landscape 1920×1080 image.
+
+  `capture({ cameraPosition })` must name the camera that is running, and is refused with `notReady` otherwise: the photo came from the device the preview had mounted while the metadata claimed the camera that was asked for. `start({ cameraPosition })` switches.
+
+  A failed `requestPermission()` leaves a state the app can retry from rather than `requesting` forever. An engine can report that the camera was taken away (`subscribeToInterruptions`), and the session fails with that code instead of showing a frozen preview; `createTestCamera()` simulates it with `emitInterruption(code?)` and a failing permission request with `emitPermissionRequestFailure(true)`.
+
+  The preview surface belongs to its engine (`attachSurface`, `createSurfaceRegistry`), not to a module-level slot two controllers shared — a capture from one screen could run through another screen's surface. `engine` and `permissions` are required by `CameraControllerOptions` (as they always were at runtime), the unused `EngineOptions` type is gone, and the artifact store reports a typed `CameraError` rather than a bare `Error`.
+
+### Patch Changes
+
+- Internal: no module in these packages is over 500 lines any more. The camera controller's session I/O moved to `sessionRuntime` and its contract to `contract.ts`; the Play adapter's shape translation to `iapShapes`; the purchase flow's failure mapping and its receipt-validation hook to modules of their own; the AI client's quota request to `quotaRequest`; the in-memory adapter's attachments and the fake ads engine's clock likewise. Behaviour is unchanged — the splits are by responsibility, and every package's suite passes as it stood. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  The repository also measures what it promised: `npm run perf` prints the median of nine runs of the deterministic hot paths against written budgets (recurrence expansion, theme construction, translation lookup, chart geometry, filter compilation), the demo app has a Performance screen reporting startup phases, time to interactive and the same benchmarks on Hermes, and `npm run check:file-size` keeps the limit from drifting. The budgets and the measured figures are recorded in `docs/standards.md` §VI.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -213,11 +213,39 @@ const inImageSpace = mapRectToImage(myGuideFrame, geometry);
 ```
 
 The pure mapping functions account for scale, letterbox or crop, orientation,
-and front-camera mirroring using the geometry you supply. In the current
-`CameraPreview`, `onGeometryChange` reports nominal image dimensions
-(`1920 × 1080`), orientation `0`, and mirroring from camera position; it does
-not yet read the selected native capture format. Use capture metadata or
-app-owned measured geometry when pixel-exact alignment is required.
+and front-camera mirroring using the geometry you supply.
+
+`onGeometryChange` fires first with nominal dimensions (`1920 × 1080`,
+orientation `0`) because the preview has been measured before the camera has,
+and again with the real ones as soon as the surface reports: the selected
+format's pixel size, the device's orientation, and the position of the device
+that actually mounted. The same values are on `state.surface`, which is `null`
+until then — map coordinates once it is set, or a rectangle will be mapped
+against a landscape image on a portrait phone.
+
+### Starting, pausing, and what "active" means
+
+`start()` resolves when the preview is producing frames, not when the request
+was made: with the VisionCamera adapter the session belongs to the `<Camera>`
+view, so the controller waits for it to report and `capture()` straight after
+`start()` works. A camera that never produces a frame fails the start after
+`startTimeoutMs` (8 s by default) instead of leaving the session in `starting`.
+
+`pause()` keeps the surface mounted and stops the camera; `resume()` therefore
+does not rebuild the device, the session and the photo output. The surface is
+unmounted only when the session stops, fails, or loses permission.
+
+An engine can report that the camera was taken away — another app, an incoming
+call, a disconnected device — through `subscribeToInterruptions`. The session
+fails with that code rather than showing a frozen preview; `createTestCamera()`
+simulates it with `emitInterruption(code?)`.
+
+### Which camera a capture comes from
+
+`capture({ cameraPosition })` must name the camera that is running: a photo
+comes from the device the preview mounted, so a request for the other one is
+refused with `notReady` rather than returning an image labelled with a camera
+that did not take it. Call `start({ cameraPosition })` to switch first.
 
 ### Quality and dimensions
 
@@ -359,8 +387,9 @@ Everything is exported from `@chipmobilesdk/rn-camera`, test doubles and conform
   `CameraState`, `AppStatus`, `DEFAULT_TEMPORARY_TTL_MS`
 - Preview and capture: `CameraPreview`, `CameraPreviewProps`, `CaptureRequest`,
   `CapturedImage`, `StartOptions` and the camera/session/capability types
-- Ports and adapters: `CameraEngine`, `EngineOptions`,
-  `createVisionCameraEngine`, `PermissionPort`,
+- Ports and adapters: `CameraEngine`, `createVisionCameraEngine`,
+  `VisionSurface`, `SurfaceInfo`, `SurfaceRegistry`, `createSurfaceRegistry`,
+  `PermissionPort`,
   `createVisionCameraPermissions`, `ArtifactStore`, `FileSystemBridge`,
   `StoreOptions`, `createCacheArtifactStore`, `createArtifactStore`
 - Mapping: `mapPointToImage`, `mapPointToPreview`, `mapRectToImage`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-camera",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

package/skills/sdk-rn-camera/SKILL.md

@@ -56,9 +56,25 @@ Runtime:
 - Conformance (`@chipmobilesdk/rn-camera/testing`): `runPermissionPortConformance`,
   `runCameraEngineConformance` — run against any adapter you write or inject
 
-Types: `CameraEngine`, `EngineOptions`, `PermissionPort`, `ArtifactStore`,
-`FileSystemBridge`, `StoreOptions`, `CameraErrorCode`, `CameraLogEvent`,
-`CameraLogEventType`, `CameraLogger`
+Types: `CameraEngine`, `PermissionPort`, `ArtifactStore`, `FileSystemBridge`,
+`StoreOptions`, `VisionSurface`, `SurfaceInfo`, `SurfaceRegistry`,
+`CameraErrorCode`, `CameraLogEvent`, `CameraLogEventType`, `CameraLogger`
+
+## Three things the lifecycle guarantees
+
+- **`start()` resolves when frames arrive.** `capture()` straight after it works, and a
+  camera that never produces a frame fails the start (8 s by default) instead of leaving
+  the session in `starting`.
+- **`pause()` keeps the surface mounted** and stops the camera, so `resume()` is cheap.
+- **`capture({ cameraPosition })` must name the running camera.** A photo comes from the
+  device the preview mounted; asking for the other one is `notReady`. Switch with
+  `start({ cameraPosition })`.
+
+## Coordinate mapping waits for the surface
+
+`state.surface` is `null` until the preview reports its real format, and
+`onGeometryChange` fires again with those numbers. Map rectangles after it is set —
+before that the geometry is a nominal landscape 1920×1080.
 
 Always pass camera log payloads through `redact` before logging.
 

package/src/config/types.ts

@@ -21,6 +21,8 @@ export type FlashMode = 'auto' | 'on' | 'off';
 export type ResizeMode = 'cover' | 'contain';
 export type ArtifactOwnership = 'packageTemporary' | 'appOwned';
 
+import type { SurfaceInfo } from '../native/visionSurface';
+
 export type SessionStatus =
 	'idle' | 'starting' | 'active' | 'paused' | 'stopping' | 'stopped' | 'error';
 
@@ -129,6 +131,12 @@ export interface CameraState {
 	readonly flashMode: FlashMode;
 	readonly torchEnabled: boolean;
 	readonly capturing: boolean;
+	/**
+	 * What the mounted preview surface reported about itself: the capture
+	 * dimensions of the selected format, its orientation, and the position of
+	 * the device actually running. `null` until a surface reports (CAM-10).
+	 */
+	readonly surface: SurfaceInfo | null;
 	readonly error: CameraErrorLike | null;
 }
 

package/src/core/captureController.ts

@@ -67,6 +67,15 @@ export function assertCaptureAllowed(context: CaptureContext, request: CaptureRe
 
 	const position = request.cameraPosition ?? context.cameraPosition;
 	assertSupported(supportsPosition(context.capabilities, position), `${position} camera`);
+	if (position !== context.cameraPosition) {
+		// The photo would come from the camera that is running, while the
+		// metadata said it came from the one that was asked for (CAM-06).
+		throw new CameraError(
+			'notReady',
+			`The ${context.cameraPosition} camera is running. Call start({ cameraPosition: ` +
+				`'${position}' }) before capturing with the ${position} camera.`,
+		);
+	}
 }
 
 /**
@@ -83,7 +92,8 @@ export function finalizeResult(
 	return {
 		...raw,
 		ownership,
-		cameraPosition: raw.cameraPosition ?? request.cameraPosition ?? context.cameraPosition,
+		// The camera that took it, which the guard above has made the running one.
+		cameraPosition: raw.cameraPosition ?? context.cameraPosition,
 		timestamp: raw.timestamp ?? Date.now(),
 		effectiveQuality: raw.effectiveQuality ?? clampQuality(request.quality),
 		effectiveMaxDimension: raw.effectiveMaxDimension ?? clampMaxDimension(request.maxDimension),

package/src/core/contract.ts

@@ -0,0 +1,109 @@
+/**
+ * What a camera controller is, for the app that drives it.
+ *
+ * The contract lives apart from the orchestration in `controller.ts`: it is
+ * what a consumer reads, and what a test double has to satisfy, while the file
+ * next to it is how this package happens to satisfy it.
+ */
+
+import type {
+	CameraPermissionState,
+	CameraState,
+	CapabilityProfile,
+	CapturedImage,
+	CaptureRequest,
+	FlashMode,
+	StartOptions,
+} from '../config/types';
+import type { CameraError } from '../diagnostics/errors';
+import type { CameraLogger } from '../diagnostics/logger';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { SurfaceInfo, VisionSurface } from '../native/visionSurface';
+import type { PermissionPort } from '../permissions/permissionPort';
+import type { ArtifactStore } from '../storage/artifactStore';
+
+export const DEFAULT_TEMPORARY_TTL_MS = 24 * 60 * 60 * 1000;
+
+export type AppStatus = 'active' | 'background';
+
+export interface CameraControllerOptions {
+	/** Required. Use the default adapters, or `createTestCamera()` in tests. */
+	readonly engine: CameraEngine;
+	readonly permissions: PermissionPort;
+	readonly store?: ArtifactStore | undefined;
+	readonly logger?: CameraLogger | undefined;
+	readonly temporaryTtlMs?: number;
+	/**
+	 * App foreground/background source. Defaults to rn-core's shared `appLifecycle()`,
+	 * where `inactive` counts as background. 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;
+	/**
+	 * How long to wait for a preview surface to report frames before failing the
+	 * start (FR-014). Only applies to an engine whose session belongs to the
+	 * surface (`awaitsSurfaceStart`). Defaults to 8 s.
+	 */
+	readonly startTimeoutMs?: number;
+	/** Test seam for that timeout. */
+	readonly scheduler?: {
+		setTimeout(callback: () => void, ms: number): unknown;
+		clearTimeout(handle: unknown): void;
+	};
+}
+
+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;
+	/**
+	 * Attaches the mounted preview surface to the engine, for an engine that
+	 * captures through it. Returns the detach function; a no-op for engines that
+	 * own their own session.
+	 */
+	attachSurface(surface: VisionSurface): () => void;
+	/**
+	 * The preview reported frames: the session is active for real, not merely
+	 * requested (CAM-08). What the surface turned out to be — the format's pixel
+	 * size, the orientation, the device's own position — is published as
+	 * `state.surface` for coordinate mapping.
+	 */
+	reportSurfaceStarted(info: SurfaceInfo): void;
+	/** The preview's own session failed, or the OS took the camera away. */
+	reportSurfaceFailed(code: CameraError['code']): void;
+	/**
+	 * Called by `CameraPreview` when the native preview surface cannot load (the
+	 * VisionCamera module is missing or unlinked). Fails the session with
+	 * `cameraUnavailable` rather than leaving a black preview and no error.
+	 */
+	reportSurfaceUnavailable(): 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>;
+}

package/src/core/controller.ts

@@ -20,10 +20,15 @@ import {
 	type StartOptions,
 } from '../config/types';
 import { CameraError, isCameraError } from '../diagnostics/errors';
-import { silentLogger, withSdkSinks, 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,
@@ -32,66 +37,15 @@ 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 | undefined;
-	readonly logger?: CameraLogger | undefined;
-	readonly temporaryTtlMs?: number;
-	/**
-	 * App foreground/background source. Defaults to rn-core's shared `appLifecycle()`,
-	 * where `inactive` counts as background. 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;
-	/**
-	 * Called by `CameraPreview` when the native preview surface cannot load (the
-	 * VisionCamera module is missing or unlinked). Fails the session with
-	 * `cameraUnavailable` rather than leaving a black preview and no error.
-	 */
-	reportSurfaceUnavailable(): 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 {
 	// rn-core's one lifecycle subscription, shared with every other package; it
@@ -99,8 +53,13 @@ function defaultAppStateSubscribe(listener: (status: AppStatus) => void): () =>
 	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 ' +
@@ -108,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 = 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;
@@ -123,13 +87,6 @@ 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;
 
@@ -138,6 +95,33 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 		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 {
 			session: session.status,
@@ -147,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,
@@ -179,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
@@ -262,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
@@ -351,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;
 		},
@@ -369,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;
 			}
@@ -379,7 +315,7 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			if (disposed) {
 				return;
 			}
-			await forceTorchOff();
+			await runtime.forceTorchOff();
 			dispatch({ type: 'PAUSE' });
 		},
 
@@ -387,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 = {}) {
@@ -498,6 +434,18 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			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;
@@ -510,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();
 		},
 	};