@chipmobilesdk/rn-camera 0.4.0 → 0.5.0

package/lib/typescript/commonjs/storage/artifactStore.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ArtifactStore port + default cache-directory adapter (FR-026..FR-029).
+ *
+ * Package-owned artifacts live in a dedicated `rn-camera` subdirectory of the
+ * platform cache directory (research R6). That dedicated prefix is what makes
+ * ownership checkable rather than advisory: `owns()` is a path-prefix test, so
+ * the package can refuse to delete anything it did not create (FR-028).
+ */
+export interface ArtifactStore {
+    /** Absolute path of the package-owned temporary directory. */
+    temporaryDirectory(): string;
+    /** True only for paths the package created (FR-028). */
+    owns(uri: string): boolean;
+    /** Deletes an artifact. Resolves even if already gone (FR-027). */
+    remove(uri: string): Promise<void>;
+    /** Deletes owned artifacts older than `olderThanMs`; returns the count. */
+    sweep(olderThanMs: number): Promise<number>;
+    /**
+     * Brings a fresh capture under the store and returns its managed URI: a file
+     * already inside the store is recorded as created by this process, a file
+     * anywhere else is moved in. Without this, a capture the engine wrote to its
+     * own temporary directory is never owned, so `cleanup()` refuses it and the
+     * sweep never sees it. Optional so app-written stores keep compiling.
+     */
+    adopt?(uri: string): Promise<string>;
+}
+/** Minimal filesystem surface the adapter needs. Injectable for tests. */
+export interface FileSystemBridge {
+    cacheDirectory(): string;
+    exists(path: string): Promise<boolean>;
+    unlink(path: string): Promise<void>;
+    list(directory: string): Promise<readonly string[]>;
+    createdAt(path: string): Promise<number>;
+    ensureDirectory(directory: string): Promise<void>;
+    /**
+     * Moves a file. Needed by `adopt()` to pull a capture out of the engine's own
+     * temporary directory; a bridge without it can only adopt files already
+     * inside the store.
+     */
+    move?(from: string, to: string): Promise<void>;
+}
+export interface StoreOptions {
+    readonly fs?: FileSystemBridge;
+    /** Directory name under the cache directory. Defaults to `rn-camera`. */
+    readonly directoryName?: string;
+}
+export declare function createArtifactStore(fs: FileSystemBridge, directoryName?: string): ArtifactStore;
+/**
+ * Default adapter. The concrete filesystem bridge is supplied by the native
+ * layer at runtime; it is a parameter rather than a hard import so the package
+ * takes no filesystem dependency of its own.
+ */
+export declare function createCacheArtifactStore(options?: StoreOptions): ArtifactStore;
+//# sourceMappingURL=artifactStore.d.ts.map

package/lib/typescript/commonjs/storage/artifactStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactStore.d.ts","sourceRoot":"","sources":["../../../../src/storage/artifactStore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,aAAa;IAC7B,8DAA8D;IAC9D,kBAAkB,IAAI,MAAM,CAAC;IAC7B,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,mEAAmE;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,2EAA2E;IAC3E,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAChC,cAAc,IAAI,MAAM,CAAC;IACzB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IACpD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;;;OAIG;IACH,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAChC;AAOD,wBAAgB,mBAAmB,CAClC,EAAE,EAAE,gBAAgB,EACpB,aAAa,SAAc,GACzB,aAAa,CAqEf;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,YAAiB,GAAG,aAAa,CAWlF"}

package/lib/typescript/commonjs/testing/conformance.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What any `PermissionPort` and `CameraEngine` must do (IOS-12, CAM-13).
+ *
+ * The same checks run against the in-memory test adapter and against the real
+ * VisionCamera adapters (native module mocked in Jest, or for real on a device),
+ * so the fake the app's tests rely on cannot drift from the adapter it stands in
+ * for. Each check builds its own port from a harness, under the conditions it
+ * needs.
+ */
+import { type Check, type ConformanceReport } from '@chipmobilesdk/rn-core/testing';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+export type SystemPermission = 'undetermined' | 'granted' | 'deniedPermanently';
+export interface PermissionHarness {
+    /** A port over a system whose permission starts in `initial`. */
+    create(initial: SystemPermission): {
+        readonly port: PermissionPort;
+        /** Changes the system permission, as Settings would. */
+        setSystemState(state: SystemPermission): void;
+        /** How many times the system prompt was shown. */
+        prompts(): number;
+    };
+}
+export interface CameraDeviceSpec {
+    readonly position: 'front' | 'back';
+    readonly hasFlash?: boolean;
+    readonly hasTorch?: boolean;
+}
+export interface EngineHarness {
+    /** An engine on a device with these cameras. */
+    create(devices: readonly CameraDeviceSpec[]): CameraEngine;
+}
+export declare const permissionPortChecks: readonly Check<PermissionHarness>[];
+export declare const cameraEngineChecks: readonly Check<EngineHarness>[];
+export declare function runPermissionPortConformance(harness: PermissionHarness): Promise<ConformanceReport>;
+export declare function runCameraEngineConformance(harness: EngineHarness): Promise<ConformanceReport>;
+//# sourceMappingURL=conformance.d.ts.map

package/lib/typescript/commonjs/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../../src/testing/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAGN,KAAK,KAAK,EACV,KAAK,iBAAiB,EACtB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,SAAS,GAAG,mBAAmB,CAAC;AAEhF,MAAM,WAAW,iBAAiB;IACjC,iEAAiE;IACjE,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG;QAClC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;QAC9B,wDAAwD;QACxD,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAC9C,kDAAkD;QAClD,OAAO,IAAI,MAAM,CAAC;KAClB,CAAC;CACF;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC7B,gDAAgD;IAChD,MAAM,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,YAAY,CAAC;CAC3D;AAED,eAAO,MAAM,oBAAoB,EAAE,SAAS,KAAK,CAAC,iBAAiB,CAAC,EA2CnE,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,SAAS,KAAK,CAAC,aAAa,CAAC,EAwC7D,CAAC;AAEF,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE7F"}

package/lib/typescript/commonjs/testing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@chipmobilesdk/rn-camera/testing`: test doubles and the port conformance suites.
+ *
+ * A separate entrypoint so the suites cannot reach a production bundle. The test
+ * adapter is also exported from the main entrypoint for compatibility; it leaves
+ * there only in a major release.
+ */
+export { createTestCamera, createMemoryFileSystem, DEFAULT_TEST_CAPABILITIES, } from './testCameraAdapter';
+export type { MemoryFileSystem, TestCameraConfig, TestCameraHandles } from './testCameraAdapter';
+export { cameraEngineChecks, permissionPortChecks, runCameraEngineConformance, runPermissionPortConformance, } from './conformance';
+export type { CameraDeviceSpec, EngineHarness, PermissionHarness, SystemPermission, } from './conformance';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,gBAAgB,EAChB,sBAAsB,EACtB,yBAAyB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,4BAA4B,GAC5B,MAAM,eAAe,CAAC;AACvB,YAAY,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,eAAe,CAAC"}

package/lib/typescript/commonjs/testing/testCameraAdapter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Deterministic in-memory camera for tests (FR-041, SC-010).
+ *
+ * These are real implementations of the same published ports the production
+ * adapters implement, not a parallel mock — so a contract change breaks them at
+ * compile time and they cannot drift. Nothing here touches a native module, the
+ * filesystem, or a permission API.
+ */
+import { type CameraPermissionState, type CapabilityProfile, type CapturedImage } from '../config/types';
+import { type CameraErrorCode } from '../diagnostics/errors';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+import { type ArtifactStore, type FileSystemBridge } from '../storage/artifactStore';
+import type { AppStatus } from '../core/controller';
+export interface MemoryFileSystem extends FileSystemBridge {
+    /** Seeds a file with an explicit creation time, for time-to-live tests. */
+    seed(path: string, createdAtMs: number): void;
+    /** Every path currently present. */
+    paths(): readonly string[];
+}
+export declare function createMemoryFileSystem(root?: string): MemoryFileSystem;
+export declare const DEFAULT_TEST_CAPABILITIES: CapabilityProfile;
+export interface TestCameraConfig {
+    readonly permission?: CameraPermissionState;
+    readonly capabilities?: Partial<CapabilityProfile>;
+    readonly captureResult?: Partial<CapturedImage>;
+    readonly captureError?: CameraErrorCode;
+    readonly startError?: CameraErrorCode;
+    readonly cacheRoot?: string;
+}
+export interface TestCameraHandles {
+    readonly engine: CameraEngine;
+    readonly permissions: PermissionPort;
+    readonly store: ArtifactStore;
+    readonly fs: MemoryFileSystem;
+    /** Drives the controller's app foreground/background handling. */
+    subscribeToAppState(listener: (status: AppStatus) => void): () => void;
+    setAppState(status: AppStatus): void;
+    /** Simulates a Settings-level permission change while running (FR-007). */
+    setPermission(state: CameraPermissionState): void;
+    /**
+     * Simulates the OS taking the camera away: an incoming call, another app,
+     * a disconnected device. A live session tears down with that code, exactly
+     * as the device adapter reports it (CAM-19), and the next start fails until
+     * `setStartError(null)` clears it.
+     */
+    emitInterruption(code?: CameraErrorCode): void;
+    /** Simulates the preview failing to produce frames. */
+    emitPermissionRequestFailure(enabled: boolean): void;
+    setCaptureError(code: CameraErrorCode | null): void;
+    setStartError(code: CameraErrorCode | null): void;
+    /** How many times `request` showed the system prompt. */
+    prompts(): number;
+    /** Every capture the engine produced, in order. */
+    captures(): readonly CapturedImage[];
+    torchState(): boolean;
+    startCount(): number;
+    stopCount(): number;
+}
+export declare function createTestCamera(config?: TestCameraConfig): TestCameraHandles;
+//# sourceMappingURL=testCameraAdapter.d.ts.map

package/lib/typescript/commonjs/testing/testCameraAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testCameraAdapter.d.ts","sourceRoot":"","sources":["../../../../src/testing/testCameraAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAGN,KAAK,qBAAqB,EAE1B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAEN,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGpD,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACzD,2EAA2E;IAC3E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,oCAAoC;IACpC,KAAK,IAAI,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,wBAAgB,sBAAsB,CAAC,IAAI,SAAW,GAAG,gBAAgB,CAkCxE;AAED,eAAO,MAAM,yBAAyB,EAAE,iBAMvC,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACnD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,kEAAkE;IAClE,mBAAmB,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvE,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACrC,2EAA2E;IAC3E,aAAa,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAClD;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/C,uDAAuD;IACvD,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACrD,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IACpD,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IAClD,yDAAyD;IACzD,OAAO,IAAI,MAAM,CAAC;IAClB,mDAAmD;IACnD,QAAQ,IAAI,SAAS,aAAa,EAAE,CAAC;IACrC,UAAU,IAAI,OAAO,CAAC;IACtB,UAAU,IAAI,MAAM,CAAC;IACrB,SAAS,IAAI,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,gBAAqB,GAAG,iBAAiB,CAkJjF"}

package/lib/typescript/module/config/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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';
+import type { SurfaceInfo } from '../native/visionSurface.js';
+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 declare function known<T>(value: T): Known<T>;
+export declare function unavailable(): Unavailable;
+/** 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;
+    /**
+     * 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;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/config/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/core/capabilities.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.js';
+export declare const EMPTY_CAPABILITIES: CapabilityProfile;
+export declare function supportsPosition(profile: CapabilityProfile | null, position: CameraPosition): boolean;
+/** `off` is always legal — it is the absence of flash, not a use of it. */
+export declare function supportsFlashMode(profile: CapabilityProfile | null, mode: FlashMode): boolean;
+export declare function supportsTorch(profile: CapabilityProfile | null): boolean;
+/** Throws the uniform unsupported error so every gate reads the same way. */
+export declare function assertSupported(supported: boolean, what: string): void;
+//# sourceMappingURL=capabilities.d.ts.map

package/lib/typescript/module/core/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../../src/core/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,oBAAiB,CAAC;AAGpF,eAAO,MAAM,kBAAkB,EAAE,iBAMhC,CAAC;AAEF,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,iBAAiB,GAAG,IAAI,EACjC,QAAQ,EAAE,cAAc,GACtB,OAAO,CAET;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAE7F;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAExE;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAItE"}

package/lib/typescript/module/core/captureController.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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).
+ */
+import { type CameraPosition, type CapabilityProfile, type CapturedImage, type CaptureRequest, type FlashMode, type Maybe, type SessionStatus } from '../config/types.js';
+import type { CameraEngine } from '../native/cameraEngine.js';
+export declare const DEFAULT_QUALITY = 0.9;
+export declare function clampQuality(quality: number | undefined): number;
+export declare function clampMaxDimension(maxDimension: number | undefined): Maybe<number>;
+export interface CaptureContext {
+    readonly engine: CameraEngine;
+    readonly sessionStatus: SessionStatus;
+    readonly permissionGranted: boolean;
+    readonly capabilities: CapabilityProfile | null;
+    readonly cameraPosition: CameraPosition;
+    readonly flashMode: FlashMode;
+}
+/**
+ * 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).
+ */
+export declare function assertCaptureAllowed(context: CaptureContext, request: CaptureRequest): void;
+/**
+ * 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).
+ */
+export declare function finalizeResult(raw: CapturedImage, request: CaptureRequest, context: CaptureContext): CapturedImage;
+/**
+ * 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 declare class SingleFlight {
+    private active;
+    get busy(): boolean;
+    run(operation: () => Promise<CapturedImage>): Promise<CapturedImage>;
+}
+//# sourceMappingURL=captureController.d.ts.map

package/lib/typescript/module/core/captureController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureController.d.ts","sourceRoot":"","sources":["../../../../src/core/captureController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,MAAM,oBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAAwB,CAAC;AAI3D,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKhE;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAKjF;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAqB3F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,cAAc,GACrB,aAAa,CAaf;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAS;IAEvB,IAAI,IAAI,IAAI,OAAO,CAElB;IAEK,GAAG,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;CAW1E"}

package/lib/typescript/module/core/contract.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.js';
+import type { CameraError } from '../diagnostics/errors.js';
+import type { CameraLogger } from '../diagnostics/logger.js';
+import type { CameraEngine } from '../native/cameraEngine.js';
+import type { SurfaceInfo, VisionSurface } from '../native/visionSurface.js';
+import type { PermissionPort } from '../permissions/permissionPort.js';
+import type { ArtifactStore } from '../storage/artifactStore.js';
+export declare const DEFAULT_TEMPORARY_TTL_MS: number;
+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>;
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/typescript/module/core/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../../src/core/contract.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/core/controller.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Camera controller — the object consuming apps actually drive.
+ *
+ * It owns observable state and orchestrates the three ports (engine,
+ * permissions, artifact store). All I/O lives here; the decisions live in
+ * `sessionMachine` and `captureController`, which stay pure so they can be
+ * tested without a camera.
+ */
+import { type CameraController, type CameraControllerOptions } from './contract.js';
+/** 24 hours (FR-029). */
+export { DEFAULT_TEMPORARY_TTL_MS, type AppStatus, type CameraController, type CameraControllerOptions, } from './contract.js';
+/** 8 s: a cold camera on a slow device, with room to spare (PERF-001 is 1.5 s). */
+export declare const DEFAULT_START_TIMEOUT_MS = 8000;
+export declare function createCameraController(options: CameraControllerOptions): CameraController;
+//# sourceMappingURL=controller.d.ts.map

package/lib/typescript/module/core/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../../src/core/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,OAAO,EAGN,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,MAAM,eAAY,CAAC;AAYpB,yBAAyB;AACzB,OAAO,EACN,wBAAwB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC5B,MAAM,eAAY,CAAC;AAQpB,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CA2ZzF"}

package/lib/typescript/module/core/sessionMachine.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Session lifecycle state machine (FR-014..FR-019).
+ *
+ * Pure and synchronous: it decides what a transition means, the controller
+ * performs the I/O. That split is what makes every lifecycle rule in
+ * `data-model.md` section 2 testable without a camera.
+ *
+ * Backgrounding STOPS rather than pauses. Both operating systems can reclaim
+ * the camera anyway, and holding it risks leaving the OS camera indicator lit
+ * after the app is no longer in front of the user (FR-015).
+ */
+import type { SessionStatus } from '../config/types.js';
+import { CameraError, type CameraErrorCode } from '../diagnostics/errors.js';
+export type SessionEvent = {
+    readonly type: 'START';
+} | {
+    readonly type: 'STARTED';
+} | {
+    readonly type: 'PAUSE';
+} | {
+    readonly type: 'RESUME';
+} | {
+    readonly type: 'STOP';
+} | {
+    readonly type: 'STOPPED';
+} | {
+    readonly type: 'BACKGROUND';
+} | {
+    readonly type: 'FOREGROUND';
+    readonly surfaceMounted: boolean;
+} | {
+    readonly type: 'FAIL';
+    readonly code: CameraErrorCode;
+} | {
+    readonly type: 'START_TIMEOUT';
+};
+export interface SessionSnapshot {
+    readonly status: SessionStatus;
+    readonly error: CameraError | null;
+}
+export declare const initialSession: SessionSnapshot;
+export declare function canStart(status: SessionStatus): boolean;
+/** Capture is only ever legal from a fully active session (FR-020). */
+export declare function canCapture(status: SessionStatus): boolean;
+export declare function sessionReducer(snapshot: SessionSnapshot, event: SessionEvent): SessionSnapshot;
+//# sourceMappingURL=sessionMachine.d.ts.map

package/lib/typescript/module/core/sessionMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionMachine.d.ts","sourceRoot":"","sources":["../../../../src/core/sessionMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,0BAAuB,CAAC;AAE1E,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CACnC;AAED,eAAO,MAAM,cAAc,EAAE,eAAiD,CAAC;AAK/E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAEvD;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAEzD;AAMD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,GAAG,eAAe,CAqD9F"}

package/lib/typescript/module/core/sessionRuntime.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The session's own I/O: starting it, waiting for frames, releasing it, and
+ * following the app in and out of the foreground.
+ *
+ * Split out of `controller.ts`, which had grown to hold three jobs at once:
+ * publishing state, running the session, and serving the public API. The
+ * decisions still live in `sessionMachine` (pure); this is the part that
+ * actually awaits the engine, and the controller composes it.
+ *
+ * It reads and writes the controller's state through `SessionContext` rather
+ * than owning it: one snapshot reaches subscribers, whichever part of the
+ * controller changed it.
+ */
+import type { StartOptions } from '../config/types.js';
+import { type CameraErrorCode } from '../diagnostics/errors.js';
+import type { CameraLogger } from '../diagnostics/logger.js';
+import type { CameraEngine } from '../native/cameraEngine.js';
+import type { SurfaceInfo } from '../native/visionSurface.js';
+import type { SessionEvent, SessionSnapshot } from './sessionMachine.js';
+/** What the runtime needs from the controller that owns the state. */
+export interface SessionContext {
+    readonly engine: CameraEngine;
+    readonly logger: CameraLogger;
+    /** How long to wait for a preview surface to report frames. */
+    readonly startTimeoutMs: number;
+    readonly scheduler: {
+        setTimeout(callback: () => void, ms: number): unknown;
+        clearTimeout(handle: unknown): void;
+    };
+    session(): SessionSnapshot;
+    dispatch(event: SessionEvent): void;
+    emit(): void;
+    cameraPosition(): 'front' | 'back';
+    setCameraPosition(position: 'front' | 'back'): void;
+    torchEnabled(): boolean;
+    setTorchEnabled(enabled: boolean): void;
+    surfaceMounted(): boolean;
+    permissionGranted(): boolean;
+    disposed(): boolean;
+}
+export interface SessionRuntime {
+    /** Starts the engine and, where the surface owns the session, waits for frames. */
+    start(options?: StartOptions): Promise<void>;
+    /** Turns the torch off and releases the camera. Safe from any state. */
+    release(): Promise<void>;
+    /** Torch off, whatever the session is doing. */
+    forceTorchOff(): Promise<void>;
+    /** The app went to the background or came back. */
+    onAppState(status: 'active' | 'background'): void;
+    /** The preview reported frames; carries what the mounted device turned out to be. */
+    reportSurfaceStarted(info: SurfaceInfo): void;
+    /** The preview's own session failed, or the OS took the camera. */
+    reportSurfaceFailed(code: CameraErrorCode): void;
+    /** The engine lost the camera: another app, a call, a disconnected device. */
+    onInterruption(code: CameraErrorCode): void;
+    /** What the surface last reported, for the published state. */
+    surfaceInfo(): SurfaceInfo | null;
+    /** Set when the app foregrounds with a surface mounted, so the session restarts. */
+    armResumeOnForeground(): void;
+    /** A release still in flight, so a restart can wait for it. */
+    pending(): Promise<void> | undefined;
+}
+export declare function createSessionRuntime(context: SessionContext): SessionRuntime;
+//# sourceMappingURL=sessionRuntime.d.ts.map

package/lib/typescript/module/core/sessionRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionRuntime.d.ts","sourceRoot":"","sources":["../../../../src/core/sessionRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAiB,CAAC;AACpD,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,0BAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAkB,CAAC;AAEtE,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE;QACnB,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QACtD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;KACpC,CAAC;IACF,OAAO,IAAI,eAAe,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,IAAI,IAAI,IAAI,CAAC;IACb,cAAc,IAAI,OAAO,GAAG,MAAM,CAAC;IACnC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IACpD,YAAY,IAAI,OAAO,CAAC;IACxB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,cAAc,IAAI,OAAO,CAAC;IAC1B,iBAAiB,IAAI,OAAO,CAAC;IAC7B,QAAQ,IAAI,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC9B,mFAAmF;IACnF,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,wEAAwE;IACxE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,gDAAgD;IAChD,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,mDAAmD;IACnD,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC;IAClD,qFAAqF;IACrF,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9C,mEAAmE;IACnE,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IACjD,8EAA8E;IAC9E,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC5C,+DAA+D;IAC/D,WAAW,IAAI,WAAW,GAAG,IAAI,CAAC;IAClC,oFAAoF;IACpF,qBAAqB,IAAI,IAAI,CAAC;IAC9B,+DAA+D;IAC/D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;CACrC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CA+K5E"}