@chipmobilesdk/rn-camera 0.2.0 → 0.2.1

package/README.md

@@ -1,364 +1,364 @@
-# @chipmobilesdk/rn-camera
-
-Reusable camera infrastructure for ChipMobileSdk-family React Native apps: permission-gated preview, still capture with consistent metadata, a session lifecycle that reliably releases the camera, app-controlled artifact retention, capability-gated flash and torch, coordinate mapping for app-drawn overlays, and a test adapter.
-
-The package is **infrastructure, not a feature**. It contains no business logic, does not know what your photos are for, sends nothing over the network, and writes nothing to the device gallery.
-
-> **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
-
-- **Status**: `0.2.x`, public npm package (see [CHANGELOG](CHANGELOG.md))
-- **Entrypoint**: `src/index.ts` — the only public entrypoint
-- **Native code authored here**: none (see [Native capability](#native-capability))
-
-## Compatibility
-
-| | Supported |
-|---|---|
-| React | >= 19.2 |
-| React Native | >= 0.85 |
-| Android | `minSdkVersion` **24**, `targetSdkVersion` 36 |
-| iOS | 15.1+ |
-| `react-native-vision-camera` | 5.1.x |
-
-> **Android `minSdkVersion` stays at 24.** Secondary sources claim VisionCamera v5 requires 26. That is wrong for 5.1.1: its `gradle.properties` declares `VisionCamera_minSdkVersion=23` and its `build.gradle` resolves `rootProject.ext.minSdkVersion` first. Bumping to 26 would drop Android 7.0 and 7.1 devices for no reason.
-
-## Install (consuming app)
-
-```bash
-npm install @chipmobilesdk/rn-camera react-native-vision-camera react-native-nitro-modules react-native-nitro-image
-cd ios && pod install && cd ..
-```
-
-`react-native-vision-camera` is a **peer dependency** — your app installs and links it once, exactly as it does `react-native-keychain` for `@chipmobilesdk/rn-auth`.
-VisionCamera 5.1.x in turn requires the Nitro modules and image packages shown
-above; they remain app-owned native dependencies.
-
-> **If your app also uses `react-native-unistyles`** (as the ChipMobileSdk demo app does), both it and VisionCamera depend on `react-native-nitro-modules`, and only one Nitro version can exist in a build. After installing, verify your theme system still works on both platforms before going further.
-
-### iOS permissions
-
-```xml
-<key>NSCameraUsageDescription</key>
-<string>Explain, in your own words, why your app needs the camera.</string>
-```
-
-That is the only declaration the package requires. No microphone, no photo library, no location.
-
-### Android permissions
-
-```xml
-<uses-permission android:name="android.permission.CAMERA" />
-<uses-feature android:name="android.hardware.camera" android:required="false" />
-```
-
-`required="false"` keeps your app installable on camera-less devices; the package reports `hasCameraHardware: false` there so you can render an unavailable state instead of failing.
-
-## Quick start
-
-```tsx
-import React, { useCallback, useEffect, useState } from 'react';
-import {
-  CameraPreview,
-  createVisionCameraEngine,
-  createVisionCameraPermissions,
-  useCameraController,
-  useCameraState,
-  type CapturedImage,
-} from '@chipmobilesdk/rn-camera';
-
-function CameraScreen() {
-  const [photo, setPhoto] = useState<CapturedImage | null>(null);
-  const controller = useCameraController({
-    engine: createVisionCameraEngine(),
-    permissions: createVisionCameraPermissions(),
-  });
-  const state = useCameraState(controller);
-
-  useEffect(() => {
-    void (async () => {
-      await controller.getCapabilities();
-      if (await controller.getPermission() === 'granted') {
-        await controller.start();
-      }
-    })();
-  }, [controller]);
-
-  const requestPermission = useCallback(async () => {
-    if (await controller.requestPermission() === 'granted') {
-      await controller.start();
-    }
-  }, [controller]);
-
-  if (state.permission !== 'granted') {
-    // Your copy, your layout — the package supplies state, not UI.
-    return <PermissionGate onRequest={requestPermission} state={state.permission} />;
-  }
-
-  return (
-    <CameraPreview controller={controller} accessibilityLabel="Camera preview">
-      <ShutterButton onPress={async () => setPhoto(await controller.capture())} />
-    </CameraPreview>
-  );
-}
-```
-
-`CameraPreview` mounts the native feed only after `controller.start()` reaches
-the `active` state. `getPermission()` only reads state; it does not prompt or
-start a session. The controller hook releases the session when the screen
-unmounts.
-
-## Core concepts
-
-### Permission is a state, not a boolean
-
-Seven distinguishable states, because each one needs different UI: `undetermined`, `requesting`, `granted`, `denied`, `deniedPermanently`, `unavailable`, `unsupported`.
-
-`getPermission()` never prompts and never opens a session — safe to call on mount. Only `requestPermission()` prompts, and it refuses to re-prompt once the OS reports a permanent denial, reporting `deniedPermanently` instead so you can route the user to system settings. Revocations made in Settings while your app runs are pushed to subscribers without a restart.
-
-### Capture returns a file reference
-
-`capture()` resolves to a **file URI plus metadata** — never a base64 string, never an in-memory buffer. Base64 inflates an image by roughly a third and holds the whole thing in JavaScript memory, and strings that size are exactly what ends up in crash logs. If you need bytes, read the file.
-
-Metadata the platform cannot determine is **explicitly marked unavailable** rather than omitted:
-
-```ts
-const image = await controller.capture();
-image.fileSize.available ? image.fileSize.value : 'not reported by this platform';
-```
-
-A bare optional could not tell "the platform does not report this" from "nobody asked", which is why the wrapper exists.
-
-### You decide what is kept
-
-The returned ownership metadata is decided at capture time by one thing —
-whether you pass a `destination`:
-
-| | No `destination` | With `destination` |
-|---|---|---|
-| Ownership | `packageTemporary` | `appOwned` |
-| Default VisionCamera write | Native temporary file | Your path, directly |
-| Automatic persistence | No | Controlled by your destination |
-
-```ts
-const temp = await controller.capture();                                  // package-owned
-const kept = await controller.capture({ destination: '/my/app/x.jpg' });  // app-owned
-
-// cleanup() only acts when the controller was given an ArtifactStore and the
-// store reports that it owns this URI.
-await controller.cleanup(temp);
-```
-
-With a `store`, the controller moves every package-temporary capture out of
-VisionCamera's own temporary directory into the store (`ArtifactStore.adopt`), so
-`cleanup()` can delete it and the sweep can reach orphans. That move needs a
-`FileSystemBridge` that implements `move()`; the app supplies the bridge, because
-the package takes no filesystem dependency of its own:
-
-```ts
-import * as RNFS from '@dr.pogodin/react-native-fs';
-
-const store = createArtifactStore({
-  cacheDirectory: () => RNFS.CachesDirectoryPath,
-  exists: RNFS.exists,
-  unlink: RNFS.unlink,
-  list: async dir => (await RNFS.readDir(dir)).filter(e => e.isFile()).map(e => e.path),
-  createdAt: async path => (await RNFS.stat(path)).mtime.getTime(),
-  ensureDirectory: async dir => { if (!(await RNFS.exists(dir))) await RNFS.mkdir(dir); },
-  move: RNFS.moveFile,
-});
-```
-
-With no `store`, captures stay in VisionCamera's directory, `cleanup()` is a no-op,
-no sweep runs, and an opted-in logger reports `unmanaged:no-store` once. The sweep
-runs when the controller is first used, uses a 24-hour default TTL, touches only
-URIs the store owns, and spares captures adopted by the running process.
-`cleanup()` is idempotent and refuses paths outside the store root.
-
-### The camera is released, not held
-
-Backgrounding **stops and releases** the camera rather than pausing it. Both operating systems can reclaim it anyway, and holding it risks leaving the OS camera indicator lit while your app is not in front of the user. Returning to the foreground restarts the preview only if backgrounding interrupted a running session, the surface is still mounted, and permission is still granted — a camera the user stopped stays stopped.
-
-Each controller permits one active session; starting the same controller again
-reports `sessionConflict`.
-
-`useCameraController` disposes its controller on unmount and replaces it if React
-remounts the component (StrictMode does this in development). A disposed controller
-rejects `start`, `resume` and `capture` with `notReady`; `stop` and `cleanup` stay
-safe to call. The package does not implement a process-wide lock
-across different controller instances, so an app should mount only one active
-camera preview at a time.
-
-### Capability gating
-
-Ask before you render:
-
-```ts
-const caps = await controller.getCapabilities();
-if (caps.hasTorch) { /* render the torch control */ }
-```
-
-Invoking something the device does not have returns `unsupportedCapability` rather than an unexpected failure. Flash mode (`auto`/`on`/`off`) applies at capture time; torch is continuous during preview and is forced off whenever the session pauses, stops, or the app backgrounds.
-
-### Overlays
-
-The package draws no bounding boxes, guide frames, or reticles — those are where apps differ. It gives you the surface (`children` renders above the feed) and the geometry:
-
-```tsx
-<CameraPreview controller={controller} onGeometryChange={setGeometry}>
-  <View style={myGuideFrame} pointerEvents="none" />
-</CameraPreview>;
-
-const inImageSpace = mapRectToImage(myGuideFrame, geometry);
-```
-
-The pure mapping functions account for scale, letterbox or crop, orientation,
-and front-camera mirroring using the geometry you supply. In the current
-`CameraPreview`, `onGeometryChange` reports nominal image dimensions
-(`1920 × 1080`), orientation `0`, and mirroring from camera position; it does
-not yet read the selected native capture format. Use capture metadata or
-app-owned measured geometry when pixel-exact alignment is required.
-
-### Quality and dimensions
-
-The VisionCamera 5.1 adapter configures the photo output once, at quality `0.9`,
-and does not resize. Each capture therefore reports `effectiveQuality: 0.9` and an
-unavailable `effectiveMaxDimension`, whatever the request asked for; the request
-hints are not applied. Perform app-side image processing when an exact upload size
-or quality is required.
-
-## Testing without hardware
-
-`createTestCamera()` returns real implementations of the same published ports the production adapters implement — not a parallel mock, so it cannot drift from the contract without a compile error.
-
-```ts
-import { createCameraController, createTestCamera } from '@chipmobilesdk/rn-camera';
-
-const camera = createTestCamera({ permission: 'granted' });
-const controller = createCameraController({
-  engine: camera.engine,
-  permissions: camera.permissions,
-  store: camera.store,
-  subscribeToAppState: camera.subscribeToAppState,
-  sweepOnInit: false,
-});
-
-await controller.requestPermission();
-await controller.getCapabilities();
-await controller.start();
-
-const image = await controller.capture();
-
-// Drive any failure path:
-camera.setCaptureError('captureFailed');
-camera.setPermission('deniedPermanently');
-camera.setAppState('background');
-camera.emitInterruption();
-```
-
-Add a module mapping so an accidental import of the native module resolves in Jest:
-
-```js
-moduleNameMapper: {
-  '^react-native-vision-camera$': '<rootDir>/__tests__/__mocks__/react-native-vision-camera.ts',
-}
-```
-
-## 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:
-
-`permissionDenied`, `cameraUnavailable`, `cameraBlocked`, `cameraInUse`, `sessionConflict`, `notReady`, `captureInProgress`, `captureFailed`, `storageFailure`, `unsupportedCapability`, `interrupted`.
-
-A double-tapped shutter produces `captureInProgress` on the second call. The package does not queue (which would give the user two photos they never asked for) and does not coalesce (which would hide a deliberate second capture behind an accidental one).
-
-## Diagnostics
-
-Logging is **off by default**, and event bodies carry codes and states only — never file paths or image data:
-
-```ts
-createCameraController({ logger: { log: event => myLogger.debug(event) } });
-```
-
-A `redact()` helper is exported for scrubbing paths and payload-shaped strings from anything else you log.
-
-## Data behaviour (for App Privacy and Data Safety)
-
-Use this when completing your store declarations:
-
-| Question | Answer for this package |
-|---|---|
-| What data is involved? | Camera imagery generated on-device by explicit user action, plus technical metadata (dimensions, mime type, size, orientation, timestamp, camera position) |
-| Transmitted off device? | **No.** The package makes no network requests of any kind |
-| Shared with third parties? | **No** |
-| Stored persistently? | A capture is a file: the default adapter uses VisionCamera's native temporary location unless the app supplies a destination. The package has no history database and does not write to the gallery |
-| Location attached? | **No.** No location data is read and no location permission is requested |
-| Written to the photo library? | **No** |
-| Tracking, ads, identifiers? | **None** |
-| On-device AI or inference? | **None in this phase** |
-
-**If your app uploads captured images off-device, that collection is yours to declare** — the package cannot know you do it. The same applies to moderation and reporting obligations if captures become user-generated content.
-
-## Native capability
-
-This package authors **zero native source**. Camera capability arrives entirely through the `react-native-vision-camera` peer dependency, mirroring how `@chipmobilesdk/rn-auth` obtains Keychain and OIDC capability.
-
-The ChipMobileSdk constitution prohibits native code in shared libraries by default. A camera cannot be implemented in TypeScript, so this is the exception in its narrowest available form: a maintained MIT library the consuming app installs, wrapped behind port interfaces this package owns.
-
-## Reserved: local frame processing (not implemented)
-
-Phase one runs **no inference, emits no AI-derived labels, and sends no frame anywhere**. The extension point is documented now so the later local-AI phase can arrive as an additive minor release without disturbing anything above.
-
-The reserved contract:
-
-```ts
-// NOT EXPORTED. Reserved shape for the local-AI phase.
-interface FrameProcessorOptions {
-  maxFps: number;                  // frame-rate cap, to protect the UI thread and battery
-  inferenceMaxDimension: number;   // lower than preview resolution
-  onFrame: (frame: ReservedFrame) => void;
-  backpressure: 'dropLatest' | 'dropOldest';
-  // Automatically paused when the app backgrounds. Frames never leave the device.
-}
-```
-
-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.
-
-- Controller and state: `createCameraController`, `CameraController`,
-  `CameraControllerOptions`, `useCameraController`, `useCameraState`,
-  `CameraState`, `AppStatus`, `DEFAULT_TEMPORARY_TTL_MS`
-- Preview and capture: `CameraPreview`, `CameraPreviewProps`, `CaptureRequest`,
-  `CapturedImage`, `StartOptions` and the camera/session/capability types
-- Ports and adapters: `CameraEngine`, `EngineOptions`,
-  `createVisionCameraEngine`, `PermissionPort`,
-  `createVisionCameraPermissions`, `ArtifactStore`, `FileSystemBridge`,
-  `StoreOptions`, `createCacheArtifactStore`, `createArtifactStore`
-- Mapping: `mapPointToImage`, `mapPointToPreview`, `mapRectToImage`,
-  `mapRectToPreview`, plus `Point`, `Rect`, and `PreviewGeometry`
-- Diagnostics: `CameraError`, `CameraErrorCode`, `isCameraError`, `redact`, and
-  the logger event/type contracts
-- Testing: `createTestCamera`, `createMemoryFileSystem`,
-  `DEFAULT_TEST_CAPABILITIES`, and their configuration/handle types
-- Metadata helpers: `known`, `unavailable`, `Known`, `Unavailable`, `Maybe`
-
-Stable for semver: types, controller, preview, mapping, errors. Experimental and may change in a minor: the diagnostics logger shape and the test adapter configuration.
-
-## License
-
-`UNLICENSED`. The npm tarball is publicly downloadable, but no open-source
-license or permission to copy, modify, or redistribute is granted.
-
-## Demo and validation
-
-The demo integration lives in `src/screens/CameraDemoScreen.tsx`. Run the
-package commands from the repository root (camera currently has no root-level
-shortcut):
-
-```bash
-npm run typecheck --workspace @chipmobilesdk/rn-camera
-npm run pack:dry-run --workspace @chipmobilesdk/rn-camera
-```
+# @chipmobilesdk/rn-camera
+
+Reusable camera infrastructure for ChipMobileSdk-family React Native apps: permission-gated preview, still capture with consistent metadata, a session lifecycle that reliably releases the camera, app-controlled artifact retention, capability-gated flash and torch, coordinate mapping for app-drawn overlays, and a test adapter.
+
+The package is **infrastructure, not a feature**. It contains no business logic, does not know what your photos are for, sends nothing over the network, and writes nothing to the device gallery.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Status**: public npm package; version in [CHANGELOG](CHANGELOG.md)
+- **Entrypoint**: `src/index.ts` — the only public entrypoint
+- **Native code authored here**: none (see [Native capability](#native-capability))
+
+## Compatibility
+
+| | Supported |
+|---|---|
+| React | >= 19.2 |
+| React Native | >= 0.85 |
+| Android | `minSdkVersion` **24**, `targetSdkVersion` 36 |
+| iOS | 15.1+ |
+| `react-native-vision-camera` | 5.1.x |
+
+> **Android `minSdkVersion` stays at 24.** Secondary sources claim VisionCamera v5 requires 26. That is wrong for 5.1.1: its `gradle.properties` declares `VisionCamera_minSdkVersion=23` and its `build.gradle` resolves `rootProject.ext.minSdkVersion` first. Bumping to 26 would drop Android 7.0 and 7.1 devices for no reason.
+
+## Install (consuming app)
+
+```bash
+npm install @chipmobilesdk/rn-camera react-native-vision-camera react-native-nitro-modules react-native-nitro-image
+cd ios && pod install && cd ..
+```
+
+`react-native-vision-camera` is a **peer dependency** — your app installs and links it once, exactly as it does `react-native-keychain` for `@chipmobilesdk/rn-auth`.
+VisionCamera 5.1.x in turn requires the Nitro modules and image packages shown
+above; they remain app-owned native dependencies.
+
+> **If your app also uses `react-native-unistyles`** (as the ChipMobileSdk demo app does), both it and VisionCamera depend on `react-native-nitro-modules`, and only one Nitro version can exist in a build. After installing, verify your theme system still works on both platforms before going further.
+
+### iOS permissions
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Explain, in your own words, why your app needs the camera.</string>
+```
+
+That is the only declaration the package requires. No microphone, no photo library, no location.
+
+### Android permissions
+
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-feature android:name="android.hardware.camera" android:required="false" />
+```
+
+`required="false"` keeps your app installable on camera-less devices; the package reports `hasCameraHardware: false` there so you can render an unavailable state instead of failing.
+
+## Quick start
+
+```tsx
+import React, { useCallback, useEffect, useState } from 'react';
+import {
+  CameraPreview,
+  createVisionCameraEngine,
+  createVisionCameraPermissions,
+  useCameraController,
+  useCameraState,
+  type CapturedImage,
+} from '@chipmobilesdk/rn-camera';
+
+function CameraScreen() {
+  const [photo, setPhoto] = useState<CapturedImage | null>(null);
+  const controller = useCameraController({
+    engine: createVisionCameraEngine(),
+    permissions: createVisionCameraPermissions(),
+  });
+  const state = useCameraState(controller);
+
+  useEffect(() => {
+    void (async () => {
+      await controller.getCapabilities();
+      if (await controller.getPermission() === 'granted') {
+        await controller.start();
+      }
+    })();
+  }, [controller]);
+
+  const requestPermission = useCallback(async () => {
+    if (await controller.requestPermission() === 'granted') {
+      await controller.start();
+    }
+  }, [controller]);
+
+  if (state.permission !== 'granted') {
+    // Your copy, your layout — the package supplies state, not UI.
+    return <PermissionGate onRequest={requestPermission} state={state.permission} />;
+  }
+
+  return (
+    <CameraPreview controller={controller} accessibilityLabel="Camera preview">
+      <ShutterButton onPress={async () => setPhoto(await controller.capture())} />
+    </CameraPreview>
+  );
+}
+```
+
+`CameraPreview` mounts the native feed only after `controller.start()` reaches
+the `active` state. `getPermission()` only reads state; it does not prompt or
+start a session. The controller hook releases the session when the screen
+unmounts.
+
+## Core concepts
+
+### Permission is a state, not a boolean
+
+Seven distinguishable states, because each one needs different UI: `undetermined`, `requesting`, `granted`, `denied`, `deniedPermanently`, `unavailable`, `unsupported`.
+
+`getPermission()` never prompts and never opens a session — safe to call on mount. Only `requestPermission()` prompts, and it refuses to re-prompt once the OS reports a permanent denial, reporting `deniedPermanently` instead so you can route the user to system settings. Revocations made in Settings while your app runs are pushed to subscribers without a restart.
+
+### Capture returns a file reference
+
+`capture()` resolves to a **file URI plus metadata** — never a base64 string, never an in-memory buffer. Base64 inflates an image by roughly a third and holds the whole thing in JavaScript memory, and strings that size are exactly what ends up in crash logs. If you need bytes, read the file.
+
+Metadata the platform cannot determine is **explicitly marked unavailable** rather than omitted:
+
+```ts
+const image = await controller.capture();
+image.fileSize.available ? image.fileSize.value : 'not reported by this platform';
+```
+
+A bare optional could not tell "the platform does not report this" from "nobody asked", which is why the wrapper exists.
+
+### You decide what is kept
+
+The returned ownership metadata is decided at capture time by one thing —
+whether you pass a `destination`:
+
+| | No `destination` | With `destination` |
+|---|---|---|
+| Ownership | `packageTemporary` | `appOwned` |
+| Default VisionCamera write | Native temporary file | Your path, directly |
+| Automatic persistence | No | Controlled by your destination |
+
+```ts
+const temp = await controller.capture();                                  // package-owned
+const kept = await controller.capture({ destination: '/my/app/x.jpg' });  // app-owned
+
+// cleanup() only acts when the controller was given an ArtifactStore and the
+// store reports that it owns this URI.
+await controller.cleanup(temp);
+```
+
+With a `store`, the controller moves every package-temporary capture out of
+VisionCamera's own temporary directory into the store (`ArtifactStore.adopt`), so
+`cleanup()` can delete it and the sweep can reach orphans. That move needs a
+`FileSystemBridge` that implements `move()`; the app supplies the bridge, because
+the package takes no filesystem dependency of its own:
+
+```ts
+import * as RNFS from '@dr.pogodin/react-native-fs';
+
+const store = createArtifactStore({
+  cacheDirectory: () => RNFS.CachesDirectoryPath,
+  exists: RNFS.exists,
+  unlink: RNFS.unlink,
+  list: async dir => (await RNFS.readDir(dir)).filter(e => e.isFile()).map(e => e.path),
+  createdAt: async path => (await RNFS.stat(path)).mtime.getTime(),
+  ensureDirectory: async dir => { if (!(await RNFS.exists(dir))) await RNFS.mkdir(dir); },
+  move: RNFS.moveFile,
+});
+```
+
+With no `store`, captures stay in VisionCamera's directory, `cleanup()` is a no-op,
+no sweep runs, and an opted-in logger reports `unmanaged:no-store` once. The sweep
+runs when the controller is first used, uses a 24-hour default TTL, touches only
+URIs the store owns, and spares captures adopted by the running process.
+`cleanup()` is idempotent and refuses paths outside the store root.
+
+### The camera is released, not held
+
+Backgrounding **stops and releases** the camera rather than pausing it. Both operating systems can reclaim it anyway, and holding it risks leaving the OS camera indicator lit while your app is not in front of the user. Returning to the foreground restarts the preview only if backgrounding interrupted a running session, the surface is still mounted, and permission is still granted — a camera the user stopped stays stopped.
+
+Each controller permits one active session; starting the same controller again
+reports `sessionConflict`.
+
+`useCameraController` disposes its controller on unmount and replaces it if React
+remounts the component (StrictMode does this in development). A disposed controller
+rejects `start`, `resume` and `capture` with `notReady`; `stop` and `cleanup` stay
+safe to call. The package does not implement a process-wide lock
+across different controller instances, so an app should mount only one active
+camera preview at a time.
+
+### Capability gating
+
+Ask before you render:
+
+```ts
+const caps = await controller.getCapabilities();
+if (caps.hasTorch) { /* render the torch control */ }
+```
+
+Invoking something the device does not have returns `unsupportedCapability` rather than an unexpected failure. Flash mode (`auto`/`on`/`off`) applies at capture time; torch is continuous during preview and is forced off whenever the session pauses, stops, or the app backgrounds.
+
+### Overlays
+
+The package draws no bounding boxes, guide frames, or reticles — those are where apps differ. It gives you the surface (`children` renders above the feed) and the geometry:
+
+```tsx
+<CameraPreview controller={controller} onGeometryChange={setGeometry}>
+  <View style={myGuideFrame} pointerEvents="none" />
+</CameraPreview>;
+
+const inImageSpace = mapRectToImage(myGuideFrame, geometry);
+```
+
+The pure mapping functions account for scale, letterbox or crop, orientation,
+and front-camera mirroring using the geometry you supply. In the current
+`CameraPreview`, `onGeometryChange` reports nominal image dimensions
+(`1920 × 1080`), orientation `0`, and mirroring from camera position; it does
+not yet read the selected native capture format. Use capture metadata or
+app-owned measured geometry when pixel-exact alignment is required.
+
+### Quality and dimensions
+
+The VisionCamera 5.1 adapter configures the photo output once, at quality `0.9`,
+and does not resize. Each capture therefore reports `effectiveQuality: 0.9` and an
+unavailable `effectiveMaxDimension`, whatever the request asked for; the request
+hints are not applied. Perform app-side image processing when an exact upload size
+or quality is required.
+
+## Testing without hardware
+
+`createTestCamera()` returns real implementations of the same published ports the production adapters implement — not a parallel mock, so it cannot drift from the contract without a compile error.
+
+```ts
+import { createCameraController, createTestCamera } from '@chipmobilesdk/rn-camera';
+
+const camera = createTestCamera({ permission: 'granted' });
+const controller = createCameraController({
+  engine: camera.engine,
+  permissions: camera.permissions,
+  store: camera.store,
+  subscribeToAppState: camera.subscribeToAppState,
+  sweepOnInit: false,
+});
+
+await controller.requestPermission();
+await controller.getCapabilities();
+await controller.start();
+
+const image = await controller.capture();
+
+// Drive any failure path:
+camera.setCaptureError('captureFailed');
+camera.setPermission('deniedPermanently');
+camera.setAppState('background');
+camera.emitInterruption();
+```
+
+Add a module mapping so an accidental import of the native module resolves in Jest:
+
+```js
+moduleNameMapper: {
+  '^react-native-vision-camera$': '<rootDir>/__tests__/__mocks__/react-native-vision-camera.ts',
+}
+```
+
+## 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:
+
+`permissionDenied`, `cameraUnavailable`, `cameraBlocked`, `cameraInUse`, `sessionConflict`, `notReady`, `captureInProgress`, `captureFailed`, `storageFailure`, `unsupportedCapability`, `interrupted`.
+
+A double-tapped shutter produces `captureInProgress` on the second call. The package does not queue (which would give the user two photos they never asked for) and does not coalesce (which would hide a deliberate second capture behind an accidental one).
+
+## Diagnostics
+
+Logging is **off by default**, and event bodies carry codes and states only — never file paths or image data:
+
+```ts
+createCameraController({ logger: { log: event => myLogger.debug(event) } });
+```
+
+A `redact()` helper is exported for scrubbing paths and payload-shaped strings from anything else you log.
+
+## Data behaviour (for App Privacy and Data Safety)
+
+Use this when completing your store declarations:
+
+| Question | Answer for this package |
+|---|---|
+| What data is involved? | Camera imagery generated on-device by explicit user action, plus technical metadata (dimensions, mime type, size, orientation, timestamp, camera position) |
+| Transmitted off device? | **No.** The package makes no network requests of any kind |
+| Shared with third parties? | **No** |
+| Stored persistently? | A capture is a file: the default adapter uses VisionCamera's native temporary location unless the app supplies a destination. The package has no history database and does not write to the gallery |
+| Location attached? | **No.** No location data is read and no location permission is requested |
+| Written to the photo library? | **No** |
+| Tracking, ads, identifiers? | **None** |
+| On-device AI or inference? | **None in this phase** |
+
+**If your app uploads captured images off-device, that collection is yours to declare** — the package cannot know you do it. The same applies to moderation and reporting obligations if captures become user-generated content.
+
+## Native capability
+
+This package authors **zero native source**. Camera capability arrives entirely through the `react-native-vision-camera` peer dependency, mirroring how `@chipmobilesdk/rn-auth` obtains Keychain and OIDC capability.
+
+The ChipMobileSdk constitution prohibits native code in shared libraries by default. A camera cannot be implemented in TypeScript, so this is the exception in its narrowest available form: a maintained MIT library the consuming app installs, wrapped behind port interfaces this package owns.
+
+## Reserved: local frame processing (not implemented)
+
+Phase one runs **no inference, emits no AI-derived labels, and sends no frame anywhere**. The extension point is documented now so the later local-AI phase can arrive as an additive minor release without disturbing anything above.
+
+The reserved contract:
+
+```ts
+// NOT EXPORTED. Reserved shape for the local-AI phase.
+interface FrameProcessorOptions {
+  maxFps: number;                  // frame-rate cap, to protect the UI thread and battery
+  inferenceMaxDimension: number;   // lower than preview resolution
+  onFrame: (frame: ReservedFrame) => void;
+  backpressure: 'dropLatest' | 'dropOldest';
+  // Automatically paused when the app backgrounds. Frames never leave the device.
+}
+```
+
+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.
+
+- Controller and state: `createCameraController`, `CameraController`,
+  `CameraControllerOptions`, `useCameraController`, `useCameraState`,
+  `CameraState`, `AppStatus`, `DEFAULT_TEMPORARY_TTL_MS`
+- Preview and capture: `CameraPreview`, `CameraPreviewProps`, `CaptureRequest`,
+  `CapturedImage`, `StartOptions` and the camera/session/capability types
+- Ports and adapters: `CameraEngine`, `EngineOptions`,
+  `createVisionCameraEngine`, `PermissionPort`,
+  `createVisionCameraPermissions`, `ArtifactStore`, `FileSystemBridge`,
+  `StoreOptions`, `createCacheArtifactStore`, `createArtifactStore`
+- Mapping: `mapPointToImage`, `mapPointToPreview`, `mapRectToImage`,
+  `mapRectToPreview`, plus `Point`, `Rect`, and `PreviewGeometry`
+- Diagnostics: `CameraError`, `CameraErrorCode`, `isCameraError`, `redact`, and
+  the logger event/type contracts
+- Testing: `createTestCamera`, `createMemoryFileSystem`,
+  `DEFAULT_TEST_CAPABILITIES`, and their configuration/handle types
+- Metadata helpers: `known`, `unavailable`, `Known`, `Unavailable`, `Maybe`
+
+Stable for semver: types, controller, preview, mapping, errors. Experimental and may change in a minor: the diagnostics logger shape and the test adapter configuration.
+
+## License
+
+`UNLICENSED`. The npm tarball is publicly downloadable, but no open-source
+license or permission to copy, modify, or redistribute is granted.
+
+## Demo and validation
+
+The demo integration lives in `src/screens/CameraDemoScreen.tsx`. Run the
+package commands from the repository root (camera currently has no root-level
+shortcut):
+
+```bash
+npm run typecheck --workspace @chipmobilesdk/rn-camera
+npm run pack:check --workspace @chipmobilesdk/rn-camera
+```