@octane-xplat/camera 0.13.0 → 0.15.0

package/src/types.ts

@@ -0,0 +1,357 @@
+/** Shared camera-session and movie-recording contract.
+ *
+ *  A `CameraSession` owns one camera acquisition shared between a
+ *  `CameraView` preview and at most one movie-recording attempt. Recording
+ *  settles with an immutable `MovieOutcome` only after the local movie is
+ *  finalized and its metadata is known — a returned clip is always
+ *  reopenable through `openOutput`.
+ *
+ *  This module is platform-pure: adapters implement
+ *  `CameraSessionBackend` per host. Adapters that do not support capture
+ *  yet report `supported: false` and reject `startRecording` with
+ *  `unsupportedPlatform` instead of fabricating behavior.
+ */
+
+/** Permission resource a `CameraSession` can inspect or request. */
+export type CameraPermissionKind = 'camera' | 'microphone'
+
+/** Portable authorization state. Checking never prompts. `blocked` and
+ *  `unknown` exist so hosts that cannot distinguish user denial from
+ *  policy refusal do not fabricate `restricted`. */
+export type CameraPermissionStatus =
+	| 'notDetermined'
+	| 'granted'
+	| 'denied'
+	| 'restricted'
+	| 'blocked'
+	| 'unknown'
+	| 'unavailable'
+
+/** Portable error categories. `unsupported*` covers missing host features,
+ *  devices, or capture configurations — including adapters that are not
+ *  implemented yet during staged delivery. */
+export type CameraCaptureErrorKind =
+	| 'permissionDenied'
+	| 'permissionRestricted'
+	| 'permissionBlocked'
+	| 'unsupportedPlatform'
+	| 'unsupportedConfiguration'
+	| 'unavailable'
+	| 'busy'
+	| 'invalidState'
+	| 'invalidArgument'
+	| 'destinationUnavailable'
+	| 'insufficientStorage'
+	| 'noMedia'
+	| 'captureFailed'
+	| 'finalizationFailed'
+	| 'storageFailed'
+	| 'configurationMissing'
+
+/** Structured diagnostic carried by failures and non-fatal warnings. */
+export interface CaptureIssue {
+	kind: CameraCaptureErrorKind
+	/** Operation being attempted, e.g. 'startRecording', 'finalize'. */
+	operation: string
+	message: string
+	permission?: CameraPermissionKind
+	/** Host-specific detail for logging; never required for control flow. */
+	cause?: unknown
+}
+
+/** Error thrown or settled by the session API. Satisfies `CaptureIssue`
+ *  so `error.kind` drives control flow without unwrapping. */
+export class CameraCaptureError extends Error implements CaptureIssue {
+	kind: CameraCaptureErrorKind
+	operation: string
+	permission?: CameraPermissionKind
+	cause?: unknown
+
+	constructor(issue: Omit<CaptureIssue, 'cause'> & { cause?: unknown }) {
+		super(issue.message)
+		this.name = 'CameraCaptureError'
+		this.kind = issue.kind
+		this.operation = issue.operation
+		this.permission = issue.permission
+		this.cause = issue.cause
+	}
+}
+
+export type CameraFacing = 'front' | 'back'
+
+/** A normalized position on the live preview as the user sees it:
+ *  `{x: 0, y: 0}` is the top-left corner and `{x: 1, y: 1}` is
+ *  bottom-right, independent of sensor orientation and front-camera
+ *  mirroring. The `CameraView` `onTap` event and
+ *  `CameraSession.focusAtPoint` share this space. */
+export interface CameraPreviewPoint {
+	x: number
+	y: number
+}
+
+export type CameraOrientation =
+	| 'portrait'
+	| 'portraitUpsideDown'
+	| 'landscapeLeft'
+	| 'landscapeRight'
+	| 'unspecified'
+
+/** Camera selection for `CameraSessionConfig.camera`. Desktop and browser
+ *  hosts expose device identities instead of front/back semantics. */
+export type CameraSelection = 'default' | 'front' | 'back' | { deviceId: string }
+
+export interface CameraSessionConfig {
+	/** Lens or device identity. Default `'default'`: rear when available. */
+	camera?: CameraSelection
+	/** Include an audio track; requires microphone permission. Default
+	 *  false — silent capture is a deliberate app choice, never a
+	 *  fallback from denied microphone access. */
+	audio?: boolean
+	/** Capture profile. `'standard'` targets 720p at 30 fps and may select
+	 *  a device-supported alternative; the started attempt discloses the
+	 *  actual configuration. */
+	profile?: 'standard'
+}
+
+/** Resolution/frame-rate combination advertised by capability discovery.
+ *  Entries are supported combinations, not independent lists. */
+export interface CameraProfileCapability {
+	profile: 'standard'
+	width: number
+	height: number
+	frameRate: number
+}
+
+export interface CameraDeviceInfo {
+	id: string
+	label: string
+	facing?: CameraFacing
+}
+
+/** What the session's host can do right now. `supported: false` means the
+ *  adapter or host cannot record (reason explains); `available` reflects
+ *  current hardware/permission state and changes over time. */
+export interface CameraSessionCapabilities {
+	supported: boolean
+	/** Why capture is unsupported or currently unavailable. */
+	reason?: string
+	available: boolean
+	cameras: CameraDeviceInfo[]
+	profiles: CameraProfileCapability[]
+	/** The session can add an audio track when permission allows. */
+	audio: boolean
+	/** `focusAtPoint` can move autofocus metering on the active camera —
+	 *  false on fixed-focus devices (common for front cameras) and on
+	 *  platforms without point-of-interest metering. */
+	focusPointOfInterest: boolean
+	/** `focusAtPoint` can move auto-exposure metering on the active
+	 *  camera. */
+	exposurePointOfInterest: boolean
+	/** Fixed orientations the source can lock for a take. */
+	orientations: CameraOrientation[]
+	/** `native` enforcement can still overshoot at media boundaries;
+	 *  `bestEffort` limits are scheduled and may overshoot more. */
+	durationLimit: 'native' | 'bestEffort'
+	/** Where `elapsedMs` comes from while recording. */
+	elapsedTime: 'nativeMedia' | 'estimated'
+	output: {
+		mimeType: string
+		container: string
+		/** `appPrivateFile` output survives dispose and app restart;
+		 *  `originLocal` is browser storage subject to site-data clearing. */
+		storage: 'appPrivateFile' | 'originLocal'
+		/** Accepts an app-supplied `destinationFileUrl` on start. */
+		destinationFileUrl: boolean
+	}
+}
+
+export type CameraRecorderState = 'idle' | 'starting' | 'recording' | 'finalizing' | 'disposed'
+
+/** Frozen capture configuration reported once capture actually begins. */
+export interface EffectiveCaptureConfig {
+	cameraId: string
+	facing?: CameraFacing
+	audio: boolean
+	width: number
+	height: number
+	frameRate: number
+	orientation: CameraOrientation
+	mimeType: string
+	container: string
+}
+
+export interface CameraSessionSnapshot {
+	state: CameraRecorderState
+	/** Non-prompting last-known authorization, refreshed by `permissions()`
+	 *  and `requestPermission()`. */
+	permission: Record<CameraPermissionKind, CameraPermissionStatus>
+	/** Camera hardware/driver availability, separate from recorder state. */
+	cameraAvailable: boolean
+	/** An active preview view is attached to this session. */
+	previewAttached: boolean
+	interrupted: boolean
+	attempt?: {
+		id: string
+		state: 'starting' | 'recording' | 'finalizing'
+		elapsedMs: number
+		configuration?: EffectiveCaptureConfig
+	}
+}
+
+/** What ended a capture attempt. `interrupted` covers system suspension
+ *  and preview teardown; `previewReleased` distinguishes an app-driven
+ *  deactivation from an OS interruption. */
+export type MovieEndReason =
+	| 'stopped'
+	| 'maximumDuration'
+	| 'interrupted'
+	| 'backgrounded'
+	| 'cameraUnavailable'
+	| 'previewReleased'
+	| 'disposed'
+	| 'captureError'
+
+/** Portable completed-output reference. `resourceId` reopens the clip
+ *  through `openOutput`; `fileUrl` additionally guarantees file-backed
+ *  native output. `synthetic` marks test-seam clips. */
+export type MovieOutput =
+	| {
+			kind: 'nativeFile'
+			resourceId: string
+			fileUrl: string
+			synthetic?: boolean
+	  }
+	| {
+			kind: 'browserStorage'
+			resourceId: string
+			retention: 'persistent' | 'bestEffort'
+			synthetic?: boolean
+	  }
+
+export interface MovieClip {
+	output: MovieOutput
+	mimeType: string
+	/** Authoritative duration read from the finalized movie. */
+	durationMs: number
+	/** Presentation dimensions after the orientation transform. */
+	width: number
+	height: number
+	orientation: CameraOrientation
+	/** Whether the finalized movie actually contains an audio track.
+	 *  Missing requested audio is a failure, not silent capture. */
+	hasAudio: boolean
+}
+
+/** One immutable terminal result per admitted attempt. `partial` marks a
+ *  usable clip ended early by an external condition — still a success;
+ *  app review decides whether to keep it. */
+export type MovieOutcome =
+	| {
+			kind: 'clip'
+			clip: MovieClip
+			endReason: MovieEndReason
+			partial: boolean
+			warning?: CaptureIssue
+	  }
+	| {
+			kind: 'failed'
+			endReason: MovieEndReason
+			stage: 'preparation' | 'capture' | 'finalization' | 'storage'
+			error: CaptureIssue
+	  }
+
+/** Ordered lifecycle observation, correlated to an attempt when relevant. */
+export type CameraSessionEvent =
+	| { type: 'stateChanged'; snapshot: CameraSessionSnapshot }
+	| { type: 'started'; attemptId: string; configuration: EffectiveCaptureConfig }
+	| { type: 'finished'; attemptId: string; outcome: MovieOutcome }
+	| {
+			type: 'interruption'
+			phase: 'began' | 'ended'
+			reason?: CameraInterruptionReason
+	  }
+	| { type: 'availability'; available: boolean }
+
+export type CameraInterruptionReason =
+	| 'background'
+	| 'audioInUse'
+	| 'cameraInUse'
+	| 'multitasking'
+	| 'systemPressure'
+	| 'unknown'
+
+export interface StartRecordingOptions {
+	/** Positive finite milliseconds. Enforcement precision comes from
+	 *  `capabilities().durationLimit`; the final duration is read from
+	 *  the movie and may overshoot. */
+	maximumDurationMs?: number
+	/** Fixed orientation for the take. Must appear in
+	 *  `capabilities().orientations`; omit for the source default. */
+	orientation?: CameraOrientation
+	/** App-supplied writable local `file://` URL (native hosts only,
+	 *  where `capabilities().output.destinationFileUrl` is true).
+	 *  Existing files are never overwritten. */
+	destinationFileUrl?: string
+}
+
+/** One admitted capture attempt. `completion` is available immediately and
+ *  settles exactly once with the terminal outcome; repeated `stop()`
+ *  joins the same finalization. */
+export interface MovieTake {
+	readonly id: string
+	readonly state: 'starting' | 'recording' | 'finalizing' | 'settled'
+	/** Elapsed capture time in milliseconds; excludes preparation and
+	 *  finalization. Source identified by `capabilities().elapsedTime`. */
+	readonly elapsedMs: number
+	readonly completion: Promise<MovieOutcome>
+	/** Requests stop and joins finalization. Returns `completion`. */
+	stop(): Promise<MovieOutcome>
+}
+
+/** Reopened access to a stored clip. `release()` frees temporary access;
+ *  it never deletes the clip. */
+export interface MovieOutputHandle {
+	/** Playable/readable location for the clip. */
+	readonly url: string
+	readonly fileUrl?: string
+	release(): void
+}
+
+export interface CameraSession {
+	/** Non-prompting permission inspection; may return `unknown` when the
+	 *  host cannot observe authorization. */
+	permissions(): Promise<Record<CameraPermissionKind, CameraPermissionStatus>>
+	/** Runs the system authorization flow for one kind. Calls are
+	 *  serialized; a status other than `notDetermined` returns without
+	 *  prompting. */
+	requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>
+	capabilities(): Promise<CameraSessionCapabilities>
+	snapshot(): CameraSessionSnapshot
+	/** Ordered lifecycle events. A caller never loses a result by
+	 *  subscribing late — `completion` is authoritative. Listener
+	 *  exceptions do not change capture. */
+	subscribe(listener: (event: CameraSessionEvent) => void): () => void
+	/** Tap-to-focus: meters one autofocus/auto-exposure pass at a
+	 *  normalized preview-space point (see `CameraPreviewPoint`), pairing
+	 *  with the `CameraView` `onTap` event. No-ops while no preview is
+	 *  attached, after `dispose`, and on hosts without point-of-interest
+	 *  metering — `capabilities()` reports `focusPointOfInterest` and
+	 *  `exposurePointOfInterest` separately. Out-of-range coordinates
+	 *  clamp to the preview edge; non-finite coordinates throw
+	 *  `invalidArgument`. Metering is per-device state: a camera swap
+	 *  through `configure` returns focus/exposure to the new device's
+	 *  default. */
+	focusAtPoint(point: CameraPreviewPoint): void
+	/** Replaces configuration while idle. Validates against current
+	 *  capabilities and rejects with `invalidState` during an attempt. */
+	configure(config: Partial<CameraSessionConfig>): Promise<void>
+	/** Admits one capture attempt. Throws `CameraCaptureError` before
+	 *  admission for invalid arguments, busy, invalid state, or
+	 *  unavailable camera — no attempt is created. */
+	startRecording(options?: StartRecordingOptions): MovieTake
+	/** Reopens a stored output for playback or reading. */
+	openOutput(output: MovieOutput): Promise<MovieOutputHandle>
+	/** Requests stop on any active attempt, awaits finalization, then
+	 *  releases camera ownership. */
+	dispose(): Promise<void>
+}

package/types/index.d.ts

@@ -1,5 +1,48 @@
 import type { UniversalComponent } from 'octane/universal'
 import type { CameraViewProps } from './props.js'
+import type { CameraSession, CameraSessionConfig } from './types.js'
+import type { SyntheticCameraScript, SyntheticCameraStorage } from './synthetic-session.js'
 
 export declare const CameraView: UniversalComponent<CameraViewProps>
 export type { CameraViewHandle, CameraViewProps, CameraAccessibilityRole } from './props.js'
+
+export declare function createCameraSession(config?: CameraSessionConfig): CameraSession
+export declare function createSyntheticCameraSession(
+	config?: CameraSessionConfig,
+	script?: Partial<SyntheticCameraScript>,
+	storage?: SyntheticCameraStorage,
+): CameraSession
+
+export declare function createMemoryCameraStorage(): SyntheticCameraStorage & {
+	files: Map<string, Uint8Array>
+}
+
+export { CameraCaptureError } from './types.js'
+export type {
+	CameraCaptureErrorKind,
+	CameraDeviceInfo,
+	CameraFacing,
+	CameraInterruptionReason,
+	CameraOrientation,
+	CameraPermissionKind,
+	CameraPermissionStatus,
+	CameraProfileCapability,
+	CameraRecorderState,
+	CameraSelection,
+	CameraSession,
+	CameraSessionCapabilities,
+	CameraSessionConfig,
+	CameraSessionEvent,
+	CameraSessionSnapshot,
+	CaptureIssue,
+	EffectiveCaptureConfig,
+	MovieClip,
+	MovieEndReason,
+	MovieOutcome,
+	MovieOutput,
+	MovieOutputHandle,
+	MovieTake,
+	StartRecordingOptions,
+} from './types.js'
+
+export type { SyntheticCameraScript, SyntheticCameraStorage } from './synthetic-session.js'

package/types/props.d.ts

@@ -1,4 +1,5 @@
 import type { Octane } from 'octane/jsx-runtime';
+import type { CameraPreviewPoint, CameraSession } from './types';
 export type CameraAccessibilityRole = 'button' | 'link' | 'search' | 'image' | 'heading' | 'adjustable' | 'summary' | 'text' | 'none' | 'progressbar' | 'checkbox' | 'switch' | 'radio' | 'spinbutton' | 'tab';
 export interface CameraViewHandle {
     /** The native preview surface (`HTMLVideoElement` on web). */
@@ -30,7 +31,11 @@ export interface CameraViewProps {
         checked?: boolean;
     };
     accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
-    /** Lens — defaults to the rear camera. */
+    /** Shared camera owner enabling movie recording. When set, the preview
+     *  attaches to the session's acquisition instead of owning one, and
+     *  `facing` must be omitted — camera selection lives on the session. */
+    session?: CameraSession;
+    /** Lens — defaults to the rear camera. Invalid together with `session`. */
     facing?: 'front' | 'back';
     /** Default true. False releases the preview session. */
     active?: boolean;
@@ -39,10 +44,18 @@ export interface CameraViewProps {
     onError?: (error: {
         message?: string;
     }) => void;
+    /** Notification-only tap event — fires with the normalized
+     *  preview-space position (`CameraPreviewPoint`) and never consumes
+     *  the gesture, so recognizers layered above the preview (double-tap,
+     *  pan) still run. Pair with `session.focusAtPoint` for tap-to-focus.
+     *  Delivered on iOS, Android, and web; desktop runtimes do not dispatch
+     *  it yet. */
+    onTap?: (point: CameraPreviewPoint) => void;
     /** Native preview surface for platform-specific controls. */
     ref?: Octane.Ref<CameraViewHandle>;
     /** Platform-specific properties applied to the preview surface. */
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    windows?: Record<string, any>;
 }

package/types/session-core.d.ts

@@ -0,0 +1,139 @@
+import type { CameraInterruptionReason, CameraPermissionKind, CameraPermissionStatus, CameraPreviewPoint, CameraSession, CameraSessionCapabilities, CameraSessionConfig, CameraSessionEvent, CameraSessionSnapshot, CaptureIssue, EffectiveCaptureConfig, MovieEndReason, MovieOutput, MovieOutputHandle, MovieTake, StartRecordingOptions } from './types';
+/** Result an adapter reports when a capture attempt settles. Media
+ *  metadata is already read from the finalized movie by the adapter. */
+export type BackendSettle = {
+    kind: 'clip';
+    output: MovieOutput;
+    mimeType: string;
+    durationMs: number;
+    width: number;
+    height: number;
+    orientation: EffectiveCaptureConfig['orientation'];
+    hasAudio: boolean;
+    /** Native duration-limit enforcement ended the take. */
+    limitReached?: boolean;
+    /** Adapter-driven endings when no earlier app/lifecycle cause exists. */
+    endReason?: MovieEndReason;
+    warning?: CaptureIssue;
+} | {
+    kind: 'failed';
+    stage: 'preparation' | 'capture' | 'finalization' | 'storage';
+    issue: CaptureIssue;
+};
+/** Per-attempt callbacks handed to `startCapture`. */
+export interface BackendCaptureSink {
+    /** Native capture actually began; exactly once per settled attempt. */
+    started(config: EffectiveCaptureConfig): void;
+    /** Capture has ended; metadata verification and storage still own the attempt. */
+    finishing(reason?: MovieEndReason): void;
+    /** Terminal result; exactly once per admitted attempt. */
+    settled(result: BackendSettle): void;
+}
+export interface BackendCaptureRequest {
+    audio: boolean;
+    orientation: EffectiveCaptureConfig['orientation'] | undefined;
+    maximumDurationMs: number | undefined;
+    /** Resolved writable path for native adapters. */
+    destinationPath: string | undefined;
+}
+/** Adapter-owned preview attach. `listener` reports preview lifecycle;
+ *  returns the detach function. */
+export interface BackendPreviewListener {
+    onReady?: () => void;
+    onError?: (issue: CaptureIssue) => void;
+}
+/** Platform adapter surface driven by the shared session core. Adapters
+ *  own permission policy, capability discovery, capture, and local output
+ *  access; the core owns states, ordering, causes, and outcomes. */
+export interface CameraSessionBackend {
+    readonly platform: string;
+    /** False when the adapter cannot capture on this host; the core
+     *  rejects `startRecording` with `unsupportedPlatform`. */
+    readonly supported: boolean;
+    checkPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
+    requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
+    getCapabilities(): Promise<CameraSessionCapabilities>;
+    /** An active, ready preview is attached and the camera source is
+     *  running — the admission requirement for `startRecording`. */
+    previewReady(): boolean;
+    /** Attach the shared-source preview to a platform view. */
+    attachPreview(host: unknown, listener?: BackendPreviewListener): () => void;
+    /** Replace configuration while idle; throws CameraCaptureError. */
+    configure?(config: CameraSessionConfig): void;
+    /** Meter one autofocus/auto-exposure pass at a normalized preview-space
+     *  point — the tap-to-focus primitive. Absent means the adapter cannot
+     *  meter at a point; the core turns it into a no-op. */
+    focusAtPoint?(point: CameraPreviewPoint): void;
+    /** Synchronous platform-specific admission checks; creates no attempt on failure. */
+    validateStart?(options: StartRecordingOptions): void;
+    /** Begin capture for an admitted attempt. Async failures settle via
+     *  `sink.settled`; a synchronous throw settles as a preparation failure. */
+    startCapture(request: BackendCaptureRequest, sink: BackendCaptureSink): void;
+    /** Request capture stop; settlement still arrives via the sink. */
+    stopCapture(): void;
+    /** Elapsed capture time in ms for the in-flight attempt. */
+    elapsedMs(): number;
+    openOutput(output: MovieOutput): Promise<MovieOutputHandle>;
+    /** Release camera ownership. The core calls this only after any
+     *  in-flight attempt has settled. */
+    release(): Promise<void>;
+    /** Reattach/reconfigure bookkeeping when the preview view is detached
+     *  while an attempt is settling — the adapter keeps hardware until
+     *  settlement, then stops. */
+    onPreviewDetached?(): void;
+    /** Lifecycle observations the adapter emits at any time. */
+    setObserver(observer: BackendObserver | undefined): void;
+}
+export interface BackendObserver {
+    interruption(phase: 'began' | 'ended', reason?: CameraInterruptionReason): void;
+    availability(available: boolean): void;
+    /** Preview became ready/unready (session running state changed). */
+    previewReady(ready: boolean): void;
+}
+/** Collapse '.' and '..' segments without touching the filesystem — the
+ *  adapters' app-private containment checks compare against this canonical
+ *  form, so a '..' inside the requested path can never keep the root
+ *  prefix while escaping it. */
+export declare const canonicalizePath: (raw: string, separator?: string) => string;
+/** The concrete session object wrapping a platform backend. Internal to
+ *  the package; `CameraSession` is the public shape. */
+export declare class SharedCameraSession implements CameraSession {
+    private backend;
+    private config;
+    private listeners;
+    private state;
+    private permission;
+    private cameraAvailable;
+    private previewAttached;
+    private interrupted;
+    private disposeRequested;
+    private disposed;
+    private lastCapabilities;
+    private requestChains;
+    private attempt;
+    constructor(backend: CameraSessionBackend, config: CameraSessionConfig);
+    /** Package-internal: attach a preview host to this session. */
+    attach(host: unknown, listener?: BackendPreviewListener): () => void;
+    get attached(): boolean;
+    private detachInternal;
+    private emit;
+    private setState;
+    snapshot(): CameraSessionSnapshot;
+    subscribe(listener: (event: CameraSessionEvent) => void): () => void;
+    permissions(): Promise<{
+        camera: CameraPermissionStatus;
+        microphone: CameraPermissionStatus;
+    }>;
+    requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
+    capabilities(): Promise<CameraSessionCapabilities>;
+    focusAtPoint(point: CameraPreviewPoint): void;
+    configure(next: Partial<CameraSessionConfig>): Promise<void>;
+    private validateCameraSelection;
+    private requestStop;
+    private handleInterruption;
+    private handleAvailability;
+    startRecording(options?: StartRecordingOptions): MovieTake;
+    openOutput(output: MovieOutput): Promise<MovieOutputHandle>;
+    dispose(): Promise<void>;
+    private finishDispose;
+}

package/types/synthetic-session.d.ts

@@ -0,0 +1,51 @@
+import type { CameraInterruptionReason, CameraPermissionStatus, CameraPreviewPoint, CameraSession, CameraSessionConfig } from './types';
+/** Development/testing seam — a deterministic camera source that drives
+ *  the shared session state machine without hardware. NOT a production
+ *  recording source: outcomes carry `synthetic: true` on their output so
+ *  seam clips stay distinguishable from real capture.
+ *
+ *  `script` is read live at each transition — mutate fields between
+ *  operations to script permissions, delayed starts, interruptions,
+ *  partial completions, and failures.
+ */
+export interface SyntheticCameraScript {
+    permission: {
+        camera: CameraPermissionStatus;
+        microphone: CameraPermissionStatus;
+    };
+    /** Camera hardware availability observation. */
+    available: boolean;
+    /** Delay before `started` reports; models slow native activation. */
+    startDelayMs: number;
+    /** Finalized clip duration reported by the seam. */
+    clipDurationMs: number;
+    /** Produce a usable clip on stop; false settles `noMedia`. */
+    produceMedia: boolean;
+    /** When set, the attempt settles failed at this stage. */
+    failAt?: 'start' | 'capture' | 'finalize' | 'storage';
+    /** Emit an interruption after this many ms of recording; the take
+     *  ends with the mapped end reason and a partial clip. */
+    interruption?: {
+        afterMs: number;
+        reason: CameraInterruptionReason;
+        endsAfterMs?: number;
+    };
+    /** When set, each `focusAtPoint` call pushes its normalized point
+     *  here so a spec can observe metering requests. */
+    focusRequests?: CameraPreviewPoint[];
+}
+export interface SyntheticCameraStorage {
+    write(path: string, bytes: Uint8Array): void | Promise<void>;
+    read(path: string): Uint8Array | undefined | Promise<Uint8Array | undefined>;
+    delete?(path: string): void | Promise<void>;
+    exists?(path: string): boolean | Promise<boolean>;
+}
+/** In-memory storage for the seam — a `fileUrl`-shaped map so outcomes
+ *  exercise the same reopen path without touching a real filesystem. */
+export declare function createMemoryCameraStorage(): SyntheticCameraStorage & {
+    files: Map<string, Uint8Array>;
+};
+/** Create a `CameraSession` backed by the deterministic synthetic source.
+ *  Marked for development and testing — never present this as live
+ *  capture to users. */
+export declare function createSyntheticCameraSession(config?: CameraSessionConfig, script?: Partial<SyntheticCameraScript>, storage?: SyntheticCameraStorage): CameraSession;