@octane-xplat/camera 0.12.0 → 0.14.0

package/src/CameraView.web.tsrx

@@ -1,5 +1,6 @@
 import { useImperativeHandle, useEffect, useRef } from 'octane'
 import type { CameraViewProps } from './props'
+import { attachSessionPreview } from './session'
 import { applyEscapeProps, layoutChildProps } from './layout-child.web'
 
 /** Live web preview backed by getUserMedia. */
@@ -13,6 +14,23 @@ export function CameraView(props: CameraViewProps) @{
 	useEffect(() => {
 		const element = video.current
 		if (!element || !active) return
+		if (props.session) {
+			if (props.facing !== undefined) {
+				props.onError?.({ message: 'camera session conflicts with facing' })
+				return
+			}
+
+			try {
+				return attachSessionPreview(props.session, element, {
+					onReady: props.onReady,
+					onError: (issue) => props.onError?.({ message: issue.message }),
+				})
+			} catch (error: any) {
+				props.onError?.({ message: error?.message ?? 'camera session error' })
+				return
+			}
+		}
+
 		const mediaDevices = navigator.mediaDevices
 		if (!mediaDevices?.getUserMedia) {
 			props.onError?.({ message: 'camera unsupported' })
@@ -51,7 +69,7 @@ export function CameraView(props: CameraViewProps) @{
 			element.srcObject = null
 			if (stream) for (const track of stream.getTracks()) track.stop()
 		}
-	}, [active, facing])
+	}, [active, facing, props.session])
 
 	useImperativeHandle(props.ref, () => ({ native: hostRef.current }), undefined);
 
@@ -93,7 +111,7 @@ export function CameraView(props: CameraViewProps) @{
 					transform: facing === 'front' ? 'scaleX(-1)' : undefined,
 				}}
 				onPlaying={() => {
-					if (readyFired.current) return
+					if (props.session || readyFired.current) return
 					readyFired.current = true
 					props.onReady?.()
 				}}

package/src/CameraView.windows.tsrx

@@ -0,0 +1,124 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useImperativeHandle, useCallback, useEffect, useRef } from 'octane'
+import { View } from '@nativescript/core'
+import { registerElement } from '@nativescript-community/octane'
+import type { Attributes } from '@nativescript-community/octane/intrinsics'
+import type { CameraViewProps } from './props'
+import { attachSessionPreview } from './session'
+import { cameraHardwarePresent, ensureCameraPermission } from './camera-permission.windows'
+import { startCameraPreview } from './camera-session.windows'
+import { applyEscapeProps, layoutChildProps, nativeAccessibilityRole, nativeAccessibilityState } from './layout-child.windows'
+import { cx } from './cx.windows'
+
+class CameraPreview extends View {
+	createNativeView() {
+		const { Microsoft } = globalThis as any
+		return new Microsoft.UI.Xaml.Controls.CaptureElement()
+	}
+}
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		camerapreview: Attributes<typeof CameraPreview>
+	}
+}
+
+registerElement('camerapreview', CameraPreview)
+
+/** Live Windows preview backed by WinUI `CaptureElement` + `MediaCapture`.
+ *  With `session`, the preview attaches to the session-owned capture so
+ *  movie recording shares it; without one the view owns its capture. */
+export function CameraView(props: CameraViewProps) @{
+	const host = useRef<any>(null)
+	const active = props.active !== false
+	const facing = props.facing ?? 'back'
+	useImperativeHandle(props.ref, () => ({ native: host.current?.nativeViewProtected }), [])
+
+	const bindHost = useCallback((view: any) => {
+		host.current = view
+	}, [])
+
+	useEffect(() => {
+		const view = host.current
+		if (!view || !active) return
+		let disposed = false
+		let stopPreview: (() => Promise<void>) | undefined
+		const fail = (message: string) => props.onError?.({ message })
+
+		if (props.session) {
+			if (props.facing !== undefined) {
+				fail('camera session conflicts with facing')
+				return
+			}
+
+			try {
+				const detach = attachSessionPreview(props.session, view, {
+					onReady: () => {
+						if (!disposed) props.onReady?.()
+					},
+					onError: (issue) => {
+						if (!disposed) fail(issue.message)
+					},
+				})
+
+				return () => {
+					disposed = true
+					detach()
+				}
+			} catch (error: any) {
+				fail(error?.message ?? 'camera session error')
+				return
+			}
+		}
+
+		if (!cameraHardwarePresent()) {
+			fail('camera unsupported')
+			return
+		}
+
+		ensureCameraPermission().then(async (granted) => {
+			if (disposed) return
+			if (!granted) {
+				fail('camera permission denied')
+				return
+			}
+
+			try {
+				stopPreview = await startCameraPreview(view, facing, () => {
+					if (!disposed) props.onReady?.()
+				})
+			} catch (error: any) {
+				if (!disposed) fail(error?.message ?? 'camera error')
+			}
+		})
+
+		return () => {
+			disposed = true
+			void stopPreview?.()
+		}
+	}, [active, facing, props.session])
+
+	useEffect(() => {
+		const view = host.current
+		if (!view) return
+		applyEscapeProps(view.nativeViewProtected, props)
+	}, [props.ref, props.windows])
+
+	<gridlayout
+		id={props.id}
+		rows="*"
+		columns="*"
+		className={cx('vx-layers', 'vx-cameraview', props.className)}
+		style={{ backgroundColor: '#000', ...props.style }}
+		{...layoutChildProps(props)}
+		accessible={props.accessible}
+		accessibilityLabel={props.accessibilityLabel}
+		accessibilityRole={nativeAccessibilityRole(props.accessibilityRole) as any}
+		accessibilityHint={props.accessibilityHint}
+		accessibilityValue={props.accessibilityValue}
+		accessibilityState={nativeAccessibilityState(props.accessibilityState) as any}
+		accessibilityLiveRegion={props.accessibilityLiveRegion as any}
+	>
+		<camerapreview ref={bindHost} row={0} col={0} />
+	</gridlayout>
+}

package/src/camera-permission.windows.ts

@@ -0,0 +1,76 @@
+/** Windows camera-permission probe for preview-only `CameraView` callers.
+ *  Uses `AppCapability` when projected and falls back to
+ *  `DeviceAccessInformation`; both are non-prompting checks — only
+ *  `RequestAccessAsync` may show the system prompt. */
+
+const windows = () => globalThis as any
+
+const toPromise = (op: any): Promise<any> => {
+	const { NSWinRT } = windows()
+	if (NSWinRT?.toPromise && op != null) {
+		return NSWinRT.toPromise(op)
+	}
+
+	if (op?.done) {
+		return new Promise((resolve, reject) => {
+			try {
+				op.done(resolve, reject)
+			} catch (cause) {
+				reject(cause)
+			}
+		})
+	}
+
+	return Promise.resolve(op)
+}
+
+export function cameraHardwarePresent(): boolean {
+	const { Windows, Microsoft } = windows()
+	return !!(
+		Windows?.Media?.Capture?.MediaCapture &&
+		Windows?.Devices?.Enumeration?.DeviceInformation &&
+		Microsoft?.UI?.Xaml?.Controls?.CaptureElement
+	)
+}
+
+export async function ensureCameraPermission(): Promise<boolean> {
+	try {
+		const { Windows } = windows()
+		const capability =
+			Windows?.Security?.Authorization?.AppCapabilityAccess?.AppCapability?.Create?.('webcam')
+
+		if (capability) {
+			const status = capability.CheckAccess()
+			// AppCapabilityAccessStatus: DeniedBySystem=0, NotDeclaredByApp=1,
+			// DeniedByUser=2, UserPromptRequired=3, Allowed=4.
+			if (status === 4) {
+				return true
+			}
+
+			if (status === 3) {
+				return (await toPromise(capability.RequestAccessAsync())) === 4
+			}
+
+			return false
+		}
+
+		const enumeration = Windows?.Devices?.Enumeration
+		const deviceClass = enumeration?.DeviceClass?.VideoCapture
+		const info =
+			deviceClass === undefined
+				? undefined
+				: enumeration?.DeviceAccessInformation?.CreateFromDeviceClass(deviceClass)
+
+		if (info) {
+			// DeviceAccessStatus: Unspecified=0, Allowed=1, DeniedByUser=2,
+			// DeniedBySystem=3. The enumeration API cannot prompt — an
+			// Unspecified outcome is resolved by the preview's own
+			// InitializeAsync, which runs the OS consent flow.
+			return info.CurrentStatus !== 2 && info.CurrentStatus !== 3
+		}
+	} catch {
+		return false
+	}
+
+	return false
+}

package/src/camera-session.macos.ts

@@ -0,0 +1,75 @@
+import '@nativescript/macos-node-api'
+
+interface CameraHost {
+	attachPreview(view: object): string | null
+	detachPreview(): void
+	installObserver(emit: (message: string) => void): void
+	permissionStatus(kind: string): string
+	requestPermissionReply(kind: string, reply: (status: string) => void): void
+	devices(): string
+	audioDeviceAvailable(): boolean
+	configure(options: { cameraId?: string; audio?: boolean; rotationAngle?: number }): string | null
+	dispose(): void
+}
+
+declare const XplatCameraHost: {
+	alloc(): { init(): CameraHost }
+}
+
+let helper: CameraHost | undefined
+const helperHost = () => (helper ??= XplatCameraHost.alloc().init())
+
+export function cameraHardwarePresent(): boolean {
+	try {
+		return JSON.parse(helperHost().devices()).length > 0
+	} catch {
+		return false
+	}
+}
+
+/** Preview-only permission entry point: prompts once from mount, mirrors the
+ *  iOS legacy path. Session code should use `session.requestPermission` —
+ *  explicit actions only. */
+export function ensureCameraPermission(): Promise<boolean> {
+	const status = helperHost().permissionStatus('camera')
+	if (status === 'granted') {
+		return Promise.resolve(true)
+	}
+
+	if (status === 'undeclared') {
+		return Promise.resolve(false)
+	}
+
+	return new Promise((resolve) =>
+		helperHost().requestPermissionReply('camera', (next) => resolve(next === 'granted')),
+	)
+}
+
+/** Legacy preview-only path: a dedicated XplatCameraHost owns the preview
+ *  session — shared with nothing, disposed with the view. The session-backed
+ *  path goes through `attachSessionPreview` instead. */
+export function startCameraPreview(
+	view: object,
+	_facing: 'front' | 'back',
+	onReady?: () => void,
+): () => void {
+	const host = XplatCameraHost.alloc().init()
+	host.installObserver(() => {})
+	const configured = host.configure({ audio: false })
+	if (configured) {
+		host.dispose()
+		throw new Error(`camera unavailable: ${configured}`)
+	}
+
+	const failure = host.attachPreview(view)
+	if (failure) {
+		host.dispose()
+		throw new Error(`camera unavailable: ${failure}`)
+	}
+
+	onReady?.()
+	return () => {
+		host.detachPreview()
+		host.dispose()
+	}
+}

package/src/camera-session.windows.ts

@@ -0,0 +1,123 @@
+/** Standalone (non-session) WinUI preview for `CameraView` without a
+ *  `session` prop. Owns a private `MediaCapture` bound to a
+ *  `CaptureElement`; the returned function stops preview and closes the
+ *  device. Session-backed previews share their capture through
+ *  `session-backend.windows.ts` instead. */
+
+const windows = () => globalThis as any
+
+const toPromise = (op: any): Promise<any> => {
+	const { NSWinRT } = windows()
+	if (NSWinRT?.toPromise && op != null) {
+		return NSWinRT.toPromise(op)
+	}
+
+	if (op?.done) {
+		return new Promise((resolve, reject) => {
+			try {
+				op.done(resolve, reject)
+			} catch (cause) {
+				reject(cause)
+			}
+		})
+	}
+
+	return Promise.resolve(op)
+}
+
+const vectorToArray = (items: any): any[] => {
+	const result: any[] = []
+	const size = Number(items?.Size ?? items?.Count ?? 0)
+	for (let index = 0; index < size; index += 1) {
+		result.push(items.GetAt(index))
+	}
+
+	return result
+}
+
+/** Attach a MediaCapture preview to the view's `CaptureElement`.
+ *  `facing` maps to enclosure panels; desktop cameras without a panel fall
+ *  back to the OS default — front/back is a preference, never a fabrication. */
+export async function startCameraPreview(
+	view: any,
+	facing: 'front' | 'back',
+	onReady?: () => void,
+): Promise<() => Promise<void>> {
+	const { Windows } = windows()
+	const enumeration = Windows?.Devices?.Enumeration
+	const captureApi = Windows?.Media?.Capture
+	if (!enumeration || !captureApi) {
+		throw new Error('camera preview unsupported')
+	}
+
+	const found = await toPromise(
+		enumeration.DeviceInformation.FindAllAsync(enumeration.DeviceClass.VideoCapture),
+	)
+
+	const devices = vectorToArray(found)
+	if (!devices.length) {
+		throw new Error('camera unavailable')
+	}
+
+	const wantedPanel = facing === 'front' ? 1 : 2
+	const device =
+		devices.find((entry: any) => Number(entry?.EnclosureLocation?.Panel) === wantedPanel) ??
+		devices[0]
+
+	const settings = new captureApi.MediaCaptureInitializationSettings()
+	settings.VideoDeviceId = String(device?.Id ?? device?.id ?? '')
+	settings.StreamingCaptureMode = 0 // Video
+	const capture = new captureApi.MediaCapture()
+	try {
+		await toPromise(capture.InitializeAsync(settings))
+	} catch (cause) {
+		try {
+			capture.Close()
+		} catch {
+			try {
+				capture.Dispose()
+			} catch {
+				// GC reclaims the device handle.
+			}
+		}
+
+		throw cause instanceof Error ? cause : new Error('camera unavailable')
+	}
+
+	const element = view?.nativeViewProtected ?? view
+	element.Source = capture
+	try {
+		if (Number(device?.EnclosureLocation?.Panel) === 1 && typeof capture.SetPreviewMirroring === 'function') {
+			capture.SetPreviewMirroring(true)
+		}
+	} catch {
+		// Mirrored preview is cosmetic.
+	}
+
+	await toPromise(capture.StartPreviewAsync())
+	onReady?.()
+
+	return async () => {
+		try {
+			element.Source = null
+		} catch {
+			// The element may already be gone.
+		}
+
+		try {
+			await toPromise(capture.StopPreviewAsync())
+		} catch {
+			// The pipeline may already be down.
+		}
+
+		try {
+			capture.Close()
+		} catch {
+			try {
+				capture.Dispose()
+			} catch {
+				// GC reclaims the device handle.
+			}
+		}
+	}
+}

package/src/cx.macos.ts

@@ -0,0 +1,5 @@
+/** Imperative `view.className` writes still need a pre-joined string —
+ * normalize arrays here so they stay space separated. */
+export function cx(...parts: any[]): string {
+	return parts.flat(Infinity).filter(Boolean).join(' ')
+}

package/src/cx.mobile.ts

@@ -1,5 +1,6 @@
-/** NativeScript's universal driver stringifies className values; normalize
- * arrays here so they stay space separated. */
+/** Imperative `view.className` writes still need a pre-joined string —
+ * NativeScript's className setter splits on ' ' only. Normalize arrays here
+ * so they stay space separated. */
 export function cx(...parts: any[]): string {
 	return parts.flat(Infinity).filter(Boolean).join(' ')
 }

package/src/cx.windows.ts

@@ -0,0 +1,6 @@
+/** Imperative `view.className` writes still need a pre-joined string —
+ * NativeScript's className setter splits on ' ' only. Normalize arrays here
+ * so they stay space separated. */
+export function cx(...parts: any[]): string {
+	return parts.flat(Infinity).filter(Boolean).join(' ')
+}

package/src/host-movie.web.ts

@@ -0,0 +1,180 @@
+import { createHostClient, type HostClient } from '@octane-xplat/platform/host'
+import { createWebKitTransport } from '@octane-xplat/platform/host/web'
+import { CameraCaptureError } from './types'
+import type { MovieOutput, MovieOutputHandle } from './types'
+
+// Inside a desktop native webview the typed host channel may expose a
+// `camera` service: truthful macOS privacy status plus app-private durable
+// file storage. Outside a host — or when the service is absent — every probe
+// resolves absent and the adapter keeps its browser storage behavior.
+
+export interface CameraHostServices {
+	camera: {
+		permissionStatus(options: { kind: string }): Promise<{ status: string }>
+		requestPermission(options: { kind: string }): Promise<{ status: string }>
+		movieDirectory(): Promise<{ fileUrl: string | null }>
+		reserveMoviePath(options: {
+			fileUrl?: string
+			container?: string
+		}): Promise<{ reservation: { fileUrl: string } | null }>
+		writeMovieFile(options: {
+			fileUrl: string
+			base64: string
+		}): Promise<{ file: { name: string; uri: string } | null }>
+		movieFileInfo(options: {
+			fileUrl: string
+		}): Promise<{ info: { exists: boolean; fileUrl?: string; size?: number } | null }>
+		readMovieFile(options: { fileUrl: string }): Promise<{ base64: string | null }>
+		deleteMovieFile(options: { fileUrl: string }): Promise<{ removed: boolean }>
+	}
+}
+
+const requiredMethods = [
+	'permissionStatus',
+	'requestPermission',
+	'movieDirectory',
+	'reserveMoviePath',
+	'writeMovieFile',
+	'movieFileInfo',
+	'readMovieFile',
+	'deleteMovieFile',
+]
+
+export type CameraHost = HostClient<CameraHostServices>
+
+let hostProbe: Promise<CameraHost | null> | undefined
+
+/** The camera-capable desktop host client, or null outside a qualified host. */
+export function cameraHost(): Promise<CameraHost | null> {
+	hostProbe ??= (async () => {
+		try {
+			const transport = createWebKitTransport()
+			if (!transport) {
+				return null
+			}
+
+			const client = createHostClient<CameraHostServices>(transport)
+			const capabilities = (await client.capabilities().catch(() => null)) as {
+				camera?: string[]
+			} | null
+
+			const methods = capabilities?.camera
+			if (Array.isArray(methods) && requiredMethods.every((name) => methods.includes(name))) {
+				return client
+			}
+
+			client.dispose()
+			return null
+		} catch {
+			return null
+		}
+	})()
+
+	return hostProbe
+}
+
+const error = (kind: 'destinationUnavailable' | 'storageFailed' | 'unavailable', message: string) =>
+	new CameraCaptureError({ kind, operation: 'storage', message })
+
+const blobToBase64 = async (bytes: Blob): Promise<string> => {
+	const data = new Uint8Array(await bytes.arrayBuffer())
+	let binary = ''
+	const chunk = 0x8000
+	for (let offset = 0; offset < data.length; offset += chunk) {
+		binary += String.fromCharCode(...data.subarray(offset, offset + chunk))
+	}
+
+	return btoa(binary)
+}
+
+const base64ToBlob = (base64: string, type: string): Blob => {
+	const binary = atob(base64)
+	const data = new Uint8Array(binary.length)
+	for (let index = 0; index < binary.length; index++) {
+		data[index] = binary.charCodeAt(index)
+	}
+
+	return new Blob([data], { type })
+}
+
+const mimeForFileUrl = (fileUrl: string): string =>
+	fileUrl.endsWith('.webm')
+		? 'video/webm'
+		: fileUrl.endsWith('.mov')
+			? 'video/quicktime'
+			: 'video/mp4'
+
+/** Reserve a host-side movie file. `destinationFileUrl` is validated
+ *  host-side: it must be a new file inside the app-private storage root. */
+export const reserveHostMovie = async (
+	host: CameraHost,
+	options: { destinationFileUrl?: string; container?: string },
+): Promise<{ fileUrl: string }> => {
+	const { reservation } = await host.call('camera', 'reserveMoviePath', {
+		fileUrl: options.destinationFileUrl,
+		container: options.container,
+	})
+
+	if (!reservation?.fileUrl) {
+		throw error(
+			'destinationUnavailable',
+			options.destinationFileUrl
+				? 'destinationFileUrl must be a new file inside the app-private recordings directory'
+				: 'The host could not allocate a movie recording file',
+		)
+	}
+
+	return reservation
+}
+
+/** Commit finalized movie bytes to host-side app-private storage. */
+export const commitHostMovie = async (
+	host: CameraHost,
+	fileUrl: string,
+	bytes: Blob,
+): Promise<MovieOutput> => {
+	const base64 = await blobToBase64(bytes)
+	const { file } = await host.call('camera', 'writeMovieFile', { fileUrl, base64 })
+	if (!file?.uri) {
+		throw error('storageFailed', 'The host could not write the recorded movie')
+	}
+
+	return { kind: 'nativeFile', resourceId: file.uri, fileUrl: file.uri }
+}
+
+/** Drop an uncommitted host reservation after a failed attempt. */
+export const removeHostReservation = async (host: CameraHost, fileUrl: string): Promise<void> => {
+	await host.call('camera', 'deleteMovieFile', { fileUrl }).catch(() => {})
+}
+
+/** Reopen a host-stored movie as a temporary playback URL. The durable
+ *  reference remains `fileUrl`; the returned url lives until `release()`. */
+export const openHostMovie = async (
+	host: CameraHost,
+	output: MovieOutput,
+): Promise<MovieOutputHandle> => {
+	if (output.kind !== 'nativeFile' || !output.fileUrl) {
+		throw new CameraCaptureError({
+			kind: 'invalidArgument',
+			operation: 'openOutput',
+			message: 'Only file-backed output can be opened through the desktop host',
+		})
+	}
+
+	const { info } = await host.call('camera', 'movieFileInfo', { fileUrl: output.fileUrl })
+	if (!info?.exists) {
+		throw error('unavailable', `Movie file is missing at ${output.fileUrl}`)
+	}
+
+	const { base64 } = await host.call('camera', 'readMovieFile', { fileUrl: output.fileUrl })
+	if (!base64) {
+		throw error('unavailable', `Movie file could not be read at ${output.fileUrl}`)
+	}
+
+	const url = URL.createObjectURL(base64ToBlob(base64, mimeForFileUrl(output.fileUrl)))
+	return {
+		url,
+		fileUrl: output.fileUrl,
+		release: () => URL.revokeObjectURL(url),
+	}
+}

package/src/index.ts

@@ -2,3 +2,34 @@
 // the iOS or Android component for the current build target.
 export { CameraView } from './CameraView'
 export type { CameraAccessibilityRole, CameraViewHandle, CameraViewProps } from './props'
+export { createCameraSession } from './session'
+export { CameraCaptureError } from './types'
+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'
+
+export { createMemoryCameraStorage, createSyntheticCameraSession } from './synthetic-session'
+export type { SyntheticCameraScript, SyntheticCameraStorage } from './synthetic-session'