@chipmobilesdk/rn-camera 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog — @chipmobilesdk/rn-camera
+
+All notable changes to this package are documented here. The package follows semantic versioning.
+
+## 0.1.0 — 2026-07-26
+
+Initial release. New package, no existing consumers, **no migration required**.
+
+### Added
+
+- **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.
+- **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.
+- **Typed error taxonomy** of 11 codes, each carrying a `recoverable` flag, plus a `redact()` helper.
+- **Test adapter** (`createTestCamera`) implementing the same published ports as the production adapters, so consuming apps can drive every permission, capability, and capture path with no hardware and no permission prompts.
+- **Opt-in diagnostics logger**, defaulting to no logging.
+
+### Guarantees
+
+- No network egress of any kind.
+- No location read, no location permission requested.
+- Nothing written to the device photo library or gallery.
+- No capture history or index retained.
+- No on-device inference, no frame processor, no AI-derived labels.
+
+### Notes
+
+- `react-native-vision-camera` (>= 5.1.1) is a **peer dependency**; the consuming app installs and links it. This package authors no native source.
+- Android `minSdkVersion` remains **24** — VisionCamera 5.1.1 declares 23 and resolves the root project value first.
+- The local frame-processing extension point is documented in the README but deliberately not exported. It is designed to arrive as an additive minor release.

package/README.md

@@ -0,0 +1,341 @@
+# @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.1.0`, public npm package
+- **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);
+```
+
+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.
+
+### 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.
+
+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.
+
+### 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
+
+`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.
+
+## 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
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@chipmobilesdk/rn-camera",
+	"version": "0.1.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",
+		"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/"
+	}
+}

package/src/config/types.ts

@@ -0,0 +1,149 @@
+/**
+ * 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

@@ -0,0 +1,44 @@
+/**
+ * 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}`);
+	}
+}