@chipmobilesdk/rn-camera 0.1.1 → 0.2.1

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

@@ -3,7 +3,6 @@ name: sdk-rn-camera
 description: "Camera capture via @chipmobilesdk/rn-camera: controller, VisionCamera engine, permissions, artifact storage, hardware-free testing. Use when adding capture/preview, handling camera permissions, storing captures, or writing camera tests."
 metadata:
   package: "@chipmobilesdk/rn-camera"
-  packageVersion: "0.1.0"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -25,13 +24,17 @@ artifact storage for captures, and a test double that needs no hardware.
 
 The camera is a hardware resource. It MUST be released when the screen loses focus or
 unmounts — a retained camera drains battery and blocks other screens from acquiring it.
-Verify teardown explicitly; this is the most common defect in camera code.
+Verify teardown explicitly; this is the most common defect in camera code. Prefer
+`useCameraController`: it disposes on unmount and survives StrictMode remounts. A
+disposed controller rejects `start`/`capture` with `notReady`.
 
 ## Captures expire
 
 `DEFAULT_TEMPORARY_TTL_MS` exists because cache-stored captures are temporary. If a
-capture must survive, move it out of the cache store deliberately — do not assume
-persistence. See `## Data behaviour` for what this means for App Privacy disclosures.
+capture must survive, pass a `destination` (app-owned) or move it out deliberately —
+do not assume persistence. Give the controller a `store` whose `FileSystemBridge`
+implements `move()`, or VisionCamera captures stay outside it and `cleanup()` cannot
+delete them. See `## Data behaviour` for what this means for App Privacy disclosures.
 
 ## Test without hardware
 
@@ -39,7 +42,7 @@ persistence. See `## Data behaviour` for what this means for App Privacy disclos
 flows be unit-tested with no device. Use these rather than mocking VisionCamera by hand —
 see `## Testing without hardware`.
 
-## Public API (v0.1.0)
+## Public API
 
 Runtime:
 

package/src/config/types.ts

@@ -1,149 +1,143 @@
-/**
- * Public type contract for @chipmobilesdk/rn-camera.
- *
- * Every type here is re-exported from `src/index.ts` (LIB-002/LIB-003). See
- * `specs/006-rn-camera-package/contracts/public-api.md` for the authoritative
- * contract and `data-model.md` for the rules behind each field.
- */
-
-/** Camera authorization status. Seven distinguishable outcomes (FR-004). */
-export type CameraPermissionState =
-	| 'undetermined'
-	| 'requesting'
-	| 'granted'
-	| 'denied'
-	| 'deniedPermanently'
-	| 'unavailable'
-	| 'unsupported';
-
-export type CameraPosition = 'front' | 'back';
-export type FlashMode = 'auto' | 'on' | 'off';
-export type ResizeMode = 'cover' | 'contain';
-export type ArtifactOwnership = 'packageTemporary' | 'appOwned';
-
-export type SessionStatus =
-	| 'idle'
-	| 'starting'
-	| 'active'
-	| 'paused'
-	| 'stopping'
-	| 'stopped'
-	| 'error';
-
-/**
- * A metadata field the platform could not determine (FR-022). Distinct from an
- * absent property so consumers can tell "not reported" from "not asked for".
- */
-export interface Unavailable {
-	readonly available: false;
-}
-
-export interface Known<T> {
-	readonly available: true;
-	readonly value: T;
-}
-
-export type Maybe<T> = Known<T> | Unavailable;
-
-export function known<T>(value: T): Known<T> {
-	return { available: true, value };
-}
-
-export function unavailable(): Unavailable {
-	return { available: false };
-}
-
-/** What this device and platform actually support (FR-033). */
-export interface CapabilityProfile {
-	readonly availablePositions: readonly CameraPosition[];
-	readonly hasFlash: boolean;
-	readonly hasTorch: boolean;
-	readonly supportsOrientationChange: boolean;
-	readonly hasCameraHardware: boolean;
-}
-
-/** Instruction to take one still photo. Carries no business context (FR-002). */
-export interface CaptureRequest {
-	/** 0..1, clamped to what the device supports. */
-	readonly quality?: number;
-	/** Longest edge in pixels, applied within device limits. */
-	readonly maxDimension?: number;
-	readonly cameraPosition?: CameraPosition;
-	readonly flashMode?: FlashMode;
-	/**
-	 * Supplying a destination makes the result `appOwned` and the package writes
-	 * directly there. Omitting it makes the result `packageTemporary` (FR-026a).
-	 * This is the only way ownership is decided.
-	 */
-	readonly destination?: string;
-}
-
-/** Result of one successful capture. Always a file reference (FR-021/FR-021a). */
-export interface CapturedImage {
-	/** File URI or handle. Never a base64 string, never an in-memory buffer. */
-	readonly uri: string;
-	readonly mimeType: string;
-	readonly width: number;
-	readonly height: number;
-	readonly timestamp: number;
-	readonly cameraPosition: CameraPosition;
-	readonly ownership: ArtifactOwnership;
-	readonly effectiveQuality: number;
-	readonly effectiveMaxDimension: Maybe<number>;
-	readonly fileSize: Maybe<number>;
-	readonly orientation: Maybe<number>;
-}
-
-/** Options accepted when starting a session. */
-export interface StartOptions {
-	readonly cameraPosition?: CameraPosition;
-}
-
-/**
- * Relationship between captured-image space and on-screen preview space.
- * Consumed by the pure mapping functions in `geometry/coordinateMapping`.
- */
-export interface PreviewGeometry {
-	readonly imageWidth: number;
-	readonly imageHeight: number;
-	readonly previewWidth: number;
-	readonly previewHeight: number;
-	readonly resizeMode: ResizeMode;
-	/** Clockwise degrees: 0, 90, 180, or 270. */
-	readonly orientation: number;
-	readonly isMirrored: boolean;
-}
-
-export interface Point {
-	readonly x: number;
-	readonly y: number;
-}
-
-export interface Rect {
-	readonly x: number;
-	readonly y: number;
-	readonly width: number;
-	readonly height: number;
-}
-
-/** Aggregate observable state exposed by the controller. */
-export interface CameraState {
-	readonly session: SessionStatus;
-	readonly permission: CameraPermissionState;
-	readonly capabilities: CapabilityProfile | null;
-	readonly cameraPosition: CameraPosition;
-	readonly flashMode: FlashMode;
-	readonly torchEnabled: boolean;
-	readonly capturing: boolean;
-	readonly error: CameraErrorLike | null;
-}
-
-/**
- * Structural view of a CameraError, kept here so `CameraState` does not create
- * a circular import with the diagnostics module.
- */
-export interface CameraErrorLike {
-	readonly code: string;
-	readonly recoverable: boolean;
-	readonly message: string;
-}
+/**
+ * Public type contract for @chipmobilesdk/rn-camera.
+ *
+ * Every type here is re-exported from `src/index.ts` (LIB-002/LIB-003). See
+ * `specs/006-rn-camera-package/contracts/public-api.md` for the authoritative
+ * contract and `data-model.md` for the rules behind each field.
+ */
+
+/** Camera authorization status. Seven distinguishable outcomes (FR-004). */
+export type CameraPermissionState =
+	| 'undetermined'
+	| 'requesting'
+	| 'granted'
+	| 'denied'
+	| 'deniedPermanently'
+	| 'unavailable'
+	| 'unsupported';
+
+export type CameraPosition = 'front' | 'back';
+export type FlashMode = 'auto' | 'on' | 'off';
+export type ResizeMode = 'cover' | 'contain';
+export type ArtifactOwnership = 'packageTemporary' | 'appOwned';
+
+export type SessionStatus =
+	'idle' | 'starting' | 'active' | 'paused' | 'stopping' | 'stopped' | 'error';
+
+/**
+ * A metadata field the platform could not determine (FR-022). Distinct from an
+ * absent property so consumers can tell "not reported" from "not asked for".
+ */
+export interface Unavailable {
+	readonly available: false;
+}
+
+export interface Known<T> {
+	readonly available: true;
+	readonly value: T;
+}
+
+export type Maybe<T> = Known<T> | Unavailable;
+
+export function known<T>(value: T): Known<T> {
+	return { available: true, value };
+}
+
+export function unavailable(): Unavailable {
+	return { available: false };
+}
+
+/** What this device and platform actually support (FR-033). */
+export interface CapabilityProfile {
+	readonly availablePositions: readonly CameraPosition[];
+	readonly hasFlash: boolean;
+	readonly hasTorch: boolean;
+	readonly supportsOrientationChange: boolean;
+	readonly hasCameraHardware: boolean;
+}
+
+/** Instruction to take one still photo. Carries no business context (FR-002). */
+export interface CaptureRequest {
+	/** 0..1, clamped to what the device supports. */
+	readonly quality?: number;
+	/** Longest edge in pixels, applied within device limits. */
+	readonly maxDimension?: number;
+	readonly cameraPosition?: CameraPosition;
+	readonly flashMode?: FlashMode;
+	/**
+	 * Supplying a destination makes the result `appOwned` and the package writes
+	 * directly there. Omitting it makes the result `packageTemporary` (FR-026a).
+	 * This is the only way ownership is decided.
+	 */
+	readonly destination?: string;
+}
+
+/** Result of one successful capture. Always a file reference (FR-021/FR-021a). */
+export interface CapturedImage {
+	/** File URI or handle. Never a base64 string, never an in-memory buffer. */
+	readonly uri: string;
+	readonly mimeType: string;
+	readonly width: number;
+	readonly height: number;
+	readonly timestamp: number;
+	readonly cameraPosition: CameraPosition;
+	readonly ownership: ArtifactOwnership;
+	readonly effectiveQuality: number;
+	readonly effectiveMaxDimension: Maybe<number>;
+	readonly fileSize: Maybe<number>;
+	readonly orientation: Maybe<number>;
+}
+
+/** Options accepted when starting a session. */
+export interface StartOptions {
+	readonly cameraPosition?: CameraPosition;
+}
+
+/**
+ * Relationship between captured-image space and on-screen preview space.
+ * Consumed by the pure mapping functions in `geometry/coordinateMapping`.
+ */
+export interface PreviewGeometry {
+	readonly imageWidth: number;
+	readonly imageHeight: number;
+	readonly previewWidth: number;
+	readonly previewHeight: number;
+	readonly resizeMode: ResizeMode;
+	/** Clockwise degrees: 0, 90, 180, or 270. */
+	readonly orientation: number;
+	readonly isMirrored: boolean;
+}
+
+export interface Point {
+	readonly x: number;
+	readonly y: number;
+}
+
+export interface Rect {
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
+}
+
+/** Aggregate observable state exposed by the controller. */
+export interface CameraState {
+	readonly session: SessionStatus;
+	readonly permission: CameraPermissionState;
+	readonly capabilities: CapabilityProfile | null;
+	readonly cameraPosition: CameraPosition;
+	readonly flashMode: FlashMode;
+	readonly torchEnabled: boolean;
+	readonly capturing: boolean;
+	readonly error: CameraErrorLike | null;
+}
+
+/**
+ * Structural view of a CameraError, kept here so `CameraState` does not create
+ * a circular import with the diagnostics module.
+ */
+export interface CameraErrorLike {
+	readonly code: string;
+	readonly recoverable: boolean;
+	readonly message: string;
+}

package/src/core/capabilities.ts

@@ -1,44 +1,41 @@
-/**
- * Capability gating (FR-033, FR-034).
- *
- * An unsupported capability must produce an `unsupportedCapability` result, not
- * an unexpected failure — that is what lets an app hide a control instead of
- * discovering at tap time that the device has no flash.
- */
-
-import type { CameraPosition, CapabilityProfile, FlashMode } from '../config/types';
-import { CameraError } from '../diagnostics/errors';
-
-export const EMPTY_CAPABILITIES: CapabilityProfile = {
-	availablePositions: [],
-	hasFlash: false,
-	hasTorch: false,
-	supportsOrientationChange: false,
-	hasCameraHardware: false,
-};
-
-export function supportsPosition(
-	profile: CapabilityProfile | null,
-	position: CameraPosition,
-): boolean {
-	return profile?.availablePositions.includes(position) ?? false;
-}
-
-/** `off` is always legal — it is the absence of flash, not a use of it. */
-export function supportsFlashMode(
-	profile: CapabilityProfile | null,
-	mode: FlashMode,
-): boolean {
-	return mode === 'off' ? true : profile?.hasFlash === true;
-}
-
-export function supportsTorch(profile: CapabilityProfile | null): boolean {
-	return profile?.hasTorch === true;
-}
-
-/** Throws the uniform unsupported error so every gate reads the same way. */
-export function assertSupported(supported: boolean, what: string): void {
-	if (!supported) {
-		throw new CameraError('unsupportedCapability', `Not supported on this device: ${what}`);
-	}
-}
+/**
+ * Capability gating (FR-033, FR-034).
+ *
+ * An unsupported capability must produce an `unsupportedCapability` result, not
+ * an unexpected failure — that is what lets an app hide a control instead of
+ * discovering at tap time that the device has no flash.
+ */
+
+import type { CameraPosition, CapabilityProfile, FlashMode } from '../config/types';
+import { CameraError } from '../diagnostics/errors';
+
+export const EMPTY_CAPABILITIES: CapabilityProfile = {
+	availablePositions: [],
+	hasFlash: false,
+	hasTorch: false,
+	supportsOrientationChange: false,
+	hasCameraHardware: false,
+};
+
+export function supportsPosition(
+	profile: CapabilityProfile | null,
+	position: CameraPosition,
+): boolean {
+	return profile?.availablePositions.includes(position) ?? false;
+}
+
+/** `off` is always legal — it is the absence of flash, not a use of it. */
+export function supportsFlashMode(profile: CapabilityProfile | null, mode: FlashMode): boolean {
+	return mode === 'off' ? true : profile?.hasFlash === true;
+}
+
+export function supportsTorch(profile: CapabilityProfile | null): boolean {
+	return profile?.hasTorch === true;
+}
+
+/** Throws the uniform unsupported error so every gate reads the same way. */
+export function assertSupported(supported: boolean, what: string): void {
+	if (!supported) {
+		throw new CameraError('unsupportedCapability', `Not supported on this device: ${what}`);
+	}
+}

package/src/core/captureController.ts

@@ -1,118 +1,120 @@
-/**
- * Capture guards, single-flight enforcement, and metadata assembly
- * (FR-020..FR-026b).
- *
- * The single-flight guard rejects rather than queues or coalesces. A queue
- * turns a double-tapped shutter into two photos the user never asked for, and
- * coalescing hides a deliberate second capture behind an accidental one — so a
- * fast, explicit `captureInProgress` error is the only option that lets the app
- * decide (clarification session 2026-07-26).
- */
-
-import {
-	known,
-	unavailable,
-	type CameraPosition,
-	type CapabilityProfile,
-	type CapturedImage,
-	type CaptureRequest,
-	type FlashMode,
-	type Maybe,
-	type SessionStatus,
-} from '../config/types';
-import { CameraError } from '../diagnostics/errors';
-import type { CameraEngine } from '../native/cameraEngine';
-import { assertSupported, supportsFlashMode, supportsPosition } from './capabilities';
-import { canCapture } from './sessionMachine';
-
-export const DEFAULT_QUALITY = 0.9;
-
-export function clampQuality(quality: number | undefined): number {
-	if (quality === undefined || Number.isNaN(quality)) {
-		return DEFAULT_QUALITY;
-	}
-	return Math.min(1, Math.max(0, quality));
-}
-
-export function clampMaxDimension(maxDimension: number | undefined): Maybe<number> {
-	if (maxDimension === undefined || !Number.isFinite(maxDimension) || maxDimension <= 0) {
-		return unavailable();
-	}
-	return known(Math.floor(maxDimension));
-}
-
-export interface CaptureContext {
-	readonly engine: CameraEngine;
-	readonly sessionStatus: SessionStatus;
-	readonly permissionGranted: boolean;
-	readonly capabilities: CapabilityProfile | null;
-	readonly cameraPosition: CameraPosition;
-	readonly flashMode: FlashMode;
-}
-
-/**
- * Validates a capture request against permission, readiness, and capability.
- * Throws before any artifact could be created, so a rejected capture never
- * leaves a file behind (FR-020).
- */
-export function assertCaptureAllowed(context: CaptureContext, request: CaptureRequest): void {
-	if (!context.permissionGranted) {
-		throw new CameraError('permissionDenied', 'Camera permission is not granted');
-	}
-	if (!canCapture(context.sessionStatus)) {
-		throw new CameraError('notReady', `Camera is not ready (session: ${context.sessionStatus})`);
-	}
-	const flashMode = request.flashMode ?? context.flashMode;
-	assertSupported(supportsFlashMode(context.capabilities, flashMode), `flash mode "${flashMode}"`);
-
-	const position = request.cameraPosition ?? context.cameraPosition;
-	assertSupported(supportsPosition(context.capabilities, position), `${position} camera`);
-}
-
-/**
- * Normalizes whatever the engine returned into the published contract, filling
- * in effective hint values and marking undeterminable fields explicitly
- * unavailable rather than guessing them (FR-022, FR-023).
- */
-export function finalizeResult(
-	raw: CapturedImage,
-	request: CaptureRequest,
-	context: CaptureContext,
-): CapturedImage {
-	const ownership = request.destination ? 'appOwned' : 'packageTemporary';
-	return {
-		...raw,
-		ownership,
-		cameraPosition: raw.cameraPosition ?? request.cameraPosition ?? context.cameraPosition,
-		timestamp: raw.timestamp ?? Date.now(),
-		effectiveQuality: raw.effectiveQuality ?? clampQuality(request.quality),
-		effectiveMaxDimension: raw.effectiveMaxDimension ?? clampMaxDimension(request.maxDimension),
-		fileSize: raw.fileSize ?? unavailable(),
-		orientation: raw.orientation ?? unavailable(),
-	};
-}
-
-/**
- * Serializes captures. Holding the in-flight promise rather than a boolean
- * means the guard cannot be defeated by two synchronous calls in the same tick.
- */
-export class SingleFlight {
-	private inFlight: Promise<CapturedImage> | null = null;
-
-	get busy(): boolean {
-		return this.inFlight !== null;
-	}
-
-	async run(operation: () => Promise<CapturedImage>): Promise<CapturedImage> {
-		if (this.inFlight) {
-			throw new CameraError('captureInProgress', 'A capture is already in progress');
-		}
-		const promise = operation();
-		this.inFlight = promise;
-		try {
-			return await promise;
-		} finally {
-			this.inFlight = null;
-		}
-	}
-}
+/**
+ * Capture guards, single-flight enforcement, and metadata assembly
+ * (FR-020..FR-026b).
+ *
+ * The single-flight guard rejects rather than queues or coalesces. A queue
+ * turns a double-tapped shutter into two photos the user never asked for, and
+ * coalescing hides a deliberate second capture behind an accidental one — so a
+ * fast, explicit `captureInProgress` error is the only option that lets the app
+ * decide (clarification session 2026-07-26).
+ */
+
+import {
+	known,
+	unavailable,
+	type CameraPosition,
+	type CapabilityProfile,
+	type CapturedImage,
+	type CaptureRequest,
+	type FlashMode,
+	type Maybe,
+	type SessionStatus,
+} from '../config/types';
+import { CameraError } from '../diagnostics/errors';
+import type { CameraEngine } from '../native/cameraEngine';
+import { assertSupported, supportsFlashMode, supportsPosition } from './capabilities';
+import { canCapture } from './sessionMachine';
+
+export const DEFAULT_QUALITY = 0.9;
+
+export function clampQuality(quality: number | undefined): number {
+	if (quality === undefined || Number.isNaN(quality)) {
+		return DEFAULT_QUALITY;
+	}
+	return Math.min(1, Math.max(0, quality));
+}
+
+export function clampMaxDimension(maxDimension: number | undefined): Maybe<number> {
+	if (maxDimension === undefined || !Number.isFinite(maxDimension) || maxDimension <= 0) {
+		return unavailable();
+	}
+	return known(Math.floor(maxDimension));
+}
+
+export interface CaptureContext {
+	readonly engine: CameraEngine;
+	readonly sessionStatus: SessionStatus;
+	readonly permissionGranted: boolean;
+	readonly capabilities: CapabilityProfile | null;
+	readonly cameraPosition: CameraPosition;
+	readonly flashMode: FlashMode;
+}
+
+/**
+ * Validates a capture request against permission, readiness, and capability.
+ * Throws before any artifact could be created, so a rejected capture never
+ * leaves a file behind (FR-020).
+ */
+export function assertCaptureAllowed(context: CaptureContext, request: CaptureRequest): void {
+	if (!context.permissionGranted) {
+		throw new CameraError('permissionDenied', 'Camera permission is not granted');
+	}
+	if (!canCapture(context.sessionStatus)) {
+		throw new CameraError('notReady', `Camera is not ready (session: ${context.sessionStatus})`);
+	}
+	const flashMode = request.flashMode ?? context.flashMode;
+	assertSupported(supportsFlashMode(context.capabilities, flashMode), `flash mode "${flashMode}"`);
+
+	const position = request.cameraPosition ?? context.cameraPosition;
+	assertSupported(supportsPosition(context.capabilities, position), `${position} camera`);
+}
+
+/**
+ * Normalizes whatever the engine returned into the published contract, filling
+ * in effective hint values and marking undeterminable fields explicitly
+ * unavailable rather than guessing them (FR-022, FR-023).
+ */
+export function finalizeResult(
+	raw: CapturedImage,
+	request: CaptureRequest,
+	context: CaptureContext,
+): CapturedImage {
+	const ownership = request.destination ? 'appOwned' : 'packageTemporary';
+	return {
+		...raw,
+		ownership,
+		cameraPosition: raw.cameraPosition ?? request.cameraPosition ?? context.cameraPosition,
+		timestamp: raw.timestamp ?? Date.now(),
+		effectiveQuality: raw.effectiveQuality ?? clampQuality(request.quality),
+		effectiveMaxDimension: raw.effectiveMaxDimension ?? clampMaxDimension(request.maxDimension),
+		fileSize: raw.fileSize ?? unavailable(),
+		orientation: raw.orientation ?? unavailable(),
+	};
+}
+
+/**
+ * Serializes captures. The slot is taken synchronously, before the operation
+ * runs, so two calls in the same tick cannot both pass the check — and the
+ * operation's own first `emit()` already sees `busy`. Holding the operation's
+ * promise instead set the slot only after that first emit, so `capturing: true`
+ * was never published at all.
+ */
+export class SingleFlight {
+	private active = false;
+
+	get busy(): boolean {
+		return this.active;
+	}
+
+	async run(operation: () => Promise<CapturedImage>): Promise<CapturedImage> {
+		if (this.active) {
+			throw new CameraError('captureInProgress', 'A capture is already in progress');
+		}
+		this.active = true;
+		try {
+			return await operation();
+		} finally {
+			this.active = false;
+		}
+	}
+}