@octane-xplat/camera 0.14.0 → 0.15.0

package/src/session-backend.web.ts

@@ -134,6 +134,11 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 		observer?.interruption('began', 'background')
 	}
 
+	// Track-caused interruptions (ended/mute) need an explicit 'ended' —
+	// a fresh live stream resolves them, and without the event the core
+	// keeps interrupted=true until the session is recreated.
+	let deviceInterrupted = false
+
 	const observeTracks = (target: MediaStream) => {
 		for (const track of target.getTracks()) {
 			track.addEventListener('ended', () => {
@@ -146,6 +151,7 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 				}
 
 				markReady(false)
+				deviceInterrupted = true
 				observer?.availability(false)
 				observer?.interruption('began', 'unknown')
 			})
@@ -157,12 +163,14 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 
 				if (stream === target) {
 					markReady(false)
+					deviceInterrupted = true
 					observer?.interruption('began', 'unknown')
 				}
 			})
 
 			track.addEventListener('unmute', () => {
 				if (stream === target && document.visibilityState !== 'hidden') {
+					deviceInterrupted = false
 					observer?.interruption('ended', 'unknown')
 					observer?.availability(true)
 					markReady(!!host)
@@ -219,6 +227,11 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 			stream = acquired
 			known.camera = 'granted'
 			observeTracks(acquired)
+			if (deviceInterrupted) {
+				deviceInterrupted = false
+				observer?.interruption('ended', 'unknown')
+			}
+
 			observer?.availability(true)
 		} catch (cause) {
 			if (owner === lease) {
@@ -498,6 +511,10 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 							]
 						: [],
 				audio: devices.some((device) => device.kind === 'audioinput'),
+				// The `pointsOfInterest` track constraint is not wired into
+				// the adapter — report honestly rather than fabricate.
+				focusPointOfInterest: false,
+				exposurePointOfInterest: false,
 				orientations: [],
 				durationLimit: 'bestEffort',
 				elapsedTime: 'estimated',

package/src/session-backend.windows.ts

@@ -1,5 +1,6 @@
 import { Application } from '@nativescript/core'
 import { CameraCaptureError } from './types'
+import { canonicalizePath } from './session-core'
 import type {
 	BackendCaptureRequest,
 	BackendCaptureSink,
@@ -533,10 +534,19 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 		const message = String(args?.Message ?? args?.message ?? 'Camera capture failed')
 		markReady(false)
 		observer?.availability(false)
-		observer?.interruption('began', /in use|denied|access/i.test(message) ? 'cameraInUse' : 'unknown')
+		observer?.interruption(
+			'began',
+			/in use|denied|access/i.test(message) ? 'cameraInUse' : 'unknown',
+		)
+
 		if (sink) {
 			// The pipeline died under a live take — try to finalize the
-			// partial media instead of discarding it outright.
+			// partial media instead of discarding it outright. wantStop
+			// makes the early stop stick while
+			// StartRecordToStorageFileAsync is still in flight, and the
+			// deadline settles the take if that call never resolves.
+			wantStop = true
+			armSettleDeadline(sink)
 			sink.finishing(/device|available|found/i.test(message) ? 'cameraUnavailable' : 'captureError')
 			void stopRecording()
 		}
@@ -545,6 +555,8 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 	const onRecordLimitationExceeded = () => {
 		// The OS-level recording limitation ended the take — finalize the
 		// usable media and keep first-cause semantics from the core.
+		wantStop = true
+		armSettleDeadline(sink)
 		sink?.finishing('interrupted')
 		void stopRecording()
 	}
@@ -850,11 +862,29 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 			return toPromise(folder.CreateFileAsync(name, collisionGenerateUniqueName))
 		}
 
-		const filePath = normalizePath(destinationPath)
+		// Durable output stays app-private like every other leaf — resolve
+		// against LocalFolder, canonicalizing first so '..' cannot escape it.
+		const filePath = canonicalizePath(normalizePath(destinationPath), '\\')
+		const localRoot = normalizePath(
+			String(storage?.ApplicationData?.Current?.LocalFolder?.Path ?? ''),
+		)
+
+		if (!localRoot || !filePath.toLowerCase().startsWith(`${localRoot.toLowerCase()}\\`)) {
+			throw error(
+				'destinationUnavailable',
+				'startRecording',
+				'destinationFileUrl must resolve inside app-private storage',
+			)
+		}
+
 		const directory = filePath.slice(0, filePath.lastIndexOf('\\'))
 		const name = filePath.slice(filePath.lastIndexOf('\\') + 1)
 		if (!directory || !name) {
-			throw error('destinationUnavailable', 'startRecording', 'destinationFileUrl is not a file path')
+			throw error(
+				'destinationUnavailable',
+				'startRecording',
+				'destinationFileUrl is not a file path',
+			)
 		}
 
 		const tempPath = String(storage?.ApplicationData?.Current?.TemporaryFolder?.Path ?? '')
@@ -985,7 +1015,13 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 			const durationMs = (await input.computeDuration()) * 1000
 			const width = await video.getDisplayWidth()
 			const height = await video.getDisplayHeight()
-			return { durationMs, width, height, hasAudio, orientation: 'unspecified' as CameraOrientation }
+			return {
+				durationMs,
+				width,
+				height,
+				hasAudio,
+				orientation: 'unspecified' as CameraOrientation,
+			}
 		} finally {
 			input.dispose()
 		}
@@ -1011,6 +1047,10 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 		finalizing = false
 		wantStop = false
 		recordStartedAt = 0
+		if (settleDeadline !== undefined) {
+			clearTimeout(settleDeadline)
+		}
+
 		const file = recordFile
 		recordFile = undefined
 		void removeFileQuietly(file)
@@ -1018,6 +1058,30 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 		teardown()
 	}
 
+	// Same 30s settle deadline the web/linux adapters carry — once
+	// finalization starts, a hung native call must still settle the take.
+	let settleDeadline: ReturnType<typeof setTimeout> | undefined
+	const armSettleDeadline = (target: BackendCaptureSink | undefined) => {
+		if (settleDeadline !== undefined) {
+			clearTimeout(settleDeadline)
+		}
+
+		if (!target) {
+			return
+		}
+
+		settleDeadline = setTimeout(() => {
+			if (sink !== target) {
+				return
+			}
+
+			finishWithError(
+				'finalization',
+				error('finalizationFailed', 'finalize', 'Movie finalization timed out'),
+			)
+		}, 30_000)
+	}
+
 	const settleClip = async (file: any) => {
 		const target = sink
 		const take = request
@@ -1025,6 +1089,10 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 			return
 		}
 
+		if (settleDeadline !== undefined) {
+			clearTimeout(settleDeadline)
+		}
+
 		try {
 			let metadata: Awaited<ReturnType<typeof nativeVideoMetadata>>
 			try {
@@ -1108,6 +1176,7 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 		}
 
 		finalizing = true
+		armSettleDeadline(sink)
 		try {
 			await toPromise(target.StopRecordAsync())
 		} catch (cause) {
@@ -1211,6 +1280,10 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 				cameras,
 				profiles: [{ profile: 'standard', ...profile }],
 				audio: (await listAudioDevices()) > 0,
+				// WinUI MediaCapture focus regions are not wired into the
+				// adapter — report honestly rather than fabricate.
+				focusPointOfInterest: false,
+				exposurePointOfInterest: false,
 				orientations:
 					capture && typeof capture.SetRecordRotationAsync === 'function'
 						? ['portrait', 'portraitUpsideDown', 'landscapeLeft', 'landscapeRight']
@@ -1476,7 +1549,12 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 			try {
 				await toPromise(storage.StorageFile.GetFileFromPathAsync(filePath))
 			} catch (cause) {
-				throw error('unavailable', 'openOutput', `Movie file is missing at ${output.fileUrl}`, cause)
+				throw error(
+					'unavailable',
+					'openOutput',
+					`Movie file is missing at ${output.fileUrl}`,
+					cause,
+				)
 			}
 
 			const handle: MovieOutputHandle = {
@@ -1491,6 +1569,10 @@ export function createSessionBackend(config: CameraSessionConfig): CameraSession
 			released = true
 			generation += 1
 			unbindLifecycle()
+			if (settleDeadline !== undefined) {
+				clearTimeout(settleDeadline)
+			}
+
 			sink = undefined
 			request = undefined
 			wantStop = false

package/src/session-core.ts

@@ -3,6 +3,7 @@ import type {
 	CameraInterruptionReason,
 	CameraPermissionKind,
 	CameraPermissionStatus,
+	CameraPreviewPoint,
 	CameraSession,
 	CameraSessionCapabilities,
 	CameraSessionConfig,
@@ -86,6 +87,10 @@ export interface CameraSessionBackend {
 	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
@@ -123,6 +128,34 @@ const issue = (
 	extra?: Partial<CaptureIssue>,
 ): CameraCaptureError => new CameraCaptureError({ kind, operation, message, ...extra })
 
+/** 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 const canonicalizePath = (raw: string, separator = '/'): string => {
+	const rooted = raw.startsWith(separator)
+	const parts: string[] = []
+	for (const part of raw.split(separator)) {
+		if (part === '' || part === '.') {
+			continue
+		}
+
+		if (part === '..') {
+			if (parts.length > 0 && parts[parts.length - 1] !== '..') {
+				parts.pop()
+			} else if (!rooted) {
+				parts.push(part)
+			}
+
+			continue
+		}
+
+		parts.push(part)
+	}
+
+	return (rooted ? separator : '') + parts.join(separator)
+}
+
 /** The concrete session object wrapping a platform backend. Internal to
  *  the package; `CameraSession` is the public shape. */
 export class SharedCameraSession implements CameraSession {
@@ -283,7 +316,14 @@ export class SharedCameraSession implements CameraSession {
 			return status
 		})
 
-		this.requestChains.set(kind, chain)
+		// Store a swallowed continuation — a rejected backend call must not
+		// poison the chain and refuse every later request with the original
+		// error. The caller still receives the real rejection.
+		this.requestChains.set(
+			kind,
+			chain.catch(() => 'unknown' as CameraPermissionStatus),
+		)
+
 		return chain
 	}
 
@@ -293,6 +333,21 @@ export class SharedCameraSession implements CameraSession {
 		return capabilities
 	}
 
+	focusAtPoint(point: CameraPreviewPoint): void {
+		if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+			throw issue('invalidArgument', 'focusAtPoint', 'point.x and point.y must be finite numbers')
+		}
+
+		if (this.disposed || this.disposeRequested) {
+			return
+		}
+
+		this.backend.focusAtPoint?.({
+			x: Math.min(1, Math.max(0, point.x)),
+			y: Math.min(1, Math.max(0, point.y)),
+		})
+	}
+
 	async configure(next: Partial<CameraSessionConfig>): Promise<void> {
 		if (this.disposed || this.disposeRequested) {
 			throw issue('invalidState', 'configure', 'CameraSession is disposed')
@@ -414,11 +469,22 @@ export class SharedCameraSession implements CameraSession {
 			}
 		}
 
-		if (
-			options.destinationFileUrl !== undefined &&
-			!options.destinationFileUrl.startsWith('file://')
-		) {
-			throw issue('invalidArgument', operation, 'destinationFileUrl must be a local file:// URL')
+		let destinationPath: string | undefined
+		if (options.destinationFileUrl !== undefined) {
+			if (!options.destinationFileUrl.startsWith('file://')) {
+				throw issue('invalidArgument', operation, 'destinationFileUrl must be a local file:// URL')
+			}
+
+			try {
+				destinationPath = decodeURIComponent(options.destinationFileUrl.slice('file://'.length))
+			} catch (cause) {
+				throw issue(
+					'invalidArgument',
+					operation,
+					'destinationFileUrl is not valid percent-encoding',
+					{ cause },
+				)
+			}
 		}
 
 		if (
@@ -577,9 +643,7 @@ export class SharedCameraSession implements CameraSession {
 			audio: this.config.audio === true,
 			orientation: options.orientation,
 			maximumDurationMs: options.maximumDurationMs,
-			destinationPath: options.destinationFileUrl?.startsWith('file://')
-				? decodeURIComponent(options.destinationFileUrl.slice('file://'.length))
-				: undefined,
+			destinationPath,
 		}
 
 		try {

package/src/synthetic-session.ts

@@ -10,6 +10,7 @@ import type {
 import type {
 	CameraInterruptionReason,
 	CameraPermissionStatus,
+	CameraPreviewPoint,
 	CameraSession,
 	CameraSessionCapabilities,
 	CameraSessionConfig,
@@ -47,6 +48,9 @@ export interface SyntheticCameraScript {
 		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 {
@@ -92,6 +96,9 @@ const capabilities: CameraSessionCapabilities = {
 	],
 	profiles: [{ profile: 'standard', width: 1280, height: 720, frameRate: 30 }],
 	audio: true,
+	// The seam accepts metering points so tests exercise the supported path.
+	focusPointOfInterest: true,
+	exposurePointOfInterest: true,
 	orientations: ['portrait', 'portraitUpsideDown', 'landscapeLeft', 'landscapeRight'],
 	durationLimit: 'native',
 	elapsedTime: 'nativeMedia',
@@ -238,6 +245,9 @@ function createSyntheticBackend(
 			reason: script.available ? undefined : 'Synthetic camera is unavailable',
 		}),
 		previewReady: () => attached && script.available,
+		focusAtPoint: (point) => {
+			script.focusRequests?.push(point)
+		},
 		attachPreview: (_host, listener) => {
 			attached = true
 			queueMicrotask(() => {

package/src/types.ts

@@ -79,6 +79,16 @@ export class CameraCaptureError extends Error implements CaptureIssue {
 
 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'
@@ -130,6 +140,13 @@ export interface CameraSessionCapabilities {
 	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;
@@ -314,6 +331,17 @@ export interface CameraSession {
 	 *  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>

package/types/props.d.ts

@@ -1,5 +1,5 @@
 import type { Octane } from 'octane/jsx-runtime';
-import type { CameraSession } from './types';
+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). */
@@ -44,6 +44,13 @@ 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. */

package/types/session-core.d.ts

@@ -1,4 +1,4 @@
-import type { CameraInterruptionReason, CameraPermissionKind, CameraPermissionStatus, CameraSession, CameraSessionCapabilities, CameraSessionConfig, CameraSessionEvent, CameraSessionSnapshot, CaptureIssue, EffectiveCaptureConfig, MovieEndReason, MovieOutput, MovieOutputHandle, MovieTake, StartRecordingOptions } from './types';
+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 = {
@@ -60,6 +60,10 @@ export interface CameraSessionBackend {
     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
@@ -86,6 +90,11 @@ export interface BackendObserver {
     /** 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 {
@@ -117,6 +126,7 @@ export declare class SharedCameraSession implements CameraSession {
     }>;
     requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
     capabilities(): Promise<CameraSessionCapabilities>;
+    focusAtPoint(point: CameraPreviewPoint): void;
     configure(next: Partial<CameraSessionConfig>): Promise<void>;
     private validateCameraSelection;
     private requestStop;

package/types/synthetic-session.d.ts

@@ -1,4 +1,4 @@
-import type { CameraInterruptionReason, CameraPermissionStatus, CameraSession, CameraSessionConfig } from './types';
+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
@@ -30,6 +30,9 @@ export interface SyntheticCameraScript {
         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>;

package/types/types.d.ts

@@ -43,6 +43,15 @@ export declare class CameraCaptureError extends Error implements CaptureIssue {
     });
 }
 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. */
@@ -86,6 +95,13 @@ export interface CameraSessionCapabilities {
     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;
@@ -248,6 +264,17 @@ export interface CameraSession {
      *  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>;