@chipmobilesdk/rn-camera 0.2.0 → 0.2.1

package/package.json

@@ -1,47 +1,44 @@
-{
-	"name": "@chipmobilesdk/rn-camera",
-	"version": "0.2.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/config",
-		"src/core",
-		"src/diagnostics",
-		"src/geometry",
-		"src/native",
-		"src/permissions",
-		"src/react",
-		"src/storage",
-		"src/testing",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-vision-camera": ">=5.1.1"
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-camera",
+	"version": "0.2.1",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/core",
+		"src/diagnostics",
+		"src/geometry",
+		"src/native",
+		"src/permissions",
+		"src/react",
+		"src/storage",
+		"src/testing",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:check": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-vision-camera": ">=5.1.1"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

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

@@ -1,75 +1,74 @@
----
-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
----
-
-# @chipmobilesdk/rn-camera
-
-Camera capture built on VisionCamera, with an injectable engine, a permission port,
-artifact storage for captures, and a test double that needs no hardware.
-
-## Use this when
-
-- Adding a capture or preview screen
-- Requesting/handling camera permissions
-- Persisting captured images and managing their lifetime
-- Writing tests for a camera flow
-- Answering a privacy/data-safety question about captures
-
-## Release the camera on unmount
-
-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. 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, 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
-
-`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`.
-
-## Public API (v0.2.0)
-
-Runtime:
-
-- `createCameraController(...)`, `useCameraController`, `useCameraState`
-- `createVisionCameraEngine(...)` — the default `CameraEngine`; injectable
-- `createVisionCameraPermissions(...)` — implements `PermissionPort`
-- `createArtifactStore(...)`, `createCacheArtifactStore(...)`
-- `CameraPreview` (+ `CameraPreviewProps`)
-- `CameraError`, `isCameraError`, `redact` — `redact` strips sensitive paths before logging
-- Testing: `createTestCamera`, `createMemoryFileSystem`, `DEFAULT_TEST_CAPABILITIES`
-
-Types: `CameraEngine`, `EngineOptions`, `PermissionPort`, `ArtifactStore`,
-`FileSystemBridge`, `StoreOptions`, `CameraErrorCode`, `CameraLogEvent`,
-`CameraLogEventType`, `CameraLogger`
-
-Always pass camera log payloads through `redact` before logging.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-camera/README.md` (~340 lines):
-
-| Need | Section |
-|---|---|
-| First integration | `## Install (consuming app)`, `## Quick start` |
-| Engine / port / store model | `## Core concepts` |
-| Tests | `## Testing without hardware` |
-| Failure handling | `## Errors`, `## Diagnostics` |
-| Privacy disclosures | `## Data behaviour (for App Privacy and Data Safety)` |
-| Native config | `## Native capability`, `## Compatibility` |
+---
+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"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-camera
+
+Camera capture built on VisionCamera, with an injectable engine, a permission port,
+artifact storage for captures, and a test double that needs no hardware.
+
+## Use this when
+
+- Adding a capture or preview screen
+- Requesting/handling camera permissions
+- Persisting captured images and managing their lifetime
+- Writing tests for a camera flow
+- Answering a privacy/data-safety question about captures
+
+## Release the camera on unmount
+
+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. 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, 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
+
+`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`.
+
+## Public API
+
+Runtime:
+
+- `createCameraController(...)`, `useCameraController`, `useCameraState`
+- `createVisionCameraEngine(...)` — the default `CameraEngine`; injectable
+- `createVisionCameraPermissions(...)` — implements `PermissionPort`
+- `createArtifactStore(...)`, `createCacheArtifactStore(...)`
+- `CameraPreview` (+ `CameraPreviewProps`)
+- `CameraError`, `isCameraError`, `redact` — `redact` strips sensitive paths before logging
+- Testing: `createTestCamera`, `createMemoryFileSystem`, `DEFAULT_TEST_CAPABILITIES`
+
+Types: `CameraEngine`, `EngineOptions`, `PermissionPort`, `ArtifactStore`,
+`FileSystemBridge`, `StoreOptions`, `CameraErrorCode`, `CameraLogEvent`,
+`CameraLogEventType`, `CameraLogger`
+
+Always pass camera log payloads through `redact` before logging.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-camera/README.md` (~340 lines):
+
+| Need | Section |
+|---|---|
+| First integration | `## Install (consuming app)`, `## Quick start` |
+| Engine / port / store model | `## Core concepts` |
+| Tests | `## Testing without hardware` |
+| Failure handling | `## Errors`, `## Diagnostics` |
+| Privacy disclosures | `## Data behaviour (for App Privacy and Data Safety)` |
+| Native config | `## Native capability`, `## Compatibility` |

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}`);
+	}
+}