@chipmobilesdk/rn-camera 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this package are documented here. The package follows semantic versioning.
 
+## [0.2.0] — 2026-11-01
+
+Lifecycle and capture-path fixes. **No code change is required**; two behaviours
+change (see Changed), and a store that should manage VisionCamera captures needs a
+`FileSystemBridge` with `move()`.
+
+### Fixed
+
+- **`useCameraController` survives a StrictMode remount.** The cleanup disposed the
+  only controller and the remount kept it, so the screen showed `idle` forever and
+  backgrounding no longer released the camera. A disposed controller is now replaced,
+  and constructing one has no side effects (it subscribes on first use), so a
+  controller React builds and discards no longer leaks listeners.
+- **`CameraPreview` subscribes to the controller.** It read `controller.state` once
+  per render, so the feed could stay unmounted after the session became active unless
+  the parent re-rendered. `useCameraState` now uses `useSyncExternalStore`.
+- **A failed capture no longer leaves `capturing: true` published**, and `capturing:
+  true` is now published at all — the single-flight slot was taken after the first
+  emit. A raw native or engine error is turned into `CameraError('captureFailed')`
+  (or `storageFailure` when saving fails), with no file path in the message.
+- **Foregrounding restarts only a session that backgrounding interrupted.** It used
+  to start any idle or stopped session while a preview was mounted — including one
+  the user had stopped, one never started, and one whose permission had been revoked.
+  A foreground that arrives while the release is still running now waits for it
+  instead of being dropped.
+- **Use after dispose is defined.** `start`, `resume`, `capture`, and the permission
+  and capability reads reject with `CameraError('notReady')`; `stop`, `pause` and
+  `cleanup` are safe no-ops.
+- **VisionCamera captures can be cleaned up.** They were saved in VisionCamera's own
+  temporary directory, outside the store, so `cleanup()` refused them and the 24-hour
+  sweep never saw them. The controller now moves each package-temporary capture into
+  the store (`ArtifactStore.adopt`), and the sweep spares captures adopted by the
+  running process. With no store, or a bridge without `move()`, the logger reports
+  `unmanaged:no-store` / `unmanaged:store-cannot-adopt` once.
+- **No more "Camera is not active" error on every session start.** The feed sent
+  `torchMode="off"` on mount; VisionCamera applies it before the camera is active
+  and leaves the native rejection unhandled. The prop is now left unset until the
+  torch is first turned on.
+- **One throwing state listener no longer breaks a transition** or starves the other
+  listeners; it is logged as `listener-threw`.
+
+### Changed
+
+- **`effectiveQuality` and `effectiveMaxDimension` report what was applied.** The
+  VisionCamera adapter echoed the request hints. Quality is fixed on the photo output
+  (0.9) and nothing resizes, so it now reports `0.9` and an unavailable max dimension.
+- **Unmounting a preview over an idle controller leaves it `idle`**, rather than
+  driving it through `stopping` to `stopped` and calling the engine's `stop()`.
+
+### Added
+
+- `ArtifactStore.adopt?(uri)` and `FileSystemBridge.move?(from, to)`, both optional.
+  `createMemoryFileSystem()` implements `move`.
+
+### Docs
+
+- The README no longer claims quality and max-dimension hints are applied, or a
+  single active session per process.
+
 ## 0.1.0 — 2026-07-26
 
 Initial release. New package, no existing consumers, **no migration required**.
@@ -10,8 +69,8 @@ Initial release. New package, no existing consumers, **no migration required**.
 
 - **Permission handling** as a seven-state contract (`undetermined`, `requesting`, `granted`, `denied`, `deniedPermanently`, `unavailable`, `unsupported`). Reading status never prompts; requesting never re-prompts after a permanent denial; revocations made in system settings are pushed to subscribers without an app restart.
 - **`CameraPreview`** surface with `cover`/`contain` resize modes, an overlay slot via `children`, and pass-through of consumer accessibility properties. Ships no styled UI and takes no theme dependency.
-- **Still capture** returning a file reference plus metadata. Undeterminable fields (`fileSize`, `orientation`) are explicitly marked unavailable rather than guessed or omitted. Quality and max-dimension hints are applied within device limits and reported back as effective values.
-- **Session lifecycle** — start, pause, resume, stop — that releases the camera on background, unmount, and stop, restarts on foreground when a surface is still mounted, and reports a single active session per process.
+- **Still capture** returning a file reference plus metadata. Undeterminable fields (`fileSize`, `orientation`) are explicitly marked unavailable rather than guessed or omitted. Quality and max-dimension hints are normalized and reported back as effective values.
+- **Session lifecycle** — start, pause, resume, stop — that releases the camera on background, unmount, and stop, restarts on foreground when a surface is still mounted, and reports a single active session per controller.
 - **Artifact ownership and cleanup**: an optional `destination` on the capture request switches the result to app-owned and writes there directly; everything else lands in the package cache directory. `cleanup()` is idempotent and refuses anything the package does not own. Orphans are swept at initialization under a 24-hour time-to-live.
 - **Capability reporting** for camera positions, flash, torch, orientation, and camera-less devices, with capture-time flash modes and a continuous torch that is forced off on pause, stop, and background.
 - **Coordinate mapping** — pure, bidirectional, accounting for scale, letterbox or crop, orientation, and front-camera mirroring, accurate within 2 device-independent pixels on a round trip.

package/README.md

@@ -2,12 +2,12 @@
 
 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.
+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.
 
-- **Status**: `0.1.0`, public npm package
+> **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))
 
@@ -25,14 +25,14 @@ The package is **infrastructure, not a feature**. It contains no business logic,
 
 ## 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.
+```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.
 
@@ -56,57 +56,57 @@ That is the only declaration the package requires. No microphone, no photo libra
 
 ## 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} />;
-  }
+```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.
+}
+```
+
+`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
 
@@ -129,42 +129,65 @@ 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 |
+### 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);
-```
-
-The default VisionCamera adapter does not automatically move its native
-temporary file into the optional package store. With no `store`, `cleanup()` is
-a no-op and no sweep runs. To enable bounded cleanup, create an
-`ArtifactStore` with an app-supplied `FileSystemBridge`, pass it to the
-controller, and place managed files under that store's temporary directory.
-Initialization then sweeps only URIs the store owns, using a 24-hour default
-TTL. `cleanup()` is idempotent and refuses paths outside the store root.
+// 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 if the surface is still mounted.
+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`.
 
-Each controller permits one active session; starting the same controller again
-reports `sessionConflict`. 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.
+`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
 
@@ -189,20 +212,20 @@ The package draws no bounding boxes, guide frames, or reticles — those are whe
 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
-
-`quality` and `maxDimension` are normalized into `effectiveQuality` and
-`effectiveMaxDimension` metadata. The current VisionCamera 5.1 adapter does
-not yet resize or re-encode the saved image, so these fields are hints rather
-than a guarantee about output bytes. Perform app-side image processing when an
-exact upload size or quality is required.
+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
 
@@ -268,7 +291,7 @@ Use this when completing your store declarations:
 | 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 |
+| 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** |
@@ -305,37 +328,37 @@ Still capture and real-time frame processing stay strictly separate.
 
 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`
+- 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
-```
+## 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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-camera",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

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

@@ -1,71 +1,75 @@
----
-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.
-
-## 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.
-
-## 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.1.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"
+  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` |

package/src/core/captureController.ts

@@ -93,26 +93,28 @@ export function finalizeResult(
 }
 
 /**
- * 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.
+ * 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 inFlight: Promise<CapturedImage> | null = null;
+	private active = false;
 
 	get busy(): boolean {
-		return this.inFlight !== null;
+		return this.active;
 	}
 
 	async run(operation: () => Promise<CapturedImage>): Promise<CapturedImage> {
-		if (this.inFlight) {
+		if (this.active) {
 			throw new CameraError('captureInProgress', 'A capture is already in progress');
 		}
-		const promise = operation();
-		this.inFlight = promise;
+		this.active = true;
 		try {
-			return await promise;
+			return await operation();
 		} finally {
-			this.inFlight = null;
+			this.active = false;
 		}
 	}
 }