@chipmobilesdk/rn-camera 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,157 @@
 # @chipmobilesdk/rn-camera
 
+## 0.5.0
+
+### Minor Changes
+
+- The test adapter is only at `@chipmobilesdk/rn-camera/testing`. `createTestCamera`,
+  `createMemoryFileSystem`, `DEFAULT_TEST_CAPABILITIES` and their configuration and handle
+  types are gone from the main entrypoint, which had re-exported them since FR-041. That
+  re-export put the fake camera in the module graph of every app that imported the
+  package, and Metro does not tree-shake it back out, so a production bundle shipped a
+  camera nobody could use (PERF-14, TOOL-09). ([#21](https://github.com/operationd8979/chip-mobile-sdk/pull/21))
+
+  **Migration:** one line in a test — `from '@chipmobilesdk/rn-camera'` becomes
+  `from '@chipmobilesdk/rn-camera/testing'`. The subpath has existed since 0.3.0 and the
+  exports are identical; nothing about the adapter itself changed. The README said the
+  main entrypoint would keep them "until the next major release": this is that move,
+  brought forward into a minor because the package is pre-1.0 and the cost was a bundle,
+  not an API.
+
+  The layer table's exception for `index.ts` importing `./testing/testCameraAdapter` is
+  gone with it, so the `sdk/boundaries` rule now holds the same line here as everywhere
+  else: test doubles stay out of production code, and the package's own contract test
+  reaches the adapter the way a consumer's test does.
+
+- Every package now ships built JavaScript with declaration files, instead of asking the
+  app to compile its TypeScript. ([#22](https://github.com/operationd8979/chip-mobile-sdk/pull/22))
+
+  Each tarball carries `lib/commonjs`, `lib/module` and `lib/typescript` (built with
+  `react-native-builder-bob`), and `src/` alongside them. What that changes for a
+  consumer:
+
+  - **Nothing to add to `transformIgnorePatterns`.** `require` resolves to the CommonJS
+    build, so an app's Jest loads this package without being told to transform it. That
+    was the one thing every consuming app had to know about us (DEP-04).
+  - **Typechecking reads our `.d.ts`** rather than compiling our source under our
+    `tsconfig`. A consumer's stricter — or looser — settings no longer meet our code.
+  - **`import` resolves to ESM**, so a bundler can tree-shake what it does not use.
+
+  No exported name changed, and no subpath moved: `.`, `./testing`, `./push`,
+  `./advanced`, `./app-auth`, `./keychain` and rn-core's twelve subpaths resolve exactly
+  as before, each now with its own declarations for both module systems. publint and
+  `attw --profile node16` pass on all twelve packages, which they could not before.
+
+  Inside the monorepo nothing changed either, and that is deliberate: every subpath also
+  declares a private `chipmobilesdk-source` condition pointing at its TypeScript, and
+  Metro, Jest and `tsc` here ask for that condition first. The demo app bundles 371
+  modules straight from `packages/*/src`, so editing a package still changes the app with
+  no build step, and coverage is still measured on the source. The condition is named for
+  this organization rather than using the conventional `source` because third-party
+  packages declare that one too — `@dr.pogodin/react-native-fs` does — and asking for it
+  pulled their sources into our stricter compile.
+
+  `npm run build:packages` builds everything, `prepack` rebuilds before any `npm pack`,
+  and `lib/` is git-ignored: the published bytes are produced by the release, never
+  committed. `npm run check:manifests` now fails a package whose `main`, `module`,
+  `types`, `source` condition, `files`, build script or `prepack` do not match this shape.
+
+### Patch Changes
+
+- Every peer range has an upper bound, and no package declares a peer it does not use. ([#21](https://github.com/operationd8979/chip-mobile-sdk/pull/21))
+
+  A peer range is now a caret, a tilde or an explicit `<`, except for `react` and
+  `react-native`: an app brings exactly one of each, so a floor is the only useful thing
+  to say about them. Every other peer is a library the app installs beside us, and an
+  open `>=` was a promise about versions nobody had run — mmkv 3→4 lost entitlements and
+  pending purchases exactly that way.
+
+  **Four of the new ceilings exclude a version that is already published**, so an app
+  that took the open range at its word may now see a peer warning. The new bound is the
+  major this release is tested against, which is the thing the old range failed to say:
+
+  | Peer | Was | Now | Published above the ceiling |
+  |---|---|---|---|
+  | `react-native-app-auth` (rn-auth) | `>=8` | `^8.0.0` | 9.0.0 |
+  | `react-native-keychain` (rn-auth) | `>=10` | `^10.0.0` | 11.0.0 |
+  | `@op-engineering/op-sqlite` (rn-local-db) | `>=17.1.0` | `^17.1.0` | 18.x, 19.x |
+  | `@react-native-firebase/messaging` (rn-notification) | `>=26.0.0` | `^26.0.0` | 27.x |
+
+  The others — `react-native-vision-camera` `^5.1.1`, `react-native-svg` `^15.15.0`,
+  `react-native-unistyles` `^3.2.0`, `@dr.pogodin/react-native-fs` `^2.39.2`,
+  `react-native-quick-crypto` `^1.0.0`, `react-native-notify-kit` `^10.5.0`,
+  `react-native-localize` `^3.7.0`, `react-native-mmkv` `^4.0.0` — exclude nothing that
+  exists today. rn-payment's mmkv range was already bounded (`>=4.0.0 <5`) and is now
+  written as the caret that means the same thing.
+
+  Peers nothing imports are gone. `rn-theme`, `rn-local-db` and `rn-notification` asked
+  for `react` without having a component or a hook between them; `rn-auth`, `rn-ai` and
+  `rn-i18n` asked for `react-native` without touching a React Native API (rn-auth reaches
+  both native modules through `lazyPeer`, rn-i18n formats on `Intl`); `rn-notification`
+  asked for `@react-native-firebase/app`, which messaging declares itself. `rn-ai` no
+  longer peers on `@chipmobilesdk/rn-auth` at all — it asks for a `TokenProvider`, a
+  two-method interface rn-auth's `auth` satisfies, so an app with its own token source
+  installs nothing extra. An app that enables push or signs in through rn-auth installs
+  the same packages as before; it is the manifest that stopped overstating.
+
+  `react-native-localize` is declared optional, which is what the code already did: the
+  time-zone reader goes through `lazyPeer` and falls back to `Intl` without it. The
+  `peerDependenciesMeta` entries that said `optional: false` are gone — that is npm's
+  default, and writing it down only invited the question of which peers were undecided.
+
+  `npm run check:manifests` now fails on an unbounded peer range, a peer nothing in
+  `src/` imports, and a `peerDependenciesMeta` entry for either, so the policy holds
+  without anyone remembering it.
+
+- Each package's public API and its weight are now recorded in the repository, so a change
+  to either is reviewed rather than discovered. ([#23](https://github.com/operationd8979/chip-mobile-sdk/pull/23))
+
+  `packages/<pkg>/etc/*.api.md` is an api-extractor report per entrypoint — twenty-seven
+  of them, generated from the declarations the package publishes and committed. A renamed
+  type, a widened union, one more optional field: all of it shows up in a pull request's
+  diff. `npm run check:api` fails when a report is out of date and `npm run api:update`
+  rewrites them.
+
+  A report that moves now needs a **minor or major** changeset for that package.
+  `check:changesets` enforces it, because the report is generated from what the package
+  publishes, and a patch release that moves the public surface is how a consumer's build
+  breaks on `npm update`. A report added for the first time is a baseline, not a change.
+  `./testing` deliberately has no report: test doubles are not a surface a release is
+  gated on.
+
+  `npm run check:size` holds every entrypoint to a budget in `.size-limit.json`, measured
+  on the ESM build with peers and rn-core treated as external — they are what an app
+  installs beside us, not our weight. Each budget started at today's measurement plus five
+  per cent, so growth becomes a decision someone makes instead of a drift nobody sees. The
+  current figures run from 500 B (`rn-core/lazy`) to 19 kB (rn-notification).
+
+  No behaviour or API changed in this release; the entry is here so the changelog records
+  when the reports and the budgets began.
+- Updated dependencies ([#22](https://github.com/operationd8979/chip-mobile-sdk/pull/22), [#23](https://github.com/operationd8979/chip-mobile-sdk/pull/23)):
+  - @chipmobilesdk/rn-core@0.2.0
+
+## 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

package/README.md

@@ -19,7 +19,7 @@ The package is **infrastructure, not a feature**. It contains no business logic,
 | React Native | >= 0.85 |
 | Android | `minSdkVersion` **24**, `targetSdkVersion` 36 |
 | iOS | 15.1+ |
-| `react-native-vision-camera` | 5.1.x |
+| `react-native-vision-camera` | `^5.1.1` |
 
 > **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.
 
@@ -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
 
@@ -232,7 +260,8 @@ or quality is required.
 `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';
+import { createCameraController } from '@chipmobilesdk/rn-camera';
+import { createTestCamera } from '@chipmobilesdk/rn-camera/testing';
 
 const camera = createTestCamera({ permission: 'granted' });
 const controller = createCameraController({
@@ -277,9 +306,11 @@ expectConformance(
 );
 ```
 
-`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.
+`createTestCamera` and its helpers live at `@chipmobilesdk/rn-camera/testing`, and only
+there as of 0.4.0 — on the main entrypoint the fake camera joined the module graph of
+every app that imported the package, which Metro does not tree-shake back out. A test
+that imported it from `@chipmobilesdk/rn-camera` changes that one line and nothing else.
+`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:
 
@@ -359,16 +390,18 @@ Everything is exported from `@chipmobilesdk/rn-camera`, test doubles and conform
   `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`,
   `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
+- Testing, from `@chipmobilesdk/rn-camera/testing` rather than the main entrypoint:
+  `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.

package/lib/commonjs/config/types.js

@@ -0,0 +1,54 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.known = known;
+exports.unavailable = unavailable;
+/**
+ * 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). */
+
+/**
+ * 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".
+ */
+
+function known(value) {
+  return {
+    available: true,
+    value
+  };
+}
+function unavailable() {
+  return {
+    available: false
+  };
+}
+
+/** What this device and platform actually support (FR-033). */
+
+/** Instruction to take one still photo. Carries no business context (FR-002). */
+
+/** Result of one successful capture. Always a file reference (FR-021/FR-021a). */
+
+/** Options accepted when starting a session. */
+
+/**
+ * Relationship between captured-image space and on-screen preview space.
+ * Consumed by the pure mapping functions in `geometry/coordinateMapping`.
+ */
+
+/** Aggregate observable state exposed by the controller. */
+
+/**
+ * Structural view of a CameraError, kept here so `CameraState` does not create
+ * a circular import with the diagnostics module.
+ */
+//# sourceMappingURL=types.js.map

package/lib/commonjs/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["known","value","available","unavailable"],"sourceRoot":"../../../src","sources":["config/types.ts"],"mappings":";;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAoBA;AACA;AACA;AACA;;AAYO,SAASA,KAAKA,CAAIC,KAAQ,EAAY;EAC5C,OAAO;IAAEC,SAAS,EAAE,IAAI;IAAED;EAAM,CAAC;AAClC;AAEO,SAASE,WAAWA,CAAA,EAAgB;EAC1C,OAAO;IAAED,SAAS,EAAE;EAAM,CAAC;AAC5B;;AAEA;;AASA;;AAgBA;;AAgBA;;AAKA;AACA;AACA;AACA;;AAwBA;;AAkBA;AACA;AACA;AACA","ignoreList":[]}

package/lib/commonjs/core/capabilities.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EMPTY_CAPABILITIES = void 0;
+exports.assertSupported = assertSupported;
+exports.supportsFlashMode = supportsFlashMode;
+exports.supportsPosition = supportsPosition;
+exports.supportsTorch = supportsTorch;
+var _errors = require("../diagnostics/errors.js");
+/**
+ * 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.
+ */
+
+const EMPTY_CAPABILITIES = exports.EMPTY_CAPABILITIES = {
+  availablePositions: [],
+  hasFlash: false,
+  hasTorch: false,
+  supportsOrientationChange: false,
+  hasCameraHardware: false
+};
+function supportsPosition(profile, position) {
+  return profile?.availablePositions.includes(position) ?? false;
+}
+
+/** `off` is always legal — it is the absence of flash, not a use of it. */
+function supportsFlashMode(profile, mode) {
+  return mode === 'off' ? true : profile?.hasFlash === true;
+}
+function supportsTorch(profile) {
+  return profile?.hasTorch === true;
+}
+
+/** Throws the uniform unsupported error so every gate reads the same way. */
+function assertSupported(supported, what) {
+  if (!supported) {
+    throw new _errors.CameraError('unsupportedCapability', `Not supported on this device: ${what}`);
+  }
+}
+//# sourceMappingURL=capabilities.js.map

package/lib/commonjs/core/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","EMPTY_CAPABILITIES","exports","availablePositions","hasFlash","hasTorch","supportsOrientationChange","hasCameraHardware","supportsPosition","profile","position","includes","supportsFlashMode","mode","supportsTorch","assertSupported","supported","what","CameraError"],"sourceRoot":"../../../src","sources":["core/capabilities.ts"],"mappings":";;;;;;;;;;AASA,IAAAA,OAAA,GAAAC,OAAA;AATA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKO,MAAMC,kBAAqC,GAAAC,OAAA,CAAAD,kBAAA,GAAG;EACpDE,kBAAkB,EAAE,EAAE;EACtBC,QAAQ,EAAE,KAAK;EACfC,QAAQ,EAAE,KAAK;EACfC,yBAAyB,EAAE,KAAK;EAChCC,iBAAiB,EAAE;AACpB,CAAC;AAEM,SAASC,gBAAgBA,CAC/BC,OAAiC,EACjCC,QAAwB,EACd;EACV,OAAOD,OAAO,EAAEN,kBAAkB,CAACQ,QAAQ,CAACD,QAAQ,CAAC,IAAI,KAAK;AAC/D;;AAEA;AACO,SAASE,iBAAiBA,CAACH,OAAiC,EAAEI,IAAe,EAAW;EAC9F,OAAOA,IAAI,KAAK,KAAK,GAAG,IAAI,GAAGJ,OAAO,EAAEL,QAAQ,KAAK,IAAI;AAC1D;AAEO,SAASU,aAAaA,CAACL,OAAiC,EAAW;EACzE,OAAOA,OAAO,EAAEJ,QAAQ,KAAK,IAAI;AAClC;;AAEA;AACO,SAASU,eAAeA,CAACC,SAAkB,EAAEC,IAAY,EAAQ;EACvE,IAAI,CAACD,SAAS,EAAE;IACf,MAAM,IAAIE,mBAAW,CAAC,uBAAuB,EAAE,iCAAiCD,IAAI,EAAE,CAAC;EACxF;AACD","ignoreList":[]}

package/lib/commonjs/core/captureController.js

@@ -0,0 +1,107 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SingleFlight = exports.DEFAULT_QUALITY = void 0;
+exports.assertCaptureAllowed = assertCaptureAllowed;
+exports.clampMaxDimension = clampMaxDimension;
+exports.clampQuality = clampQuality;
+exports.finalizeResult = finalizeResult;
+var _types = require("../config/types.js");
+var _errors = require("../diagnostics/errors.js");
+var _capabilities = require("./capabilities.js");
+var _sessionMachine = require("./sessionMachine.js");
+/**
+ * Capture guards, single-flight enforcement, and metadata assembly
+ * (FR-020..FR-026b).
+ *
+ * The single-flight guard rejects rather than queues or coalesces. A queue
+ * turns a double-tapped shutter into two photos the user never asked for, and
+ * coalescing hides a deliberate second capture behind an accidental one — so a
+ * fast, explicit `captureInProgress` error is the only option that lets the app
+ * decide (clarification session 2026-07-26).
+ */
+
+const DEFAULT_QUALITY = exports.DEFAULT_QUALITY = 0.9;
+function clampQuality(quality) {
+  if (quality === undefined || Number.isNaN(quality)) {
+    return DEFAULT_QUALITY;
+  }
+  return Math.min(1, Math.max(0, quality));
+}
+function clampMaxDimension(maxDimension) {
+  if (maxDimension === undefined || !Number.isFinite(maxDimension) || maxDimension <= 0) {
+    return (0, _types.unavailable)();
+  }
+  return (0, _types.known)(Math.floor(maxDimension));
+}
+/**
+ * Validates a capture request against permission, readiness, and capability.
+ * Throws before any artifact could be created, so a rejected capture never
+ * leaves a file behind (FR-020).
+ */
+function assertCaptureAllowed(context, request) {
+  if (!context.permissionGranted) {
+    throw new _errors.CameraError('permissionDenied', 'Camera permission is not granted');
+  }
+  if (!(0, _sessionMachine.canCapture)(context.sessionStatus)) {
+    throw new _errors.CameraError('notReady', `Camera is not ready (session: ${context.sessionStatus})`);
+  }
+  const flashMode = request.flashMode ?? context.flashMode;
+  (0, _capabilities.assertSupported)((0, _capabilities.supportsFlashMode)(context.capabilities, flashMode), `flash mode "${flashMode}"`);
+  const position = request.cameraPosition ?? context.cameraPosition;
+  (0, _capabilities.assertSupported)((0, _capabilities.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 _errors.CameraError('notReady', `The ${context.cameraPosition} camera is running. Call start({ cameraPosition: ` + `'${position}' }) before capturing with the ${position} camera.`);
+  }
+}
+
+/**
+ * Normalizes whatever the engine returned into the published contract, filling
+ * in effective hint values and marking undeterminable fields explicitly
+ * unavailable rather than guessing them (FR-022, FR-023).
+ */
+function finalizeResult(raw, request, context) {
+  const ownership = request.destination ? 'appOwned' : 'packageTemporary';
+  return {
+    ...raw,
+    ownership,
+    // 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),
+    fileSize: raw.fileSize ?? (0, _types.unavailable)(),
+    orientation: raw.orientation ?? (0, _types.unavailable)()
+  };
+}
+
+/**
+ * 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.
+ */
+class SingleFlight {
+  active = false;
+  get busy() {
+    return this.active;
+  }
+  async run(operation) {
+    if (this.active) {
+      throw new _errors.CameraError('captureInProgress', 'A capture is already in progress');
+    }
+    this.active = true;
+    try {
+      return await operation();
+    } finally {
+      this.active = false;
+    }
+  }
+}
+exports.SingleFlight = SingleFlight;
+//# sourceMappingURL=captureController.js.map

package/lib/commonjs/core/captureController.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_types","require","_errors","_capabilities","_sessionMachine","DEFAULT_QUALITY","exports","clampQuality","quality","undefined","Number","isNaN","Math","min","max","clampMaxDimension","maxDimension","isFinite","unavailable","known","floor","assertCaptureAllowed","context","request","permissionGranted","CameraError","canCapture","sessionStatus","flashMode","assertSupported","supportsFlashMode","capabilities","position","cameraPosition","supportsPosition","finalizeResult","raw","ownership","destination","timestamp","Date","now","effectiveQuality","effectiveMaxDimension","fileSize","orientation","SingleFlight","active","busy","run","operation"],"sourceRoot":"../../../src","sources":["core/captureController.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/core/contract.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DEFAULT_TEMPORARY_TTL_MS = void 0;
+/**
+ * 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.
+ */
+
+const DEFAULT_TEMPORARY_TTL_MS = exports.DEFAULT_TEMPORARY_TTL_MS = 24 * 60 * 60 * 1000;
+//# sourceMappingURL=contract.js.map

package/lib/commonjs/core/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_TEMPORARY_TTL_MS","exports"],"sourceRoot":"../../../src","sources":["core/contract.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAkBO,MAAMA,wBAAwB,GAAAC,OAAA,CAAAD,wBAAA,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI","ignoreList":[]}