@octane-xplat/camera 0.0.0-nightly.g2e22171

package/src/movie-storage.web.ts

@@ -0,0 +1,164 @@
+import { CameraCaptureError } from './types'
+import type { MovieClip, MovieOutput, MovieOutputHandle } from './types'
+
+const databaseName = 'octane-xplat-camera'
+const storeName = 'movies'
+
+type StoredMovie = { id: string; clip?: MovieClip; bytes?: Blob }
+
+const storageError = (cause: unknown) =>
+	new CameraCaptureError({
+		kind:
+			cause instanceof DOMException && cause.name === 'QuotaExceededError'
+				? 'insufficientStorage'
+				: 'storageFailed',
+		operation: 'storage',
+		message: 'The movie could not be committed to origin-local storage',
+		cause,
+	})
+
+/** Each operation closes its database; playback survives session and page lifetimes. */
+async function transact<T>(
+	mode: IDBTransactionMode,
+	operation: (store: IDBObjectStore, result: (value: T) => void) => void,
+): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		let database: IDBDatabase | undefined
+		let transaction: IDBTransaction | undefined
+		let result: T
+		let done = false
+		const finish = (cause?: unknown) => {
+			if (done) {
+				return
+			}
+
+			done = true
+			clearTimeout(timer)
+			database?.close()
+			if (cause) {
+				reject(storageError(cause))
+			} else {
+				resolve(result)
+			}
+		}
+
+		const timer = setTimeout(() => {
+			transaction?.abort()
+			finish(new Error('Storage transaction timed out'))
+		}, 15_000)
+
+		const request = indexedDB.open(databaseName, 1)
+		request.onupgradeneeded = () => request.result.createObjectStore(storeName, { keyPath: 'id' })
+		request.onerror = () => finish(request.error)
+		request.onblocked = () => finish(new Error('Storage upgrade is blocked by another page'))
+		request.onsuccess = () => {
+			database = request.result
+			if (done) {
+				database.close()
+				return
+			}
+
+			try {
+				transaction = database.transaction(storeName, mode, { durability: 'strict' })
+				transaction.oncomplete = () => finish()
+				transaction.onabort = () =>
+					finish(transaction?.error ?? new Error('Storage transaction aborted'))
+
+				transaction.onerror = () =>
+					finish(transaction?.error ?? new Error('Storage transaction failed'))
+
+				operation(transaction.objectStore(storeName), (value) => {
+					result = value
+				})
+			} catch (cause) {
+				finish(cause)
+			}
+		}
+	})
+}
+
+export async function reserveMovie(): Promise<string> {
+	const estimate = await navigator.storage.estimate()
+	if (
+		estimate.quota !== undefined &&
+		estimate.usage !== undefined &&
+		estimate.quota - estimate.usage < 1_048_576
+	) {
+		throw new CameraCaptureError({
+			kind: 'insufficientStorage',
+			operation: 'reserve',
+			message: 'Origin storage has less than 1 MiB free',
+		})
+	}
+
+	const id = crypto.randomUUID()
+	await transact<void>('readwrite', (store) => {
+		store.add({ id })
+	})
+
+	return id
+}
+
+export async function commitMovie(id: string, bytes: Blob, clip: MovieClip): Promise<void> {
+	if (!(await navigator.storage.persisted())) {
+		throw new CameraCaptureError({
+			kind: 'destinationUnavailable',
+			operation: 'storage',
+			message: 'Persistent origin storage is no longer granted',
+		})
+	}
+
+	await transact<void>('readwrite', (store) => {
+		store.put({ id, bytes, clip } satisfies StoredMovie)
+	})
+
+	// Reopen the committed entry before handing ownership to the app.
+	const stored = await readMovie(id)
+	if (!stored.bytes || stored.bytes.size !== bytes.size || !stored.clip) {
+		throw storageError(new Error('Committed movie cannot be reopened'))
+	}
+}
+
+export async function removeReservation(id: string): Promise<void> {
+	await transact<void>('readwrite', (store) => {
+		store.delete(id)
+	})
+}
+
+async function readMovie(id: string): Promise<StoredMovie> {
+	return transact<StoredMovie>('readonly', (store, result) => {
+		const request = store.get(id)
+		request.onsuccess = () => result(request.result ?? { id })
+	})
+}
+
+export async function openStoredMovie(output: MovieOutput): Promise<MovieOutputHandle> {
+	if (output.kind !== 'browserStorage' || output.synthetic) {
+		throw new CameraCaptureError({
+			kind: 'invalidArgument',
+			operation: 'openOutput',
+			message: 'Expected an origin-local movie reference',
+		})
+	}
+
+	const stored = await readMovie(output.resourceId)
+	if (!stored.bytes || !stored.clip) {
+		throw new CameraCaptureError({
+			kind: 'destinationUnavailable',
+			operation: 'openOutput',
+			message: 'Movie is missing or site data was cleared',
+		})
+	}
+
+	const url = URL.createObjectURL(stored.bytes)
+	let released = false
+	return {
+		url,
+		release: () => {
+			if (!released) {
+				released = true
+				URL.revokeObjectURL(url)
+			}
+		},
+	}
+}

package/src/preview-tap.ts

@@ -0,0 +1,34 @@
+import type { CameraPreviewPoint } from './types'
+
+/** Attach a notification-only 'tap' observer to a preview host view and
+ *  report each tap as a `CameraPreviewPoint` normalized to the view's
+ *  bounds. The tap gesture never consumes the touch — recognizers layered
+ *  above the preview still see it. Platforms whose runtime never
+ *  dispatches 'tap' simply never fire the callback. */
+export function observePreviewTap(
+	view: any,
+	onTap: ((point: CameraPreviewPoint) => void) | undefined,
+): () => void {
+	if (!view || !onTap || typeof view.on !== 'function') {
+		return () => {}
+	}
+
+	const handler = (args: any) => {
+		const size = view.getActualSize?.()
+		const width = size?.width ?? 0
+		const height = size?.height ?? 0
+		const x = typeof args?.getX === 'function' ? args.getX() : NaN
+		const y = typeof args?.getY === 'function' ? args.getY() : NaN
+		if (!(width > 0) || !(height > 0) || !Number.isFinite(x) || !Number.isFinite(y)) {
+			return
+		}
+
+		onTap({
+			x: Math.min(1, Math.max(0, x / width)),
+			y: Math.min(1, Math.max(0, y / height)),
+		})
+	}
+
+	view.on('tap', handler)
+	return () => view.off?.('tap', handler)
+}

package/src/props.ts

@@ -0,0 +1,77 @@
+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). */
+	native: any
+}
+
+export interface CameraViewProps {
+	className?: any
+	style?: any
+	id?: string
+	row?: number
+	col?: number
+	rowSpan?: number
+	colSpan?: number
+	dock?: 'left' | 'top' | 'right' | 'bottom'
+	left?: number
+	top?: number
+	flexGrow?: number
+	flexShrink?: number
+	alignSelf?: string
+	order?: number
+	accessible?: boolean
+	accessibilityLabel?: string
+	accessibilityRole?: CameraAccessibilityRole
+	accessibilityHint?: string
+	accessibilityValue?: string
+	accessibilityState?: {
+		disabled?: boolean
+		selected?: boolean
+		checked?: boolean
+	}
+	accessibilityLiveRegion?: 'none' | 'polite' | 'assertive'
+	/** 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
+	/** Fires after the preview surface starts. */
+	onReady?: () => void
+	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/src/session-backend.android.ts

@@ -0,0 +1,439 @@
+import { Application } from '@nativescript/core'
+import { CameraCaptureError } from './types'
+import { canonicalizePath } from './session-core'
+import type {
+	BackendCaptureSink,
+	BackendObserver,
+	BackendPreviewListener,
+	CameraSessionBackend,
+} from './session-core'
+
+import type {
+	CameraPermissionKind,
+	CameraPermissionStatus,
+	CameraSessionConfig,
+	CaptureIssue,
+} from './types'
+
+let requestCode = 7820
+let permissionChain: Promise<unknown> = Promise.resolve()
+let owner: object | undefined
+
+const nativeBridge = () => (globalThis as any).com?.octanexplat?.camera?.CameraSessionBridge
+const permissionName = (kind: CameraPermissionKind) =>
+	kind === 'camera' ? 'android.permission.CAMERA' : 'android.permission.RECORD_AUDIO'
+
+const error = (kind: CaptureIssue['kind'], operation: string, message: string, cause?: unknown) =>
+	new CameraCaptureError({ kind, operation, message, cause })
+
+const context = () => Application.android.context
+const preferences = () => context().getSharedPreferences('octane-camera-permissions', 0)
+
+async function checkPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus> {
+	const activity = Application.android.foregroundActivity ?? Application.android.startActivity
+	if (!activity) {
+		return 'unavailable'
+	}
+
+	const permission = permissionName(kind)
+	if (activity.checkSelfPermission(permission) === 0) {
+		return 'granted'
+	}
+
+	return preferences().getBoolean(kind, false)
+		? activity.shouldShowRequestPermissionRationale(permission)
+			? 'denied'
+			: 'blocked'
+		: 'notDetermined'
+}
+
+function requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus> {
+	const result = permissionChain.then(async () => {
+		const status = await checkPermission(kind)
+		if (status !== 'notDetermined') {
+			return status
+		}
+
+		const activity = Application.android.foregroundActivity ?? Application.android.startActivity
+		if (!activity) {
+			return 'unavailable' as const
+		}
+
+		return new Promise<CameraPermissionStatus>((resolve) => {
+			const code = requestCode++
+			const finish = (value: CameraPermissionStatus) => {
+				clearTimeout(timer)
+				Application.android.off(Application.android.activityRequestPermissionsEvent, onResult)
+				resolve(value)
+			}
+
+			const onResult = (args: any) => {
+				if (args.requestCode !== code) {
+					return
+				}
+
+				if (!args.grantResults?.length) {
+					finish('unknown')
+					return
+				}
+
+				preferences().edit().putBoolean(kind, true).apply()
+				finish(
+					args.grantResults[0] === 0
+						? 'granted'
+						: activity.shouldShowRequestPermissionRationale(permissionName(kind))
+							? 'denied'
+							: 'blocked',
+				)
+			}
+
+			const timer = setTimeout(() => finish('unknown'), 120_000)
+			Application.android.on(Application.android.activityRequestPermissionsEvent, onResult)
+			try {
+				activity.requestPermissions([permissionName(kind)], code)
+			} catch {
+				finish('unavailable')
+			}
+		})
+	})
+
+	permissionChain = result.catch(() => {})
+	return result
+}
+
+export function createSessionBackend(config: CameraSessionConfig): CameraSessionBackend {
+	let currentConfig = { ...config }
+	let observer: BackendObserver | undefined
+	let bridge: any
+	let host: any
+	let listener: BackendPreviewListener | undefined
+	let sink: BackendCaptureSink | undefined
+	let released = false
+	const lease = {}
+	const selected = () =>
+		typeof currentConfig.camera === 'object'
+			? `id:${currentConfig.camera.deviceId}`
+			: (currentConfig.camera ?? 'default')
+
+	const releaseLease = () => {
+		if (owner === lease) {
+			owner = undefined
+		}
+	}
+
+	const onSuspend = () => bridge?.background()
+	const onResume = () => bridge?.foreground()
+	const ensureBridge = () => {
+		if (bridge) {
+			return
+		}
+
+		const Bridge = nativeBridge()
+		if (!Bridge) {
+			throw error(
+				'unsupportedPlatform',
+				'preview',
+				'CameraX video bridge is missing from the native build',
+			)
+		}
+
+		bridge = new Bridge(
+			context(),
+			new Bridge.Listener({
+				event(type: string, payload: string) {
+					if (type === 'ready') {
+						observer?.previewReady(payload === 'true')
+						if (payload === 'true') {
+							listener?.onReady?.()
+						}
+					} else if (type === 'availability') {
+						observer?.availability(payload === 'true')
+					} else if (type === 'interruption') {
+						observer?.interruption('began', payload as any)
+					} else if (type === 'recovered') {
+						observer?.interruption('ended', payload as any)
+					} else if (type === 'previewError') {
+						observer?.availability(false)
+						listener?.onError?.(error('unavailable', 'preview', payload))
+						if (!host) {
+							releaseLease()
+						}
+					} else if (type === 'finishing') {
+						sink?.finishing(payload ? (payload as any) : undefined)
+					} else if (type === 'started') {
+						sink?.started(JSON.parse(payload))
+					} else if (type === 'finished' || type === 'failed') {
+						const target = sink
+						sink = undefined
+						if (!host) {
+							releaseLease()
+						}
+
+						const result = JSON.parse(payload)
+						target?.settled(
+							type === 'finished'
+								? result
+								: {
+										kind: 'failed',
+										stage: result.stage,
+										issue: error(result.kind, result.stage, result.message),
+									},
+						)
+					}
+				},
+			}),
+		)
+
+		Application.on(Application.suspendEvent, onSuspend)
+		Application.on(Application.resumeEvent, onResume)
+	}
+
+	return {
+		platform: 'android',
+		get supported() {
+			return !!nativeBridge()
+		},
+		checkPermission,
+		requestPermission: async (kind) => {
+			const status = await requestPermission(kind)
+			if (
+				kind === 'camera' &&
+				status === 'granted' &&
+				host &&
+				!sink &&
+				!released &&
+				!bridge?.isReady()
+			) {
+				try {
+					ensureBridge()
+					bridge.attach(host, selected())
+				} catch (cause) {
+					observer?.availability(false)
+					listener?.onError?.(
+						error(
+							'unavailable',
+							'preview',
+							'Could not activate CameraX after permission approval',
+							cause,
+						),
+					)
+				}
+			}
+
+			return status
+		},
+		getCapabilities: async () => {
+			const value = bridge ? JSON.parse(bridge.capabilities()) : { cameras: [], profiles: [] }
+			const supported = !!nativeBridge()
+			return {
+				supported,
+				available: !!bridge?.isReady(),
+				reason: !supported
+					? 'CameraX video bridge is missing from the native build'
+					: !bridge?.isReady()
+						? 'An active permitted preview is required'
+						: undefined,
+				cameras: value.cameras,
+				profiles: value.profiles,
+				audio: context().getPackageManager().hasSystemFeature('android.hardware.microphone'),
+				// The bridge only reports metering support once a camera is
+				// bound — absent fields read as unsupported, which is honest
+				// for the current acquisition state.
+				focusPointOfInterest: value.focusPointOfInterest === true,
+				exposurePointOfInterest: value.exposurePointOfInterest === true,
+				orientations: [],
+				durationLimit: 'native',
+				elapsedTime: 'nativeMedia',
+				output: {
+					mimeType: 'video/mp4',
+					container: 'mp4',
+					storage: 'appPrivateFile',
+					destinationFileUrl: true,
+				},
+			}
+		},
+		previewReady: () => !!bridge?.isReady(),
+		validateStart: (options) => {
+			if (
+				options.maximumDurationMs !== undefined &&
+				options.maximumDurationMs > 9_223_372_036_854
+			) {
+				throw error(
+					'unsupportedConfiguration',
+					'startRecording',
+					'The duration exceeds CameraX media-time range',
+				)
+			}
+
+			if (options.orientation && options.orientation !== 'unspecified') {
+				throw error(
+					'unsupportedConfiguration',
+					'startRecording',
+					'Fixed cardinal orientation has not been qualified on this Android source',
+				)
+			}
+		},
+		attachPreview: (target, callbacks) => {
+			if (released || sink) {
+				throw error('invalidState', 'attachPreview', 'The camera is disposed or finalizing')
+			}
+
+			if (owner && owner !== lease) {
+				throw error('busy', 'attachPreview', 'Another camera session is still finalizing')
+			}
+
+			owner = lease
+			host = target
+			listener = callbacks
+			try {
+				ensureBridge()
+			} catch (cause) {
+				host = undefined
+				listener = undefined
+				releaseLease()
+				throw error(
+					'unavailable',
+					'attachPreview',
+					'Could not construct the CameraX native bridge',
+					cause,
+				)
+			}
+
+			void checkPermission('camera').then((status) => {
+				if (released || !host) {
+					return
+				}
+
+				if (status !== 'granted') {
+					listener?.onError?.(
+						error(
+							'permissionDenied',
+							'preview',
+							'Request camera permission before activating this preview',
+						),
+					)
+
+					return
+				}
+
+				try {
+					bridge.attach(host, selected())
+				} catch (cause) {
+					listener?.onError?.(
+						error('unavailable', 'preview', 'Could not bind shared CameraX preview', cause),
+					)
+				}
+			})
+
+			return () => {
+				host = undefined
+				listener = undefined
+				bridge.detach()
+				if (!sink) {
+					releaseLease()
+				}
+			}
+		},
+		configure: (next) => {
+			const sourceChanged =
+				JSON.stringify(next.camera) !== JSON.stringify(currentConfig.camera) ||
+				next.profile !== currentConfig.profile
+
+			currentConfig = { ...next }
+			if (host && sourceChanged) {
+				bridge.detach()
+				bridge.attach(host, selected())
+			}
+		},
+		focusAtPoint: (point) => {
+			try {
+				bridge?.focusAtPoint?.(point.x, point.y)
+			} catch {
+				// A missed metering pass must not fault the session.
+			}
+		},
+		startCapture: (request, target) => {
+			sink = target
+			if (request.destinationPath) {
+				// Durable output stays app-private like every other leaf —
+				// canonicalize so '..' cannot escape the files root.
+				const destination = canonicalizePath(request.destinationPath)
+				let filesRoot = ''
+				try {
+					filesRoot = context()?.getFilesDir?.().getAbsolutePath?.() ?? ''
+				} catch {
+					filesRoot = ''
+				}
+
+				if (!filesRoot || !destination.startsWith(`${filesRoot}/`)) {
+					sink = undefined
+					target.settled({
+						kind: 'failed',
+						stage: 'preparation',
+						issue: error(
+							'destinationUnavailable',
+							'startRecording',
+							'destinationFileUrl must resolve inside the app-private files directory',
+						),
+					})
+
+					return
+				}
+
+				request = { ...request, destinationPath: destination }
+			}
+
+			try {
+				bridge.start(
+					request.audio,
+					request.destinationPath ?? '',
+					request.maximumDurationMs === undefined
+						? 0
+						: Math.max(1, Math.ceil(request.maximumDurationMs)),
+				)
+			} catch (cause) {
+				sink = undefined
+				target.settled({
+					kind: 'failed',
+					stage: 'preparation',
+					issue: error(
+						'captureFailed',
+						'startRecording',
+						'CameraX could not begin recording',
+						cause,
+					),
+				})
+			}
+		},
+		stopCapture: () => bridge?.stop(),
+		elapsedMs: () => Number(bridge?.elapsedMs() ?? 0),
+		openOutput: async (output) => {
+			if (output.kind !== 'nativeFile' || output.synthetic) {
+				throw error('invalidArgument', 'openOutput', 'Expected a native Android movie reference')
+			}
+
+			try {
+				const url = nativeBridge().openOutput(output.resourceId, output.fileUrl)
+				return { url, fileUrl: url, release: () => {} }
+			} catch (cause) {
+				throw error(
+					'destinationUnavailable',
+					'openOutput',
+					'The stored Android movie cannot be reopened',
+					cause,
+				)
+			}
+		},
+		release: async () => {
+			released = true
+			Application.off(Application.suspendEvent, onSuspend)
+			Application.off(Application.resumeEvent, onResume)
+			bridge?.release()
+			host = undefined
+			releaseLease()
+		},
+		setObserver: (value) => {
+			observer = value
+		},
+	}
+}