@chipmobilesdk/rn-camera 0.2.0 → 0.3.0

package/src/geometry/coordinateMapping.ts

@@ -1,129 +1,129 @@
-/**
- * Bidirectional coordinate mapping between preview space and captured-image
- * space (FR-036, SC-012).
- *
- * Pure functions with no native involvement (research R5). Everything needed is
- * already known in JavaScript, so keeping this pure is what makes the 2-pixel
- * round-trip tolerance verifiable in CI rather than only on a device.
- *
- * Composition order, preview -> image: undo mirror, undo letterbox/crop offset,
- * undo scale, undo orientation. Image -> preview reverses it exactly.
- */
-
-import type { Point, PreviewGeometry, Rect } from '../config/types';
-
-/** Orientation rotates the image for display, swapping dimensions at 90/270. */
-function isQuarterTurn(orientation: number): boolean {
-	const normalized = ((orientation % 360) + 360) % 360;
-	return normalized === 90 || normalized === 270;
-}
-
-function normalizeOrientation(orientation: number): 0 | 90 | 180 | 270 {
-	const normalized = ((Math.round(orientation / 90) * 90) % 360 + 360) % 360;
-	return normalized as 0 | 90 | 180 | 270;
-}
-
-interface Projection {
-	readonly scale: number;
-	readonly offsetX: number;
-	readonly offsetY: number;
-	/** Image dimensions as displayed, after orientation. */
-	readonly displayWidth: number;
-	readonly displayHeight: number;
-}
-
-function projection(geometry: PreviewGeometry): Projection {
-	const swap = isQuarterTurn(geometry.orientation);
-	const displayWidth = swap ? geometry.imageHeight : geometry.imageWidth;
-	const displayHeight = swap ? geometry.imageWidth : geometry.imageHeight;
-
-	const scaleX = geometry.previewWidth / displayWidth;
-	const scaleY = geometry.previewHeight / displayHeight;
-	// `cover` fills and crops the overflow; `contain` fits and letterboxes.
-	const scale =
-		geometry.resizeMode === 'cover' ? Math.max(scaleX, scaleY) : Math.min(scaleX, scaleY);
-
-	return {
-		scale,
-		// Negative under `cover` (cropped away), positive under `contain`
-		// (letterbox bands). The same arithmetic covers both.
-		offsetX: (geometry.previewWidth - displayWidth * scale) / 2,
-		offsetY: (geometry.previewHeight - displayHeight * scale) / 2,
-		displayWidth,
-		displayHeight,
-	};
-}
-
-/** Display-space point -> original image point, undoing the rotation. */
-function unrotate(point: Point, geometry: PreviewGeometry): Point {
-	switch (normalizeOrientation(geometry.orientation)) {
-		case 90:
-			return { x: point.y, y: geometry.imageHeight - point.x };
-		case 180:
-			return { x: geometry.imageWidth - point.x, y: geometry.imageHeight - point.y };
-		case 270:
-			return { x: geometry.imageWidth - point.y, y: point.x };
-		default:
-			return point;
-	}
-}
-
-/** Original image point -> display-space point, applying the rotation. */
-function rotate(point: Point, geometry: PreviewGeometry): Point {
-	switch (normalizeOrientation(geometry.orientation)) {
-		case 90:
-			return { x: geometry.imageHeight - point.y, y: point.x };
-		case 180:
-			return { x: geometry.imageWidth - point.x, y: geometry.imageHeight - point.y };
-		case 270:
-			return { x: point.y, y: geometry.imageWidth - point.x };
-		default:
-			return point;
-	}
-}
-
-/**
- * Maps a preview-space point into captured-image space. Points outside the
- * visible region stay representable (they fall outside the image bounds) rather
- * than being clamped to an edge, so callers can detect an out-of-frame overlay.
- */
-export function mapPointToImage(point: Point, geometry: PreviewGeometry): Point {
-	const { scale, offsetX, offsetY } = projection(geometry);
-	const x = geometry.isMirrored ? geometry.previewWidth - point.x : point.x;
-	return unrotate({ x: (x - offsetX) / scale, y: (point.y - offsetY) / scale }, geometry);
-}
-
-/** Maps a captured-image point into preview space. Exact inverse of the above. */
-export function mapPointToPreview(point: Point, geometry: PreviewGeometry): Point {
-	const { scale, offsetX, offsetY } = projection(geometry);
-	const rotated = rotate(point, geometry);
-	const x = rotated.x * scale + offsetX;
-	return {
-		x: geometry.isMirrored ? geometry.previewWidth - x : x,
-		y: rotated.y * scale + offsetY,
-	};
-}
-
-/** Axis-aligned bounding box of the mapped corners — exact for quarter turns. */
-function boundsOf(a: Point, b: Point): Rect {
-	return {
-		x: Math.min(a.x, b.x),
-		y: Math.min(a.y, b.y),
-		width: Math.abs(b.x - a.x),
-		height: Math.abs(b.y - a.y),
-	};
-}
-
-export function mapRectToImage(rect: Rect, geometry: PreviewGeometry): Rect {
-	return boundsOf(
-		mapPointToImage({ x: rect.x, y: rect.y }, geometry),
-		mapPointToImage({ x: rect.x + rect.width, y: rect.y + rect.height }, geometry),
-	);
-}
-
-export function mapRectToPreview(rect: Rect, geometry: PreviewGeometry): Rect {
-	return boundsOf(
-		mapPointToPreview({ x: rect.x, y: rect.y }, geometry),
-		mapPointToPreview({ x: rect.x + rect.width, y: rect.y + rect.height }, geometry),
-	);
-}
+/**
+ * Bidirectional coordinate mapping between preview space and captured-image
+ * space (FR-036, SC-012).
+ *
+ * Pure functions with no native involvement (research R5). Everything needed is
+ * already known in JavaScript, so keeping this pure is what makes the 2-pixel
+ * round-trip tolerance verifiable in CI rather than only on a device.
+ *
+ * Composition order, preview -> image: undo mirror, undo letterbox/crop offset,
+ * undo scale, undo orientation. Image -> preview reverses it exactly.
+ */
+
+import type { Point, PreviewGeometry, Rect } from '../config/types';
+
+/** Orientation rotates the image for display, swapping dimensions at 90/270. */
+function isQuarterTurn(orientation: number): boolean {
+	const normalized = ((orientation % 360) + 360) % 360;
+	return normalized === 90 || normalized === 270;
+}
+
+function normalizeOrientation(orientation: number): 0 | 90 | 180 | 270 {
+	const normalized = (((Math.round(orientation / 90) * 90) % 360) + 360) % 360;
+	return normalized as 0 | 90 | 180 | 270;
+}
+
+interface Projection {
+	readonly scale: number;
+	readonly offsetX: number;
+	readonly offsetY: number;
+	/** Image dimensions as displayed, after orientation. */
+	readonly displayWidth: number;
+	readonly displayHeight: number;
+}
+
+function projection(geometry: PreviewGeometry): Projection {
+	const swap = isQuarterTurn(geometry.orientation);
+	const displayWidth = swap ? geometry.imageHeight : geometry.imageWidth;
+	const displayHeight = swap ? geometry.imageWidth : geometry.imageHeight;
+
+	const scaleX = geometry.previewWidth / displayWidth;
+	const scaleY = geometry.previewHeight / displayHeight;
+	// `cover` fills and crops the overflow; `contain` fits and letterboxes.
+	const scale =
+		geometry.resizeMode === 'cover' ? Math.max(scaleX, scaleY) : Math.min(scaleX, scaleY);
+
+	return {
+		scale,
+		// Negative under `cover` (cropped away), positive under `contain`
+		// (letterbox bands). The same arithmetic covers both.
+		offsetX: (geometry.previewWidth - displayWidth * scale) / 2,
+		offsetY: (geometry.previewHeight - displayHeight * scale) / 2,
+		displayWidth,
+		displayHeight,
+	};
+}
+
+/** Display-space point -> original image point, undoing the rotation. */
+function unrotate(point: Point, geometry: PreviewGeometry): Point {
+	switch (normalizeOrientation(geometry.orientation)) {
+		case 90:
+			return { x: point.y, y: geometry.imageHeight - point.x };
+		case 180:
+			return { x: geometry.imageWidth - point.x, y: geometry.imageHeight - point.y };
+		case 270:
+			return { x: geometry.imageWidth - point.y, y: point.x };
+		default:
+			return point;
+	}
+}
+
+/** Original image point -> display-space point, applying the rotation. */
+function rotate(point: Point, geometry: PreviewGeometry): Point {
+	switch (normalizeOrientation(geometry.orientation)) {
+		case 90:
+			return { x: geometry.imageHeight - point.y, y: point.x };
+		case 180:
+			return { x: geometry.imageWidth - point.x, y: geometry.imageHeight - point.y };
+		case 270:
+			return { x: point.y, y: geometry.imageWidth - point.x };
+		default:
+			return point;
+	}
+}
+
+/**
+ * Maps a preview-space point into captured-image space. Points outside the
+ * visible region stay representable (they fall outside the image bounds) rather
+ * than being clamped to an edge, so callers can detect an out-of-frame overlay.
+ */
+export function mapPointToImage(point: Point, geometry: PreviewGeometry): Point {
+	const { scale, offsetX, offsetY } = projection(geometry);
+	const x = geometry.isMirrored ? geometry.previewWidth - point.x : point.x;
+	return unrotate({ x: (x - offsetX) / scale, y: (point.y - offsetY) / scale }, geometry);
+}
+
+/** Maps a captured-image point into preview space. Exact inverse of the above. */
+export function mapPointToPreview(point: Point, geometry: PreviewGeometry): Point {
+	const { scale, offsetX, offsetY } = projection(geometry);
+	const rotated = rotate(point, geometry);
+	const x = rotated.x * scale + offsetX;
+	return {
+		x: geometry.isMirrored ? geometry.previewWidth - x : x,
+		y: rotated.y * scale + offsetY,
+	};
+}
+
+/** Axis-aligned bounding box of the mapped corners — exact for quarter turns. */
+function boundsOf(a: Point, b: Point): Rect {
+	return {
+		x: Math.min(a.x, b.x),
+		y: Math.min(a.y, b.y),
+		width: Math.abs(b.x - a.x),
+		height: Math.abs(b.y - a.y),
+	};
+}
+
+export function mapRectToImage(rect: Rect, geometry: PreviewGeometry): Rect {
+	return boundsOf(
+		mapPointToImage({ x: rect.x, y: rect.y }, geometry),
+		mapPointToImage({ x: rect.x + rect.width, y: rect.y + rect.height }, geometry),
+	);
+}
+
+export function mapRectToPreview(rect: Rect, geometry: PreviewGeometry): Rect {
+	return boundsOf(
+		mapPointToPreview({ x: rect.x, y: rect.y }, geometry),
+		mapPointToPreview({ x: rect.x + rect.width, y: rect.y + rect.height }, geometry),
+	);
+}

package/src/index.ts

@@ -1,78 +1,78 @@
-/**
- * @chipmobilesdk/rn-camera — reusable camera infrastructure for
- * ChipMobileSdk-family React Native apps.
- *
- * This is the single public entrypoint (LIB-003). Modules under `core/`,
- * `native/`, `permissions/`, `storage/`, `geometry/`, `diagnostics/`, and
- * `testing/` are private; import them only through this file.
- *
- * The package contains no business logic, sends nothing over the network, and
- * writes nothing to the device gallery. Phase one runs no on-device inference —
- * see the reserved frame-processing extension point in the README.
- */
-
-// Public types
-export type {
-	ArtifactOwnership,
-	CameraErrorLike,
-	CameraPermissionState,
-	CameraPosition,
-	CameraState,
-	CapabilityProfile,
-	CapturedImage,
-	CaptureRequest,
-	FlashMode,
-	Known,
-	Maybe,
-	Point,
-	PreviewGeometry,
-	Rect,
-	ResizeMode,
-	SessionStatus,
-	StartOptions,
-	Unavailable,
-} from './config/types';
-export { known, unavailable } from './config/types';
-
-// Controller
-export { createCameraController, DEFAULT_TEMPORARY_TTL_MS } from './core/controller';
-export type {
-	AppStatus,
-	CameraController,
-	CameraControllerOptions,
-} from './core/controller';
-
-// Ports + default adapters
-export type { CameraEngine, EngineOptions } from './native/cameraEngine';
-export { createVisionCameraEngine } from './native/cameraEngine';
-export type { PermissionPort } from './permissions/permissionPort';
-export { createVisionCameraPermissions } from './permissions/permissionPort';
-export type { ArtifactStore, FileSystemBridge, StoreOptions } from './storage/artifactStore';
-export { createArtifactStore, createCacheArtifactStore } from './storage/artifactStore';
-
-// React surface
-export { CameraPreview } from './react/CameraPreview';
-export type { CameraPreviewProps } from './react/CameraPreview';
-export { useCameraController, useCameraState } from './react/hooks';
-
-// Coordinate mapping (pure)
-export {
-	mapPointToImage,
-	mapPointToPreview,
-	mapRectToImage,
-	mapRectToPreview,
-} from './geometry/coordinateMapping';
-
-// Diagnostics
-export { CameraError, isCameraError, redact } from './diagnostics/errors';
-export type { CameraErrorCode } from './diagnostics/errors';
-export type { CameraLogEvent, CameraLogEventType, CameraLogger } from './diagnostics/logger';
-
-// Test adapter (FR-041) — exported from the single entrypoint so consumer tests
-// exercise the same published ports the real adapters implement.
-export { createTestCamera, createMemoryFileSystem, DEFAULT_TEST_CAPABILITIES } from './testing/testCameraAdapter';
-export type {
-	MemoryFileSystem,
-	TestCameraConfig,
-	TestCameraHandles,
-} from './testing/testCameraAdapter';
+/**
+ * @chipmobilesdk/rn-camera — reusable camera infrastructure for
+ * ChipMobileSdk-family React Native apps.
+ *
+ * This is the single public entrypoint (LIB-003). Modules under `core/`,
+ * `native/`, `permissions/`, `storage/`, `geometry/`, `diagnostics/`, and
+ * `testing/` are private; import them only through this file.
+ *
+ * The package contains no business logic, sends nothing over the network, and
+ * writes nothing to the device gallery. Phase one runs no on-device inference —
+ * see the reserved frame-processing extension point in the README.
+ */
+
+// Public types
+export type {
+	ArtifactOwnership,
+	CameraErrorLike,
+	CameraPermissionState,
+	CameraPosition,
+	CameraState,
+	CapabilityProfile,
+	CapturedImage,
+	CaptureRequest,
+	FlashMode,
+	Known,
+	Maybe,
+	Point,
+	PreviewGeometry,
+	Rect,
+	ResizeMode,
+	SessionStatus,
+	StartOptions,
+	Unavailable,
+} from './config/types';
+export { known, unavailable } from './config/types';
+
+// Controller
+export { createCameraController, DEFAULT_TEMPORARY_TTL_MS } from './core/controller';
+export type { AppStatus, CameraController, CameraControllerOptions } from './core/controller';
+
+// Ports + default adapters
+export type { CameraEngine, EngineOptions } from './native/cameraEngine';
+export { createVisionCameraEngine } from './native/cameraEngine';
+export type { PermissionPort } from './permissions/permissionPort';
+export { createVisionCameraPermissions } from './permissions/permissionPort';
+export type { ArtifactStore, FileSystemBridge, StoreOptions } from './storage/artifactStore';
+export { createArtifactStore, createCacheArtifactStore } from './storage/artifactStore';
+
+// React surface
+export { CameraPreview } from './react/CameraPreview';
+export type { CameraPreviewProps } from './react/CameraPreview';
+export { useCameraController, useCameraState } from './react/hooks';
+
+// Coordinate mapping (pure)
+export {
+	mapPointToImage,
+	mapPointToPreview,
+	mapRectToImage,
+	mapRectToPreview,
+} from './geometry/coordinateMapping';
+
+// Diagnostics
+export { CameraError, isCameraError, redact } from './diagnostics/errors';
+export type { CameraErrorCode } from './diagnostics/errors';
+export type { CameraLogEvent, CameraLogEventType, CameraLogger } from './diagnostics/logger';
+
+// Test adapter (FR-041) — exported from the single entrypoint so consumer tests
+// exercise the same published ports the real adapters implement.
+export {
+	createTestCamera,
+	createMemoryFileSystem,
+	DEFAULT_TEST_CAPABILITIES,
+} from './testing/testCameraAdapter';
+export type {
+	MemoryFileSystem,
+	TestCameraConfig,
+	TestCameraHandles,
+} from './testing/testCameraAdapter';

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;
 				}
 			};
 		},