@octane-xplat/camera 0.13.0 → 0.14.0

package/src/synthetic-session.ts

@@ -0,0 +1,367 @@
+import { SharedCameraSession } from './session-core'
+import type {
+	BackendCaptureRequest,
+	BackendCaptureSink,
+	BackendObserver,
+	BackendSettle,
+	CameraSessionBackend,
+} from './session-core'
+
+import type {
+	CameraInterruptionReason,
+	CameraPermissionStatus,
+	CameraSession,
+	CameraSessionCapabilities,
+	CameraSessionConfig,
+	MovieOutput,
+} 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
+	}
+}
+
+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 function createMemoryCameraStorage(): SyntheticCameraStorage & {
+	files: Map<string, Uint8Array>
+} {
+	const files = new Map<string, Uint8Array>()
+	return {
+		files,
+		write: (path, bytes) => {
+			files.set(path, bytes)
+		},
+		read: (path) => files.get(path),
+		delete: (path) => {
+			files.delete(path)
+		},
+		exists: (path) => files.has(path),
+	}
+}
+
+const defaultScript = (): SyntheticCameraScript => ({
+	permission: { camera: 'granted', microphone: 'granted' },
+	available: true,
+	startDelayMs: 20,
+	clipDurationMs: 3000,
+	produceMedia: true,
+})
+
+const capabilities: CameraSessionCapabilities = {
+	supported: true,
+	available: true,
+	cameras: [
+		{ id: 'synthetic-back', label: 'Synthetic back camera', facing: 'back' },
+		{ id: 'synthetic-front', label: 'Synthetic front camera', facing: 'front' },
+	],
+	profiles: [{ profile: 'standard', width: 1280, height: 720, frameRate: 30 }],
+	audio: true,
+	orientations: ['portrait', 'portraitUpsideDown', 'landscapeLeft', 'landscapeRight'],
+	durationLimit: 'native',
+	elapsedTime: 'nativeMedia',
+	output: {
+		mimeType: 'video/quicktime',
+		container: 'mov',
+		storage: 'appPrivateFile',
+		destinationFileUrl: true,
+	},
+}
+
+/** Create a `CameraSession` backed by the deterministic synthetic source.
+ *  Marked for development and testing — never present this as live
+ *  capture to users. */
+export function createSyntheticCameraSession(
+	config: CameraSessionConfig = {},
+	script: Partial<SyntheticCameraScript> = {},
+	storage: SyntheticCameraStorage = createMemoryCameraStorage(),
+): CameraSession {
+	const controls: SyntheticCameraScript = { ...defaultScript(), ...script }
+	return new SharedCameraSession(createSyntheticBackend(controls, storage), config)
+}
+
+function createSyntheticBackend(
+	script: SyntheticCameraScript,
+	storage: SyntheticCameraStorage,
+): CameraSessionBackend {
+	let observer: BackendObserver | undefined
+	let attached = false
+	let sink: BackendCaptureSink | undefined
+	let startedAt: number | undefined
+	let timers: ReturnType<typeof setTimeout>[] = []
+	let pendingRequest: BackendCaptureRequest | undefined
+
+	const later = (ms: number, fn: () => void) => {
+		timers.push(setTimeout(fn, ms))
+	}
+
+	const clearTimers = () => {
+		for (const timer of timers) {
+			clearTimeout(timer)
+		}
+
+		timers = []
+	}
+
+	const settleClip = async (request: BackendCaptureRequest, limitReached: boolean) => {
+		const path =
+			request.destinationPath ??
+			`/synthetic/clip-${Date.now()}-${Math.random().toString(36).slice(2)}.mov`
+
+		if (!script.produceMedia) {
+			sink?.settled({
+				kind: 'failed',
+				stage: 'capture',
+				issue: {
+					kind: 'noMedia',
+					operation: 'finalize',
+					message: 'Synthetic source produced no media',
+				},
+			})
+
+			return
+		}
+
+		if (script.failAt === 'finalize') {
+			sink?.settled({
+				kind: 'failed',
+				stage: 'finalization',
+				issue: {
+					kind: 'finalizationFailed',
+					operation: 'finalize',
+					message: 'Synthetic finalization failure',
+				},
+			})
+
+			return
+		}
+
+		if (script.failAt === 'storage') {
+			sink?.settled({
+				kind: 'failed',
+				stage: 'storage',
+				issue: {
+					kind: 'storageFailed',
+					operation: 'store',
+					message: 'Synthetic storage failure',
+				},
+			})
+
+			return
+		}
+
+		try {
+			// Not playable media — seam bytes stand in for a fixture. The
+			// output is marked `synthetic` so nothing mistakes it for real
+			// capture.
+			await storage.write(path, new Uint8Array([0x78, 0x70, 0x6c, 0x61, 0x74]))
+		} catch (cause) {
+			sink?.settled({
+				kind: 'failed',
+				stage: 'storage',
+				issue: {
+					kind: 'storageFailed',
+					operation: 'store',
+					message: cause instanceof Error ? cause.message : String(cause),
+					cause,
+				},
+			})
+
+			return
+		}
+
+		const output: MovieOutput = {
+			kind: 'nativeFile',
+			resourceId: `synthetic:${path}`,
+			fileUrl: `file://${path}`,
+			synthetic: true,
+		}
+
+		const settle: BackendSettle = {
+			kind: 'clip',
+			output,
+			mimeType: 'video/quicktime',
+			durationMs: script.clipDurationMs,
+			width: 1280,
+			height: 720,
+			orientation: request.orientation ?? 'portrait',
+			hasAudio: request.audio,
+			limitReached,
+		}
+
+		sink?.settled(settle)
+	}
+
+	return {
+		platform: 'synthetic',
+		supported: true,
+		checkPermission: async (kind) => script.permission[kind],
+		requestPermission: async (kind) => script.permission[kind],
+		getCapabilities: async () => ({
+			...capabilities,
+			available: script.available,
+			reason: script.available ? undefined : 'Synthetic camera is unavailable',
+		}),
+		previewReady: () => attached && script.available,
+		attachPreview: (_host, listener) => {
+			attached = true
+			queueMicrotask(() => {
+				listener?.onReady?.()
+				observer?.previewReady(true)
+			})
+
+			return () => {
+				attached = false
+				observer?.previewReady(false)
+			}
+		},
+		startCapture: (request, attemptSink) => {
+			sink = attemptSink
+			pendingRequest = request
+			if (!script.available) {
+				attemptSink.settled({
+					kind: 'failed',
+					stage: 'preparation',
+					issue: {
+						kind: 'unavailable',
+						operation: 'startRecording',
+						message: 'Synthetic camera is unavailable',
+					},
+				})
+
+				return
+			}
+
+			if (script.failAt === 'start') {
+				later(script.startDelayMs, () => {
+					attemptSink.settled({
+						kind: 'failed',
+						stage: 'preparation',
+						issue: {
+							kind: 'captureFailed',
+							operation: 'startRecording',
+							message: 'Synthetic start failure',
+						},
+					})
+				})
+
+				return
+			}
+
+			later(script.startDelayMs, () => {
+				startedAt = Date.now()
+				attemptSink.started({
+					cameraId: 'synthetic-back',
+					facing: 'back',
+					audio: request.audio,
+					width: 1280,
+					height: 720,
+					frameRate: 30,
+					orientation: request.orientation ?? 'portrait',
+					mimeType: 'video/quicktime',
+					container: 'mov',
+				})
+
+				if (script.interruption) {
+					later(script.interruption.afterMs, () => {
+						observer?.interruption('began', script.interruption?.reason)
+						if (script.interruption?.endsAfterMs !== undefined) {
+							later(script.interruption.endsAfterMs, () => {
+								observer?.interruption('ended', script.interruption?.reason)
+							})
+						}
+					})
+				}
+
+				if (request.maximumDurationMs !== undefined) {
+					later(request.maximumDurationMs, () => {
+						void settleClip(request, true)
+					})
+				}
+
+				if (script.failAt === 'capture') {
+					later(50, () => {
+						attemptSink.settled({
+							kind: 'failed',
+							stage: 'capture',
+							issue: {
+								kind: 'captureFailed',
+								operation: 'record',
+								message: 'Synthetic capture failure',
+							},
+						})
+					})
+				}
+			})
+		},
+		stopCapture: () => {
+			// Settle asynchronously — native stop is async too.
+			const request = pendingRequest
+			later(5, () => {
+				if (request) {
+					void settleClip(request, false)
+				}
+			})
+		},
+		elapsedMs: () => (startedAt === undefined ? 0 : Date.now() - startedAt),
+		openOutput: async (output) => {
+			const path = output.kind === 'nativeFile' ? output.fileUrl.slice('file://'.length) : ''
+			const exists = storage.exists ? await storage.exists(path) : !!(await storage.read(path))
+			if (!exists) {
+				throw new Error(`Synthetic clip is missing at ${output.resourceId}`)
+			}
+
+			return {
+				url: output.kind === 'nativeFile' ? output.fileUrl : output.resourceId,
+				fileUrl: output.kind === 'nativeFile' ? output.fileUrl : undefined,
+				release: () => {},
+			}
+		},
+		release: async () => {
+			attached = false
+			clearTimers()
+			sink = undefined
+			startedAt = undefined
+			pendingRequest = undefined
+		},
+		onPreviewDetached: () => {},
+		setObserver: (next) => {
+			observer = next
+		},
+	}
+}

package/src/types.ts

@@ -0,0 +1,329 @@
+/** 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'
+
+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
+	/** 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
+	/** 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>
+}