@chipmobilesdk/rn-camera 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # @chipmobilesdk/rn-camera
 
+## 0.4.0
+
+### Minor Changes
+
+- `start()` resolves when the preview is producing frames. With the VisionCamera adapter the session belongs to the `<Camera>` view, so the controller now waits for that view to report instead of calling the session active as soon as the request was made — `capture()` straight after `start()` used to fail with `notReady`. A camera that never produces a frame fails the start after `startTimeoutMs` (8 s by default) rather than leaving the session in `starting` forever, and the native session errors the preview reports map to `cameraInUse`, `cameraBlocked`, `permissionDenied`, `cameraUnavailable` or `interrupted`. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  `pause()` keeps the preview surface mounted and stops the camera, so `resume()` no longer rebuilds the device, the session and the photo output — the whole first-frame cost was paid on every resume, with a black flash to go with it.
+
+  Geometry comes from the camera. `onGeometryChange` fires again with the selected format's pixel size, the device's orientation and the position of the device that actually mounted, as soon as the surface reports them; the same values are published as `state.surface`. Mapping a rectangle on a portrait phone was being done against a nominal landscape 1920×1080 image.
+
+  `capture({ cameraPosition })` must name the camera that is running, and is refused with `notReady` otherwise: the photo came from the device the preview had mounted while the metadata claimed the camera that was asked for. `start({ cameraPosition })` switches.
+
+  A failed `requestPermission()` leaves a state the app can retry from rather than `requesting` forever. An engine can report that the camera was taken away (`subscribeToInterruptions`), and the session fails with that code instead of showing a frozen preview; `createTestCamera()` simulates it with `emitInterruption(code?)` and a failing permission request with `emitPermissionRequestFailure(true)`.
+
+  The preview surface belongs to its engine (`attachSurface`, `createSurfaceRegistry`), not to a module-level slot two controllers shared — a capture from one screen could run through another screen's surface. `engine` and `permissions` are required by `CameraControllerOptions` (as they always were at runtime), the unused `EngineOptions` type is gone, and the artifact store reports a typed `CameraError` rather than a bare `Error`.
+
+### Patch Changes
+
+- Internal: no module in these packages is over 500 lines any more. The camera controller's session I/O moved to `sessionRuntime` and its contract to `contract.ts`; the Play adapter's shape translation to `iapShapes`; the purchase flow's failure mapping and its receipt-validation hook to modules of their own; the AI client's quota request to `quotaRequest`; the in-memory adapter's attachments and the fake ads engine's clock likewise. Behaviour is unchanged — the splits are by responsibility, and every package's suite passes as it stood. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  The repository also measures what it promised: `npm run perf` prints the median of nine runs of the deterministic hot paths against written budgets (recurrence expansion, theme construction, translation lookup, chart geometry, filter compilation), the demo app has a Performance screen reporting startup phases, time to interactive and the same benchmarks on Hermes, and `npm run check:file-size` keeps the limit from drifting. The budgets and the measured figures are recorded in `docs/standards.md` §VI.
+
+## 0.3.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+
+### Patch Changes
+
+- `createCameraController` accepts an explicit `undefined` for `store` and `logger`, so
+  apps compiling with `exactOptionalPropertyTypes` type-check against the package.
+  `VisionCameraFeed` leaves `torchMode` unset until the app first touches the torch,
+  instead of passing `undefined`. No other change. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -213,11 +213,39 @@ 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.
+and front-camera mirroring using the geometry you supply.
+
+`onGeometryChange` fires first with nominal dimensions (`1920 × 1080`,
+orientation `0`) because the preview has been measured before the camera has,
+and again with the real ones as soon as the surface reports: the selected
+format's pixel size, the device's orientation, and the position of the device
+that actually mounted. The same values are on `state.surface`, which is `null`
+until then — map coordinates once it is set, or a rectangle will be mapped
+against a landscape image on a portrait phone.
+
+### Starting, pausing, and what "active" means
+
+`start()` resolves when the preview is producing frames, not when the request
+was made: with the VisionCamera adapter the session belongs to the `<Camera>`
+view, so the controller waits for it to report and `capture()` straight after
+`start()` works. A camera that never produces a frame fails the start after
+`startTimeoutMs` (8 s by default) instead of leaving the session in `starting`.
+
+`pause()` keeps the surface mounted and stops the camera; `resume()` therefore
+does not rebuild the device, the session and the photo output. The surface is
+unmounted only when the session stops, fails, or loses permission.
+
+An engine can report that the camera was taken away — another app, an incoming
+call, a disconnected device — through `subscribeToInterruptions`. The session
+fails with that code rather than showing a frozen preview; `createTestCamera()`
+simulates it with `emitInterruption(code?)`.
+
+### Which camera a capture comes from
+
+`capture({ cameraPosition })` must name the camera that is running: a photo
+comes from the device the preview mounted, so a request for the other one is
+refused with `notReady` rather than returning an image labelled with a camera
+that did not take it. Call `start({ cameraPosition })` to switch first.
 
 ### Quality and dimensions
 
@@ -256,6 +284,31 @@ camera.setAppState('background');
 camera.emitInterruption();
 ```
 
+### Conformance
+
+`@chipmobilesdk/rn-camera/testing` also ships the checks every `PermissionPort` and
+`CameraEngine` must pass. The package runs them against the test adapter and against the
+VisionCamera adapters; run them against your own adapter, or from a demo screen on a
+device, the same way:
+
+```ts
+import { expectConformance } from '@chipmobilesdk/rn-core/testing';
+import { runPermissionPortConformance } from '@chipmobilesdk/rn-camera/testing';
+
+expectConformance(
+  await runPermissionPortConformance({
+    create(initial) {
+      // a port over a system whose permission starts in `initial`
+      return { port, setSystemState, prompts };
+    },
+  }),
+);
+```
+
+`createTestCamera` and its helpers are exported from `./testing` too; the main
+entrypoint keeps them until the next major release. `camera.prompts()` counts how often
+`request()` showed the system prompt.
+
 Add a module mapping so an accidental import of the native module resolves in Jest:
 
 ```js
@@ -266,7 +319,8 @@ moduleNameMapper: {
 
 ## 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:
+Every failure is a `CameraError` with a `code` and a `retryable` flag (`recoverable` is kept as its deprecated alias), so you branch on the code rather than string-matching a message. `CameraError` extends `SdkError` from `@chipmobilesdk/rn-core`, so `isSdkError(error)` recognises it alongside every other package's errors, `error.pkg` names this package, and `error.redactedCause` (when present) is the underlying failure reduced to log-safe text.
+
 
 `permissionDenied`, `cameraUnavailable`, `cameraBlocked`, `cameraInUse`, `sessionConflict`, `notReady`, `captureInProgress`, `captureFailed`, `storageFailure`, `unsupportedCapability`, `interrupted`.
 
@@ -326,15 +380,16 @@ 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.
+Everything is exported from `@chipmobilesdk/rn-camera`, test doubles and conformance suites also from `@chipmobilesdk/rn-camera/testing`. 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`,
+- Ports and adapters: `CameraEngine`, `createVisionCameraEngine`,
+  `VisionSurface`, `SurfaceInfo`, `SurfaceRegistry`, `createSurfaceRegistry`,
+  `PermissionPort`,
   `createVisionCameraPermissions`, `ArtifactStore`, `FileSystemBridge`,
   `StoreOptions`, `createCacheArtifactStore`, `createArtifactStore`
 - Mapping: `mapPointToImage`, `mapPointToPreview`, `mapRectToImage`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-camera",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -10,6 +10,11 @@
 			"types": "./src/index.ts",
 			"react-native": "./src/index.ts",
 			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
 		}
 	},
 	"files": [
@@ -29,9 +34,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

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

@@ -53,10 +53,28 @@ Runtime:
 - `CameraPreview` (+ `CameraPreviewProps`)
 - `CameraError`, `isCameraError`, `redact` — `redact` strips sensitive paths before logging
 - Testing: `createTestCamera`, `createMemoryFileSystem`, `DEFAULT_TEST_CAPABILITIES`
+- Conformance (`@chipmobilesdk/rn-camera/testing`): `runPermissionPortConformance`,
+  `runCameraEngineConformance` — run against any adapter you write or inject
 
-Types: `CameraEngine`, `EngineOptions`, `PermissionPort`, `ArtifactStore`,
-`FileSystemBridge`, `StoreOptions`, `CameraErrorCode`, `CameraLogEvent`,
-`CameraLogEventType`, `CameraLogger`
+Types: `CameraEngine`, `PermissionPort`, `ArtifactStore`, `FileSystemBridge`,
+`StoreOptions`, `VisionSurface`, `SurfaceInfo`, `SurfaceRegistry`,
+`CameraErrorCode`, `CameraLogEvent`, `CameraLogEventType`, `CameraLogger`
+
+## Three things the lifecycle guarantees
+
+- **`start()` resolves when frames arrive.** `capture()` straight after it works, and a
+  camera that never produces a frame fails the start (8 s by default) instead of leaving
+  the session in `starting`.
+- **`pause()` keeps the surface mounted** and stops the camera, so `resume()` is cheap.
+- **`capture({ cameraPosition })` must name the running camera.** A photo comes from the
+  device the preview mounted; asking for the other one is `notReady`. Switch with
+  `start({ cameraPosition })`.
+
+## Coordinate mapping waits for the surface
+
+`state.surface` is `null` until the preview reports its real format, and
+`onGeometryChange` fires again with those numbers. Map rectangles after it is set —
+before that the geometry is a nominal landscape 1920×1080.
 
 Always pass camera log payloads through `redact` before logging.
 

package/src/config/types.ts

@@ -21,6 +21,8 @@ export type FlashMode = 'auto' | 'on' | 'off';
 export type ResizeMode = 'cover' | 'contain';
 export type ArtifactOwnership = 'packageTemporary' | 'appOwned';
 
+import type { SurfaceInfo } from '../native/visionSurface';
+
 export type SessionStatus =
 	'idle' | 'starting' | 'active' | 'paused' | 'stopping' | 'stopped' | 'error';
 
@@ -129,6 +131,12 @@ export interface CameraState {
 	readonly flashMode: FlashMode;
 	readonly torchEnabled: boolean;
 	readonly capturing: boolean;
+	/**
+	 * What the mounted preview surface reported about itself: the capture
+	 * dimensions of the selected format, its orientation, and the position of
+	 * the device actually running. `null` until a surface reports (CAM-10).
+	 */
+	readonly surface: SurfaceInfo | null;
 	readonly error: CameraErrorLike | null;
 }
 

package/src/core/captureController.ts

@@ -67,6 +67,15 @@ export function assertCaptureAllowed(context: CaptureContext, request: CaptureRe
 
 	const position = request.cameraPosition ?? context.cameraPosition;
 	assertSupported(supportsPosition(context.capabilities, position), `${position} camera`);
+	if (position !== context.cameraPosition) {
+		// The photo would come from the camera that is running, while the
+		// metadata said it came from the one that was asked for (CAM-06).
+		throw new CameraError(
+			'notReady',
+			`The ${context.cameraPosition} camera is running. Call start({ cameraPosition: ` +
+				`'${position}' }) before capturing with the ${position} camera.`,
+		);
+	}
 }
 
 /**
@@ -83,7 +92,8 @@ export function finalizeResult(
 	return {
 		...raw,
 		ownership,
-		cameraPosition: raw.cameraPosition ?? request.cameraPosition ?? context.cameraPosition,
+		// The camera that took it, which the guard above has made the running one.
+		cameraPosition: raw.cameraPosition ?? context.cameraPosition,
 		timestamp: raw.timestamp ?? Date.now(),
 		effectiveQuality: raw.effectiveQuality ?? clampQuality(request.quality),
 		effectiveMaxDimension: raw.effectiveMaxDimension ?? clampMaxDimension(request.maxDimension),

package/src/core/contract.ts

@@ -0,0 +1,109 @@
+/**
+ * What a camera controller is, for the app that drives it.
+ *
+ * The contract lives apart from the orchestration in `controller.ts`: it is
+ * what a consumer reads, and what a test double has to satisfy, while the file
+ * next to it is how this package happens to satisfy it.
+ */
+
+import type {
+	CameraPermissionState,
+	CameraState,
+	CapabilityProfile,
+	CapturedImage,
+	CaptureRequest,
+	FlashMode,
+	StartOptions,
+} from '../config/types';
+import type { CameraError } from '../diagnostics/errors';
+import type { CameraLogger } from '../diagnostics/logger';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { SurfaceInfo, VisionSurface } from '../native/visionSurface';
+import type { PermissionPort } from '../permissions/permissionPort';
+import type { ArtifactStore } from '../storage/artifactStore';
+
+export const DEFAULT_TEMPORARY_TTL_MS = 24 * 60 * 60 * 1000;
+
+export type AppStatus = 'active' | 'background';
+
+export interface CameraControllerOptions {
+	/** Required. Use the default adapters, or `createTestCamera()` in tests. */
+	readonly engine: CameraEngine;
+	readonly permissions: PermissionPort;
+	readonly store?: ArtifactStore | undefined;
+	readonly logger?: CameraLogger | undefined;
+	readonly temporaryTtlMs?: number;
+	/**
+	 * App foreground/background source. Defaults to rn-core's shared `appLifecycle()`,
+	 * where `inactive` counts as background. Injectable so lifecycle rules are
+	 * testable without an app (FR-015).
+	 */
+	readonly subscribeToAppState?: (listener: (status: AppStatus) => void) => () => void;
+	/**
+	 * Set false to skip the sweep that runs when the controller is first used
+	 * (tests). Defaults to true.
+	 */
+	readonly sweepOnInit?: boolean;
+	/**
+	 * How long to wait for a preview surface to report frames before failing the
+	 * start (FR-014). Only applies to an engine whose session belongs to the
+	 * surface (`awaitsSurfaceStart`). Defaults to 8 s.
+	 */
+	readonly startTimeoutMs?: number;
+	/** Test seam for that timeout. */
+	readonly scheduler?: {
+		setTimeout(callback: () => void, ms: number): unknown;
+		clearTimeout(handle: unknown): void;
+	};
+}
+
+export interface CameraController {
+	readonly state: CameraState;
+	subscribe(listener: (state: CameraState) => void): () => void;
+
+	getPermission(): Promise<CameraPermissionState>;
+	requestPermission(): Promise<CameraPermissionState>;
+
+	start(options?: StartOptions): Promise<void>;
+	pause(): Promise<void>;
+	resume(): Promise<void>;
+	stop(): Promise<void>;
+
+	capture(request?: CaptureRequest): Promise<CapturedImage>;
+	cleanup(image: CapturedImage | string): Promise<void>;
+
+	getCapabilities(): Promise<CapabilityProfile>;
+	setFlashMode(mode: FlashMode): void;
+	setTorch(enabled: boolean): Promise<void>;
+
+	/** Marks the preview surface mounted, enabling foreground auto-restart. */
+	setSurfaceMounted(mounted: boolean): void;
+	/**
+	 * Attaches the mounted preview surface to the engine, for an engine that
+	 * captures through it. Returns the detach function; a no-op for engines that
+	 * own their own session.
+	 */
+	attachSurface(surface: VisionSurface): () => void;
+	/**
+	 * The preview reported frames: the session is active for real, not merely
+	 * requested (CAM-08). What the surface turned out to be — the format's pixel
+	 * size, the orientation, the device's own position — is published as
+	 * `state.surface` for coordinate mapping.
+	 */
+	reportSurfaceStarted(info: SurfaceInfo): void;
+	/** The preview's own session failed, or the OS took the camera away. */
+	reportSurfaceFailed(code: CameraError['code']): void;
+	/**
+	 * Called by `CameraPreview` when the native preview surface cannot load (the
+	 * VisionCamera module is missing or unlinked). Fails the session with
+	 * `cameraUnavailable` rather than leaving a black preview and no error.
+	 */
+	reportSurfaceUnavailable(): void;
+	/**
+	 * Releases ports, listeners, and the camera. Safe to call twice. Afterwards
+	 * `start`, `resume`, `capture` and the permission and capability reads reject
+	 * with `notReady`; `stop`, `pause` and `cleanup` stay safe no-ops so teardown
+	 * code never has to check.
+	 */
+	dispose(): Promise<void>;
+}