@chipmobilesdk/rn-camera 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # @chipmobilesdk/rn-camera
 
+## 0.3.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+
+### Patch Changes
+
+- `createCameraController` accepts an explicit `undefined` for `store` and `logger`, so
+  apps compiling with `exactOptionalPropertyTypes` type-check against the package.
+  `VisionCameraFeed` leaves `torchMode` unset until the app first touches the torch,
+  instead of passing `undefined`. No other change. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -256,6 +256,31 @@ camera.setAppState('background');
 camera.emitInterruption();
 ```
 
+### Conformance
+
+`@chipmobilesdk/rn-camera/testing` also ships the checks every `PermissionPort` and
+`CameraEngine` must pass. The package runs them against the test adapter and against the
+VisionCamera adapters; run them against your own adapter, or from a demo screen on a
+device, the same way:
+
+```ts
+import { expectConformance } from '@chipmobilesdk/rn-core/testing';
+import { runPermissionPortConformance } from '@chipmobilesdk/rn-camera/testing';
+
+expectConformance(
+  await runPermissionPortConformance({
+    create(initial) {
+      // a port over a system whose permission starts in `initial`
+      return { port, setSystemState, prompts };
+    },
+  }),
+);
+```
+
+`createTestCamera` and its helpers are exported from `./testing` too; the main
+entrypoint keeps them until the next major release. `camera.prompts()` counts how often
+`request()` showed the system prompt.
+
 Add a module mapping so an accidental import of the native module resolves in Jest:
 
 ```js
@@ -266,7 +291,8 @@ moduleNameMapper: {
 
 ## Errors
 
-Every failure is a `CameraError` with a `code` and a `recoverable` flag, so you branch on the code rather than string-matching a message:
+Every failure is a `CameraError` with a `code` and a `retryable` flag (`recoverable` is kept as its deprecated alias), so you branch on the code rather than string-matching a message. `CameraError` extends `SdkError` from `@chipmobilesdk/rn-core`, so `isSdkError(error)` recognises it alongside every other package's errors, `error.pkg` names this package, and `error.redactedCause` (when present) is the underlying failure reduced to log-safe text.
+
 
 `permissionDenied`, `cameraUnavailable`, `cameraBlocked`, `cameraInUse`, `sessionConflict`, `notReady`, `captureInProgress`, `captureFailed`, `storageFailure`, `unsupportedCapability`, `interrupted`.
 
@@ -326,7 +352,7 @@ Still capture and real-time frame processing stay strictly separate.
 
 ## Public API
 
-Everything is exported from `@chipmobilesdk/rn-camera`. Modules under `core/`, `native/`, `permissions/`, `storage/`, `geometry/`, `diagnostics/`, and `testing/` are private — do not deep-import them.
+Everything is exported from `@chipmobilesdk/rn-camera`, test doubles and conformance suites also from `@chipmobilesdk/rn-camera/testing`. Modules under `core/`, `native/`, `permissions/`, `storage/`, `geometry/`, `diagnostics/`, and `testing/` are private — do not deep-import them.
 
 - Controller and state: `createCameraController`, `CameraController`,
   `CameraControllerOptions`, `useCameraController`, `useCameraState`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-camera",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -10,6 +10,11 @@
 			"types": "./src/index.ts",
 			"react-native": "./src/index.ts",
 			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
 		}
 	},
 	"files": [
@@ -29,9 +34,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

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

@@ -53,6 +53,8 @@ Runtime:
 - `CameraPreview` (+ `CameraPreviewProps`)
 - `CameraError`, `isCameraError`, `redact` — `redact` strips sensitive paths before logging
 - 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`,

package/src/core/controller.ts

@@ -7,6 +7,8 @@
  * tested without a camera.
  */
 
+import { appLifecycle, createListenerSet } from '@chipmobilesdk/rn-core';
+
 import {
 	type CameraPermissionState,
 	type CameraPosition,
@@ -18,7 +20,7 @@ import {
 	type StartOptions,
 } from '../config/types';
 import { CameraError, isCameraError } from '../diagnostics/errors';
-import { silentLogger, type CameraLogger } from '../diagnostics/logger';
+import { silentLogger, withSdkSinks, type CameraLogger } from '../diagnostics/logger';
 import type { CameraEngine } from '../native/cameraEngine';
 import type { PermissionPort } from '../permissions/permissionPort';
 import type { ArtifactStore } from '../storage/artifactStore';
@@ -39,12 +41,13 @@ export type AppStatus = 'active' | 'background';
 export interface CameraControllerOptions {
 	readonly engine?: CameraEngine;
 	readonly permissions?: PermissionPort;
-	readonly store?: ArtifactStore;
-	readonly logger?: CameraLogger;
+	readonly store?: ArtifactStore | undefined;
+	readonly logger?: CameraLogger | undefined;
 	readonly temporaryTtlMs?: number;
 	/**
-	 * App foreground/background source. Defaults to React Native `AppState`.
-	 * Injectable so lifecycle rules are testable without an app (FR-015).
+	 * 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;
 	/**
@@ -75,6 +78,12 @@ export interface CameraController {
 
 	/** 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
@@ -85,13 +94,9 @@ export interface CameraController {
 }
 
 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();
+	// rn-core's one lifecycle subscription, shared with every other package; it
+	// requires react-native only on first subscribe (PERF-07).
+	return appLifecycle().subscribe(state => listener(state === 'active' ? 'active' : 'background'));
 }
 
 export function createCameraController(options: CameraControllerOptions = {}): CameraController {
@@ -107,7 +112,7 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 	const engine: CameraEngine = options.engine;
 	const permissions: PermissionPort = options.permissions;
 	const store = options.store;
-	const logger = options.logger ?? silentLogger;
+	const logger = withSdkSinks(options.logger ?? silentLogger);
 	const ttlMs = options.temporaryTtlMs ?? DEFAULT_TEMPORARY_TTL_MS;
 
 	let session: SessionSnapshot = initialSession;
@@ -129,7 +134,9 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 	let detach: (() => void) | null = null;
 
 	const capture = new SingleFlight();
-	const listeners = new Set<(state: CameraState) => void>();
+	const listeners = createListenerSet<[CameraState]>({
+		onListenerError: () => logger.log({ type: 'session', code: 'listener-threw' }),
+	});
 
 	function snapshot(): CameraState {
 		return {
@@ -154,15 +161,9 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 
 	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' });
-			}
-		}
+		// Isolated: one throwing subscriber neither starves the others nor unwinds
+		// into the transition that emitted, which left the controller half-updated.
+		listeners.notify(current);
 	}
 
 	function dispatch(event: Parameters<typeof sessionReducer>[1]): void {
@@ -336,10 +337,7 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 				return () => undefined;
 			}
 			attach();
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
+			return listeners.add(listener);
 		},
 
 		async getPermission() {
@@ -492,6 +490,14 @@ export function createCameraController(options: CameraControllerOptions = {}): C
 			emit();
 		},
 
+		reportSurfaceUnavailable() {
+			if (disposed) {
+				return;
+			}
+			logger.log({ type: 'session', code: 'surface-unavailable', recoverable: false });
+			dispatch({ type: 'FAIL', code: 'cameraUnavailable' });
+		},
+
 		setSurfaceMounted(mounted: boolean) {
 			if (disposed) {
 				return;

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/native/cameraEngine.ts

@@ -14,6 +14,7 @@
  * mounted preview surface (see `visionSurface`).
  */
 
+import { loadVisionCamera } from './visionCameraPeer';
 import type {
 	CapabilityProfile,
 	CapturedImage,
@@ -49,8 +50,12 @@ interface DiscoveredDevice {
  * 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');
+	// 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.

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/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

@@ -33,6 +33,9 @@ export interface CameraPreviewProps {
 	readonly children?: React.ReactNode;
 }
 
+/** The feed module failed to load; distinct from `null`, which means not requested. */
+const FEED_UNAVAILABLE = 'unavailable' as const;
+
 /** Nominal capture dimensions until the engine reports the real format. */
 const DEFAULT_IMAGE_WIDTH = 1920;
 const DEFAULT_IMAGE_HEIGHT = 1080;
@@ -101,10 +104,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,7 +124,7 @@ export const CameraPreview: React.FC<CameraPreviewProps> = ({
 			accessibilityRole={accessibilityRole}
 			testID="rn-camera-preview"
 		>
-			{Feed ? (
+			{Feed && Feed !== FEED_UNAVAILABLE ? (
 				<Feed
 					cameraPosition={state.cameraPosition}
 					resizeMode={resizeMode}

package/src/react/VisionCameraFeed.tsx

@@ -26,6 +26,7 @@ import {
 	type CameraPosition,
 	type CapturedImage,
 	type CaptureRequest,
+	type Maybe,
 	type ResizeMode,
 } from '../config/types';
 import { DEFAULT_QUALITY } from '../core/captureController';
@@ -57,6 +58,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}`;
 }
@@ -122,10 +128,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.
@@ -171,7 +174,8 @@ export const VisionCameraFeed: React.FC<VisionCameraFeedProps> = ({
 			outputs={[photoOutput]}
 			isActive={true}
 			resizeMode={resizeMode}
-			torchMode={torchMode}
+			// Left unset until the app first touches the torch, so the device's own default stands.
+			{...(torchMode === undefined ? {} : { torchMode })}
 		/>
 	);
 };

package/src/testing/conformance.ts

@@ -0,0 +1,140 @@
+/**
+ * What any `PermissionPort` and `CameraEngine` must do (IOS-12, CAM-13).
+ *
+ * The same checks run against the in-memory test adapter and against the real
+ * VisionCamera adapters (native module mocked in Jest, or for real on a device),
+ * so the fake the app's tests rely on cannot drift from the adapter it stands in
+ * for. Each check builds its own port from a harness, under the conditions it
+ * needs.
+ */
+import {
+	ensure,
+	runChecks,
+	type Check,
+	type ConformanceReport,
+} from '@chipmobilesdk/rn-core/testing';
+
+import type { CameraPermissionState } from '../config/types';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+
+export type SystemPermission = 'undetermined' | 'granted' | 'deniedPermanently';
+
+export interface PermissionHarness {
+	/** A port over a system whose permission starts in `initial`. */
+	create(initial: SystemPermission): {
+		readonly port: PermissionPort;
+		/** Changes the system permission, as Settings would. */
+		setSystemState(state: SystemPermission): void;
+		/** How many times the system prompt was shown. */
+		prompts(): number;
+	};
+}
+
+export interface CameraDeviceSpec {
+	readonly position: 'front' | 'back';
+	readonly hasFlash?: boolean;
+	readonly hasTorch?: boolean;
+}
+
+export interface EngineHarness {
+	/** An engine on a device with these cameras. */
+	create(devices: readonly CameraDeviceSpec[]): CameraEngine;
+}
+
+export const permissionPortChecks: readonly Check<PermissionHarness>[] = [
+	{
+		name: 'reads the status without prompting',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			ensure((await system.port.getStatus()) === 'undetermined', 'expected undetermined');
+			ensure(system.prompts() === 0, 'getStatus prompted');
+		},
+	},
+	{
+		name: 'reports a grant after prompting once',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			const state = await system.port.request();
+			ensure(state === 'granted', `expected granted, got ${state}`);
+			ensure(system.prompts() === 1, `expected one prompt, got ${system.prompts()}`);
+		},
+	},
+	{
+		name: 'never prompts again after a permanent denial',
+		async run(harness) {
+			const system = harness.create('deniedPermanently');
+			const state = await system.port.request();
+			ensure(state === 'deniedPermanently', `expected deniedPermanently, got ${state}`);
+			ensure(system.prompts() === 0, 'prompted after a permanent denial');
+		},
+	},
+	{
+		name: 'tells subscribers about a change, and nothing after unsubscribing',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			const seen: CameraPermissionState[] = [];
+			const unsubscribe = system.port.subscribe(state => seen.push(state));
+			await system.port.request();
+			ensure(seen.includes('granted'), `subscriber saw ${JSON.stringify(seen)}`);
+			unsubscribe();
+			unsubscribe();
+			const before = seen.length;
+			system.setSystemState('deniedPermanently');
+			await system.port.getStatus();
+			ensure(seen.length === before, 'notified after unsubscribing');
+		},
+	},
+];
+
+export const cameraEngineChecks: readonly Check<EngineHarness>[] = [
+	{
+		name: 'refuses to start without a camera, as cameraUnavailable',
+		async run(harness) {
+			const engine = harness.create([]);
+			let code: unknown;
+			try {
+				await engine.start({});
+			} catch (error) {
+				code = (error as { code?: unknown }).code;
+			}
+			ensure(code === 'cameraUnavailable', `expected cameraUnavailable, got ${String(code)}`);
+		},
+	},
+	{
+		name: 'starts when a camera exists',
+		async run(harness) {
+			await harness.create([{ position: 'back' }]).start({});
+		},
+	},
+	{
+		name: 'reports capabilities from the cameras present',
+		async run(harness) {
+			const capabilities = await harness
+				.create([{ position: 'back', hasTorch: true, hasFlash: true }, { position: 'front' }])
+				.getCapabilities();
+			ensure(capabilities.hasCameraHardware, 'no camera hardware reported');
+			ensure(capabilities.hasTorch && capabilities.hasFlash, 'torch or flash not reported');
+			const positions = [...capabilities.availablePositions].sort();
+			ensure(positions.join(',') === 'back,front', `positions ${positions.join(',')}`);
+		},
+	},
+	{
+		name: 'stops safely, even without a start and twice',
+		async run(harness) {
+			const engine = harness.create([{ position: 'back' }]);
+			await engine.stop();
+			await engine.stop();
+		},
+	},
+];
+
+export function runPermissionPortConformance(
+	harness: PermissionHarness,
+): Promise<ConformanceReport> {
+	return runChecks(() => harness, permissionPortChecks);
+}
+
+export function runCameraEngineConformance(harness: EngineHarness): Promise<ConformanceReport> {
+	return runChecks(() => harness, cameraEngineChecks);
+}

package/src/testing/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `@chipmobilesdk/rn-camera/testing`: test doubles and the port conformance suites.
+ *
+ * A separate entrypoint so the suites cannot reach a production bundle. The test
+ * adapter is also exported from the main entrypoint for compatibility; it leaves
+ * there only in a major release.
+ */
+
+export {
+	createTestCamera,
+	createMemoryFileSystem,
+	DEFAULT_TEST_CAPABILITIES,
+} from './testCameraAdapter';
+export type { MemoryFileSystem, TestCameraConfig, TestCameraHandles } from './testCameraAdapter';
+
+export {
+	cameraEngineChecks,
+	permissionPortChecks,
+	runCameraEngineConformance,
+	runPermissionPortConformance,
+} from './conformance';
+export type {
+	CameraDeviceSpec,
+	EngineHarness,
+	PermissionHarness,
+	SystemPermission,
+} from './conformance';

package/src/testing/testCameraAdapter.ts

@@ -7,6 +7,8 @@
  * filesystem, or a permission API.
  */
 
+import { createListenerSet } from '@chipmobilesdk/rn-core';
+
 import {
 	known,
 	unavailable,
@@ -100,6 +102,8 @@ export interface TestCameraHandles {
 	emitInterruption(): void;
 	setCaptureError(code: CameraErrorCode | null): void;
 	setStartError(code: CameraErrorCode | null): void;
+	/** How many times `request` showed the system prompt. */
+	prompts(): number;
 	/** Every capture the engine produced, in order. */
 	captures(): readonly CapturedImage[];
 	torchState(): boolean;
@@ -122,11 +126,13 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 	let starts = 0;
 	let stops = 0;
 	let sequence = 0;
+	let promptCount = 0;
 
 	const produced: CapturedImage[] = [];
-	const permissionListeners = new Set<(state: CameraPermissionState) => void>();
-	const appStateListeners = new Set<(status: AppStatus) => void>();
-	const interruptionListeners = new Set<() => void>();
+	// The same listener sets as the real adapters, so a throwing subscriber behaves
+	// identically here and on a device.
+	const permissionListeners = createListenerSet<[CameraPermissionState]>();
+	const appStateListeners = createListenerSet<[AppStatus]>();
 
 	const permissions: PermissionPort = {
 		async getStatus() {
@@ -137,19 +143,14 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 			if (permission === 'deniedPermanently') {
 				return permission;
 			}
-			permission =
-				permission === 'undetermined' || permission === 'denied' ? 'granted' : permission;
-			for (const listener of permissionListeners) {
-				listener(permission);
+			if (permission === 'undetermined' || permission === 'denied') {
+				promptCount += 1;
+				permission = 'granted';
 			}
+			permissionListeners.notify(permission);
 			return permission;
 		},
-		subscribe(listener) {
-			permissionListeners.add(listener);
-			return () => {
-				permissionListeners.delete(listener);
-			};
-		},
+		subscribe: listener => permissionListeners.add(listener),
 	};
 
 	const engine: CameraEngine = {
@@ -211,30 +212,18 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 		store,
 		fs,
 
-		subscribeToAppState(listener) {
-			appStateListeners.add(listener);
-			return () => {
-				appStateListeners.delete(listener);
-			};
-		},
+		subscribeToAppState: listener => appStateListeners.add(listener),
 
 		setAppState(status) {
-			for (const listener of appStateListeners) {
-				listener(status);
-			}
+			appStateListeners.notify(status);
 		},
 
 		setPermission(state) {
 			permission = state;
-			for (const listener of permissionListeners) {
-				listener(state);
-			}
+			permissionListeners.notify(state);
 		},
 
 		emitInterruption() {
-			for (const listener of interruptionListeners) {
-				listener();
-			}
 			// An interruption behaves like the OS taking the camera away: the next
 			// start attempt fails until the app clears it.
 			startError = 'interrupted';
@@ -248,6 +237,7 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 			startError = code;
 		},
 
+		prompts: () => promptCount,
 		captures: () => produced,
 		torchState: () => torch,
 		startCount: () => starts,