@chipmobilesdk/rn-camera 0.3.0 → 0.5.0

package/package.json

@@ -1,20 +1,34 @@
 {
 	"name": "@chipmobilesdk/rn-camera",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"private": false,
 	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
+	"source": "./src/index.ts",
+	"main": "./lib/commonjs/index.js",
+	"module": "./lib/module/index.js",
+	"types": "./lib/typescript/commonjs/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
+			"chipmobilesdk-source": "./src/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/index.d.ts",
+				"default": "./lib/module/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/index.d.ts",
+				"default": "./lib/commonjs/index.js"
+			}
 		},
 		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
+			"chipmobilesdk-source": "./src/testing/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/testing/index.d.ts",
+				"default": "./lib/module/testing/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/testing/index.d.ts",
+				"default": "./lib/commonjs/testing/index.js"
+			}
 		}
 	},
 	"files": [
@@ -30,23 +44,45 @@
 		"src/testing",
 		"skills",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"lib"
 	],
 	"sideEffects": false,
 	"scripts": {
+		"build": "bob build",
 		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
-		"pack:check": "npm pack --dry-run"
+		"pack:check": "npm pack --dry-run",
+		"prepack": "npm run build"
 	},
 	"dependencies": {
-		"@chipmobilesdk/rn-core": "^0.1.0"
+		"@chipmobilesdk/rn-core": "^0.2.0"
 	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",
-		"react-native-vision-camera": ">=5.1.1"
+		"react-native-vision-camera": "^5.1.1"
 	},
 	"publishConfig": {
 		"access": "public",
 		"registry": "https://registry.npmjs.org/"
+	},
+	"react-native-builder-bob": {
+		"source": "src",
+		"output": "lib",
+		"targets": [
+			[
+				"commonjs",
+				{
+					"esm": true
+				}
+			],
+			[
+				"module",
+				{
+					"esm": true
+				}
+			],
+			"typescript"
+		]
 	}
 }

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

@@ -39,8 +39,10 @@ delete them. See `## Data behaviour` for what this means for App Privacy disclos
 ## Test without hardware
 
 `createTestCamera`, `createMemoryFileSystem` and `DEFAULT_TEST_CAPABILITIES` let camera
-flows be unit-tested with no device. Use these rather than mocking VisionCamera by hand —
-see `## Testing without hardware`.
+flows be unit-tested with no device. Import them from
+`@chipmobilesdk/rn-camera/testing`, never the main entrypoint — as of 0.4.0 that is the
+only place they are, so a fake camera cannot reach an app's bundle. Use these rather
+than mocking VisionCamera by hand — see `## Testing without hardware`.
 
 ## Public API
 
@@ -52,13 +54,30 @@ Runtime:
 - `createArtifactStore(...)`, `createCacheArtifactStore(...)`
 - `CameraPreview` (+ `CameraPreviewProps`)
 - `CameraError`, `isCameraError`, `redact` — `redact` strips sensitive paths before logging
-- Testing: `createTestCamera`, `createMemoryFileSystem`, `DEFAULT_TEST_CAPABILITIES`
+- Testing (`@chipmobilesdk/rn-camera/testing`): `createTestCamera`,
+  `createMemoryFileSystem`, `DEFAULT_TEST_CAPABILITIES`
 - 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();
 		},
 	};